From 31af05b5a77d1fd4c16f5530289e822b709c7bcf Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:26:51 +0100 Subject: [PATCH 01/10] add an AGENTS.md to the project --- AGENTS.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..3d9d4f20 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,109 @@ +# AGENTS.md + +This file provides guidance to WARP (warp.dev) when working with code in this repository. + +## Overview + +This repository provides command completion signatures ("specs") for Warp terminal. It contains two Rust crates: + +- **`warp-command-signatures`**: The main library that embeds and exposes command specs. Used as a dependency by `warp-internal`. +- **`warp-completion-metadata`**: Core types for signatures, arguments, options, generators, and the Fig-compatible JSON schema. + +## Build and Test Commands + +```bash +# Build +cargo build + +# Run tests +cargo test --verbose + +# Lint (fmt + clippy) +cargo fmt -p warp-command-signatures -p warp-completion-metadata +cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings + +# Autogenerate PowerShell cmdlet specs (requires pwsh installed) +cargo run --bin autogenerate_powershell +``` + +## Architecture + +### Command Specs (JSON) + +Specs are JSON files based on the [Fig completion spec schema](https://fig.io/docs/reference), but **Warp does not use Fig's JavaScript generators**. Instead: + +- The `generatorName` field references Rust-based generators (see below) +- Fig's `generateSpec` JavaScript field is present in some imported specs but is **ignored** by Warp +- Static suggestions, templates (`filepaths`, `folders`), and subcommand/option definitions work as documented + +| Location | Description | +|----------|-------------| +| `command-signatures/json/*.json` | Hand-written specs | +| `command-signatures/json/autogenerated/powershell/*.json` | Auto-generated PowerShell cmdlet specs | +| `command-signatures/json/overrides/powershell/*.json` | Hand-written overrides for autogenerated specs | + +The `assets.rs` module uses `rust-embed` to flatten these directories into a single namespace at compile time, so callers just use `signature_by_name("git")`. + +### Generators (Rust) + +Generators produce dynamic completions by running shell commands. They are defined in `command-signatures/src/generators/` (one file per command or command family). + +A generator consists of: +1. A `GeneratorProcess` (either a static `CommandBuilder` or a function that builds a command from tokens) +2. An `on_complete_callback` that parses the command output into `Suggestion`s + +JSON specs reference generators via the `generatorName` field (e.g. `"generatorName": "branches"`). The mapping from name → Rust code is established in `generators/mod.rs` via `dynamic_command_signature_data()`. + +Example from `brew.rs`: +```rust +CommandSignatureGenerators::new("brew") + .add_generator( + "formulae_generator", // Referenced in JSON as "generatorName": "formulae_generator" + Generator::script(CommandBuilder::single_command("brew list -1"), |output| { + output.trim().lines() + .map(|line| Suggestion::with_description(line, "Installed formula")) + .collect_unordered_results() + }), + ) +``` + +### Override System + +For autogenerated specs (currently PowerShell only), hand-written augmentations live in `json/overrides/`. Overrides are matched by option name or argument index and merged at generation time. Only `template` and `generatorName` fields are currently supported for overrides. + +## Adding a New Command Spec + +1. **JSON spec**: Create `command-signatures/json/.json` following the Fig schema +2. **Generator** (if needed): Add a new file in `command-signatures/src/generators/`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` + +### Recommended Examples + +When creating new specs, use these as reference: + +- **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions +- **Complex spec with multiple generators**: `json/brew.json` + `src/generators/brew.rs` — shows subcommands, options, and multiple generators (`formulae_generator`, `services`, etc.) + +## Local Development with warp-internal + +To test changes locally, update `warp-internal/Cargo.toml` to point to your local checkout: + +```toml +warp-command-signatures = { path = "../command-signatures/command-signatures", default-features = false } +``` + +When ready to release, revert to the git dependency with the new commit hash. + +## Key Types + +- `Signature`: Defines a command/subcommand (name, options, arguments, subcommands) +- `Argument`: A positional parameter with types (Template, Generator, or literal Suggestion) +- `Opt`: A flag/option with optional arguments +- `Generator`: Produces dynamic suggestions by running shell commands +- `Template`: Built-in generators for files/folders + +## Testing Invariants + +Tests in `lib.rs` verify: +- All `GeneratorName`s referenced in specs exist in `dynamic_command_signature_data()` +- All JSON specs deserialize without error +- Generator commands contain no unsafe (unquoted) newlines (required for TMUX control mode) From a0e1cdb02c0b5edadbb794c451eabcd17f524a63 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:32:54 +0100 Subject: [PATCH 02/10] remove linking with warp-internal --- AGENTS.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3d9d4f20..2c3e5bae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,16 +83,6 @@ When creating new specs, use these as reference: - **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions - **Complex spec with multiple generators**: `json/brew.json` + `src/generators/brew.rs` — shows subcommands, options, and multiple generators (`formulae_generator`, `services`, etc.) -## Local Development with warp-internal - -To test changes locally, update `warp-internal/Cargo.toml` to point to your local checkout: - -```toml -warp-command-signatures = { path = "../command-signatures/command-signatures", default-features = false } -``` - -When ready to release, revert to the git dependency with the new commit hash. - ## Key Types - `Signature`: Defines a command/subcommand (name, options, arguments, subcommands) From eeb0e45bcd11e765dab6af1b38372295428b702d Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:37:28 +0100 Subject: [PATCH 03/10] set Rust version for CI --- .github/workflows/CI.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index b6aa1027..26a55243 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -12,6 +12,9 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 + - uses: dtolnay/rust-toolchain@1.85 + with: + components: rustfmt, clippy - name: Run cargo fmt uses: actions-rs/cargo@v1 with: @@ -26,6 +29,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 + - uses: dtolnay/rust-toolchain@1.85 - name: Run tests uses: actions-rs/cargo@v1 with: From 152cf577164034c9c8f14869b9aef5f23a1bb2b6 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:40:15 +0100 Subject: [PATCH 04/10] invoke cargo directly --- .github/workflows/CI.yml | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 26a55243..1506b447 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -16,22 +16,13 @@ jobs: with: components: rustfmt, clippy - name: Run cargo fmt - uses: actions-rs/cargo@v1 - with: - command: fmt - args: -p warp-command-signatures -p warp-completion-metadata + run: cargo fmt -p warp-command-signatures -p warp-completion-metadata --check - name: Run cargo clippy - uses: actions-rs/cargo@v1 - with: - command: clippy - args: -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings + run: cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: dtolnay/rust-toolchain@1.85 - name: Run tests - uses: actions-rs/cargo@v1 - with: - command: test - args: --verbose + run: cargo test --verbose From 8987f1f233d76d772360243bcc741821dc204261 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:51:25 +0100 Subject: [PATCH 05/10] fix rustfmt failures --- completion-metadata/src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/completion-metadata/src/lib.rs b/completion-metadata/src/lib.rs index 0b644906..2c3f91af 100644 --- a/completion-metadata/src/lib.rs +++ b/completion-metadata/src/lib.rs @@ -253,7 +253,7 @@ pub enum Shell { /// A shell that can assume POSIX-compliant syntax. Posix, Powershell, - CmdExe + CmdExe, } impl Shell { @@ -262,7 +262,7 @@ impl Shell { match self { Shell::Posix => "2>/dev/null", Shell::Powershell => "2> $null", - Shell::CmdExe => "2> NUL" + Shell::CmdExe => "2> NUL", } } } From e09f0cce5d2998c55574f6993494245e21b7cc77 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:57:40 +0100 Subject: [PATCH 06/10] update rust toolchain version --- rust-toolchain.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 4c4ea7ca..eaadc1fe 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,5 +1,5 @@ [toolchain] -channel = "1.82" +channel = "1.85" components = ["rustfmt", "clippy"] targets = ["aarch64-apple-darwin", "x86_64-apple-darwin"] profile = "minimal" From d997b2f5e77cb1089d4fbde7245843d32e44ef28 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 12:57:59 +0100 Subject: [PATCH 07/10] AGENTS.md add some style guidelines --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 2c3e5bae..200f82fb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,8 @@ For autogenerated specs (currently PowerShell only), hand-written augmentations 1. **JSON spec**: Create `command-signatures/json/.json` following the Fig schema 2. **Generator** (if needed): Add a new file in `command-signatures/src/generators/`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` +**Style guideline**: Match the formatting conventions used in the command's `--help` output. For example, if the help text uses `UPPER_CASE` for positional argument names, use the same casing in the spec's argument `name` field. + ### Recommended Examples When creating new specs, use these as reference: From 7e9b8e64456d2c1b90d95fe6f56e982b0f282f7c Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 17:58:37 +0100 Subject: [PATCH 08/10] remove redundant rust version --- .github/workflows/CI.yml | 6 ++---- rust-toolchain.toml | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 1506b447..badf9db8 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -12,9 +12,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: dtolnay/rust-toolchain@1.85 - with: - components: rustfmt, clippy + - uses: dtolnay/rust-toolchain@stable - name: Run cargo fmt run: cargo fmt -p warp-command-signatures -p warp-completion-metadata --check - name: Run cargo clippy @@ -23,6 +21,6 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: dtolnay/rust-toolchain@1.85 + - uses: dtolnay/rust-toolchain@stable - name: Run tests run: cargo test --verbose diff --git a/rust-toolchain.toml b/rust-toolchain.toml index eaadc1fe..6316a9c5 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,5 +1,5 @@ [toolchain] -channel = "1.85" +channel = "1.92" components = ["rustfmt", "clippy"] targets = ["aarch64-apple-darwin", "x86_64-apple-darwin"] profile = "minimal" From c141fc183db2c1a9a253fc808605340627cbf256 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Fri, 13 Feb 2026 18:00:22 +0100 Subject: [PATCH 09/10] dial back rust version so that lint doesnt fail --- rust-toolchain.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 6316a9c5..eaadc1fe 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -1,5 +1,5 @@ [toolchain] -channel = "1.92" +channel = "1.85" components = ["rustfmt", "clippy"] targets = ["aarch64-apple-darwin", "x86_64-apple-darwin"] profile = "minimal" From dfb8cd89485c9187ff7a247b472761bda257f4c2 Mon Sep 17 00:00:00 2001 From: Andy Carlson <2yinyang2@gmail.com> Date: Thu, 19 Feb 2026 17:44:49 +0100 Subject: [PATCH 10/10] move some stuff into skills.md --- .agents/skills/add-command-spec/SKILL.md | 24 +++++++++++++++++ .github/workflows/CI.yml | 2 -- AGENTS.md | 33 +----------------------- 3 files changed, 25 insertions(+), 34 deletions(-) create mode 100644 .agents/skills/add-command-spec/SKILL.md diff --git a/.agents/skills/add-command-spec/SKILL.md b/.agents/skills/add-command-spec/SKILL.md new file mode 100644 index 00000000..f0152fb4 --- /dev/null +++ b/.agents/skills/add-command-spec/SKILL.md @@ -0,0 +1,24 @@ +--- +name: add-command-spec +description: Guide for adding new command completion specs to warp-command-signatures. Use when creating a new JSON spec for shell command completions, adding generators for dynamic suggestions, or extending existing command specs. +--- + +# Adding a New Command Spec + +## Steps + +1. **Create JSON spec**: `command-signatures/json/.json` following the [Fig completion spec schema](https://fig.io/docs/reference) +2. **Create generator** (if needed): Add `command-signatures/src/generators/.rs`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` + +## Style Guideline + +Match the formatting conventions used in the command's `--help` output. For example, if the help text uses `UPPER_CASE` for positional argument names, use the same casing in the spec's argument `name` field. + +## Validation + +Run `cargo test` to verify the spec deserializes correctly and any referenced `generatorName`s exist. + +## Reference Examples + +- **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions +- **Complex spec with multiple generators**: `json/brew.json` + `src/generators/brew.rs` — shows subcommands, options, and multiple generators (`formulae_generator`, `services`, etc.) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index badf9db8..6f1ff504 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -12,7 +12,6 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: dtolnay/rust-toolchain@stable - name: Run cargo fmt run: cargo fmt -p warp-command-signatures -p warp-completion-metadata --check - name: Run cargo clippy @@ -21,6 +20,5 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - uses: dtolnay/rust-toolchain@stable - name: Run tests run: cargo test --verbose diff --git a/AGENTS.md b/AGENTS.md index 200f82fb..f973efc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This file provides guidance to WARP (warp.dev) when working with code in this repository. +This file provides guidance to agents when working with code in this repository. ## Overview @@ -9,23 +9,6 @@ This repository provides command completion signatures ("specs") for Warp termin - **`warp-command-signatures`**: The main library that embeds and exposes command specs. Used as a dependency by `warp-internal`. - **`warp-completion-metadata`**: Core types for signatures, arguments, options, generators, and the Fig-compatible JSON schema. -## Build and Test Commands - -```bash -# Build -cargo build - -# Run tests -cargo test --verbose - -# Lint (fmt + clippy) -cargo fmt -p warp-command-signatures -p warp-completion-metadata -cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings - -# Autogenerate PowerShell cmdlet specs (requires pwsh installed) -cargo run --bin autogenerate_powershell -``` - ## Architecture ### Command Specs (JSON) @@ -71,20 +54,6 @@ CommandSignatureGenerators::new("brew") For autogenerated specs (currently PowerShell only), hand-written augmentations live in `json/overrides/`. Overrides are matched by option name or argument index and merged at generation time. Only `template` and `generatorName` fields are currently supported for overrides. -## Adding a New Command Spec - -1. **JSON spec**: Create `command-signatures/json/.json` following the Fig schema -2. **Generator** (if needed): Add a new file in `command-signatures/src/generators/`, define a `generator()` function returning `CommandSignatureGenerators`, and register it in `generators/mod.rs` - -**Style guideline**: Match the formatting conventions used in the command's `--help` output. For example, if the help text uses `UPPER_CASE` for positional argument names, use the same casing in the spec's argument `name` field. - -### Recommended Examples - -When creating new specs, use these as reference: - -- **Simple spec with generator**: `json/kill.json` + `src/generators/kill.rs` — minimal example showing `generatorName` usage for process and signal completions -- **Complex spec with multiple generators**: `json/brew.json` + `src/generators/brew.rs` — shows subcommands, options, and multiple generators (`formulae_generator`, `services`, etc.) - ## Key Types - `Signature`: Defines a command/subcommand (name, options, arguments, subcommands)