fix(update): no non-interactive path — crashes without a TTY, add --yes

[admarble]

Summary

sequant update has no usable non-interactive path. It is interactive-only and, without a TTY, dies with a raw ExitPromptError stack trace instead of a clean message. There is no --yes/-y flag.

Split out from #708 (which covers the two correctness bugs in the update/sync flow); this is the headless/ergonomics half.

Behavior

update always prompts Apply updates? (Y/n). Piping or running without a controlling TTY produces:

ExitPromptError: User force closed the prompt with 0 null
    at .../@inquirer/core/dist/lib/create-prompt.js:67:20
    ...
Node.js v23.11.0

i.e. an unhandled crash with a stack trace, not a graceful exit.

The only non-interactive alternative is sequant sync, but per #708 sync is version-marker-only and silently reports "up to date" on real content drift — so today there is no trustworthy non-interactive way to apply template updates. Current workaround is yes | sequant update, which is non-obvious.

Acceptance criteria

• sequant update --yes (and -y) applies updates without prompting.
• When stdin is not a TTY and --yes was not passed, update exits with a clear, actionable message (e.g. "non-interactive shell: re-run with --yes") — not an ExitPromptError stack trace.
• Docs/help make clear which command to use for automation (paired with the fix(update/sync): sync reports 'up to date' on content drift; update overwrites in-place customizations (constitution) #708 sync fix).

Notes

Lower priority than #708 — most users update via the Claude Code plugin's auto-update path; this bites CI/scripted/dogfooding flows.

[admarble]

→ PROCEED — Add non-interactive --yes/-y path; replace ExitPromptError crash with a clean message

Workflow: spec → exec → qa (-Q)

Clear ACs (3). Small but multi-surface: flag + TTY guard + graceful exit + docs. Touches bin/cli.ts — coordinate with #713 (also edits bin/cli.ts) to avoid a merge conflict.

[admarble]

Spec / Plan (Standard — 3 ACs)

Acceptance Criteria & verification

• AC-1 update --yes/-y applies updates without prompting — Integration Test
• AC-2 Non-TTY + no --yes → actionable message naming --yes, clean non-zero exit, no ExitPromptError — Integration Test
• AC-3 --help, cheat-sheet, troubleshooting document --yes + automation guidance — Manual/doc check

Plan

1. Add -y, --yes to the update command (bin/cli.ts:177) + UpdateOptions.yes.
2. nonInteractive = yes || force; guard both prompt sites — dev-URL (update.ts:108) and apply-confirm (update.ts:219).
3. When a prompt is needed but stdin is not a TTY and --yes absent → print actionable message, exit non-zero (no ExitPromptError throw).
4. Docs: cheat-sheet.md, troubleshooting.md, help text.

Key decisions

• Keep --yes (auto-answer) distinct from --force (overwrite local modifications). --yes must not imply force.
• Guard must cover the first-time dev-URL prompt too, not just apply-confirm — otherwise first-run-in-CI still crashes.
• Non-TTY guard exits non-zero so scripts can detect misuse.

Open questions

1. Confirm --yes ≠ --force semantics (recommended: keep distinct).
2. Confirm guard covers update.ts:108 (recommended: yes).
3. Exit code on non-TTY refusal (recommended: 1).

Coordination: #713 also edits bin/cli.ts — both worktrees currently empty; rebase whichever merges second.

Workflow: exec → qa (-Q, quality loop on).

[admarble]

Exec Progress Update

PR: #715 — created ✅

AC Coverage

AC	Description	Status	Evidence
AC-1	update --yes/-y applies without prompting	✅	bin/cli.ts flag + update.ts apply-confirm skip; E2E: echo "" | update --yes → "Updated 5 files", exit 0
AC-2	Non-TTY + no --yes → actionable message, clean non-zero exit, no ExitPromptError	✅	refuseNonInteractive() guards both prompt sites; E2E piped → message naming --yes + exit 1, no stack trace
AC-3	--help / cheat-sheet / troubleshooting document --yes + automation	✅	--help shows -y, --yes; docs/reference/cheat-sheet.md; docs/troubleshooting.md

Key files changed

• bin/cli.ts — register -y, --yes on update
• src/commands/update.ts — UpdateOptions.yes, refuseNonInteractive() TTY guard on both prompt sites
• src/commands/update.integration.test.ts — 3 new tests (AC-1, AC-2 apply-confirm + first-run guard)
• docs/reference/cheat-sheet.md, docs/troubleshooting.md, CHANGELOG.md

Checks

• npm run build ✅ · npm run lint ✅ (0 warnings) · vitest update.integration ✅ 5/5
• E2E smoke in temp-init'd project confirmed both AC-1 and AC-2 against the real CLI

CLI Wiring Self-Check

New Field	CLI Flag	Help Text	Status
yes	-y, --yes	"Apply updates without prompting (for CI/non-interactive shells)"	✅ Complete

Quality Plan Alignment

N/A — no Feature Quality Planning section in issue (Standard 3-AC spec).

Notes / coordination

Touches bin/cli.ts alongside #713 — single additive .option(); rebase whichever merges second.

[admarble]

QA Review for Issue #709

AC Coverage

AC	Source	Description	Status	Notes
AC-1	Original	update --yes/-y applies updates without prompting	MET	-y, --yes registered in bin/cli.ts; apply-confirm skipped when options.yes. Integration test AC-1 asserts inquirer.prompt not called + file written; E2E: echo "" | update --yes → "Updated 5 files", exit 0
AC-2	Original	Non-TTY + no --yes → actionable message naming --yes, clean non-zero exit, no ExitPromptError	MET	refuseNonInteractive() guards both prompt sites (dev-URL setup + apply-confirm), prints msg naming --yes, sets exitCode=1, returns (no throw). Tests AC-2 ×2; E2E piped → message + exit 1, no stack trace
AC-3	Original	--help, cheat-sheet, troubleshooting document --yes + automation	MET	--help shows -y, --yes; cheat-sheet.md (automation note + "when to use" row); troubleshooting.md (update crashes in CI section)

Coverage: 3/3 AC items fully met

---

CI Status

Check	State	Bucket	Impact
build (22.x)	SUCCESS	pass	✅ MET
typecheck	SUCCESS	pass	✅ MET
validate-skills	SUCCESS	pass	✅ MET
validate-plugin	SUCCESS	pass	✅ MET

CI Summary: 4 passed, 0 pending, 0 failed (waited for build matrix to complete)

---

Quality Metrics

Metric	Value	Status
Type issues (any)	0 new	OK
Deleted tests	0	OK
Files changed	6	OK
Lines added	+157	-
Lines deleted	-5	-

Local: npm run build ✅ · npm run lint ✅ (0 warnings) · vitest ✅ 42/42 (update.integration + tty + sync)

---

Test Coverage Analysis

Changed File	Tier	Has Tests?	Test File
src/commands/update.ts	Standard	✅ Yes	update.integration.test.ts (+3 tests)
bin/cli.ts	Standard	✅ Indirect	flag verified via --help + E2E

Coverage: Changed logic fully covered. New tests use save/restore of process.stdin.isTTY and process.exitCode — clean teardown, no global leakage.

---

Code Review

Strengths:

• Reuses the existing isStdinTTY() util rather than hand-rolling TTY detection.
• Both prompt sites guarded — the first-run dev-URL prompt (not just apply-confirm), which is the subtle case that would otherwise crash first-run-in-CI.
• --yes kept semantically distinct from --force (auto-answer vs. overwrite in-place customizations), exactly per the spec's key decision.
• process.exitCode = 1 + return matches the established sync.ts non-zero-exit pattern; no process.exit() hard-kill.

Issues: None blocking.

Suggestions (non-blocking, out of #709 scope):

• src/lib/wizard.ts also calls inquirer.prompt without a TTY guard. It's reached via init's setup flow (gated by --skip-setup/--yes), not by update, so it's outside this PR's blast radius. Worth a follow-up issue to confirm init's wizard degrades cleanly in non-TTY shells.

---

CLI Registration Verification

Interface Field	Runtime Usage	CLI Registered	Status
yes	options.yes (update.ts:115, :208)	-y, --yes in bin/cli.ts	✅ OK

Verification Status: Passed (flag confirmed in update --help)

---

Execution Evidence

Test Type	Command	Exit Code	Result
Non-TTY, no --yes	echo "" | sequant update	1	Clean message naming --yes, no ExitPromptError ✅
Non-TTY, --yes	echo "" | sequant update --yes	0	"Updated 5 files" ✅
Help	sequant update --help	0	Shows -y, --yes ✅

Evidence status: Complete

---

CHANGELOG Verification

Check	Status
CHANGELOG.md exists	✅ Found
User-facing changes	✅ Yes (fix(#709) commit)
[Unreleased] entry	✅ Present (### Added, references #709)
Entry format	✅ Valid (issue number included)

Result: CHANGELOG requirements met

---

Manual Test ACs

AC	Verification Method	Runtime Test Status	Evidence
AC-3	Manual/doc check	✅ Executed	grep confirmed --yes + automation guidance in --help, cheat-sheet, troubleshooting

AC-1 / AC-2 are integration-test ACs — executed (42/42 pass) and corroborated by E2E smoke.

---

Risk Assessment

• Likely failure mode: A non-TTY-but-interactive edge (stdin redirected from a file on an attached terminal) is treated as non-interactive and refuses without --yes — the safe direction (refuse, don't crash).
• Not tested: No automated test for the --dry-run + non-TTY interaction, but traced manually: a configured project returns at the dryRun guard before the apply-confirm site, so update --dry-run needs no --yes (no regression); a first-run non-TTY --dry-run now exits 1 cleanly instead of crashing (strict improvement).
• Sibling sites considered: src/lib/wizard.ts has an unguarded inquirer.prompt but is outside fix(update): no non-interactive path — crashes without a TTY, add --yes #709's blast radius (invoked by init, not update) — surfaced as a follow-up suggestion above, not widened into this PR.
• Sibling-line audit: Both inquirer.prompt call sites in update.ts (dev-URL setup line ~118, apply-confirm line ~208) are guarded by refuseNonInteractive() — no unguarded prompt remains in the file.

---

Adversarial Re-Read

Findings: No gaps found because: (1) ran the implementation against the issue body's verbatim repro — the piped-stdin ExitPromptError crash is now a clean message + exit 1 (E2E confirmed); (2) the "Updated 5 files" / exit-1 evidence is post-fix validation, not a pre-fix bug repro; (3) inspected process state — worktree clean, 0 commits behind main, change committed (55982b8) and pushed; (4) sibling sites cited explicitly — intra-file both prompt sites guarded, cross-file wizard.ts is out-of-blast-radius and filed as a suggestion; (5) checked Non-Goals — --yes stays distinct from --force, no scope creep into overwrite semantics.

Status: Clean

---

Verdict: READY_FOR_MERGE

All 3 ACs MET with literal verification, end-to-end execution evidence, full CI green, complete docs, and a CHANGELOG entry. Implementation is minimal, reuses existing utilities, and guards both prompt sites (including the easy-to-miss first-run dev-URL prompt). The only finding is an out-of-scope sibling (wizard.ts) appropriately deferred to a follow-up rather than widening this PR.

Documentation

• --help text added (-y, --yes)
• docs/ updated (cheat-sheet + troubleshooting)
• CHANGELOG entry added

Documentation: /docs 709 optional — the feature is already documented in cheat-sheet and troubleshooting.

Next Steps

1. Merge PR fix(#709): non-interactive update path — add --yes, replace ExitPromptError crash #715 (coordinate the one-line bin/cli.ts addition with fix(sync): areSkillsOutdated/checkAndWarnSkillsOutdated pre-flight is version-only — misses content drift (sibling of #708) #713 — trivial rebase).
2. Optional follow-up: confirm init's wizard.ts prompt degrades cleanly in non-TTY shells.

[admarble]

QA Review for Issue #709 (re-run, independent verification)

PR #715 · all 4 CI checks green · 5/5 integration tests pass · build clean.

AC Coverage

AC	Source	Description	Status	Notes
AC-1	Original	update --yes/-y applies updates without prompting	MET	-y, --yes registered in bin/cli.ts and surfaced in --help. Apply-confirm skipped when options.yes; applySet for --yes is newFiles + modifiedFiles (local-overrides stay protected — correctly distinct from --force). Test AC-1 asserts inquirer.prompt not called + file written + exit 0.
AC-2	Original	Non-TTY + no --yes → actionable message naming --yes, clean non-zero exit, no ExitPromptError	MET	refuseNonInteractive() guards both prompt sites (first-run dev-URL setup at L117 and apply-confirm at L210), prints a red/yellow message naming --yes, sets process.exitCode = 1, and returns — never reaches inquirer, so no throw. Tests AC-2 ×2 (apply-confirm + first-run guard) both pass.
AC-3	Original	--help / cheat-sheet / troubleshooting document --yes + automation	MET	--help shows -y, --yes …; docs/reference/cheat-sheet.md adds the --yes row + automation callout; docs/troubleshooting.md adds an "update crashes in CI / scripts" section; CHANGELOG [Unreleased] entry present.

Coverage: 3/3 AC items fully met (no derived ACs — standard spec).

Quality Metrics

Metric	Value	Status
Type issues (any)	0	OK
Deleted tests	0	OK
Files changed	6	OK
Lines added	+157	-
Lines deleted	-5	-

CI Status

Check	Conclusion	Impact
build (22.x)	SUCCESS	✅
typecheck	SUCCESS	✅
validate-skills	SUCCESS	✅
validate-plugin	SUCCESS	✅

CI Summary: 4 passed, 0 pending, 0 failed.

CLI Registration Verification

Field	Runtime Usage	CLI Registered	Status
yes	options.yes (update.ts L114, L209)	-y, --yes in bin/cli.ts	✅ OK

Status: Passed.

Code Review

Strengths:

• Both prompt sites guarded — no unguarded inquirer.prompt remains in update.ts (verified by grep).
• --yes (auto-answer) kept semantically distinct from --force (overwrite in-place customizations); local-overrides remain protected under --yes, matching the issue's explicit requirement.
• refuseNonInteractive() sets process.exitCode (not process.exit()), so the message flushes and the function returns cleanly — exactly the AC-2 "clean exit, not a crash" contract.
• Reuses the existing isStdinTTY() helper from src/lib/tty.ts rather than re-detecting TTY.

Issues: None.

Suggestions: None blocking. (Minor: the message names only --yes; --force is an intentional omission since it has different semantics.)

Execution Evidence

Test	Command	Result
Build	npm run build (tsc)	✅ exit 0
Tests	vitest run update.integration.test.ts	✅ 5/5 pass
Help	update --help	✅ shows -y, --yes
Smoke	printf '' | update --dry-run (non-TTY)	✅ no ExitPromptError

Self-Evaluation

• Verified working: Yes — built the worktree, ran the integration suite, exercised --help and a piped (non-TTY) invocation against the compiled CLI.
• Test efficacy: High — AC-2 tests assert process.exitCode === 1, no write, no prompt, and the message contains --yes; AC-1 asserts no-prompt + write under a TTY.
• Likely failure mode: A future third prompt added to update without a TTY guard — current diff covers both existing sites.
• Verdict confidence: High.

---

Verdict: READY_FOR_MERGE

All three ACs met literally, CI green, build + tests pass, CLI flag registered and reachable. Clean, well-scoped, well-tested change.

Documentation

• README/docs updated (cheat-sheet, troubleshooting)
• CHANGELOG entry added ([Unreleased] → Added)

Next Steps

1. Merge PR fix(#709): non-interactive update path — add --yes, replace ExitPromptError crash #715.