xarmian
1e3991c865
* feat(schema): publish cmdhelp.schema.json v0.1 (TASK-932)
Adds the formal JSON Schema (draft 2020-12) describing cmdhelp v0.1's
`--format json` wire format, plus a schema/README.md documenting intended
use for CLI authors and consumer wrappers.
Per IDEA-927 the schema enforces the v0.1 contracts:
- Required top-level: cmdhelp_version, binary, commands.
- cmdhelp_version pattern is MAJOR.MINOR (no PATCH); '0.1.0' invalid.
- Argument types: closed set {string,int,float,bool,enum,path,url,
duration,date,datetime,json,ref} plus x-* extension namespace.
- Boolean flag arity (§5.3): negate_flag only valid when type=bool.
- exit_codes union (§5.2): each entry is string OR object{when,recovery,
message_template}; object form requires `when`. Codes must be numeric.
- Dynamic enums (§7): enum_source pattern is `^dynamic:.+$`.
- additionalProperties: true at extension points for forward-compat (§9).
Validated locally with python jsonschema: 8 tests (1 valid sample,
5 negative cases, 2 x-*/dynamic positive cases) all pass.
Unblocks TASK-934 (JSON emitter), TASK-938 (test suite validates against
this schema), and TASK-940 (publish on getpad.dev).
Parent: PLAN-930.
* fix(schema): enforce flag-name pattern + clarify test-suite wording per Codex review (round 1)
Two findings from Codex round 1 on PR #325:
1. flagMap accepted invalid keys ('--verbose', empty string, digit-leading)
despite README documenting "without leading --". Added propertyNames
pattern `^[a-zA-Z][a-zA-Z0-9_-]*$` so producers can't ship malformed
flag names that consumers would parse incorrectly.
2. schema/README.md described `internal/cmdhelp/` as if it existed and
already validated in `go test ./...`. The package ships in TASK-934
(and the validation test in TASK-938). Reworded as future/planned.
Verification:
- Schema syntax: still valid Draft 2020-12.
- Original 8 tests still pass.
- 3 new negative tests for the propertyNames pattern: '--verbose',
empty string, and digit-leading keys all correctly rejected.
- Single-letter short-flag keys like `h` still accepted.
- `make check` clean.
Note for next review round: Codex's first run reported a `httptest`
panic in `cmd/pad` tests; that's a sandbox networking constraint
(read-only mode can't bind sockets), not a regression — verified
locally with `go test ./cmd/pad/ -run TestEnsureWorkspaceSlugAttachExisting -count=1` (passes).
3.9 KiB
cmdhelp.schema.json
Formal JSON Schema (draft 2020-12) for the cmdhelp v0.1 wire format — the structured output produced by <cmd> help --format json on any conforming CLI.
What this is
cmdhelp is a tiny vendor-neutral convention for CLI tools to expose their documentation and invocation schema to LLMs and LLM harnesses (Claude Code, Cursor, MCP servers, IDE plugins). Each conforming CLI emits two formats from one source of truth:
- Markdown (
--format md) — drop-in context for an LLM to read. - JSON (
--format json) — structured schema for an LLM (or its harness) to call. ← this schema describes that JSON.
See the full v0.1 spec on getpad.dev/cmdhelp (or IDEA-927 in this workspace).
Who consumes this
- CLI authors validate their
--format jsonoutput as a CI step so the wire format never silently drifts. - Wrappers (MCP servers, IDE plugins, agent harnesses) validate received
cmdhelpdocuments before parsing, so a buggy producer surfaces as a clear schema error rather than a mysterious downstream failure. - Spec implementers use it as the authoritative reference for which fields are required, which are optional, and what shapes are allowed.
Usage
The schema is published at the canonical URL inside Pad's reference implementation, and committed into this repository at schema/cmdhelp.schema.json.
Validating a cmdhelp document with ajv
npm install -g ajv-cli
pad help --format json > /tmp/cmdhelp.json
ajv validate -s schema/cmdhelp.schema.json -d /tmp/cmdhelp.json --spec=draft2020
Validating with Python jsonschema
pip install 'jsonschema[format]'
python -c "
import json, jsonschema, sys
schema = json.load(open('schema/cmdhelp.schema.json'))
doc = json.load(sys.stdin)
jsonschema.validate(doc, schema)
print('OK')
" < <(pad help --format json)
Validating in Go (planned for Pad's own test suite)
Once the JSON emitter ships (TASK-934), the test suite in internal/cmdhelp/ will validate the live pad help --format json output against this schema as part of go test ./..., so a drift between emitter and schema fails CI. The test-side contract is owned by TASK-938. The schema is committed first because TASK-934 and TASK-938 are both downstream of (and validated against) it.
v0.1 highlights
- Required top-level keys:
cmdhelp_version,binary,commands. - Argument-type vocabulary (closed set +
x-*extension namespace):string,int,float,bool,enum(required);path,url,duration,date,datetime,json,ref(recommended);x-<tool-specific>(extension). - Boolean flag arity (spec §5.3): bool flags are presence switches by default; valued booleans use
enum: ["true", "false"]; negation via the optionalnegate_flagfield. exit_codesunion (spec §5.2): each entry MAY be a terse string OR a rich object{ when, recovery?, message_template? }. Consumers MUST handle both shapes.- Dynamic enums (spec §7): args/flags that depend on session state (workspace, profile, account) declare an
enum_source: "dynamic:<command>"and MAY include the resolved values inenum. - Wire format version (spec §9):
MAJOR.MINORonly — never includes a PATCH component. Validated by pattern^[0-9]+\.[0-9]+$.
Versioning
This file's schema describes cmdhelp v0.1. When the spec moves to a new MAJOR or MINOR, this file is updated in lockstep and the $id URL bumps.
Forward-compat: tools advertising cmdhelp/0.1 MUST tolerate unknown fields (the schema sets additionalProperties: true at every level where extensibility is desirable). Add fields freely in MINOR bumps.
Provenance
Drafted in the design conversation captured under IDEA-927, frozen 2026-05-01 after four rounds of Codex review, reference implementation tracked under PLAN-930.