[Feature]: Add --json output to preset list and extension list

[nicolehaugen]

Problem Statement

Both preset list and extension list emit human-formatted text only; there is no --json. Verified on main: preset_list() and preset_info() in presets/_commands.py take zero optional arguments (no flag anywhere in the file), same for extension _commands.py. Consumers (wizard UI, external tooling, CI checks) have to regex-scrape stdout. The speckit-wizard-canvas extension does exactly this in composition/preset-order.mjs::parsePresetListOutput, and the file's header comment explicitly notes:

"The CLI's specify preset list command prints installed presets in precedence order (first line = winner). That IS the precedence."

Beyond the missing --json, list_installed() in each registry omits fields consumers need:

• Extensions (extensions/__init__.py:3399-3427) return command_count + hook_count only — no template or script counts, even though manifest.templates and manifest.scripts exist post-[Feature]: Allow extensions to declare templates and scripts in their manifest #4010.
• Presets (presets/__init__.py:4049-4088) return template_count + tags only — no command_count, no script_count. The single template_count is misleading because presets contribute commands and scripts in separate manifest.commands / manifest.scripts lists.
• author is dropped on the read path in both registries. The field exists in the manifest (and is even a filter parameter in the catalog search code path at extensions/__init__.py:4127), but neither list_installed() includes it in its return dict.
• Neither surface exposes the structured source (see companion "Record structured provenance for installed presets and extensions" issue). The registry stores it; the read path drops it.

Proposed Solution

Add --json to both commands. The output is a JSON array of objects:

{
  "id": "speckit.git",
  "name": "SpecKit Git",
  "description": "Git-flow helpers",
  "version": "1.2.0",
  "author": "…",
  "priority": 100,
  "enabled": true,
  "source": { "kind": "catalog", "catalog": "speckit-official" },
  "provides": { "commands": 4, "templates": 2, "scripts": 1, "hooks": 3 }
}

