Add Warp.dev Terminal Support

[JosXa]

Add Warp.dev Terminal Support

Summary

This pull request adds comprehensive support for Warp.dev terminal rules to the dotagent project. Warp.dev is a modern terminal application that allows users to define custom rules and workflows. This implementation enables users to import Warp rules from WARP.md files and export their unified .agent/ rules back to Warp format.

What is Warp.dev?

Warp.dev is a next-generation terminal application that provides:

• AI-powered command suggestions and completions
• Workflow automation capabilities
• Shared sessions and collaboration features
• Custom rule definitions for terminal behavior
• Modern UI with built-in command documentation

Warp uses WARP.md files to store terminal configuration, rules, and workflow definitions, similar to how other tools use their respective configuration files.

Changes Made

Type Definitions (src/types.ts)

• Added 'warp' to the Format type union
• Updated ImportResult.format and ExportOptions.format to use the new Format type for better type safety

Importer Implementation (src/importers.ts)

• Added importWarp() function to read and parse WARP.md files
• Added detection for both WARP.md and WARP.local.md files in importAll()
• Implemented private rule detection for Warp local files
• Created metadata with appropriate description: "Warp.dev terminal rules and instructions"
• Preserved content formatting and structure during import

Exporter Implementation (src/exporters.ts)

• Added exportToWarp() function to convert unified rules to Warp format
• Implemented support for both always-apply and conditional rules
• Added proper headers from rule descriptions
• Integrated Warp export into the exportAll() function
• Maintained consistent formatting with other single-file exporters

CLI Integration (src/cli.ts)

• Added 'warp' to supported formats in help text and validation
• Added Warp.dev option to export format selection menu
• Implemented auto-detection of WARP.md files in convert command
• Added proper error handling and help text updates
• Included WARP.md and WARP.local.md in gitignore patterns

Module Exports (src/index.ts)

• Exported importWarp and exportToWarp functions for public API access
• Maintained consistent export structure with other formats

Testing (test/warp.test.ts)

• Comprehensive test suite covering all Warp functionality:
  • Import from WARP.md and WARP.local.md files
  • Export to Warp format with proper formatting
  • Round-trip conversion (import → export → import)
  • Private rules handling
  • Conditional rules support
  • Edge cases (empty files, malformed content)
  • Content preservation during conversion

Integration Tests (test/integration/roundtrip.test.ts)

• Added Warp format verification to round-trip integration tests
• Ensures Warp rules are properly included in full export/import workflows

How the Warp Format Works

File Structure

• Public rules: WARP.md in repository root
• Private rules: WARP.local.md in repository root (automatically excluded from version control)

Format Characteristics

• Single-file Markdown format similar to AGENTS.md
• Supports standard Markdown headings, lists, and code blocks
• No special frontmatter or metadata within the file
• Content is preserved as-is during import/export
• Rules are organized using Markdown structure within the file

Integration Pattern

Warp follows the same pattern as other single-file formats (AGENTS.md, CLAUDE.md, etc.):

1. Import reads the entire file content as a single rule block
2. Export combines all rules with appropriate headers
3. Conditional rules are referenced in a separate section

Testing Information

Unit Tests

• 467 lines of comprehensive test coverage in test/warp.test.ts
• Tests cover import, export, private rules, conditional rules, and edge cases
• All tests pass with current implementation

Integration Tests

• Warp format is included in round-trip integration tests
• Verified compatibility with full export/import workflows
• Tested alongside all other supported formats

Manual Testing

• Tested with sample WARP.md files containing various content types
• Verified private rules handling with WARP.local.md
• Confirmed CLI integration works correctly

Breaking Changes or Migration Notes

No Breaking Changes

This is a purely additive feature that does not affect existing functionality:

• All existing formats continue to work unchanged
• No changes to existing APIs or data structures
• Backward compatibility is fully maintained

Migration Notes

Existing users can:

1. Continue using all current features without any changes
2. Optionally add Warp support by:
   • Running dotagent import . to detect existing WARP.md files
   • Using dotagent export --format warp to export rules to Warp format
   • Including warp in multi-format exports

Example Usage

Importing Warp Rules

# Import from current directory (detects WARP.md)
dotagent import .

# Import from specific repository
dotagent import /path/to/repo

# Preview import without changes
dotagent import . --dry-run

Exporting to Warp Format

# Export to Warp format specifically
dotagent export --format warp

# Export to multiple formats including Warp
dotagent export --formats copilot,warp,cursor

# Export all formats (includes Warp)
dotagent export --formats all

# Export with private rules included
dotagent export --format warp --include-private

Converting Warp Files

# Convert WARP.md to .agent/ directory
dotagent convert WARP.md

# Convert with explicit format specification
dotagent convert WARP.md -f warp

Sample WARP.md Content

# Terminal Configuration

This project uses specific terminal configurations for optimal development experience.

## Shell Setup

