feat(template): drafts --json prints summaries, and its help says so

[CarmenDou]

What

With InsForge/instacloud-platform#650, GET /orgs/{orgId}/templates serves one summary per template, with no services, variables or publish requirements. insta template drafts --json prints that array as served, so its help now says so and names insta template draft <code> --json for one draft in full. The table reads only summary fields and is unchanged, so the released CLI keeps working. Release this after #650 is in production: against an older platform --json still prints full drafts, which the new help would misdescribe.

The agent-facing reference is updated in the same change set: InsForge/instacloud-skills#168 changes the template authoring row of insta/cli-reference.md to say template drafts --json returns one summary per template with no services, variables or publish requirements, and that template draft <code> --json reads one draft. Merge the two together, after #650 is in production.

How

• src/commands/template-author.ts: TemplateDraftSummary, the fields the table reads, types the list and draftListLines.
• src/index.ts: the drafts command's --json option describes the summaries.
• test/template-author.test.ts: the list tests use summary rows with every platform key, and a help test spawns template drafts --help.

Verify

• Before the source change, with the new tests: node node_modules/vitest/vitest.mjs run test/template-author.test.ts on Node 22 printed 1 failed | 63 passed. The failure was the help test, expected 'Usage: insta template drafts [options…' to contain 'one summary per template'. The list tests already passed with summary rows.
• After the change: the same command printed Tests 64 passed (64). After the review fixes (a key-set test for the summary fixture, and the help test checks the exit status): Tests 65 passed (65).
• npm run typecheck (tsc -p tsconfig.json --noEmit) on Node 22 printed no errors and exited 0.
• The vitest run that npm test runs, on Node 22: Test Files 102 passed (102), Tests 2115 passed (2115).

🤖 Generated with Claude Code

[cubic-dev-ai]

No issues found across 3 files

_{View guided diff | Turn on auto-fix | Re-trigger cubic}

[jwfing]

Summary

The implementation matches the described summary-response behavior, but the required agent-facing command-reference update is missing.

Requirements context

Intent was derived from the PR description and the repository’s contributor guidance. The linked platform PR #650 was not publicly accessible from this environment, so its contract could not be independently inspected; assessment of that contract relies on this PR’s description. The repository explicitly requires command and flag changes to be mirrored in InsForge/instacloud-skills/insta/cli-reference.md in the same change set (CONTRIBUTING.md:43-46).

Findings

Critical

• The changed template drafts --json output contract and help text are not mirrored in the agent-facing CLI reference. This PR now specifies that the option returns summaries without services, variables, or publish requirements (src/index.ts:584-587), while none of the changed files updates the required reference. Because the repository calls such a command/flag change “only half done” until the reference is updated in the same change set (CONTRIBUTING.md:43-46), add or link the corresponding InsForge/instacloud-skills update documenting the summary shape and directing agents to template draft <code> --json for full details.

Suggestion

(none)

Information

• Functionality and software engineering: the request remains a single API call, JSON is passed through unchanged, and table rendering uses only the summary fields it needs (src/commands/template-author.ts:27-28, src/commands/template-author.ts:68-74, src/commands/template-author.ts:203-208). Tests cover summary-shaped rows, exact JSON pass-through, help text, and successful help-command exit status (test/template-author.test.ts:115-128, test/template-author.test.ts:174-194, test/template-author.test.ts:622-631).
• Compatibility: older platforms may still return full drafts, which remain printable because the implementation does not filter runtime response properties; only the help becomes accurate after platform #650 is deployed (src/commands/template-author.ts:203-208, src/index.ts:584-587). Preserve the release ordering stated in the PR description.
• Security: no security-relevant changes were found. The PR adds no dependencies, inputs, authorization changes, shell interpolation, or new secret/PII output; the child process is test-only and uses fixed arguments (test/template-author.test.ts:622-631).
• Performance: no performance concerns were found. The implementation retains one HTTP request and the existing linear table/JSON rendering path (src/commands/template-author.ts:203-208).
• Verification: git diff --check main...HEAD passed. The required local gate could not run because dependencies are absent in the review checkout (tsc: not found); the configured gate remains tsc --noEmit followed by Vitest (package.json:35-40).

Verdict

Request changes: the missing command-reference synchronization is an explicit repository requirement and therefore blocking.

[jwfing]

Summary

The change correctly documents and tests the summary response while leaving table rendering and JSON pass-through behavior intact.

Requirements context

Intent was derived from the PR description, the repository’s CLI development guidance, and companion InsForge/instacloud-skills#168. The private platform PR #650 was not directly accessible, so its response contract was assessed from those sources: the list endpoint returns summary rows without services, variables, or publish requirements; the single-draft command remains the full-detail path. The documented merge order—platform #650 in production first, then this PR together with skills #168—is required to avoid temporarily inaccurate help and agent documentation.

Findings

Critical

(none)

Suggestion

• test/template-author.test.ts:625-625 — Pass an environment containing INSTA_NO_AUTOUPDATE=1 and INSTA_NO_TELEMETRY=1 to the spawned CLI, matching test/help-surface.test.ts. Importing src/index.ts invokes the update checker, which can inspect or update user-level state and spawn a detached process; disabling it keeps this help test isolated and deterministic.

Information

• src/commands/template-author.ts:27-28, src/commands/template-author.ts:203-208, test/template-author.test.ts:115-120, test/template-author.test.ts:189-193 — Software engineering and functionality look sound. The table is typed against exactly the fields it reads, the API response is still printed without transformation under --json, and tests cover the summary fixture, unchanged table rendering, JSON pass-through, and help text.
• src/index.ts:584-587, test/template-author.test.ts:622-631 — The help wording clearly explains the reduced list payload and points users to the full-draft command; the regression test checks both statements and the child exit status.
• src/commands/template-author.ts:203-208 — No security-relevant behavior changed: authentication, authorization, request paths, and input handling are untouched, and no dependency was added. The existing authenticated GET response continues to be emitted only when the user requests JSON.
• src/commands/template-author.ts:203-208 — No performance concerns: the change adds no requests, loops, blocking runtime I/O, or material allocations. The only new subprocess is test-only.

Verdict

Approved under the specified severity rule: there are no Critical findings. GitHub’s Linux and Windows test checks are green; local typechecking could not be repeated because this checkout has no installed tsc dependency.

[jwfing]

LGTM - approved.