Preset objects omit hooks from provides (presets don't contribute hooks). The provides counts are integers, one per manifest kind. Ordering in the JSON array is the same precedence order the text output already uses (so parsePresetListOutput becomes JSON.parse(stdout) on the wizard side). Update list_installed() in both registries to compute the missing counts from the manifest fields landed by #4010 and to surface author.

Alternatives Considered

• Emit YAML. Rejected — the whole point is to let the wizard drop js-yaml.
• Emit only new fields via a separate list --extra flag. Rejected — every consumer would then need two calls.
• Leave counts flat (command_count, hook_count) rather than grouping into provides. Rejected — mixes wire shape with the composition/stack view (filed separately as specify artifact), where the grouped shape is required.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

Not applicable

Use Cases

1. speckit-wizard-canvas replaces composition/preset-order.mjs regex parser with JSON.parse(execFileSync("specify", ["preset", "list", "--json"])).
2. A CI job asserts "the speckit.constitution preset is installed and enabled at priority ≥ 100" with jq, no text parsing.
3. External catalog UIs query extension list --json to reconcile installed vs. remotely-available extensions by id + source.catalog.
4. Support triage: paste specify preset list --json output into a bug report for exact reproduction context.

Acceptance Criteria

• specify preset list --json and specify extension list --json emit a JSON array to stdout with id, name, description, version, author, priority, enabled, source, provides for each entry.
• Extension provides includes commands, templates, scripts, hooks integer counts. Preset provides includes commands, templates, scripts integer counts (no hooks).
• list_installed() in both registries is updated to compute the missing per-kind counts from the current manifest schema, including entries landed by [Feature]: Allow extensions to declare templates and scripts in their manifest #4010.
• source is the structured object from the companion provenance issue (or { "kind": "local" } for legacy records).
• Array order matches the existing text-output precedence order (documented as authoritative in composition/preset-order.mjs).
• Non-zero exit code and stderr JSON {"error": "..."} on failure so consumers can distinguish success from empty-array success.
• Tests: JSON schema round-trip, count parity with the text output, missing-field defaults (author: null), legacy installed.json read.
• Docs: preset list / extension list sections in the CLI reference show the --json shape.

Additional Context

Direct replacement for plugins/spec-kit-copilot-wizard/extensions/speckit-wizard-canvas/composition/preset-order.mjs in github/spec-kit-copilot. Depends on the companion "Record structured provenance for installed presets and extensions" issue.

[github-actions]

Feature assessment — json-list-output · Stage 1/5: Intake

Idea Intake: Add --json to preset list and extension list

• Slug: json-list-output
• Created: 2026-08-19
• Source: pasted text (GitHub issue [Feature]: Add --json output to preset list and extension list #4211, github/spec-kit)
• Type: improvement

Idea (as captured)

Both preset list and extension list emit human-formatted text only; there is no --json. Verified on main: preset_list() and preset_info() in presets/_commands.py take zero optional arguments, same for extension _commands.py. Consumers (wizard UI, external tooling, CI checks) have to regex-scrape stdout. The speckit-wizard-canvas extension does exactly this in composition/preset-order.mjs::parsePresetListOutput, and the file's header comment explicitly notes: "The CLI's specify preset list command prints installed presets in precedence order (first line = winner). That IS the precedence."

Beyond the missing --json, list_installed() in each registry omits fields consumers need: Extensions return command_count + hook_count only — no template or script counts. Presets return template_count + tags only — no command_count, no script_count. author is dropped on the read path in both registries. Neither surface exposes the structured source.

Restated

Add a --json flag to specify preset list and specify extension list that emits a structured JSON array of installed items with a richer set of fields (id, name, description, version, author, priority, enabled, source, provides). Additionally, update list_installed() in both registries to compute and surface the currently missing per-kind counts, author, and structured source.

Origin & Context

• Raised by: @nicolehaugen (GitHub issue [Feature]: Add --json output to preset list and extension list #4211)
• Trigger: The speckit-wizard-canvas extension currently regex-parses specify preset list stdout, and external tooling/CI checks have no structured way to query installed preset/extension state. The manifest schema already carries the needed fields post-[Feature]: Allow extensions to declare templates and scripts in their manifest #4010 but the read path drops them.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Is the source field available in the registry metadata today, or does it depend on the companion "Record structured provenance" issue being completed first?]
• [NEEDS CLARIFICATION: Should --json go to stdout only, or also support --output <file>?]
• [NEEDS CLARIFICATION: What is the expected behaviour when zero items are installed — empty array [] or an error?]
• [NEEDS CLARIFICATION: Is there a Preset hooks field at all, or do presets genuinely never contribute hooks?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4211 · 603.6 AIC · ⌖ 18.4 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — json-list-output · Stage 2/5: Research

Idea Research: Add --json to preset list and extension list

• Slug: json-list-output
• Created: 2026-08-19
• Evidence confidence (overall): high

Users & Demand

• The speckit-wizard-canvas extension (composition/preset-order.mjs) is documented (in its own header comment) to regex-parse specify preset list stdout to determine preset resolution order. This is an internally-observed brittle dependency, not a stated want. (confidence: high — cited in issue body, first-party code in github/spec-kit-copilot)
• CI use case (assert preset enabled at priority ≥ 100 with jq) is a plausible pattern but is stated without evidence of an existing CI job doing this. (confidence: low — ASSUMPTION)
• External catalog UI use case is forward-looking; no evidence of an existing consumer. (confidence: low — ASSUMPTION)
• Support triage use case (paste JSON into bug reports) is plausible and follows common CLI tooling patterns (e.g., docker inspect, gh repo view --json). (confidence: medium — cited pattern in wider ecosystem)

Prior Art

• specify version --json (implemented): src/specify_cli/__init__.py:450–467 shows the project already has a --json flag pattern with typer.Option, JSON-to-stdout, and stderr separation. (confidence: high — codebase, direct read)
• specify workflow run --json (implemented): src/specify_cli/workflows/_commands.py:1314–1316 confirms the pattern is established for multiple commands, with _error_console(json_output) routing errors to stderr. (confidence: high — codebase)
• extension list --available / --all flags already exist, confirming the command accepts options. (confidence: high — src/specify_cli/extensions/_commands.py:419–423)
• No prior attempt to add --json to preset list or extension list found in codebase. (confidence: high)

Market & Context

• Machine-readable CLI output is a mature pattern: gh (GitHub CLI), docker, kubectl, npm all support --json / -o json. (confidence: high — industry-standard)
• Alternative today: consumers regex-scrape stdout, which is explicitly what preset-order.mjs does. This is fragile and breaks silently on text output changes. (confidence: high — cited in issue)

Data & Constraints

• ExtensionManifest already exposes .templates (line 714) and .scripts (line 719) in src/specify_cli/extensions/__init__.py, but list_installed() (line 3399–3441) does not include them in its return dict. The data is already computed; it just is not surfaced. (confidence: high — codebase)
• PresetManifest.author exists (src/specify_cli/presets/__init__.py:508–510) and is used in catalog search, but PresetManager.list_installed() does not include it. (confidence: high — codebase)
• ExtensionManifest has no author property — author for extensions lives in the registry metadata JSON (ext_data.get("author", "")), not the manifest class. (confidence: high — codebase)
• Structured source does not exist yet: registry metadata stores source as a flat string ("catalog" or "local"). The proposed {"kind": "catalog", "catalog": "speckit-official"} structured object depends on a companion "Record structured provenance" issue not yet implemented. A fallback {"kind": "local"} for legacy records is the safe default. (confidence: high — codebase)
• Existing --json implementations route errors to stderr as {"error": "..."} JSON — a pattern is established.

Evidence Against the Idea

• The structured source field (the most novel part of the proposed schema) depends on a companion issue not yet merged. Shipping --json now with a flat source fallback and upgrading later is viable but creates a minor schema evolution.
• The provides grouping adds a wire-format change over the existing flat command_count/hook_count dict, requiring internal callers to update.
• No external consumer (outside github/spec-kit-copilot) has been identified; the primary beneficiary is the internal wizard canvas.

Gaps & Open Questions

• [NEEDS CLARIFICATION: Does ExtensionManifest need an author property added, or should author be read from registry metadata in list_installed()?]
• [NEEDS CLARIFICATION: Should --json emit structured source immediately (requires companion provenance issue) or a flat fallback stepping stone?]
• [NEEDS CLARIFICATION: Does PresetManifest have a commands list analogous to ExtensionManifest.commands?]

Sources

• src/specify_cli/extensions/__init__.py (lines 3399–3441, 4127–4157, 671–724) — direct codebase read
• src/specify_cli/presets/__init__.py (lines 4049–4088, 508–510) — direct codebase read
• src/specify_cli/extensions/_commands.py (lines 419–453) — direct codebase read
• src/specify_cli/presets/_commands.py (lines 47–90) — direct codebase read
• src/specify_cli/__init__.py (lines 450–467) — direct codebase read
• src/specify_cli/workflows/_commands.py (lines 71–76, 1314–1316) — direct codebase read
• GitHub issue [Feature]: Add --json output to preset list and extension list #4211 body — treated as untrusted data / problem statement

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4211 · 603.6 AIC · ⌖ 18.4 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — json-list-output · Stage 3/5: Problem

Problem Definition: Add --json to preset list and extension list

• Slug: json-list-output
• Created: 2026-08-19
• Inputs used: intake.md | research.md

Problem Statement

Consumers of the Spec Kit CLI (internal tooling, CI scripts, wizard UIs) cannot reliably query the set of installed presets and extensions and their metadata because the two list commands emit only human-formatted text — forcing them to regex-parse stdout, which is fragile and breaks silently when the display format changes. Additionally, the data returned by list_installed() in both registries is incomplete: author, per-kind artifact counts (templates, scripts), and structured provenance (source) are not surfaced, even though the underlying manifest and registry objects already hold them.

Affected Users & Stakeholders

• Users: Extension and preset consumers writing automation (CI jobs, external tools) — affected by needing to regex-parse text output with no structured alternative.
• Users: speckit-wizard-canvas authors (github/spec-kit-copilot) — directly affected; their composition/preset-order.mjs explicitly parses specify preset list stdout and documents this as a known fragility.
• Stakeholders: Spec Kit CLI maintainers — bear ongoing maintenance cost of keeping the text format stable enough to parse, without any documented contract.

Goals

• Provide a stable, machine-readable output format for specify preset list and specify extension list so consumers can drop regex parsing.
• Surface the fields that consumers already need but list_installed() currently omits: author, per-kind provides counts, and structured source.
• Follow the existing --json flag pattern established by specify version --json and specify workflow run --json.

Non-Goals

• Changing or removing the existing human-formatted text output.
• Implementing the companion "Record structured provenance" issue — can ship with a flat source fallback and upgrade later.
• Adding --json to any other commands beyond preset list and extension list.
• Changing the resolution-order sorting logic.

Success Metrics

• specify preset list --json emits a valid JSON array to stdout (baseline: not supported).
• specify extension list --json emits a valid JSON array to stdout (baseline: not supported).
• Each element includes id, name, description, version, author, priority, enabled, source, provides with correct types (baseline: none available programmatically).
• speckit-wizard-canvas parsePresetListOutput can be replaced with JSON.parse(stdout) (qualitative).
• Non-zero exit code + {"error": "..."} on stderr for failure cases, consistent with existing --json commands.

Cost of Inaction

The speckit-wizard-canvas regex parser remains the only way to query installed preset order programmatically. Any change to the text output of specify preset list silently breaks it. The gap between what the manifest/registry stores and what the CLI exposes grows wider as more fields (post-#4010) are added to manifests but not surfaced.

Open Questions

• [NEEDS CLARIFICATION: Should source ship as {"kind": "local" | "catalog"} now (with upgrade path for full provenance later), or block on the companion provenance issue?]
• [NEEDS CLARIFICATION: Does PresetManifest expose commands and scripts lists analogous to ExtensionManifest?]
• [NEEDS CLARIFICATION: Should author for extensions come from registry metadata or require adding an author property to ExtensionManifest?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4211 · 603.6 AIC · ⌖ 18.4 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — json-list-output · Stage 4/5: Concept

Concept: Add --json to preset list and extension list

• Slug: json-list-output
• Created: 2026-08-19
• Recommended option: Option A — Incremental --json flag with flat source

Options

Option A — Incremental --json flag with flat source

• Sketch: Add --json to preset list and extension list following the established typer.Option pattern (specify version --json, specify workflow run --json). Enrich list_installed() in both registries to include author, per-kind provides counts (computed from existing manifest.templates, manifest.scripts, manifest.commands, manifest.hooks), and a flat source object ({"kind": "local" | "catalog"}). The existing text output is unchanged. Array order matches the existing precedence sort. Errors go to stderr as {"error": "..."} with non-zero exit.
• Appetite: small (days — 1–2 weeks)
• Trade-offs: Wins — unblocks speckit-wizard-canvas, ships quickly, follows established pattern, no new dependencies. Sacrifices — source is flat (not full provenance); a schema bump will be needed when the companion provenance issue lands.
• Rabbit holes: Whether PresetManifest exposes commands and scripts lists (if not, those counts may need a small manifest change). Whether author for extensions needs a new ExtensionManifest.author property or can be read from registry metadata.

Option B — Full structured source (block on companion provenance issue)

• Sketch: Same as Option A, but wait for the "Record structured provenance" issue to land first, then ship --json with the full {"kind": "catalog", "catalog": "speckit-official"} source object.
• Appetite: medium (weeks — depends on provenance issue timeline)
• Trade-offs: Wins — ships the complete schema in one go, no schema evolution needed. Sacrifices — delays the fix for speckit-wizard-canvas by an unknown amount; the current pain is real and growing.
• Rabbit holes: Provenance issue timeline is unknown and outside this feature's control.

Option C — Do nothing (accept status quo)

• Sketch: Leave preset list and extension list as human-formatted only. Document the text format as a stable contract.
• Appetite: small (documentation only)
• Trade-offs: Wins — zero implementation risk. Sacrifices — speckit-wizard-canvas continues to regex-parse; the hidden data in list_installed() stays hidden.
• Rabbit holes: Real risk that text format diverges from the de-facto contract without notice.

Recommendation

Option A. The problem is real and codebase-verified: ExtensionManifest already exposes .templates and .scripts; the --json flag pattern is established across multiple commands; PresetManifest.author is available. The primary consumer (speckit-wizard-canvas) is in pain today and cannot wait on the companion provenance issue. Shipping with source: {"kind": "local" | "catalog"} as a flat fallback is honest about current state and provides a clear upgrade path. Option B delays needlessly; Option C accepts a fragile contract as permanent.

Out of Scope (for the recommended option)

• Full structured source with catalog name (deferred to companion provenance issue)
• --json on any commands other than preset list and extension list
• Removing or modifying the human-formatted text output
• Preset hooks field (presets do not contribute hooks)

Assumptions to Validate

• ExtensionManifest does not have an author property; author must be read from registry metadata in list_installed().
• PresetManifest does or can expose commands and scripts list counts.
• The flat source fallback is an acceptable stepping stone for speckit-wizard-canvas.
• The existing typer version supports adding --json alongside existing flags on extension list without conflict.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4211 · 603.6 AIC · ⌖ 18.4 AIC · ⊞ 38K · ◷

[github-actions]

Feature assessment — json-list-output · Stage 5/5: Decision — verdict go

Decision: Add --json to preset list and extension list

• Slug: json-list-output
• Decided: 2026-08-19
• Verdict: go
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Real, codebase-verified fragility: speckit-wizard-canvas explicitly regex-parses specify preset list stdout (documented in the file's own header). list_installed() in both registries provably omits fields (author, template/script counts) that already exist in the underlying manifest objects.
Evidence strength	adequate	The primary consumer pain is internally confirmed from two sources (issue body + referenced external repo). Secondary use cases (CI, external catalog UIs) are plausible assumptions without a confirmed consumer. Codebase evidence (missing fields, existing --json pattern) is high-confidence direct reads.
Value vs. inaction	strong	Cost of doing nothing is concrete: speckit-wizard-canvas regex parser breaks silently on any text format change; manifest fields added by #4010 are invisible on the read path. Implementation cost is small (follows established pattern, data already available).
Feasibility / appetite	strong	Established --json pattern exists in three places. ExtensionManifest.templates and .scripts are already accessible. PresetManifest.author exists. Option A is a small appetite with no new dependencies.
Strategic fit	strong	Machine-readable CLI output is a first-class concern for a toolkit that positions itself as automation-friendly. Consistent --json across commands is an explicit capability the project already invests in (version, workflow run).
Risk posture	strong	Key risks identified and mitigated: structured source deferred to flat fallback; author for extensions read from registry metadata; text output unchanged so no regressions. No serious unmitigated risk.

Verdict & Rationale

Go. Problem validity is strong (codebase-confirmed, not assumed), evidence strength is adequate (the primary consumer is internally verified), and a shaped concept with a small appetite exists that follows an established implementation pattern. All required scorecard gates pass. The one open dependency (structured source) is explicitly descoped with a safe fallback — it does not block the core value. The feature is bounded, low-risk, and directly unblocks a documented internal fragility.

If go — Handoff to /speckit-specify

• Problem: Consumers of specify preset list and specify extension list cannot query installed state programmatically; they are forced to regex-parse human-formatted text, and list_installed() in both registries omits author, per-kind artifact counts, and source that already exist in the underlying manifests/registry.
• Chosen approach: Option A — add --json flag to both commands following the established typer.Option pattern; enrich list_installed() in both registries to include author, provides object with per-kind counts, and a flat source: {"kind": "local" | "catalog"} fallback.
• In scope: specify preset list --json; specify extension list --json; list_installed() enrichment in both registries; author and provides counts; flat source fallback; non-zero exit + {"error": "..."} on stderr for failure; tests (JSON schema round-trip, count parity with text output, missing-field defaults, legacy registry read); CLI reference docs update.
• Out of scope: Structured source with catalog name (companion provenance issue); --json on other commands; text output changes; preset hooks field.
• Success metrics: Valid JSON array to stdout for both commands; each element has id, name, description, version, author, priority, enabled, source, provides with correct types; speckit-wizard-canvas parsePresetListOutput can be replaced by JSON.parse(stdout); non-zero exit on error.
• Carried-forward open questions:
  • [NEEDS CLARIFICATION: Does PresetManifest expose commands and scripts lists? If not, a small manifest addition may be required.]
  • [NEEDS CLARIFICATION: Should author for extensions be read from registry metadata dict or require adding ExtensionManifest.author property?]
  • [NEEDS CLARIFICATION: When the companion provenance issue lands, should source be upgraded in-place (minor schema bump) or via a new flag?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4211 · 603.6 AIC · ⌖ 18.4 AIC · ⊞ 38K · ◷