- Use Zsh with Oh My Zsh
- Configure custom aliases for common commands
- Enable syntax highlighting

## Development Workflow

```bash
npm run dev      # Start development server
npm run test     # Run tests
npm run build    # Build for production

Terminal Features

Enable the following Warp features:

• AI Command Suggestions
• Workflow automation
• Shared sessions

## Benefits of This Implementation

1. **Seamless Integration**: Warp users can now manage their terminal rules alongside other AI tool configurations
2. **Consistent Experience**: Warp follows the same patterns as other supported formats
3. **Private Rules Support**: Local Warp configurations are properly handled with version control exclusion
4. **Full Feature Parity**: Supports conditional rules, metadata, and all existing dotagent features
5. **Comprehensive Testing**: Extensive test coverage ensures reliability and correctness

This implementation maintains the high standards of the dotagent project while extending its utility to the growing Warp.dev user community.

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit

* **New Features**
  * Warp format is now supported for importing and exporting rules and appears as a valid CLI format option (including help text and auto-detect hints)
  * Users can import from WARP.md / WARP.local.md and export to WARP.md

* **Documentation**
  * README and new docs updated with Warp usage and API references; added project overview guidance

* **Tests**
  * Added comprehensive tests for Warp import/export and round-trip scenarios

* **Chores**
  * Repository ignore patterns updated to exclude Warp artifacts
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[coderabbitai]

Warning

Rate limit exceeded

@JosXa has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 7 minutes and 26 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 60bf7f8 and d1435f8.

📒 Files selected for processing (12)

• .agent/guidelines.md (1 hunks)
• .gitignore (1 hunks)
• AGENTS.md (1 hunks)
• README.md (7 hunks)
• src/cli.ts (13 hunks)
• src/exporters.ts (2 hunks)
• src/importers.ts (3 hunks)
• src/index.ts (2 hunks)
• src/types.ts (3 hunks)
• test/integration/roundtrip.test.ts (1 hunks)
• test/interactive-export-flow.test.ts (7 hunks)
• test/warp.test.ts (1 hunks)

Walkthrough

Adds full Warp format support: new importWarp/exportToWarp functions, wiring into CLI, import/export flows, public API re-exports, type updates (new Format), tests, and documentation (WARP.md handling and .gitignore updates).

Changes

Cohort / File(s)	Summary
Core Warp Implementation src/importers.ts, src/exporters.ts	Adds importWarp(filePath) to read WARP.md / WARP.local.md and produce a Warp ImportResult. Adds exportToWarp(rules, outputPath, options) to render rules into WARP.md (handles private rules, alwaysApply vs conditional, headers, and sections). Integrates Warp into exportAll.
Type & API Layer src/types.ts, src/index.ts	Introduces Format union type; updates ImportResult.format and ExportOptions.format to use Format. Re-exports importWarp and exportToWarp from public API.
CLI Integration src/cli.ts	Wires Warp into CLI flows: imports/exports, help text, validation and auto-detect lists, interactive selections, dry-run messages, and gitignore/export path handling (WARP.md).
Tests & Documentation test/integration/roundtrip.test.ts, test/warp.test.ts, README.md, .gitignore, AGENTS.md	Adds comprehensive test/warp.test.ts suite and updates roundtrip tests to include warp. Documents Warp in README and AGENTS.md; updates .gitignore to include WARP.md.

Sequence Diagram(s)

sequenceDiagram
    rect rgb(240,248,255)
    participant CLI
    participant Importers as "importers"
    participant Exporters as "exporters"
    participant FS as "FileSystem"
    end

    alt Import Flow (Warp)
        CLI->>Importers: importWarp(filePath)
        Importers->>FS: read WARP.md / WARP.local.md
        FS-->>Importers: file content
        Importers->>Importers: parse into RuleBlock(s), set private if .local.md
        Importers-->>CLI: ImportResult { filePath, rules, format: "warp", raw }
    end

    alt Export Flow (Warp)
        CLI->>Exporters: exportToWarp(rules, outputPath, options)
        Exporters->>Exporters: filter private (if !includePrivate)
        Exporters->>Exporters: separate alwaysApply vs conditional, build content
        Exporters->>FS: write WARP.md / WARP.local.md
        FS-->>Exporters: write confirmation
        Exporters-->>CLI: success / path
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay extra attention to: import/export edge cases in src/importers.ts / src/exporters.ts; private-file (.local.md) handling; type updates in src/types.ts; and the new comprehensive tests test/warp.test.ts.

Possibly related PRs

• Add support for Roo Code and JetBrains Junie #16 — Adds support for a new single-file format and touches the same core surfaces (CLI, importers, exporters, index, types).
• feat: add --formats and --no-gitignore flags for non-interactive export #8 — Modifies CLI export flow and flags; overlaps with CLI wiring and export option handling changed here.

Suggested labels

released

Poem

🐰 I hopped a trail of markdown bright,
WARPed the rules from day to night.
Import, export — tidy and neat,
Round-trip safe, a tasty treat.
Cheers from a rabbit, code complete! 🎉

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Warp.dev Terminal Support' accurately summarizes the main change: adding Warp.dev integration to the codebase with import/export functionality, matching the substantial additions across CLI, importers, exporters, types, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/cli.ts (1)

185-200: Remove the stray closing bracket

There’s an extra ] immediately after the exportFormats array, which makes the file fail to parse and stops the CLI from compiling/running. Drop the extra bracket so the array closes only once.

         { name: 'Warp.dev (WARP.md)', value: 'warp' }
       ]
-      ]

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ef66926 and d5e19dd.

📒 Files selected for processing (11)

• pr-description.md (1 hunks)
• src/cli.ts (11 hunks)
• src/exporters.ts (2 hunks)
• src/importers.ts (2 hunks)
• src/index.ts (2 hunks)
• src/types.ts (3 hunks)
• test-import-warp.cjs (1 hunks)
• test-import-warp.js (1 hunks)
• test-warp.md (1 hunks)
• test/integration/roundtrip.test.ts (1 hunks)
• test/warp.test.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (6)

test-import-warp.js (2)

src/importers.ts (1)

• importWarp (881-906)

src/index.ts (1)

• importWarp (23-23)

test-import-warp.cjs (1)

src/importers.ts (1)

• importWarp (881-906)

src/exporters.ts (1)

src/types.ts (2)

• RuleBlock (16-23)
• ExportOptions (37-43)

test/warp.test.ts (3)

src/importers.ts (1)

• importWarp (881-906)

src/types.ts (1)

• RuleBlock (16-23)

src/exporters.ts (1)

• exportToWarp (549-569)

src/cli.ts (3)

src/exporters.ts (1)

• exportToWarp (549-569)

src/index.ts (2)

• exportToWarp (42-42)
• importWarp (23-23)

src/importers.ts (1)

• importWarp (881-906)

src/importers.ts (2)

src/index.ts (3)

• importWarp (23-23)
• ImportResult (49-49)
• RuleBlock (48-48)

src/types.ts (2)

• ImportResult (25-30)
• RuleBlock (16-23)

🪛 markdownlint-cli2 (0.18.1)

pr-description.md

179-179: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (11)

src/exporters.ts (2)

549-569: LGTM! Warp exporter follows established patterns.

The exportToWarp function is well-implemented and consistent with other single-file exporters (Windsurf, Zed, Codex, Claude). It correctly filters private rules, separates always-apply from conditional rules, and uses appropriate header formatting.

---

588-588: LGTM! Warp format correctly integrated into exportAll.

The integration follows the established pattern and uses the correct output path (WARP.md).

test/integration/roundtrip.test.ts (1)

131-131: LGTM! Integration test correctly updated for Warp format.

The test assertion ensures Warp format is included in the exported formats, consistent with the new functionality.

test-warp.md (1)

1-15: LGTM! Test fixture is appropriate.

The test file provides suitable sample content for Warp format testing with clear structure and multiple rule examples.

src/index.ts (2)

22-23: LGTM! Public API correctly updated.

The importWarp export is properly added to the public API, enabling external usage of Warp import functionality.

---

42-42: LGTM! Export function correctly exposed.

The exportToWarp function is properly exported, completing the public API for Warp format support.

src/types.ts (2)

1-1: LGTM! Format type correctly extended with Warp support.

The Format type union now includes 'warp', providing type safety for the new format across the codebase.

---

26-26: LGTM! Type references updated correctly.

Both ImportResult.format and ExportOptions.format now use the Format type, ensuring consistency and type safety.

Also applies to: 38-38

src/importers.ts (3)

247-265: LGTM! Warp format detection correctly integrated into importAll.

The integration follows the established pattern for format detection, checking for both public (WARP.md) and private (WARP.local.md) variants with proper error handling.

---

874-879: LGTM! importJunie return structure improved.

The explicit return structure with format, filePath, rules, and raw fields makes the function consistent with other importers and properly typed.

---

881-905: LGTM! importWarp function correctly implemented.

The function follows the established pattern for single-file importers, correctly handles private file detection, and returns a properly structured ImportResult. The metadata includes an appropriate description and the content is properly trimmed.

[JosXa]

⚠️ Note: Workflow Configuration Needed

The Claude Code Review workflow is currently failing due to a missing repository secret. To enable automated code reviews:

1. Go to Settings → Secrets and variables → Actions
2. Add a new repository secret: CLAUDE_CODE_OAUTH_TOKEN
3. Set the value to your Claude Code OAuth token

Alternatively, you can temporarily disable this workflow by commenting out .github/workflows/claude-code-review.yml.

This does not affect the Warp feature implementation - all code changes are tested and working correctly (125/125 tests passing ✅).