diff --git a/specs/GH396/product.md b/specs/GH396/product.md new file mode 100644 index 00000000..3b96a588 --- /dev/null +++ b/specs/GH396/product.md @@ -0,0 +1,124 @@ +# Product specification: command signature contribution workflow + +## Related issue + +[#396](https://github.com/warpdotdev/command-signatures/issues/396) — Document the command signature contribution workflow + +## Problem + +`README.md` explains where handwritten, autogenerated, and override command signatures live, how to run the PowerShell autogenerator, and how overrides are matched. It does not give contributors an end-to-end workflow for choosing the correct file type, formatting changes, regenerating derived files, validating the repository, or preparing a reviewable pull request. + +The missing workflow forces contributors to infer requirements from `package.json`, `script/presubmit`, `.github/workflows/CI.yml`, and implementation details. The README also says that only `template` can be overridden, while `command-signatures/src/overrides.rs` currently supports both `template` and `generatorName`. + +## Goals + +- Add a concise, public contribution workflow that is usable without agent-only guidance. +- Explain how to choose among a handwritten signature, a PowerShell-autogenerated signature, and an override. +- Document the repository-provided formatting and validation commands in the order contributors should use them. +- State every condition that requires PowerShell autogeneration and how generated changes must be separated for review. +- Correct the documented override fields without removing the existing explanation of merge semantics. +- Give contributors a concrete checklist to complete before opening a pull request. + +## Documentation location decision + +Add a `Contributing command signatures` section to `README.md`, after `Overriding Autogenerated Commands` and before `License`. Do not add a new `CONTRIBUTING.md`. + +The README already contains the signature layout, autogeneration command, and override model that the workflow depends on. Keeping the concise checklist adjacent to those details avoids splitting a small repository's contributor guidance across two documents and directly satisfies the issue's request. A standalone contribution guide can be reconsidered if the repository later accumulates broader contribution policies. + +## Desired behavior + +### Preserve and correct the existing reference material + +Keep the current directory descriptions, override matching rules, positional-index behavior, option-name behavior, and `Set-Location` example. Replace the stale statement that only `template` is supported with the code-backed behavior: + +- overrides can set `template` and `generatorName`; +- both fields apply to top-level positional arguments and to option arguments; +- positional arguments are selected by `index`, and options are selected by `name`; +- other fields on the underlying argument and option types are not supported unless added to the override implementation. + +### Add a destination decision rule + +The workflow must tell contributors: + +1. Use `command-signatures/json/.json` for a handwritten command signature. Today, every top-level JSON file in this directory is handwritten. +2. Treat `command-signatures/json/autogenerated/powershell/*.json` as generated output. Do not edit these files directly. Change `command-signatures/src/bin/autogenerate_powershell.rs` or its supporting generation code when the derived shape or behavior must change, then regenerate. +3. Use `command-signatures/json/overrides/powershell/.json` for a persistent, per-cmdlet `template` or `generatorName` adjustment that the PowerShell source data does not provide. Regenerate after changing an override because overrides are applied while generated files are written. + +The rule must make clear that an override is an input to generation, not a patch applied at runtime, and that direct changes under `json/autogenerated/` will be overwritten. + +### Document the command sequence + +The workflow must present these steps in this order: + +1. Install the pinned Node dependencies with `npm ci` when they are not already installed. +2. Format changed handwritten or override JSON with a targeted command such as: + + `npm run format -- command-signatures/json/.json` + + The section may also mention `npm run format` for all non-ignored signature JSON. It must not tell contributors to format `command-signatures/json/autogenerated/` with Prettier because `.prettierignore` excludes that directory and the generator owns its serialization. +3. Run `cargo run --bin autogenerate_powershell` when any of the following is true: + - PowerShell autogeneration logic or supporting conversion behavior changed; + - a file under `command-signatures/json/overrides/powershell/` changed; + - the contributor is intentionally refreshing output for an upstream Microsoft PowerShell cmdlet/help/metadata change. +4. Run `script/presubmit` after formatting and any required regeneration. Explain that this is the final local validation entry point and that it runs: + - `npm run format:check`; + - `cargo fmt -p warp-command-signatures -p warp-completion-metadata --check`; + - `cargo clippy -p warp-command-signatures -p warp-completion-metadata --all-targets --all-features -- -D warnings`; + - `cargo test --verbose`. + +`npm run format:check` may be shown as a standalone quick check, but the workflow must not imply that contributors need to run it separately when `script/presubmit` has passed. The README should state that pull-request CI mirrors the format, lint, and test checks. + +### Require reviewable generated changes + +When regeneration changes files under `command-signatures/json/autogenerated/powershell/`, contributors must: + +- inspect the generated diff and verify that it is limited to intended cmdlets and fields; +- keep generated output in a separate commit from the generator or override source changes that caused it; +- avoid hand-editing generated output to hide or repair unexpected results. + +Separating commits is required even when the source input is an override, not only when the Rust autogenerator changes. + +### Add a pre-pull-request checklist + +The checklist must require contributors to verify: + +- the change is in the correct handwritten, autogenerated, or override location; +- no generated PowerShell file was edited directly; +- changed JSON was formatted by the repository command; +- PowerShell autogeneration was rerun whenever a generator input changed; +- the generated diff is expected and isolated in a separate commit when present; +- the changed signature or override describes the intended command, arguments, options, templates, and generators; +- `script/presubmit` passes from the repository root; +- the pull request explains whether it contains handwritten, generator, override, or regenerated changes. + +## Relationship to agent guidance + +`.agents/skills/add-command-spec/SKILL.md` remains specialized guidance for automated agents, including command research, dynamic generator implementation, GUI verification, and agent-specific submission conventions. The public README workflow must be independently usable by human contributors and must not require readers to consult that skill. + +The implementation should reuse the skill's repository-backed formatting and presubmit sequence where it overlaps, but should not duplicate its agent-only research and GUI process. No change to the skill is required by this issue; for shared validation facts, the README is the public contributor-facing source and both documents must remain consistent with `package.json` and `script/presubmit`. + +## Non-goals + +- Changing any signature JSON, generated PowerShell output, override data, Rust generator behavior, or validation tooling. +- Adding a new signature, generator, override field, test, or CI job. +- Defining a PowerShell installation or version-management policy. +- Moving or deleting the existing README reference material. +- Creating a comprehensive general-purpose `CONTRIBUTING.md`. +- Copying agent-only GUI testing, screenshot, branch naming, or pull-request title rules into the public workflow. + +## Acceptance criteria + +- The implementation changes `README.md` only; it does not modify signature data, generator code, CI, scripts, or agent skills. +- `README.md` contains a `Contributing command signatures` section in the location specified above. +- The section contains the three-way destination rule and explicitly prohibits direct edits to autogenerated PowerShell JSON. +- The documented command order and command strings match `package.json`, `script/presubmit`, and `.github/workflows/CI.yml`. +- The section lists generator-code changes, override changes, and intentional upstream PowerShell metadata refreshes as regeneration triggers. +- Generated PowerShell output is required to be reviewed and committed separately from its source change. +- The pre-pull-request checklist covers location, formatting, regeneration, generated diff review, behavior, validation, and pull-request description. +- The override documentation says that `template` and `generatorName` are supported and preserves the existing matching semantics and example. +- The README workflow is understandable without `.agents/skills/add-command-spec/SKILL.md` and does not reproduce that skill's agent-only instructions. +- All existing technical details remain unless this specification explicitly corrects them. + +## Open questions + +- The repository does not pin a PowerShell version or module set for autogeneration. Recommendation: keep environment standardization out of scope for #396, describe regeneration only for intentional upstream refreshes, and require careful generated-diff review. Maintainers can request a separate reproducibility issue if a pinned environment is desired. diff --git a/specs/GH396/tech.md b/specs/GH396/tech.md new file mode 100644 index 00000000..7564b2cd --- /dev/null +++ b/specs/GH396/tech.md @@ -0,0 +1,122 @@ +# Technical specification: command signature contribution workflow + +## Current implementation + +- `README.md` describes handwritten files under `command-signatures/json/*.json`, generated files under `command-signatures/json/autogenerated/**/*.json`, the PowerShell generator command, and persistent overrides under `command-signatures/json/overrides/**/*.json`. +- `README.md` currently says only `template` is supported by overrides. +- `command-signatures/src/overrides.rs` deserializes both `template` and `generatorName` for argument overrides. `apply_overrides` assigns either field to top-level arguments selected by index and option arguments selected by option name plus argument index. +- Existing override files exercise both supported fields. For example, `command-signatures/json/overrides/powershell/Set-Location.json` uses `template`, while `command-signatures/json/overrides/powershell/Wait-Process.json` uses `generatorName`. +- `command-signatures/src/bin/autogenerate_powershell.rs` reads PowerShell cmdlet help and metadata, calls `apply_overrides`, and writes the resulting JSON under `command-signatures/json/autogenerated/powershell/`. +- `package.json` defines `npm run format` and `npm run format:check` using Prettier. `.prettierignore` excludes `command-signatures/json/autogenerated/`. +- `script/presubmit` runs JSON format checking, Cargo formatting, Clippy with warnings denied, and the full Rust test suite. +- `.github/workflows/CI.yml` implements the same format, lint, and test groups for pull requests. +- `.agents/skills/add-command-spec/SKILL.md` has a broader agent workflow, but there is no public `CONTRIBUTING.md` and no human-facing end-to-end checklist. + +At the time this specification was written, the repository tracks 496 handwritten top-level JSON signatures, 663 generated PowerShell signatures, and 10 PowerShell override files. These counts demonstrate the three active paths but must not be copied into the workflow because they will drift. + +## Files affected by implementation + +### Required + +- `README.md` + - Preserve the existing `JSON Command Signatures` and `Overriding Autogenerated Commands` explanations. + - Correct the supported override fields. + - Add the new contribution workflow immediately before `License`. + +### Explicitly unchanged + +- `command-signatures/json/**` +- `command-signatures/src/**` +- `script/presubmit` +- `package.json` +- `.github/workflows/CI.yml` +- `.prettierignore` +- `.agents/skills/add-command-spec/SKILL.md` + +## Proposed README structure + +Retain the current top-level `JSON Command Signatures` section and its `Overriding Autogenerated Commands` subsection, then add: + +1. `Contributing command signatures` +2. `Choose the signature source` + - handwritten JSON; + - PowerShell-generated JSON; + - persistent PowerShell override. +3. `Format and regenerate` + - optional dependency setup; + - targeted JSON formatting; + - the three PowerShell regeneration triggers; + - generated-directory ownership. +4. `Validate the change` + - `script/presubmit` as the required final command; + - concise expansion of its current checks; + - relationship to pull-request CI. +5. `Before opening a pull request` + - checklist from `product.md`; + - separate-commit requirement for generated output. + +The exact heading depth may be adjusted to fit the README, but the order and content requirements are normative. + +## Command accuracy + +The implementation must copy commands from these repository sources: + +- `package.json`: `npm run format -- command-signatures/json/.json` and the optional standalone `npm run format:check`; +- `.github/workflows/CI.yml` and `package-lock.json`: reproducible dependency installation with `npm ci`; +- `README.md`: `cargo run --bin autogenerate_powershell`; +- `script/presubmit`: `script/presubmit` and the Cargo commands it aggregates. + +`npm ci` is the reproducible dependency-install command used by `.github/workflows/CI.yml`; it is setup, not a validation check. `npm run format:check` is already the first step in `script/presubmit`, so documentation should not require both commands back-to-back. + +## PowerShell regeneration behavior + +The generated result is a function of: + +- PowerShell help and command metadata available to the local `pwsh` process; +- the Rust autogenerator and supporting conversion code; +- matching JSON under `command-signatures/json/overrides/powershell/`. + +Therefore, a change to any repository-controlled generator input—Rust generation behavior or an override—requires rerunning `cargo run --bin autogenerate_powershell`. An upstream refresh is intentional only when the contributor means to update the PowerShell-derived snapshot. The workflow must not claim that `script/presubmit` regenerates files; it only validates the checked-in result. + +Because the generator obtains data from the installed PowerShell environment and no version is pinned in the repository, the workflow must not promise byte-for-byte reproducibility across arbitrary environments. Unexpected broad churn should be investigated rather than committed. + +## Override behavior to document + +`command-signatures/src/overrides.rs` defines the supported public shape: + +- command-level `args`: one or many entries selected by zero-based `index`; +- command-level `options`: entries selected by `name`; +- each option's `args`: one or many entries selected by zero-based `index`; +- argument values: `template` and `generatorName`, each accepting the shapes supported by the current deserializer; +- a non-empty override value replaces the corresponding generated argument field. + +The README should stay conceptual and preserve its current example; it does not need to reproduce Rust data structures or deserialization details. It must no longer state that `template` is the only supported value. + +## Edge cases + +- A change only to handwritten top-level JSON does not require PowerShell autogeneration. +- A change to a PowerShell override requires both formatting the override and regenerating the corresponding generated result. +- A generator run may produce broad changes because local PowerShell metadata differs. Contributors must inspect and explain the output rather than assume all churn is valid. +- Prettier does not cover autogenerated JSON because `.prettierignore` excludes it. Contributors must not work around the ignore file by formatting generated output separately. +- `script/presubmit` can pass without proving that generated files are current because it does not run the PowerShell generator. The checklist must make regeneration an explicit contributor responsibility. +- An override can refer to an argument or option that no longer exists in the generated source; generation fails rather than silently applying it elsewhere. The workflow should direct contributors to resolve generator or override inputs, not patch the output. + +## Testing strategy + +The implementation is documentation-only, so no new automated tests are required. Reviewers should: + +1. Confirm that the implementation diff changes only `README.md`. +2. Compare every documented command with `package.json`, `script/presubmit`, and `.github/workflows/CI.yml`. +3. Compare regeneration conditions with `command-signatures/src/bin/autogenerate_powershell.rs` and `command-signatures/src/overrides.rs`. +4. Confirm the supported override fields against `ArgOverrides` and `apply_overrides`. +5. Confirm that the existing override matching explanation and `Set-Location` example remain present. +6. Confirm that no tracked file under `command-signatures/json/` changed. +7. Run `script/presubmit` to verify that the documented final validation entry point remains valid. + +## Security and privacy + +This change introduces no new runtime behavior, network boundary, authentication decision, secret handling, or user-data processing. The workflow should not instruct contributors to paste command output or environment details into signature files. Since the PowerShell generator executes local `pwsh` commands and rewrites many tracked files, documentation must limit regeneration to intentional cases and require diff inspection; no change to that existing trust boundary is part of #396. + +## Open questions + +- PowerShell autogeneration is not tied to a pinned PowerShell version or module snapshot. The recommended scope is to document intentional regeneration and review safeguards now, while leaving reproducible environment design to a separate issue.