Spec: list command with graceful empty-input handling (#377)

[warp-factories]

Summary

Specifies a new command-signatures list capability backed by a reusable library API and thin clap CLI. Embedded assets are the default source; --file has a binding single-object-or-array Fig-compatible grammar, with [] and empty {} treated as successful empty collections. The design defines deterministic text/JSON output, explicit non-panicking outcomes, and bounded parsing at 10 MiB, nesting depth 64, and 10,000 top-level commands.

Open questions

No user-visible contract questions remain. Maintainers may choose minor implementation details around path ownership and test-only dependencies without changing the normative input, output, limits, or exit behavior.

Issue: #377

[warp-factories]

This PR was generated with Warp.

Comment @warp-factory on this PR to send it follow-up work.

  

[warp-factories]

Ready for maintainer review

The factory ran a review pass on this spec and looped one revision with the author. Current head 6bfa046 is clean: no critical, important, or minor findings outstanding.

Two issues were found and fixed during that loop:

• Non-binding grammar. The external-file contract was stated in a way an implementer could satisfy in mutually exclusive ways. It is now one binding rule — --file takes a single Fig-compatible Command object or an array of them, and empty bytes, whitespace, [], and {} are all successful empty collections.
• Unbounded input handling (security). The original parser fully materialized an arbitrary user-supplied file. The spec now binds limits of 10 MiB, JSON depth 64, and 10,000 top-level commands, each with a distinct diagnostic and exit 1. For calibration: the 1,169 embedded spec files top out at ~1.3 MB (json/mongocli.json), so the caps leave substantial headroom.

Ownership: .github/STAKEHOLDERS has no path-specific rule for the new specs/ tree — the four specific rules (/command-signatures/, /src/, /Cargo.toml, /README.md) don't cover it, so it falls to the repo-wide default owner. Requesting @vikvang on that basis rather than guessing a better-fitting owner.

Worth flagging for whoever approves: if this spec is implemented as written, the change surface splits ownership — command-signatures/src/ and its crate manifest map to @captainsafia, while the root workspace Cargo.toml (where the clap dependency would land) maps to @vkodithala.

This review is advisory, not a merge decision. Implementation stays blocked until a maintainer approves this spec PR.

Responding as Warp for OSS: View run