[nrodd]

Chunk 8 of the test plan. Four files, 70 tests. No source changes.

Based on #42 (the harness). GitHub will retarget this to main when that merges. Independent of #43–#49.

Split by module rather than piled into one file:

File	Covers	Tests
promptReview.test.ts	the transparency gate and its loopback page	17
openAgent.test.ts	canOpenAgent, the osascript path, the copy offer	21
guides.test.ts	demo.ts + followUp.ts	20
logo.test.ts	colour degradation and showLogo	12

Two boundaries carry the weight

The prompt page is served to a browser

So the prompt is escaped — and the ampersand has to be escaped first, or < in a prompt comes back double-decoded. There's a test for that ordering specifically.

Also: choosing to read the prompt can never abort the run. A browser that won't open still reaches the confirm, the page is served on loopback only, 404s anything but /, and is torn down once the user answers.

osascript composes a shell command inside an AppleScript literal

cd '<dir>' && '<binary>' goes inside do script "…". The project directory is whatever path the user happens to be in, so both quoting layers are tested against a directory containing a single quote (/work/it's; rm -rf ~), a double quote, and a backslash — asserting the injected command never reaches an unquoted position.

The clipboard guard

On the app and manual paths the clipboard still holds an install prompt the user hasn't pasted yet. Reopening the editor must not force them to overwrite it, so the bundled "open and copy" offer degrades to a warned copy-only question instead. Easy to regress into silently clobbering, so it's pinned.

Plus the failure ladder: a decline copies nothing, a Ctrl+C returns without throwing, a clipboard error stops before opening the agent, and a launch that fails after a successful copy still reports the copy.

The guides

installPending flipping the lead line (a GUI handoff hasn't run yet; a terminal run that exited 0 without an install marker may have been refused — neither should present the snippet as live), the demo prompt going to the clipboard as a single line because some agents submit on a pasted newline, the prompt printing outside the note where the copy question can sit beside it, and --yes showing the guide but skipping the offer.

logo.ts

Only tested for degradation, since it's cosmetic: a window narrower than the art prints nothing at all rather than wrapping it into noise, no colour support emits no escape codes, non-TTY renders one static frame, and the animation always restores the cursor.

One note for review

demo.ts's header comment says the guide "never throws, because everything before it has already succeeded". It has no try/catch — the guarantee actually comes from offerCopyAndOpen swallowing clipboard and launch failures itself. True today, but it's an implied dependency rather than a local property. There's a test recording the real behaviour so it's visible; happy to add a try/catch instead if you'd rather the guarantee be local.

Verification

70 tests passing (123 on this branch), typecheck clean. Mutation-checked three security-relevant behaviours — removing the shell-quote escaping, removing the clipboardBusy guard, and removing HTML escaping — and confirmed exactly the right tests fail, then reverted.

---

Note

Low Risk
Test-only additions that document and guard existing UX/security behavior; no runtime behavior changes in this diff.

Overview
Adds four Vitest modules (~70 tests) with no production code changes, locking in post-install hand-off behavior split by area: promptReview, openAgent, demo/follow-up guides, and terminal logo rendering.

Prompt review tests pin HTML escaping (including ampersand-first ordering), a loopback-only page that 404s non-/, teardown after consent, and flows where choosing to read the prompt still proceeds if the browser fails—while explicit cancel/decline still aborts.

Open agent / copy offer tests cover side-effect-free canOpenAgent, Terminal.app osascript quoting for hostile project paths, the clipboardBusy downgrade (warned copy-only, no silent overwrite), and the failure ladder (decline, Ctrl+C, clipboard error before launch, launch failure after copy).

Closing guides assert install-pending vs complete messaging, single-line demo clipboard text, prompts printed outside clack notes, --yes skipping interactive offers, analytics events, and that showDemoGuide’s “never throws” claim currently depends on offerCopyAndOpen not rejecting.

Logo tests focus on graceful degradation: narrow terminals skip art, no ANSI without color, static frames when not animating, cursor restore when animating.

^{Reviewed by Cursor Bugbot for commit 3368aa8. Bugbot is set up for automated code reviews on this repo. Configure here.}