From dd4266dc4b5acb72772c32e4aec32835d659a094 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Nov 2026 07:19:24 +0800 Subject: [PATCH] Check each app build with an agent from another model family before its owner is asked to try it (GST-3025) (#4465) Adds `gstack-first-use`: before an app build reaches its owner as "ready to try", an agent from another model family plays that exact build, does the plan's first five day-one actions with a screenshot or video of each, and checks every link. Only then does it print the "try this build" message. Why: a recent app build passed every review and its owner still found the first screen broken, because nothing tried the build the way the owner would. Nothing to do now; the first real use is that app's next build. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/red-team#4 reader=red-team --- README.md | 1 + bin/gstack-doctor-components.sh | 6 + bin/gstack-first-use | 148 +++++++ capy/skill/gstack/captain.md | 8 + ...st-use-check-before-owner-tries-a-build.md | 1 + docs/first-use-check.md | 93 +++++ docs/troubleshooting.md | 30 ++ lib/first-use-message.ts | 115 ++++++ lib/first-use.ts | 324 +++++++++++++++ lib/result-codes-capy.ts | 30 ++ test/first-use.test.ts | 369 ++++++++++++++++++ test/fixtures/first-use/autoplan-plan.md | 25 ++ test/fixtures/first-use/one-page-plan.md | 17 + test/fixtures/first-use/play.json | 24 ++ test/helpers/free-fixtures-data.ts | 1 + 15 files changed, 1192 insertions(+) create mode 100755 bin/gstack-first-use create mode 100644 changelog.d/first-use-check-before-owner-tries-a-build.md create mode 100644 docs/first-use-check.md create mode 100644 lib/first-use-message.ts create mode 100644 lib/first-use.ts create mode 100644 test/first-use.test.ts create mode 100644 test/fixtures/first-use/autoplan-plan.md create mode 100644 test/fixtures/first-use/one-page-plan.md create mode 100644 test/fixtures/first-use/play.json diff --git a/README.md b/README.md index 59a4f1e74..d863952d2 100644 --- a/README.md +++ b/README.md @@ -272,6 +272,7 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file | [First Production Deploy](docs/howto-bring-up-a-first-deploy.md) | What to do when `/setup-deploy` says nothing is deployed yet: hosting, env and secrets, DNS, checking it works, then back to `/setup-deploy` | | [Land a fix in someone else's repo](docs/howto-land-a-fix-in-someone-elses-repo.md) | Read their rules, search for the same fix, run every guard their CI runs before opening, keep it small, answer each review point in a new commit | | [Run a human playtest](docs/howto-run-human-playtests.md) | Ask about moments and where people would stop, and why a back-to-back pick between two builds measures the order, not the build | +| [Check a build before its owner tries it](docs/first-use-check.md) | `gstack-first-use`: an agent from another model family plays the exact build cold, does the first five day-one actions with evidence, checks every link, and only then prints the "try this build" message | | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge | | [GBrain quick tour](docs/gbrain-quick-tour.md) | The four setup paths, MCP registration, the per-repo trust policy, memory sync, Conductor env vars | | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` | diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index ee78184e6..8226db504 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -410,6 +410,12 @@ gstack_result_anchor() { ARCHIVE_GH_READ_FAILED) printf '%s' 'archive-gh-read-failed' ;; ARCHIVE_PR_STATE_UNKNOWN) printf '%s' 'archive-pr-state-unknown' ;; ARCHIVE_POLICY_UNREADABLE) printf '%s' 'archive-policy-unreadable' ;; + FIRST_USE_PLAN_UNREADY) printf '%s' 'first-use-plan-unready' ;; + FIRST_USE_PLAY_SPEC_INCOMPLETE) printf '%s' 'first-use-play-spec-incomplete' ;; + FIRST_USE_SAME_FAMILY) printf '%s' 'first-use-same-family' ;; + FIRST_USE_NO_PRIVATE_DRIVE) printf '%s' 'first-use-no-private-drive' ;; + FIRST_USE_RECORD_INVALID) printf '%s' 'first-use-record-invalid' ;; + FIRST_USE_REFUSED) printf '%s' 'first-use-refused' ;; BUDGET_CAP_REACHED) printf '%s' 'budget-cap-reached' ;; BUDGET_READING_MISSING) printf '%s' 'budget-reading-missing' ;; METER_SCOPE_PARENT) printf '%s' 'meter-scope-parent' ;; diff --git a/bin/gstack-first-use b/bin/gstack-first-use new file mode 100755 index 000000000..55285ada7 --- /dev/null +++ b/bin/gstack-first-use @@ -0,0 +1,148 @@ +#!/usr/bin/env -S bun --no-env-file --config=/dev/null +/** + * gstack-first-use — the cold first-use check for an app build (docs/first-use-check.md). + * + * gstack-first-use start --app --plan --play --platform ios|android|web --commit + * (--testflight | --deploy ) --builder --checker [--json] + * gstack-first-use brief --run + * gstack-first-use record --run --action --verdict pass|fail --evidence --device --account --by [--note ] [--json] + * gstack-first-use predict --run --score <1-10> --why --by [--json] + * gstack-first-use links --run --account --device-class ios|android|web [--json] + * gstack-first-use check --run --platform … --commit … (--testflight … | --deploy …) [--json] + * gstack-first-use message --run --platform … --commit … (--testflight … | --deploy …) + * gstack-first-use score --run --score <1-10> --words "" --by [--json] + * gstack-first-use show --run [--json] + * gstack-first-use root + * + * start freezes the first five rows of the plan's ### Day one table and the build fingerprint into a + * write-once manifest; brief prints what the checker from the other model family gets; record, predict + * and links write its evidence, predicted score and dated link receipts; check prints FIRST_USE: pass + * or refuses (FIRST_USE_REFUSED); message prints the "try this build" text only when check passes; + * score keeps the owner's score and words beside the prediction. Records live in the owner's private + * user-level Capy Drive folder (GSTACK_FIRST_USE_DIR overrides). Logic: lib/first-use.ts. + */ +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { EXIT, exitTableHelp } from '../lib/headless-artifacts'; +import { buildLabel, checkLinks, decide, ownerScore, predict, readManifest, recordResult, recordRoot, startRun, type BuildId, type FirstUseError } from '../lib/first-use'; +import { renderBrief, renderPlayMessage } from '../lib/first-use-message'; +import { resultLine } from '../lib/result-codes'; + +const HELP = `gstack-first-use — a cold first-use check on an app build before its owner tries it (docs/first-use-check.md) + + start --app --plan --play --platform ios|android|web --commit + (--testflight | --deploy ) --builder --checker [--json] + brief --run what the checker from the other model family is given + record --run --action --verdict pass|fail --evidence --device --account --by [--note ] + predict --run --score <1-10> --why --by + links --run --account --device-class ios|android|web check every play link now, as the owner-equivalent audience + check --run --platform … --commit … (--testflight … | --deploy …) FIRST_USE: pass, or refused + message --run --platform … --commit … (--testflight … | --deploy …) the "try this build" text, only after a pass + score --run --score <1-10> --words "" --by + show --run [--json] + root where records live + +${exitTableHelp()}`; + +const flag = (args: string[], name: string) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }; +const say = (line: string) => process.stdout.write(line + '\n'); +const refuse = (cmd: string, e: FirstUseError) => { process.stderr.write(resultLine(`gstack-first-use ${cmd}`, e.code, e.detail) + '\n'); return e.code === 'FIRST_USE_RECORD_INVALID' ? EXIT.fail : EXIT.refused; }; +const buildArgs = (a: string[]): Partial => ({ platform: flag(a, '--platform') as BuildId['platform'], commit: flag(a, '--commit'), testflight: flag(a, '--testflight'), deploy: flag(a, '--deploy') }); + +/** The --run directory, which must sit inside the record root so evidence and scores stay in the private record. */ +function runDir(cmd: string, a: string[]): string | number { + const run = flag(a, '--run'); + if (!run) { process.stderr.write(`gstack-first-use: ${cmd} needs --run \n`); return EXIT.usage; } + const root = recordRoot(); + if ('error' in root) return refuse(cmd, root.error); + let real: string, realRoot: string; + try { real = fs.realpathSync(run); realRoot = fs.realpathSync(root.root); } catch { return refuse(cmd, { code: 'FIRST_USE_RECORD_INVALID', detail: `no run directory at ${run}` }); } + if (!real.startsWith(realRoot + path.sep)) return refuse(cmd, { code: 'FIRST_USE_RECORD_INVALID', detail: `${run} is outside the record root ${root.root}` }); + return real; +} + +function cmdStart(a: string[], json: boolean): number { + const need = ['--app', '--plan', '--play', '--platform', '--commit', '--builder', '--checker'].filter(f => !flag(a, f)); + if (need.length) { process.stderr.write(`gstack-first-use: start needs ${need.join(', ')}\n`); return EXIT.usage; } + const root = recordRoot(); + if ('error' in root) return refuse('start', root.error); + let play: unknown; + try { play = JSON.parse(fs.readFileSync(flag(a, '--play')!, 'utf8')); } catch { return refuse('start', { code: 'FIRST_USE_PLAY_SPEC_INCOMPLETE', detail: `${flag(a, '--play')} is not a readable JSON play spec` }); } + const r = startRun({ root: root.root, app: flag(a, '--app')!, planPath: flag(a, '--plan')!, build: buildArgs(a), play, builder: flag(a, '--builder')!, checker: flag(a, '--checker')! }); + if ('error' in r) return refuse('start', r.error); + if (json) { say(JSON.stringify({ run: r.dir, actions: r.manifest.actions.length, rows_sha256: r.manifest.source.rows_sha256, build: r.manifest.build })); return EXIT.ok; } + say(`FIRST_USE_RUN: ${r.dir}`); + say(`FIRST_USE_FROZEN: ${r.manifest.actions.length} actions rows=${r.manifest.source.rows_sha256.slice(0, 12)} build=${buildLabel(r.manifest.build)} checker=${r.manifest.checker.model}`); + r.manifest.actions.forEach(x => say(` ${x.n}. ${x.action}`)); + say(`NEXT: gstack-first-use brief --run "${r.dir}" (give it to one fresh agent on ${r.manifest.checker.model}, never a ${r.manifest.builder.family} model)`); + return EXIT.ok; +} + +function cmdShow(dir: string, json: boolean): number { + const read = readManifest(dir); + if ('error' in read) return refuse('show', read.error); + const m = read.manifest; + const d = decide(dir, m.build); + const summary = { app: m.app, build: buildLabel(m.build), checker: m.checker.model, actions: m.actions.length, passed: d.passed, reasons: d.reasons, + predicted: d.prediction?.score ?? null, owner: d.owner ? { score: d.owner.score, words: d.owner.words, at: d.owner.at } : null, + gap: d.prediction && d.owner ? d.owner.score - d.prediction.score : null }; + if (json) { say(JSON.stringify(summary)); return EXIT.ok; } + say(`FIRST_USE_SHOW: app=${m.app} build=${summary.build} passed=${d.passed}/${m.actions.length} predicted=${summary.predicted ?? 'none'} owner=${summary.owner?.score ?? 'none'}${summary.gap === null ? '' : ` gap=${summary.gap > 0 ? '+' : ''}${summary.gap}`}`); + if (summary.owner) say(`OWNER_WORDS: ${summary.owner.words}`); + for (const r of d.reasons) say(`OPEN: ${r}`); + return EXIT.ok; +} + +async function main(argv: string[]): Promise { + const [cmd, ...a] = argv; + if (!cmd || cmd === '--help' || cmd === '-h') { say(HELP); return cmd ? EXIT.ok : EXIT.usage; } + const json = a.includes('--json'); + if (cmd === 'root') { const r = recordRoot(); if ('error' in r) return refuse('root', r.error); say(`FIRST_USE_ROOT: ${r.root}`); return EXIT.ok; } + if (cmd === 'start') return cmdStart(a, json); + if (!['brief', 'record', 'predict', 'links', 'check', 'message', 'score', 'show'].includes(cmd)) { process.stderr.write(`gstack-first-use: unknown command ${cmd}\n${HELP}\n`); return EXIT.usage; } + const dir = runDir(cmd, a); + if (typeof dir === 'number') return dir; + if (cmd === 'show') return cmdShow(dir, json); + if (cmd === 'brief') { + const read = readManifest(dir); + if ('error' in read) return refuse(cmd, read.error); + process.stdout.write(renderBrief(read.manifest, dir)); + process.stderr.write(`DISPATCH: give this brief, and nothing else about the build, to one fresh agent on ${read.manifest.checker.model} (not a ${read.manifest.builder.family} model) on its own machine; it runs its own gstack install check first\n`); + return EXIT.ok; + } + if (cmd === 'record') { + const n = Number(flag(a, '--action')); + const r = recordResult({ dir, action: Number.isInteger(n) ? n : -1, verdict: flag(a, '--verdict') ?? '', evidence: flag(a, '--evidence') ?? '', device: flag(a, '--device') ?? '', account: flag(a, '--account') ?? '', by: flag(a, '--by') ?? '', note: flag(a, '--note') }); + if ('error' in r) return refuse(cmd, r.error); + say(json ? JSON.stringify(r.result) : `FIRST_USE_RESULT: action=${r.result.action} verdict=${r.result.verdict} evidence=${r.result.evidence.file} sha256=${r.result.evidence.sha256.slice(0, 12)}`); + return EXIT.ok; + } + if (cmd === 'predict') { + const r = predict({ dir, score: flag(a, '--score') ?? '', why: flag(a, '--why') ?? '', by: flag(a, '--by') ?? '' }); + if ('error' in r) return refuse(cmd, r.error); + say(json ? JSON.stringify(r.prediction) : `FIRST_USE_PREDICTED: ${r.prediction.score} (${r.prediction.by.model})`); + return EXIT.ok; + } + if (cmd === 'score') { + const r = ownerScore({ dir, score: flag(a, '--score') ?? '', words: flag(a, '--words') ?? '', by: flag(a, '--by') ?? '' }); + if ('error' in r) return refuse(cmd, r.error); + say(json ? JSON.stringify({ score: r.owner.score, at: r.owner.at }) : `FIRST_USE_OWNER_SCORE: ${r.owner.score} recorded in the private record`); + return EXIT.ok; + } + if (cmd === 'links') { + const r = await checkLinks(dir, { account: flag(a, '--account'), device_class: flag(a, '--device-class') as BuildId['platform'] }); + if ('error' in r) return refuse(cmd, r.error); + if (json) say(JSON.stringify(r.receipts)); + else r.receipts.forEach(x => say(`LINK: ${x.verdict} status=${x.status || x.error || 'none'} as=${x.audience.device_class} ${x.url}`)); + return r.receipts.every(x => x.verdict === 'live') ? EXIT.ok : EXIT.fail; + } + const d = decide(dir, buildArgs(a)); + if (!d.ok) return refuse(cmd, { code: 'FIRST_USE_REFUSED', detail: d.reasons.join('; ') }); + if (cmd === 'message') { process.stdout.write(renderPlayMessage(d)); return EXIT.ok; } + const m = d.manifest!; + say(json ? JSON.stringify({ ok: true, app: m.app, build: m.build, passed: d.passed, links: d.links.length, predicted: d.prediction?.score }) + : `FIRST_USE: pass app=${m.app} build=${buildLabel(m.build)} actions=${d.passed}/${m.actions.length} links=${d.links.length}/${m.play.links.length} checker=${m.checker.model} predicted=${d.prediction?.score}`); + return EXIT.ok; +} + +process.exit(await main(process.argv.slice(2))); diff --git a/capy/skill/gstack/captain.md b/capy/skill/gstack/captain.md index 0e9374902..6287ee0ea 100644 --- a/capy/skill/gstack/captain.md +++ b/capy/skill/gstack/captain.md @@ -170,3 +170,11 @@ take every reading (start, notes, close) from its own row of the root thread's ` reason=budget_exhausted`, `status=incomplete`), the lane reports the BUDGET and RECOVER lines and asks the owner; it never raises the cap itself. The owner's answer runs the RECOVER line with `--approved-by --words ""`, and `gstack-approvals add` records the same words. + +## 5. Asks to try a build + +An ask for the owner to try an app build, and any "v1 is ready" report, goes out only after the build clears +`gstack-first-use` (`docs/first-use-check.md` in the checkout): an agent from another model family plays that exact +build cold on the same kind of device and does the plan's first five day-one actions, with a screenshot or video of +each. Send the text `gstack-first-use message` prints, unchanged; when it refuses, fix the build and replay instead of +asking. Record the owner's score and words with `gstack-first-use score`, never in a PR or the repository. diff --git a/changelog.d/first-use-check-before-owner-tries-a-build.md b/changelog.d/first-use-check-before-owner-tries-a-build.md new file mode 100644 index 000000000..38a83b8e1 --- /dev/null +++ b/changelog.d/first-use-check-before-owner-tries-a-build.md @@ -0,0 +1 @@ +- **A cold first-use check before an app build reaches its owner (GST-3025).** New `gstack-first-use` freezes the first five day-one actions from the plan and the exact build, has an agent from another model family play that build on the same kind of device with a screenshot or video for each action, checks every link within 15 minutes of sending, and prints the "try this build" message only when all of it passes. The owner's score and words are kept beside the checker's predicted score in the owner's private drive. See `docs/first-use-check.md`. diff --git a/docs/first-use-check.md b/docs/first-use-check.md new file mode 100644 index 000000000..467bf40b5 --- /dev/null +++ b/docs/first-use-check.md @@ -0,0 +1,93 @@ +# Check an app build before its owner tries it + +When an agent builds an app for someone, every review can pass and the first thing the owner taps can still be broken. `gstack-first-use` closes that gap. Before a build reaches its owner as "ready to try", a fresh agent from a **different model family** than the one that built it plays that exact build cold, on the same kind of device and account the owner uses. It does the first five things the plan says the owner will do on day one, saves a screenshot or short video of each, checks that every link in the message is live, and predicts the owner's score from 1 to 10. Only when all of that passes does the tool print the "try this build" message. + +It gates two things: the message that asks the owner to try a build, and any "v1 is ready" report. It does not gate `/ship`: code review and the first-use check answer different questions. + +## The steps + +Run these from the thread that owns the build (on Capy, a Captain or the agent building the app). + +1. **Freeze the five actions and the build.** + + ```bash + gstack-first-use start --app plantpal --plan plan.md --play play.json \ + --platform ios --commit --testflight 17 \ + --builder anthropic/claude-opus-5-5 --checker openai/gpt-6.2-sol + ``` + + It reads the first five rows of the plan's day-one table, records their hash, the play spec and the build fingerprint (the commit plus the TestFlight build number, or `--deploy ` for a web or Android build) in a write-once `manifest.json`, and prints `FIRST_USE_RUN: `. It refuses when the table is missing or malformed, has fewer than five rows, has an empty cell in its first five rows or still has a row marked `assumed` among them, when the play spec misses a part, or when the checker's model family is the builder's. + +2. **Hand the checker its brief.** `gstack-first-use brief --run ` prints everything the checker gets: the device and account, the play text, and the five frozen actions with the commands to record each. Give it to one fresh agent on the `--checker` model and nothing else about the build: no plan, no code, no notes. Every value the brief puts into a command is shell-quoted, so the checker can paste the lines as they are. On Capy, start a subagent with that model on `machine: "fresh"`; it attaches a cloud phone with `tools.capy.phone` (`attach`, then `install` with the build from `tools.mobile.build`) and drives the screen with `tools.capy.computer`, or opens a web build in the browser. It runs its own gstack install check first. + +3. **The checker records each action and predicts the score.** + + ```bash + gstack-first-use record --run --action 1 --verdict pass --evidence today.png \ + --device "iPhone 17 Pro (cloud)" --account "fresh Apple ID" --by openai/gpt-6.2-sol + gstack-first-use predict --run --score 6 --why "reminders work, adding plants is slow" --by openai/gpt-6.2-sol + ``` + + The evidence file (PNG, JPEG, GIF, WebP, HEIC, MP4, MOV or WebM, up to 100 MB) is copied into the run and recorded with its hash and size. A fail needs `--note` saying what happened. Only the checker's family may record, and `--account` must be the play spec's owner-equivalent account exactly (the brief prints it), so a pass on a developer or admin account doesn't count. Replaying an action adds a new result; the newest one counts. + +4. **Check the links right before sending.** `gstack-first-use links --run --account "" --device-class ios` opens every link in the play spec and writes a dated receipt for each, bound to that audience: the owner-equivalent account and the build's device class. It refuses any other audience, and the gate counts only receipts for this one. A link passes on a 2xx or 3xx answer. A 401 or 403 passes only when the play spec marks the link `"login_gated": true`. The request itself carries no sign-in, so for a login-gated link the receipt proves the link is up and gated; the checker's played results on that account prove the sign-in works. + +5. **Print the message.** `gstack-first-use message --run --platform ios --commit --testflight 17` prints the "try this build" text only when every check below passes, and refuses otherwise, printing nothing on stdout. Send that text as it is. For a "v1 is ready" report, run `gstack-first-use check` with the same flags and paste its `FIRST_USE: pass …` line. + +6. **Save the owner's reaction.** When the owner replies, `gstack-first-use score --run --score 4 --words "4, Talk is slow" --by ""`. `gstack-first-use show --run ` prints the predicted score, the owner's score and words, and the gap between them. + +## What the gate refuses + +`check` and `message` pass only when all of these hold. Each failure is listed in the `FIRST_USE_REFUSED` line ([troubleshooting](troubleshooting.md#first-use-refused)). + +- The build you're about to send is the one that was checked (`build_mismatch`). +- The plan's first five day-one rows haven't changed since `start` (`source_changed`, `source_missing`). An edit elsewhere in the plan doesn't count. +- Every frozen action's newest result, from the checker's family on the owner-equivalent account, is a pass, and its evidence file still matches its hash (`action__not_played`, `action__failed`, `action__evidence_stale`). +- Every link has a live receipt from the last 15 minutes, checked as the owner-equivalent account and device class (`link_unchecked`, `link_down`, `link_stale`). +- The checker predicted a score (`no_predicted_score`). + +The message never shows the predicted score, so it can't anchor the owner's own. + +## The day-one table + +Both kinds of plan feed the check in one format: the day-one table that `/autoplan` puts on the plan-approval page, and the one-page list of the first five things the owner does on day one. Either one needs a heading named `Day one` (any level; `Day-one page` also works) followed by a table with these seven columns, in any order: + +| action | frequency | source | feature | route | first build | check | +|---|---|---|---|---|---|---| +| sees which plant needs water today | daily | owner words 1 | Today list | root screen | build 1 | the plant due today is at the top, marked due | + +The table needs at least five rows, and every cell of the first five needs a value; the check freezes those five in table order. A row whose source starts with `assumed` must be confirmed with the owner before `start` will freeze it. `test/first-use.test.ts` pins this format with one fixture of each kind, so a change to the table parser fails that test instead of quietly changing what gets checked. + + +## Play-message requirements + +Every ask to play or try a build carries full play instructions in the same message (the factory's play-instructions rule, R47). The play spec is a JSON file with one field per part, and `start` refuses one that's missing any: + +| Part | Field | Notes | +|---|---|---| +| 1. The links | `links`: `[{ "label", "url", "login_gated"? }]` | http or https; each checked live within 15 minutes of sending | +| 2. Device and setup | `device`, `setup`, `account` | the owner's device kind and account kind; the checker plays on the same kind, and results and link receipts are bound to `account` and the build's platform | +| 3. What it is, in a sentence | `what` | | +| 4. How to start | `start` | | +| 5. Controls | `controls` | | +| 6. How long to play | `minutes` | a whole number from 1 to 240 | +| 7. What we want to learn | `learn` | | +| 8. How to report back | `report` | the message adds "a score from 1 to 10 and one line" | +| 9. Known quirks | `quirks` | "none" is fine; empty isn't | +| 10. Reply word | `reply_word` | one word | + +## Where the record lives + +The record holds the owner's own scores and words, so it stays private. On Capy it lives in the owner's user-level Capy Drive folder (`~/.capy/drive/user-*/first-use///`), which every thread the owner has opened can read and nobody else's can. If none or several such folders are mounted, the tool refuses rather than fall back to the machine's throwaway folder. Off Capy it lives under the gstack state root (`first-use/`). `GSTACK_FIRST_USE_DIR` overrides both. Nothing from a run belongs in a public repository or a PR body. + +A run directory holds `manifest.json`, `results/`, `evidence/`, `links/`, `prediction.json` and `owner/`. Every file is written once; to check again (a new build, changed day-one rows, a new prediction), start a new run. + +## How we'll know it helps + +With a handful of builds, this is a case series, not an eval. For each build, keep the pass count, the owner's score and words, the predicted score, and any escape: a day-one action that failed on the owner's device after the check passed it. The targets are zero escapes and a median owner score of 7 or more across the next three app builds. `gstack-first-use show --json` prints each run's numbers. + +## What it doesn't do yet + +- It doesn't drive the owner's own phone; it plays on a cloud device of the same kind. +- It doesn't dispatch the checker by itself; the thread that owns the build starts it with the brief. +- It doesn't check the wording of other messages sent to the owner. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3da9afc66..ee35ecf7b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2405,6 +2405,36 @@ whose Plan line differs from the PR body's current line. **Fix.** The lane fixes the PR body's Plan line if needed and reruns `gstack-ship-queue ready --pr ` at the pin. + +### `gstack-first-use start: ... (FIRST_USE_PLAN_UNREADY)` + +**Meaning.** `start` could not freeze the day-one actions: the plan has no `### Day one` table, the table is missing a column or has fewer than five rows, one of its first five rows has an empty cell, or one of them is still marked `assumed`. Exit 3; nothing is written. **Fix.** Give the plan the pinned table ([first-use-check.md](first-use-check.md#the-day-one-table)) and confirm every assumed row with the owner, then rerun `start`. + + +### `gstack-first-use start: ... (FIRST_USE_PLAY_SPEC_INCOMPLETE)` + +**Meaning.** The play spec JSON misses one of the ten parts every ask to play or try a build carries (links, device and setup, what it is, how to start, controls, how long, what we want to learn, how to report back, known quirks, reply word). The line names each missing part and field. Exit 3. **Fix.** Fill them in ([first-use-check.md](first-use-check.md#play-spec)); "none" is a fine value for known quirks. + + +### `gstack-first-use start|record|predict: ... (FIRST_USE_SAME_FAMILY)` + +**Meaning.** The check needs an agent from a different model family than the one that built the app. The builder and checker are the same family, a family could not be read from the model id, or `--by` on a result or prediction is not the run's checker family. Exit 3. **Fix.** Pass full `provider/model` ids from different families, and let only the checker record results. + + +### `gstack-first-use: ... (FIRST_USE_NO_PRIVATE_DRIVE)` + +**Meaning.** On Capy the record holds the owner's scores and words, so it lives only in his private user-level drive folder. None or several `~/.capy/drive/user-*` folders are mounted, so the tool refuses rather than writing to the machine's throwaway folder. Exit 3. **Fix.** Run it in a thread the owner owns, or set `GSTACK_FIRST_USE_DIR` to his private folder. + + +### `gstack-first-use: ... (FIRST_USE_RECORD_INVALID)` + +**Meaning.** A value or file is invalid: a bad `--commit`, `--action`, `--verdict` or score, an `--account` or `--device-class` that isn't the run's owner-equivalent audience, a run directory outside the record root, evidence that is not a screenshot or short video (or is empty, a link, or over 100 MB), an unreadable manifest, or a second prediction on a run. Exit 1. **Fix.** Correct the value. Run files are written once; to redo a check, start a new run. + + +### `gstack-first-use check|message: ... (FIRST_USE_REFUSED)` + +**Meaning.** The build has not cleared its first-use check, so `message` prints no "try this build" text and `check` prints no `FIRST_USE: pass` line. The detail lists every reason: `build_mismatch`, `source_changed`, `source_missing`, `action__not_played`, `action__failed`, `action__evidence_stale`, `link_unchecked`, `link_down`, `link_stale` (over 15 minutes old), `no_predicted_score`, `record_unreadable`. Exit 3. **Fix.** Fix the build and replay failed actions, rerun `links` right before sending, or start a new run for a new build or changed day-one rows. + ## /ship token budget and fresh-context handoffs (gstack-ship-budget) The flow, the BUDGET line field by field and the meters are in [ship-budget.md](ship-budget.md). diff --git a/lib/first-use-message.ts b/lib/first-use-message.ts new file mode 100644 index 000000000..151d7b4c0 --- /dev/null +++ b/lib/first-use-message.ts @@ -0,0 +1,115 @@ +/** + * first-use-message — the play spec and the two texts the first-use check prints + * (docs/first-use-check.md). The play spec holds the ten parts every ask to play + * or try a build carries (the factory's R47): the links, the device and setup, + * what it is, how to start, the controls, how long, what we want to learn, how + * to report back, known quirks and the reply word. renderPlayMessage() is the + * only "try this build" text, printed after decide() passes; renderBrief() is + * what the cold checker from the other model family is given, and nothing more. + */ +import { buildLabel, type Decision, type FirstUseError, type Manifest } from './first-use'; + +export interface PlayLink { url: string; label: string; login_gated?: boolean } +export interface PlaySpec { + links: PlayLink[]; device: string; setup: string; account: string; what: string; start: string; + controls: string; minutes: number; learn: string; report: string; quirks: string; reply_word: string; +} +/** R47's ten parts in order, with the play-spec fields each one reads. */ +export const PLAY_PARTS: Array<{ part: string; fields: Array }> = [ + { part: 'The links, each checked live minutes before sending', fields: ['links'] }, + { part: 'Device and setup', fields: ['device', 'setup', 'account'] }, + { part: 'What it is, in a sentence', fields: ['what'] }, + { part: 'How to start', fields: ['start'] }, + { part: 'Controls', fields: ['controls'] }, + { part: 'How long to play', fields: ['minutes'] }, + { part: 'What we want to learn', fields: ['learn'] }, + { part: 'How to report back', fields: ['report'] }, + { part: 'Known quirks', fields: ['quirks'] }, + { part: 'Reply word', fields: ['reply_word'] }, +]; +const TEXT_FIELDS = ['device', 'setup', 'account', 'what', 'start', 'controls', 'learn', 'report', 'quirks', 'reply_word'] as const; + +/** A complete play spec, or the R47 parts it is missing. "none" is a fine answer for quirks; an empty field is not. */ +export function checkPlaySpec(raw: unknown): { spec: PlaySpec } | { error: FirstUseError } { + const o = (raw && typeof raw === 'object' ? raw : {}) as Record; + const bad = new Set(); + for (const f of TEXT_FIELDS) if (typeof o[f] !== 'string' || !(o[f] as string).trim()) bad.add(f); + if (typeof o.reply_word === 'string' && !/^[A-Za-z][A-Za-z0-9-]{0,23}$/.test(o.reply_word.trim())) bad.add('reply_word'); + if (!Number.isInteger(o.minutes) || (o.minutes as number) < 1 || (o.minutes as number) > 240) bad.add('minutes'); + const links = Array.isArray(o.links) ? o.links as Array> : []; + const linkOk = (l: Record) => typeof l?.label === 'string' && !!l.label.trim() && typeof l.url === 'string' && /^https?:\/\/[^\s]+$/.test(l.url) + && (l.login_gated === undefined || typeof l.login_gated === 'boolean'); + if (!links.length || !links.every(linkOk)) bad.add('links'); + if (bad.size) { + const parts = PLAY_PARTS.filter(p => p.fields.some(f => bad.has(f))).map(p => `${p.part} (${p.fields.filter(f => bad.has(f)).join(', ')})`); + return { error: { code: 'FIRST_USE_PLAY_SPEC_INCOMPLETE', detail: `missing or invalid: ${parts.join('; ')}` } }; + } + const spec: PlaySpec = { + links: links.map(l => ({ url: l.url as string, label: (l.label as string).trim(), ...(l.login_gated ? { login_gated: true } : {}) })), + minutes: o.minutes as number, + ...Object.fromEntries(TEXT_FIELDS.map(f => [f, (o[f] as string).trim()])) as Omit, + }; + return { spec }; +} + +const hhmm = (iso: string) => iso.slice(11, 16); +const platformName = { ios: 'iOS', android: 'Android', web: 'web' } as const; + +/** The "try this build" message: R47's ten parts, then what the cold check covered. Call only after decide() passed. */ +export function renderPlayMessage(d: Decision, now: Date = new Date()): string { + const m = d.manifest!, p = m.play; + const checked = d.links.map(l => Date.parse(l.checked_at)); + const oldest = Math.min(...checked); + const ago = Math.max(0, Math.round((now.getTime() - oldest) / 60_000)); + return [ + `**Try ${m.app}: ${buildLabel(m.build)}**`, '', + `1. **Links** (each checked live at ${new Date(oldest).toISOString().slice(11, 16)} UTC, ${ago} min before this message):`, + ...p.links.map(l => ` - [${l.label}](${l.url})${l.login_gated ? ' (asks you to sign in)' : ''}`), + `2. **Device and setup:** ${p.device}. ${p.setup} Account: ${p.account}.`, + `3. **What it is:** ${p.what}`, + `4. **How to start:** ${p.start}`, + `5. **Controls:** ${p.controls}`, + `6. **How long:** about ${p.minutes} minutes.`, + `7. **What we want to learn:** ${p.learn}`, + `8. **How to report back:** ${p.report} Give it a score from 1 to 10 and one line on what stood out.`, + `9. **Known quirks:** ${p.quirks}`, + `10. **Reply word:** ${p.reply_word}, then your score and your line, for example "${p.reply_word} 7, the first screen was slow".`, + '', + `Checked before it reached you: an agent from another model family (${m.checker.model}) played this exact build cold on a ${platformName[m.build.platform]} cloud device and did the first ${m.actions.length} things you'll do on day one. All ${d.passed} worked, with a screenshot or video of each:`, + ...m.actions.map(a => `- ${a.action}`), + '', + ].join('\n'); +} + +/** One POSIX shell word: single quotes, with each embedded single quote closed, escaped and reopened. */ +export const shellQuote = (v: string) => `'${v.replace(/'/g, `'\\''`)}'`; + +/** What the cold checker is given: the build, the device and account, the play message parts and the frozen actions, with the commands that record each. */ +export function renderBrief(m: Manifest, dir: string): string { + const p = m.play, b = m.build; + const install = b.platform === 'web' + ? 'open the first link in a browser on that device' + : `attach a ${platformName[b.platform]} phone (\`tools.capy.phone\` with action "attach", platform "${b.platform}" and the model closest to the device above), install this exact build on it (action "install"; ${b.testflight ? `TestFlight build ${b.testflight}` : `version ${b.deploy}`}), and drive its screen with \`tools.capy.computer.on({ machine_id })\``; + const by = `--by ${shellQuote(m.checker.model)}`, run = `--run ${shellQuote(dir)}`; + return [ + `# Cold first-use check: ${m.app}, ${buildLabel(b)}`, '', + `You are playing this build for the first time, as its owner will. You run on ${m.checker.model}; the team that built it runs on ${m.builder.family} models, and you have not seen its plan, code, notes or messages. Do not read them: you get only what the owner gets, below.`, '', + '## Device and account', '', + `Use the same kind of device and account as the owner: ${p.device}. ${p.setup} Account: ${p.account} (play only on this kind of account; \`record\` takes it exactly). On Capy, ${install}.`, '', + '## What the owner is told', '', + `- What it is: ${p.what}`, `- Links: ${p.links.map(l => `${l.label} ${l.url}`).join('; ')}`, `- How to start: ${p.start}`, `- Controls: ${p.controls}`, + `- How long: about ${p.minutes} minutes`, `- Known quirks: ${p.quirks}`, '', + `## The ${m.actions.length} things the owner will do on day one (frozen ${m.created_at.slice(0, 10)})`, '', + ...m.actions.map(a => `${a.n}. ${a.action} (${a.frequency || 'how often unstated'}). Way in: ${a.route || 'not stated'}. It works when: ${a.check}`), '', + '## What to do', '', + '1. Do each action as the owner would, from a cold start, with no help beyond the text above.', + '2. Capture a screenshot or a short video that shows the result, then record it. A pass means the owner would see it work on the first try; anything else is a fail, and the note says what happened:', + '', '```bash', `gstack-first-use record ${run} --action N --verdict pass --evidence FILE --device 'DEVICE YOU USED' --account ${shellQuote(p.account)} ${by}`, + `gstack-first-use record ${run} --action N --verdict fail --evidence FILE --device 'DEVICE YOU USED' --account ${shellQuote(p.account)} ${by} --note 'WHAT HAPPENED'`, '```', '', + '3. Predict the owner\'s score from 1 to 10 for this build, with one line on why:', '', + '```bash', `gstack-first-use predict ${run} --score N --why 'ONE LINE' ${by}`, '```', '', + '4. Report back: one line per action (pass or fail and why), your predicted score, and the one thing most likely to disappoint the owner.', + '', + ].join('\n'); +} + diff --git a/lib/first-use.ts b/lib/first-use.ts new file mode 100644 index 000000000..3f7ed6a7e --- /dev/null +++ b/lib/first-use.ts @@ -0,0 +1,324 @@ +/** + * first-use — the cold first-use check for an app build (docs/first-use-check.md). + * Before a build reaches its owner as "ready to try", an agent from another model + * family plays that exact build on the same kind of device and account and does + * the first five things the plan's day-one table says the owner will do. This + * module keeps the record: an immutable start manifest (the frozen day-one rows + * with their hash, the play spec, the build fingerprint, the builder's and the + * checker's model families), one write-once file per action result with its + * evidence copied in and hashed, dated link receipts, the checker's predicted + * score and the owner's scores and words. decide() reads it back and refuses the + * "try it" message unless every frozen action passed on this build, every link + * was live within 15 minutes, the day-one rows are unchanged and a prediction + * exists. The record lives in the owner's private user-level Capy Drive folder + * on Capy (never the public repository), else under the gstack state root. + */ +import * as crypto from 'node:crypto'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { parseDayOne } from './autoplan-owner-text'; +import { resolveStateRoot } from './state-root'; +import { checkPlaySpec, type PlaySpec } from './first-use-message'; + +export const FIRST_USE_ACTIONS = 5; +export const LINK_FRESH_MS = 15 * 60 * 1000; +export const EVIDENCE_MAX_BYTES = 100 * 1024 * 1024; +export const EVIDENCE_KINDS: Record = { + '.png': 'screenshot', '.jpg': 'screenshot', '.jpeg': 'screenshot', '.gif': 'screenshot', '.webp': 'screenshot', '.heic': 'screenshot', + '.mp4': 'video', '.mov': 'video', '.webm': 'video', +}; +export type FirstUseCode = 'FIRST_USE_PLAN_UNREADY' | 'FIRST_USE_PLAY_SPEC_INCOMPLETE' | 'FIRST_USE_SAME_FAMILY' | 'FIRST_USE_NO_PRIVATE_DRIVE' | 'FIRST_USE_RECORD_INVALID' | 'FIRST_USE_REFUSED'; +export interface FirstUseError { code: FirstUseCode; detail: string } +type Result = T | { error: FirstUseError }; +const fail = (code: FirstUseCode, detail: string) => ({ error: { code, detail } }); + +export interface FrozenAction { n: number; action: string; frequency: string; feature: string; route: string; first_build: string; check: string; source: string } +export interface BuildId { platform: 'ios' | 'android' | 'web'; commit: string; testflight?: string; deploy?: string } +export interface Manifest { + schema_version: 1; kind: 'first-use-manifest'; app: string; created_at: string; + source: { path: string; rows_sha256: string }; actions: FrozenAction[]; + build: BuildId & { fingerprint: string }; play: PlaySpec; + builder: { model: string; family: string }; checker: { model: string; family: string }; +} +export interface ActionResult { + schema_version: 1; kind: 'first-use-result'; action: number; action_text: string; build_fingerprint: string; at: string; + verdict: 'pass' | 'fail'; evidence: { file: string; sha256: string; bytes: number; kind: 'screenshot' | 'video' }; + device: string; account: string; by: { model: string; family: string }; note: string; +} +/** Who a check speaks for: the owner-equivalent account from the play spec and the build's device class. */ +export interface Audience { account: string; device_class: BuildId['platform'] } +export const audienceOf = (m: Manifest): Audience => ({ account: m.play.account, device_class: m.build.platform }); +const sameAudience = (a: Partial | undefined, b: Audience) => a?.account === b.account && a?.device_class === b.device_class; +export interface LinkReceipt { schema_version: 1; kind: 'first-use-link'; url: string; build_fingerprint: string; audience: Audience; checked_at: string; status: number; login_gated: boolean; verdict: 'live' | 'down'; error?: string } +export interface Prediction { schema_version: 1; kind: 'first-use-prediction'; score: number; why: string; by: { model: string; family: string }; at: string; build_fingerprint: string } +export interface OwnerScore { schema_version: 1; kind: 'first-use-owner-score'; score: number; words: string; by: string; at: string; build_fingerprint: string } + +const FAMILY_WORDS: Array<[string, RegExp]> = [ + ['anthropic', /\b(claude|opus|sonnet|haiku|fable)\b/], + ['openai', /\b(gpt|codex|chatgpt)\b/], + ['google', /\bgemini\b/], + ['xai', /\bgrok\b/], + ['meta', /\b(llama|muse)\b/], + ['deepseek', /\bdeepseek\b/], + ['moonshotai', /\bkimi\b/], + ['qwen', /\bqwen\b/], +]; +/** + * A model's family: a known provider before the slash (`openai/gpt-6.2-sol` is openai), a bare family name, or a known + * model word, which also wins over a routing prefix (`openrouter/anthropic/claude-…` is anthropic); else the unknown + * provider before the slash, or undefined. + */ +export function modelFamily(model: string): string | undefined { + const s = model.trim().toLowerCase(); + if (!s) return undefined; + const slash = s.indexOf('/'); + const prefix = slash > 0 ? s.slice(0, slash) : s; + if (FAMILY_WORDS.some(([f]) => f === prefix)) return prefix; + return FAMILY_WORDS.find(([, re]) => re.test(s))?.[0] ?? (slash > 0 ? prefix : undefined); +} + +/** The first five rows of the plan's `### Day one` table (lib/autoplan-owner-text.ts parses it; the format is pinned by test/first-use.test.ts). */ +export function freezeActions(planText: string): Result<{ actions: FrozenAction[]; rows_sha256: string }> { + const day = parseDayOne(planText); + if (day.status === 'none') return fail('FIRST_USE_PLAN_UNREADY', 'the plan has no ### Day one table'); + if (day.status === 'malformed') return fail('FIRST_USE_PLAN_UNREADY', day.reason ?? 'the day-one table is malformed'); + if (day.rows.length < FIRST_USE_ACTIONS) return fail('FIRST_USE_PLAN_UNREADY', `the day-one table has ${day.rows.length} row${day.rows.length === 1 ? '' : 's'}; the check needs ${FIRST_USE_ACTIONS}`); + const rows = day.rows.slice(0, FIRST_USE_ACTIONS); + const blank = rows.map((r, i) => [r.frequency, r.source, r.feature, r.route, r.first_build, r.check].some(c => !c.trim()) ? i + 1 : 0).filter(Boolean); + if (blank.length) return fail('FIRST_USE_PLAN_UNREADY', `day-one row ${blank.join(', ')} has an empty cell; every column of the first ${FIRST_USE_ACTIONS} rows needs a value`); + const assumed = rows.map((r, i) => r.assumed ? i + 1 : 0).filter(Boolean); + if (assumed.length) return fail('FIRST_USE_PLAN_UNREADY', `day-one row ${assumed.join(', ')} is still marked assumed`); + const actions = rows.map((r, i) => ({ n: i + 1, action: r.action, frequency: r.frequency, feature: r.feature, route: r.route, first_build: r.first_build, check: r.check, source: r.source })); + return { actions, rows_sha256: sha256(JSON.stringify(actions)) }; +} + +/** Validates a build id; the fingerprint is the hash of platform, commit and the TestFlight build or deploy version. */ +export function buildFingerprint(b: Partial): Result { + if (b.platform !== 'ios' && b.platform !== 'android' && b.platform !== 'web') return fail('FIRST_USE_RECORD_INVALID', '--platform must be ios, android or web'); + if (!/^[0-9a-f]{40}$/.test(b.commit ?? '')) return fail('FIRST_USE_RECORD_INVALID', '--commit must be the full 40-character commit the build was made from'); + const tf = b.testflight?.trim(), dep = b.deploy?.trim(); + if (!!tf === !!dep) return fail('FIRST_USE_RECORD_INVALID', 'give exactly one of --testflight or --deploy '); + const id: BuildId = { platform: b.platform, commit: b.commit!, ...(tf ? { testflight: tf } : { deploy: dep }) }; + return { ...id, fingerprint: sha256(JSON.stringify([id.platform, id.commit, id.testflight ?? '', id.deploy ?? ''])).slice(0, 16) }; +} +export const buildLabel = (b: BuildId) => `${b.commit.slice(0, 12)}, ${b.testflight ? `TestFlight build ${b.testflight}` : `deploy ${b.deploy}`}`; + +/** + * Where records live: GSTACK_FIRST_USE_DIR; on Capy (GSTACK_CAPY=1) the one `~/.capy/drive/user-*` folder's + * `first-use/` (none or several refuses, never the throwaway machine folder); elsewhere `/first-use`. + */ +export function recordRoot(env: NodeJS.ProcessEnv = process.env): Result<{ root: string }> { + if (env.GSTACK_FIRST_USE_DIR) return { root: path.resolve(env.GSTACK_FIRST_USE_DIR) }; + if (env.GSTACK_CAPY !== '1') return { root: path.join(resolveStateRoot(env), 'first-use') }; + const drive = path.join(env.HOME || os.homedir(), '.capy', 'drive'); + let found: string[] = []; + try { found = fs.readdirSync(drive).filter(d => d.startsWith('user-') && fs.statSync(path.join(drive, d)).isDirectory()); } catch { /* no drive mounted */ } + if (found.length !== 1) return fail('FIRST_USE_NO_PRIVATE_DRIVE', found.length ? `${found.length} user-level drive folders (${found.join(', ')})` : `no user-level drive folder under ${drive}`); + return { root: path.join(drive, found[0]!, 'first-use') }; +} + +const sha256 = (data: string | Buffer) => crypto.createHash('sha256').update(data).digest('hex'); +const stamp = (d: Date) => d.toISOString().replace(/[-:]/g, ''); +const writeOnce = (file: string, value: unknown) => { + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', { flag: 'wx' }); +}; +const readJson = (file: string): T | undefined => { try { return JSON.parse(fs.readFileSync(file, 'utf8')) as T; } catch { return undefined; } }; + +export interface StartInput { root: string; app: string; planPath: string; build: Partial; play: unknown; builder: string; checker: string; now?: Date } +/** Freezes the day-one rows and writes the run's manifest once; returns the run directory. */ +export function startRun(o: StartInput): Result<{ dir: string; manifest: Manifest }> { + if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(o.app)) return fail('FIRST_USE_RECORD_INVALID', '--app must be a lowercase slug like ghome'); + let planText: string; + try { planText = fs.readFileSync(o.planPath, 'utf8'); } catch { return fail('FIRST_USE_PLAN_UNREADY', `cannot read ${o.planPath}`); } + const frozen = freezeActions(planText); + if ('error' in frozen) return frozen; + const play = checkPlaySpec(o.play); + if ('error' in play) return play; + const build = buildFingerprint(o.build); + if ('error' in build) return build; + const builder = modelFamily(o.builder), checker = modelFamily(o.checker); + if (!builder || !checker) return fail('FIRST_USE_SAME_FAMILY', `unknown model family for ${!builder ? `--builder ${o.builder}` : `--checker ${o.checker}`}`); + if (builder === checker) return fail('FIRST_USE_SAME_FAMILY', `builder and checker are both ${builder}`); + const now = o.now ?? new Date(); + const manifest: Manifest = { + schema_version: 1, kind: 'first-use-manifest', app: o.app, created_at: now.toISOString(), + source: { path: path.resolve(o.planPath), rows_sha256: frozen.rows_sha256 }, actions: frozen.actions, + build, play: play.spec, builder: { model: o.builder, family: builder }, checker: { model: o.checker, family: checker }, + }; + const dir = path.join(o.root, o.app, `${stamp(now)}-${build.fingerprint.slice(0, 8)}`); + try { writeOnce(path.join(dir, 'manifest.json'), manifest); } catch (e) { return fail('FIRST_USE_RECORD_INVALID', `cannot write ${dir}/manifest.json: ${(e as Error).message}`); } + return { dir, manifest }; +} + +export function readManifest(dir: string): Result<{ manifest: Manifest }> { + const m = readJson(path.join(dir, 'manifest.json')); + if (!m || m.schema_version !== 1 || m.kind !== 'first-use-manifest' || !Array.isArray(m.actions) || !m.build?.fingerprint) return fail('FIRST_USE_RECORD_INVALID', `no readable manifest.json in ${dir}`); + return { manifest: m }; +} + +/** The checker's own model, from its own family: the builder never grades its own build. */ +function checkerOf(m: Manifest, by: string): Result<{ by: { model: string; family: string } }> { + const family = modelFamily(by); + if (!family || family !== m.checker.family) return fail('FIRST_USE_SAME_FAMILY', `--by ${by} is ${family ?? 'an unknown family'}; this run's checker is ${m.checker.family} (${m.checker.model})`); + return { by: { model: by, family } }; +} + +export interface RecordInput { dir: string; action: number; verdict: string; evidence: string; device: string; account: string; by: string; note?: string; now?: Date } +/** One write-once result for one frozen action; the evidence file is copied into the run and hashed. */ +export function recordResult(o: RecordInput): Result<{ file: string; result: ActionResult }> { + const read = readManifest(o.dir); + if ('error' in read) return read; + const m = read.manifest; + const action = m.actions.find(a => a.n === o.action); + if (!action) return fail('FIRST_USE_RECORD_INVALID', `--action must be 1 to ${m.actions.length}`); + if (o.verdict !== 'pass' && o.verdict !== 'fail') return fail('FIRST_USE_RECORD_INVALID', '--verdict must be pass or fail'); + if (!o.device.trim()) return fail('FIRST_USE_RECORD_INVALID', 'name the --device you played on'); + if (o.account.trim() !== m.play.account) return fail('FIRST_USE_RECORD_INVALID', `play on the owner-equivalent account and pass it exactly: --account "${m.play.account}"`); + if (o.verdict === 'fail' && !o.note?.trim()) return fail('FIRST_USE_RECORD_INVALID', 'a fail needs --note saying what happened'); + const who = checkerOf(m, o.by); + if ('error' in who) return who; + const ev = copyEvidence(o.dir, o.action, o.evidence); + if ('error' in ev) return ev; + const now = o.now ?? new Date(); + const result: ActionResult = { + schema_version: 1, kind: 'first-use-result', action: o.action, action_text: action.action, build_fingerprint: m.build.fingerprint, at: now.toISOString(), + verdict: o.verdict, evidence: ev.evidence, device: o.device.trim(), account: o.account.trim(), by: who.by, note: o.note?.trim() ?? '', + }; + const file = path.join(o.dir, 'results', `${o.action}-${stamp(now)}-${crypto.randomBytes(3).toString('hex')}.json`); + try { writeOnce(file, result); } catch (e) { return fail('FIRST_USE_RECORD_INVALID', `cannot write ${file}: ${(e as Error).message}`); } + return { file, result }; +} + +function copyEvidence(dir: string, n: number, src: string): Result<{ evidence: ActionResult['evidence'] }> { + const kind = EVIDENCE_KINDS[path.extname(src).toLowerCase()]; + if (!kind) return fail('FIRST_USE_RECORD_INVALID', `evidence must be a screenshot or short video (${Object.keys(EVIDENCE_KINDS).join(' ')})`); + let st: fs.Stats; + try { st = fs.lstatSync(src); } catch { return fail('FIRST_USE_RECORD_INVALID', `no evidence file at ${src}`); } + if (!st.isFile()) return fail('FIRST_USE_RECORD_INVALID', 'the evidence must be a regular file, not a link or directory'); + if (st.size === 0 || st.size > EVIDENCE_MAX_BYTES) return fail('FIRST_USE_RECORD_INVALID', `the evidence is ${st.size} bytes (1 to ${EVIDENCE_MAX_BYTES})`); + const bytes = fs.readFileSync(src); + const digest = sha256(bytes); + const file = path.join('evidence', `${n}-${digest.slice(0, 16)}${path.extname(src).toLowerCase()}`); + try { + fs.mkdirSync(path.join(dir, 'evidence'), { recursive: true }); + if (!fs.existsSync(path.join(dir, file))) fs.writeFileSync(path.join(dir, file), bytes, { flag: 'wx' }); + } catch (e) { return fail('FIRST_USE_RECORD_INVALID', `cannot write ${path.join(dir, file)}: ${(e as Error).message}`); } + return { evidence: { file, sha256: digest, bytes: bytes.length, kind } }; +} + +export type Fetcher = (url: string) => Promise<{ status: number }>; +export const liveFetcher: Fetcher = async url => { + const res = await fetch(url, { method: 'GET', redirect: 'follow', signal: AbortSignal.timeout(15_000) }); + await res.body?.cancel().catch(() => undefined); + return { status: res.status }; +}; + +/** + * Checks every play link once for the run's audience (the owner-equivalent account and device class) and writes a + * dated receipt per link bound to that audience; a login-gated link passes on 401 or 403 only when the play spec marks it. + */ +export async function checkLinks(dir: string, as: Partial, fetcher: Fetcher = liveFetcher, now: () => Date = () => new Date()): Promise> { + const read = readManifest(dir); + if ('error' in read) return read; + const m = read.manifest, audience = audienceOf(m); + if (!sameAudience(as, audience)) return fail('FIRST_USE_RECORD_INVALID', `check links as the owner-equivalent audience: --account "${audience.account}" --device-class ${audience.device_class}`); + const receipts: LinkReceipt[] = []; + for (const [i, link] of m.play.links.entries()) { + let status = 0, error: string | undefined; + try { status = (await fetcher(link.url)).status; } catch (e) { error = (e as Error).message || String(e); } + const gated = !!link.login_gated; + const live = (status >= 200 && status < 400) || (gated && (status === 401 || status === 403)); + const at = now(); + const receipt: LinkReceipt = { schema_version: 1, kind: 'first-use-link', url: link.url, build_fingerprint: m.build.fingerprint, audience, checked_at: at.toISOString(), status, login_gated: gated, verdict: live ? 'live' : 'down', ...(error ? { error } : {}) }; + const file = path.join(dir, 'links', `${stamp(at)}-${i + 1}-${crypto.randomBytes(3).toString('hex')}.json`); + try { writeOnce(file, receipt); } catch (e) { return fail('FIRST_USE_RECORD_INVALID', `cannot write ${file}: ${(e as Error).message}`); } + receipts.push(receipt); + } + return { receipts }; +} + +const score = (s: string) => /^(10|[1-9])$/.test(s.trim()) ? Number(s.trim()) : undefined; + +/** The checker's predicted owner score, written once per run. */ +export function predict(o: { dir: string; score: string; why: string; by: string; now?: Date }): Result<{ prediction: Prediction }> { + const read = readManifest(o.dir); + if ('error' in read) return read; + const n = score(o.score); + if (n === undefined || !o.why.trim()) return fail('FIRST_USE_RECORD_INVALID', 'predict needs --score 1-10 and --why '); + const who = checkerOf(read.manifest, o.by); + if ('error' in who) return who; + const prediction: Prediction = { schema_version: 1, kind: 'first-use-prediction', score: n, why: o.why.trim(), by: who.by, at: (o.now ?? new Date()).toISOString(), build_fingerprint: read.manifest.build.fingerprint }; + try { writeOnce(path.join(o.dir, 'prediction.json'), prediction); } catch { return fail('FIRST_USE_RECORD_INVALID', 'this run already has a predicted score; start a new run to predict again'); } + return { prediction }; +} + +/** The owner's own score and exact words, appended (the newest counts); kept beside the prediction in the private record. */ +export function ownerScore(o: { dir: string; score: string; words: string; by: string; now?: Date }): Result<{ owner: OwnerScore }> { + const read = readManifest(o.dir); + if ('error' in read) return read; + const n = score(o.score); + if (n === undefined || !o.words.trim() || !o.by.trim()) return fail('FIRST_USE_RECORD_INVALID', 'score needs --score 1-10, --words "" and --by '); + const now = o.now ?? new Date(); + const owner: OwnerScore = { schema_version: 1, kind: 'first-use-owner-score', score: n, words: o.words, by: o.by.trim(), at: now.toISOString(), build_fingerprint: read.manifest.build.fingerprint }; + const file = path.join(o.dir, 'owner', `${stamp(now)}-${crypto.randomBytes(3).toString('hex')}.json`); + try { writeOnce(file, owner); } catch (e) { return fail('FIRST_USE_RECORD_INVALID', `cannot write ${file}: ${(e as Error).message}`); } + return { owner }; +} + +function readDir(dir: string): { rows: T[]; unreadable: string[] } { + const rows: T[] = [], unreadable: string[] = []; + let names: string[] = []; + try { names = fs.readdirSync(dir).filter(f => f.endsWith('.json')).sort(); } catch { /* none yet */ } + for (const f of names) { const r = readJson(path.join(dir, f)); if (r) rows.push(r); else unreadable.push(f); } + return { rows, unreadable }; +} +const newest = (rows: T[]) => [...rows].sort((a, b) => (a.at ?? a.checked_at ?? '').localeCompare(b.at ?? b.checked_at ?? '')).at(-1); + +export interface Decision { ok: boolean; reasons: string[]; manifest?: Manifest; passed: number; links: LinkReceipt[]; prediction?: Prediction; owner?: OwnerScore } +/** + * Whether this run clears the build about to be sent: the same build, unchanged day-one rows, a pass with intact + * evidence for every frozen action, a live receipt under 15 minutes old for every play link, and a predicted score. + */ +export function decide(dir: string, build: Partial, now: Date = new Date()): Decision { + const read = readManifest(dir); + if ('error' in read) return { ok: false, reasons: [read.error.detail], passed: 0, links: [] }; + const m = read.manifest, reasons: string[] = []; + const current = buildFingerprint(build); + if ('error' in current) reasons.push(current.error.detail); + else if (current.fingerprint !== m.build.fingerprint) reasons.push(`build_mismatch: this run checked ${buildLabel(m.build)}, not ${buildLabel(current)}`); + let planText: string | undefined; + try { planText = fs.readFileSync(m.source.path, 'utf8'); } catch { reasons.push(`source_missing: ${m.source.path}`); } + if (planText !== undefined) { + const again = freezeActions(planText); + if ('error' in again) reasons.push(`source_changed: ${again.error.detail}`); + else if (again.rows_sha256 !== m.source.rows_sha256) reasons.push('source_changed: the day-one rows changed since the check started; start a new run'); + } + if (m.builder.family === m.checker.family) reasons.push('same_family'); + const results = readDir(path.join(dir, 'results')); + if (results.unreadable.length) reasons.push(`record_unreadable: results/${results.unreadable.join(', results/')}`); + let passed = 0; + for (const a of m.actions) { + const r = newest(results.rows.filter(x => x.action === a.n && x.build_fingerprint === m.build.fingerprint && x.by?.family === m.checker.family && x.account === m.play.account)); + if (!r) { reasons.push(`action_${a.n}_not_played`); continue; } + if (r.verdict !== 'pass') { reasons.push(`action_${a.n}_failed: ${r.note}`); continue; } + let bytes: Buffer | undefined; + try { bytes = fs.readFileSync(path.join(dir, r.evidence.file)); } catch { /* missing */ } + if (!bytes || bytes.length !== r.evidence.bytes || sha256(bytes) !== r.evidence.sha256) { reasons.push(`action_${a.n}_evidence_stale`); continue; } + passed++; + } + const receipts = readDir(path.join(dir, 'links')); + const links: LinkReceipt[] = []; + for (const link of m.play.links) { + const r = newest(receipts.rows.filter(x => x.url === link.url && x.build_fingerprint === m.build.fingerprint && sameAudience(x.audience, audienceOf(m)))); + if (!r) { reasons.push(`link_unchecked: ${link.url} (as ${m.play.account} on ${m.build.platform})`); continue; } + links.push(r); + if (r.verdict !== 'live') reasons.push(`link_down: ${link.url} (status ${r.status || r.error || 'none'})`); + else if (now.getTime() - Date.parse(r.checked_at) > LINK_FRESH_MS) reasons.push(`link_stale: ${link.url} was checked at ${r.checked_at}, over 15 minutes ago`); + } + const prediction = readJson(path.join(dir, 'prediction.json')); + if (!prediction) reasons.push('no_predicted_score'); + const owner = newest(readDir(path.join(dir, 'owner')).rows); + return { ok: reasons.length === 0, reasons, manifest: m, passed, links, prediction, owner }; +} diff --git a/lib/result-codes-capy.ts b/lib/result-codes-capy.ts index b6dcf3b1c..d42752d6f 100644 --- a/lib/result-codes-capy.ts +++ b/lib/result-codes-capy.ts @@ -200,4 +200,34 @@ export const CAPY_RESULT_CODES = { summary: 'gstack-archive-check landed found no usable .gstack/plain-titles.json (missing, invalid or with no codes), so it cannot tell a tracker code from any other ref and closes nothing', fix: 'run it from the repository root, where .gstack/plain-titles.json lives; if the file is missing or invalid there, fix it on main (docs/ship-policy.md#plain-titles) and rerun; close nothing until then', }, + FIRST_USE_PLAN_UNREADY: { + anchor: 'first-use-plan-unready', + summary: 'the plan has no usable ### Day one table to freeze (missing, malformed, fewer than five complete rows, or a row still marked assumed)', + fix: 'add or fix the ### Day one table (action, frequency, source, feature, route, first build, check) and confirm every assumed row with the owner, then run start again', + }, + FIRST_USE_PLAY_SPEC_INCOMPLETE: { + anchor: 'first-use-play-spec-incomplete', + summary: 'the play spec is missing one or more of the ten parts every ask to play or try a build carries', + fix: 'fill in the parts the line names in the play spec JSON (docs/first-use-check.md#play-spec), then run start again', + }, + FIRST_USE_SAME_FAMILY: { + anchor: 'first-use-same-family', + summary: 'the checker is from the builder’s model family, its family is unknown, or a result was recorded by a model other than the run’s checker family', + fix: 'name the builder and checker as provider/model ids from different families (for example anthropic/… and openai/…), and record results only from the checker', + }, + FIRST_USE_NO_PRIVATE_DRIVE: { + anchor: 'first-use-no-private-drive', + summary: 'on Capy, the first-use record needs exactly one user-level Capy Drive folder (~/.capy/drive/user-*) and found none or several', + fix: 'run it in a thread of the build’s owner, where his private user drive is mounted, or set GSTACK_FIRST_USE_DIR to his private folder; never fall back to the machine folder', + }, + FIRST_USE_RECORD_INVALID: { + anchor: 'first-use-record-invalid', + summary: 'a first-use record input or file is invalid (bad flag value, unreadable manifest, a run outside the record root, bad evidence, or a write-once file that already exists)', + fix: 'correct the value the line names; never edit or delete files in a run directory, start a new run instead', + }, + FIRST_USE_REFUSED: { + anchor: 'first-use-refused', + summary: 'the build has not cleared its first-use check, so no "try this build" message or "v1 is ready" report may go out', + fix: 'act on each reason the line lists: replay the failed or unplayed actions, rerun links within 15 minutes of sending, add the predicted score, or start a new run for a new build or changed day-one rows', + }, } satisfies Record; diff --git a/test/first-use.test.ts b/test/first-use.test.ts new file mode 100644 index 000000000..96b2e543d --- /dev/null +++ b/test/first-use.test.ts @@ -0,0 +1,369 @@ +/** + * The first-use check (lib/first-use.ts, lib/first-use-message.ts, bin/gstack-first-use; + * docs/first-use-check.md). Every owner, app, plan and build here is made up. Pins the + * day-one table format both plan sources share (autoplan's ### Day one table and the + * one-page day-one list), so a change to lib/autoplan-owner-text.ts fails here rather + * than silently changing what the check freezes. Runs under a temporary HOME, drive and + * record root, serves its links from a local server, and proves the real drive is untouched. + */ +import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +import { spawnSync } from 'node:child_process'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { DAY_ONE_COLUMNS, DAY_ONE_TITLES } from '../lib/autoplan-owner-text'; +import { buildFingerprint, checkLinks, decide, freezeActions, modelFamily, ownerScore, predict, readManifest, recordResult, recordRoot, startRun, type Fetcher } from '../lib/first-use'; +import { checkPlaySpec, PLAY_PARTS, renderBrief, renderPlayMessage } from '../lib/first-use-message'; + +const ROOT = path.resolve(import.meta.dir, '..'); +const FIX = path.join(ROOT, 'test', 'fixtures', 'first-use'); +const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'first-use-')); +afterAll(() => fs.rmSync(TMP, { recursive: true, force: true })); + +const AUTOPLAN = fs.readFileSync(path.join(FIX, 'autoplan-plan.md'), 'utf8'); +const ONE_PAGE = fs.readFileSync(path.join(FIX, 'one-page-plan.md'), 'utf8'); +const PLAY = JSON.parse(fs.readFileSync(path.join(FIX, 'play.json'), 'utf8')); +const COMMIT = 'c0ffee'.padEnd(40, '0'); +const BUILD = { platform: 'ios' as const, commit: COMMIT, testflight: '17' }; +const T0 = new Date('2026-11-18T10:00:00Z'); +const ACTIONS = [ + 'adds her first three plants by photo', 'sees which plant needs water today', 'marks a plant as watered', 'gets a reminder at 8am', "opens a plant's care card", +]; +let n = 0; +const fresh = (name: string) => { const d = path.join(TMP, `${name}-${++n}`); fs.mkdirSync(d, { recursive: true }); return d; }; +const shot = (dir: string, name = 'shot.png', body = 'png bytes') => { const f = path.join(dir, name); fs.writeFileSync(f, body); return f; }; +const playWith = (port: number) => ({ ...PLAY, links: PLAY.links.map((l: { url: string }) => ({ ...l, url: l.url.replace('PORT', String(port)) })) }); +const AS = { account: PLAY.account, device_class: 'ios' as const }; +const okFetch: Fetcher = async url => ({ status: url.endsWith('/account') ? 401 : 200 }); + +/** A run on its own plan copy and record root, with every action passed, the links checked and a prediction. */ +function passedRun(o: { plan?: string } = {}) { + const root = fresh('root'), work = fresh('work'); + const planPath = path.join(work, 'plan.md'); + fs.writeFileSync(planPath, o.plan ?? AUTOPLAN); + const r = startRun({ root, app: 'plantpal', planPath, build: BUILD, play: playWith(1), builder: 'anthropic/claude-opus-5-5', checker: 'openai/gpt-6.2-sol', now: T0 }); + if ('error' in r) throw new Error(r.error.detail); + for (let a = 1; a <= 5; a++) { + const rec = recordResult({ dir: r.dir, action: a, verdict: 'pass', evidence: shot(work, `a${a}.png`, `screen ${a}`), device: 'iPhone 17 Pro (cloud)', account: PLAY.account, by: 'openai/gpt-6.2-sol', now: T0 }); + if ('error' in rec) throw new Error(rec.error.detail); + } + const p = predict({ dir: r.dir, score: '6', why: 'the reminder works but adding plants is slow', by: 'openai/gpt-6.2-sol', now: T0 }); + if ('error' in p) throw new Error(p.error.detail); + return { ...r, planPath, work, root }; +} + +describe('the day-one table format (pinned)', () => { + test('the parser this check reads keeps its titles and columns', () => { + expect(DAY_ONE_TITLES).toEqual(['Day one', 'Day-one page', 'Day one page']); + expect([...DAY_ONE_COLUMNS]).toEqual(['action', 'frequency', 'source', 'feature', 'route', 'first build', 'check']); + }); + + test('an autoplan plan and a one-page day-one list freeze the same five actions', () => { + const a = freezeActions(AUTOPLAN), b = freezeActions(ONE_PAGE); + if ('error' in a || 'error' in b) throw new Error('fixture did not freeze'); + expect(a.actions.map(x => x.action)).toEqual(ACTIONS); + expect(b.actions).toEqual(a.actions); + expect(b.rows_sha256).toBe(a.rows_sha256); + expect(a.actions[3]).toEqual({ n: 4, action: 'gets a reminder at 8am', frequency: 'daily', feature: 'Morning reminder', route: 'notification', first_build: 'build 1', check: 'a notification arrives at 8:00 on the device', source: 'calendar habit' }); + }); + + test('a sixth row marked assumed is not frozen; an assumed row in the first five refuses', () => { + expect('error' in freezeActions(AUTOPLAN)).toBe(false); + const assumed = AUTOPLAN.replace('| gets a reminder at 8am | daily | calendar habit |', '| gets a reminder at 8am | daily | assumed |'); + const r = freezeActions(assumed); + expect('error' in r && r.error).toEqual({ code: 'FIRST_USE_PLAN_UNREADY', detail: 'day-one row 4 is still marked assumed' }); + }); + + test('fewer than five rows, or an empty cell in the first five, refuses', () => { + const four = ONE_PAGE.replace(/^\| opens a plant's care card .*\n/m, ''); + expect(freezeActions(four)).toEqual({ error: { code: 'FIRST_USE_PLAN_UNREADY', detail: 'the day-one table has 4 rows; the check needs 5' } }); + const blank = ONE_PAGE.replace('| Morning reminder | notification |', '| Morning reminder | |'); + expect(freezeActions(blank)).toEqual({ error: { code: 'FIRST_USE_PLAN_UNREADY', detail: 'day-one row 4 has an empty cell; every column of the first 5 rows needs a value' } }); + }); + + test('no table, a missing column or an empty table refuses', () => { + expect(freezeActions('# A plan\n\nNo day one here.\n')).toEqual({ error: { code: 'FIRST_USE_PLAN_UNREADY', detail: 'the plan has no ### Day one table' } }); + const noCheck = ONE_PAGE.replace('| Check |', '| Notes |'); + expect('error' in freezeActions(noCheck) && freezeActions(noCheck)).toMatchObject({ error: { detail: 'the table has no check column' } }); + const empty = '## Day one\n\n| action | frequency | source | feature | route | first build | check |\n|---|---|---|---|---|---|---|\n'; + expect(freezeActions(empty)).toMatchObject({ error: { code: 'FIRST_USE_PLAN_UNREADY' } }); + }); +}); + +describe('model families and build fingerprints', () => { + test('families come from the provider prefix, a family name or a known model word', () => { + expect(modelFamily('openai/gpt-6.2-sol')).toBe('openai'); + expect(modelFamily('anthropic/claude-opus-5-5')).toBe('anthropic'); + expect(modelFamily('claude-fable-5-2')).toBe('anthropic'); + expect(modelFamily('gpt-6-astra')).toBe('openai'); + expect(modelFamily('google')).toBe('google'); + expect(modelFamily('gemini-4-carbon')).toBe('google'); + expect(modelFamily('mystery-model')).toBeUndefined(); + expect(modelFamily('openrouter/anthropic/claude-opus-5-5')).toBe('anthropic'); + expect(modelFamily('bedrock/anthropic.claude-sonnet-5-5')).toBe('anthropic'); + expect(modelFamily('zai/glm-5.3')).toBe('zai'); + }); + + test('a same-family or unknown checker refuses at start', () => { + const work = fresh('fam'), planPath = path.join(work, 'plan.md'); + fs.writeFileSync(planPath, AUTOPLAN); + const base = { root: fresh('root'), app: 'plantpal', planPath, build: BUILD, play: PLAY }; + expect(startRun({ ...base, builder: 'anthropic/claude-opus-5-5', checker: 'claude-fable-5-2' })).toMatchObject({ error: { code: 'FIRST_USE_SAME_FAMILY', detail: 'builder and checker are both anthropic' } }); + expect(startRun({ ...base, builder: 'anthropic/claude-opus-5-5', checker: 'mystery-model' })).toMatchObject({ error: { code: 'FIRST_USE_SAME_FAMILY' } }); + }); + + test('a build needs a full commit and exactly one of TestFlight build or deploy version', () => { + expect(buildFingerprint({ ...BUILD, commit: 'abc123' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(buildFingerprint({ ...BUILD, deploy: 'v1' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(buildFingerprint({ platform: 'web', commit: COMMIT })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + const a = buildFingerprint(BUILD), b = buildFingerprint({ ...BUILD, testflight: '18' }); + if ('error' in a || 'error' in b) throw new Error('valid builds refused'); + expect(a.fingerprint).not.toBe(b.fingerprint); + expect(a.fingerprint).toMatch(/^[0-9a-f]{16}$/); + }); +}); + +describe('the play spec carries the ten parts of every play ask', () => { + test('the fixture is complete and the parts are in order', () => { + expect('spec' in checkPlaySpec(PLAY)).toBe(true); + expect(PLAY_PARTS.map(p => p.part)).toEqual([ + 'The links, each checked live minutes before sending', 'Device and setup', 'What it is, in a sentence', 'How to start', 'Controls', + 'How long to play', 'What we want to learn', 'How to report back', 'Known quirks', 'Reply word', + ]); + }); + + test('missing parts are named', () => { + const { controls: _c, quirks: _q, ...rest } = PLAY; + const r = checkPlaySpec({ ...rest, links: [{ label: 'x', url: 'ftp://nope' }], minutes: 0 }); + expect(r).toEqual({ error: { code: 'FIRST_USE_PLAY_SPEC_INCOMPLETE', detail: 'missing or invalid: The links, each checked live minutes before sending (links); Controls (controls); How long to play (minutes); Known quirks (quirks)' } }); + expect(checkPlaySpec({ ...PLAY, reply_word: 'two words' })).toMatchObject({ error: { detail: 'missing or invalid: Reply word (reply_word)' } }); + }); +}); + +describe('where records live', () => { + test('override, then the one user drive on Capy, else the state root', () => { + const home = fresh('home'); + expect(recordRoot({ GSTACK_FIRST_USE_DIR: path.join(home, 'x') })).toEqual({ root: path.join(home, 'x') }); + expect(recordRoot({ HOME: home, GSTACK_CAPY: '1' })).toMatchObject({ error: { code: 'FIRST_USE_NO_PRIVATE_DRIVE' } }); + fs.mkdirSync(path.join(home, '.capy', 'drive', 'user-ada-example'), { recursive: true }); + fs.mkdirSync(path.join(home, '.capy', 'drive', 'project-plantpal'), { recursive: true }); + expect(recordRoot({ HOME: home, GSTACK_CAPY: '1' })).toEqual({ root: path.join(home, '.capy', 'drive', 'user-ada-example', 'first-use') }); + fs.mkdirSync(path.join(home, '.capy', 'drive', 'user-bo-example'), { recursive: true }); + expect(recordRoot({ HOME: home, GSTACK_CAPY: '1' })).toMatchObject({ error: { code: 'FIRST_USE_NO_PRIVATE_DRIVE', detail: '2 user-level drive folders (user-ada-example, user-bo-example)' } }); + expect(recordRoot({ HOME: home, GSTACK_STATE_ROOT: path.join(home, 'state') })).toEqual({ root: path.join(home, 'state', 'first-use') }); + }); +}); + +describe('the gate', () => { + test('five passes, live links and a prediction clear the exact build, and the message carries every part', async () => { + const r = passedRun(); + expect(decide(r.dir, BUILD, T0).reasons).toEqual(['link_unchecked: http://127.0.0.1:1/testflight (as a fresh Apple ID with notifications allowed on ios)', 'link_unchecked: http://127.0.0.1:1/account (as a fresh Apple ID with notifications allowed on ios)']); + const links = await checkLinks(r.dir, AS, okFetch, () => T0); + expect('receipts' in links && links.receipts.map(x => x.verdict)).toEqual(['live', 'live']); + const d = decide(r.dir, BUILD, new Date(T0.getTime() + 5 * 60_000)); + expect(d).toMatchObject({ ok: true, reasons: [], passed: 5 }); + const msg = renderPlayMessage(d, new Date(T0.getTime() + 5 * 60_000)); + for (const [i, label] of ['Links', 'Device and setup', 'What it is', 'How to start', 'Controls', 'How long', 'What we want to learn', 'How to report back', 'Known quirks', 'Reply word'].entries()) { + expect(msg).toContain(`${i + 1}. **${label}`); + } + expect(msg).toContain('checked live at 10:00 UTC, 5 min before this message'); + expect(msg).toContain('[TestFlight invite](http://127.0.0.1:1/testflight)'); + expect(msg).toContain('(asks you to sign in)'); + expect(msg).toContain('Try plantpal: c0ffee000000, TestFlight build 17'); + for (const a of ACTIONS) expect(msg).toContain(`- ${a}`); + expect(msg).not.toContain('predict'); + }); + + test('another build, a stale link, a changed day-one row and tampered evidence each refuse', async () => { + const r = passedRun(); + await checkLinks(r.dir, AS, okFetch, () => T0); + expect(decide(r.dir, { ...BUILD, testflight: '18' }, T0).reasons).toEqual(['build_mismatch: this run checked c0ffee000000, TestFlight build 17, not c0ffee000000, TestFlight build 18']); + expect(decide(r.dir, BUILD, new Date(T0.getTime() + 16 * 60_000)).reasons).toEqual([ + 'link_stale: http://127.0.0.1:1/testflight was checked at 2026-11-18T10:00:00.000Z, over 15 minutes ago', + 'link_stale: http://127.0.0.1:1/account was checked at 2026-11-18T10:00:00.000Z, over 15 minutes ago', + ]); + fs.writeFileSync(r.planPath, AUTOPLAN.replace('gets a reminder at 8am', 'gets a reminder at 9am')); + expect(decide(r.dir, BUILD, T0).reasons).toEqual(['source_changed: the day-one rows changed since the check started; start a new run']); + fs.writeFileSync(r.planPath, AUTOPLAN + '\nAn edit outside the table does not count.\n'); + expect(decide(r.dir, BUILD, T0).ok).toBe(true); + const ev = fs.readdirSync(path.join(r.dir, 'evidence')).find(f => f.startsWith('2-'))!; + fs.writeFileSync(path.join(r.dir, 'evidence', ev), 'edited'); + expect(decide(r.dir, BUILD, T0).reasons).toEqual(['action_2_evidence_stale']); + }); + + test('a failed action, a down link and a missing prediction refuse; the newest result for an action counts', async () => { + const root = fresh('root'), work = fresh('work'), planPath = path.join(work, 'plan.md'); + fs.writeFileSync(planPath, ONE_PAGE); + const r = startRun({ root, app: 'plantpal', planPath, build: BUILD, play: playWith(1), builder: 'anthropic/claude-opus-5-5', checker: 'gemini-4-carbon', now: T0 }); + if ('error' in r) throw new Error(r.error.detail); + const rec = (a: number, verdict: string, at: Date, note?: string) => recordResult({ dir: r.dir, action: a, verdict, evidence: shot(work, `a${a}-${verdict}.mp4`, `${a}${verdict}`), device: 'iPhone 17 Pro (cloud)', account: PLAY.account, by: 'google/gemini-4-carbon', note, now: at }); + for (let a = 1; a <= 4; a++) rec(a, 'pass', T0); + expect(rec(5, 'fail', T0)).toMatchObject({ error: { detail: 'a fail needs --note saying what happened' } }); + rec(5, 'fail', T0, 'the care card is blank'); + await checkLinks(r.dir, AS, async () => ({ status: 401 }), () => T0); + expect(decide(r.dir, BUILD, T0).reasons).toEqual([ + 'action_5_failed: the care card is blank', 'link_down: http://127.0.0.1:1/testflight (status 401)', 'no_predicted_score', + ]); + rec(5, 'pass', new Date(T0.getTime() + 60_000)); + await checkLinks(r.dir, AS, okFetch, () => new Date(T0.getTime() + 60_000)); + expect(predict({ dir: r.dir, score: '7', why: 'clean', by: 'gemini-4-carbon' })).toMatchObject({ prediction: { score: 7 } }); + expect(predict({ dir: r.dir, score: '8', why: 'again', by: 'gemini-4-carbon' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(decide(r.dir, BUILD, T0)).toMatchObject({ ok: true, passed: 5 }); + }); + + test('link receipts and results bind the owner-equivalent account and device class', async () => { + const r = passedRun(); + expect(await checkLinks(r.dir, { account: 'any session', device_class: 'ios' }, okFetch, () => T0)).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(await checkLinks(r.dir, { account: PLAY.account, device_class: 'web' }, okFetch, () => T0)).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(fs.existsSync(path.join(r.dir, 'links'))).toBe(false); + const other = { schema_version: 1, kind: 'first-use-link', url: 'http://127.0.0.1:1/testflight', build_fingerprint: JSON.parse(fs.readFileSync(path.join(r.dir, 'manifest.json'), 'utf8')).build.fingerprint, audience: { account: 'a developer account', device_class: 'ios' }, checked_at: T0.toISOString(), status: 200, login_gated: false, verdict: 'live' }; + fs.mkdirSync(path.join(r.dir, 'links')); + fs.writeFileSync(path.join(r.dir, 'links', 'other.json'), JSON.stringify(other)); + expect(decide(r.dir, BUILD, T0).reasons[0]).toBe('link_unchecked: http://127.0.0.1:1/testflight (as a fresh Apple ID with notifications allowed on ios)'); + expect(recordResult({ dir: r.dir, action: 1, verdict: 'pass', evidence: shot(r.work, 'dev.png'), device: 'd', account: 'a developer account', by: 'openai/gpt-6.2-sol' })).toMatchObject({ error: { detail: 'play on the owner-equivalent account and pass it exactly: --account "a fresh Apple ID with notifications allowed"' } }); + }); + + test('the builder cannot record a result or a prediction, and evidence must be a screenshot or video', () => { + const r = passedRun(); + expect(recordResult({ dir: r.dir, action: 1, verdict: 'pass', evidence: shot(r.work, 'self.png'), device: 'd', account: PLAY.account, by: 'anthropic/claude-opus-5-5' })).toMatchObject({ error: { code: 'FIRST_USE_SAME_FAMILY' } }); + expect(recordResult({ dir: r.dir, action: 1, verdict: 'pass', evidence: shot(r.work, 'notes.txt'), device: 'd', account: PLAY.account, by: 'openai/gpt-6.2-sol' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(recordResult({ dir: r.dir, action: 6, verdict: 'pass', evidence: shot(r.work, 'six.png'), device: 'd', account: PLAY.account, by: 'openai/gpt-6.2-sol' })).toMatchObject({ error: { detail: '--action must be 1 to 5' } }); + const link = path.join(r.work, 'link.png'); + fs.symlinkSync(shot(r.work, 'real.png'), link); + expect(recordResult({ dir: r.dir, action: 1, verdict: 'pass', evidence: link, device: 'd', account: PLAY.account, by: 'openai/gpt-6.2-sol' })).toMatchObject({ error: { detail: 'the evidence must be a regular file, not a link or directory' } }); + }); + + test('the owner score and words sit beside the prediction; the manifest is written once', () => { + const r = passedRun(); + expect(ownerScore({ dir: r.dir, score: '4', words: '', by: 'GStack Minder' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + ownerScore({ dir: r.dir, score: '4', words: '4, Talk is slow', by: 'GStack Minder', now: T0 }); + ownerScore({ dir: r.dir, score: '5', words: '5, better after the fix', by: 'GStack Minder', now: new Date(T0.getTime() + 60_000) }); + const d = decide(r.dir, BUILD, T0); + expect(d.prediction?.score).toBe(6); + expect(d.owner).toMatchObject({ score: 5, words: '5, better after the fix' }); + expect(fs.readdirSync(path.join(r.dir, 'owner'))).toHaveLength(2); + const again = startRun({ root: r.root, app: 'plantpal', planPath: r.planPath, build: BUILD, play: PLAY, builder: 'anthropic/claude-opus-5-5', checker: 'openai/gpt-6.2-sol', now: T0 }); + expect(again).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + }); + + test('a record write that fails refuses with FIRST_USE_RECORD_INVALID instead of throwing', async () => { + const r = passedRun(); + for (const d of ['results', 'links', 'owner']) { + fs.rmSync(path.join(r.dir, d), { recursive: true, force: true }); + fs.writeFileSync(path.join(r.dir, d), 'not a directory'); + } + expect(recordResult({ dir: r.dir, action: 1, verdict: 'pass', evidence: shot(r.work, 'again.png', 'again'), device: 'd', account: PLAY.account, by: 'openai/gpt-6.2-sol' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(await checkLinks(r.dir, AS, okFetch)).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + expect(ownerScore({ dir: r.dir, score: '4', words: '4, fine', by: 'GStack Minder' })).toMatchObject({ error: { code: 'FIRST_USE_RECORD_INVALID' } }); + }); + + test('the brief shell-quotes every value it puts into the record and predict lines', () => { + const work = fresh('quote'), planPath = path.join(work, 'plan.md'), marker = path.join(work, 'ran'); + fs.writeFileSync(planPath, AUTOPLAN); + const account = `Ada's "test" $HOME \`touch ${marker}\` $(touch ${marker}) account`; + const r = startRun({ root: path.join(fresh('root'), 'it\'s "$x"'), app: 'plantpal', planPath, build: BUILD, play: { ...PLAY, account }, builder: 'anthropic/claude-opus-5-5', checker: 'openai/gpt-6.2-sol', now: T0 }); + if ('error' in r) throw new Error(r.error.detail); + const lines = renderBrief(r.manifest, r.dir).split('\n').filter(l => l.startsWith('gstack-first-use ')); + expect(lines).toHaveLength(3); + for (const line of lines) { + const argv = spawnSync('bash', ['-c', line.replace(/^gstack-first-use /, "printf '%s\\n' ")], { encoding: 'utf8', timeout: 10_000 }).stdout.split('\n'); + expect(argv[argv.indexOf('--run') + 1]).toBe(r.dir); + expect(argv[argv.indexOf('--by') + 1]).toBe('openai/gpt-6.2-sol'); + if (line.includes(' record ')) expect(argv[argv.indexOf('--account') + 1]).toBe(account); + } + expect(fs.existsSync(marker)).toBe(false); + }); + + test('the brief gives the checker only the play text and the frozen actions', () => { + const r = passedRun(); + const read = readManifest(r.dir); + if ('error' in read) throw new Error('no manifest'); + const brief = renderBrief(read.manifest, r.dir); + expect(brief).toContain('You run on openai/gpt-6.2-sol; the team that built it runs on anthropic models'); + expect(brief).toContain('tools.capy.phone'); + expect(brief).toContain('TestFlight build 17'); + for (const a of ACTIONS) expect(brief).toContain(a); + expect(brief).toContain(`gstack-first-use record --run '${r.dir}' --action N --verdict pass --evidence FILE --device 'DEVICE YOU USED' --account 'a fresh Apple ID with notifications allowed' --by 'openai/gpt-6.2-sol'`); + expect(brief).not.toContain('Ada Example'); + expect(brief).not.toContain(r.planPath); + }); +}); + +describe('gstack-first-use (CLI, temporary HOME and drive)', () => { + const BIN = path.join(ROOT, 'bin', 'gstack-first-use'); + const realDrive = path.join(os.homedir(), '.capy', 'drive'); + const realRecords = () => { try { return fs.readdirSync(realDrive).filter(d => fs.existsSync(path.join(realDrive, d, 'first-use'))).map(d => `${d}:${fs.readdirSync(path.join(realDrive, d, 'first-use')).join(',')}`); } catch { return []; } }; + let server: ReturnType; + let home: string, env: Record; + const before = realRecords(); + beforeAll(() => { + server = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: req => new Response('ok', { status: new URL(req.url).pathname === '/account' ? 403 : 200 }) }); + home = fresh('home'); + fs.mkdirSync(path.join(home, '.capy', 'drive', 'user-ada-example'), { recursive: true }); + env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GSTACK_')).map(([k, v]) => [k, v ?? ''])); + Object.assign(env, { HOME: home, GSTACK_CAPY: '1', GSTACK_STATE_ROOT: path.join(home, 'state') }); + }); + afterAll(() => server?.stop(true)); + const cli = async (...args: string[]) => { + const p = Bun.spawn([process.execPath, BIN, ...args], { env, stdout: 'pipe', stderr: 'pipe', timeout: 30_000 }); + const [stdout, stderr, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited]); + return { stdout, stderr, code }; + }; + + test('start, brief, record, predict, links, message, score and show in the owner\'s private drive', async () => { + const work = fresh('cli'); + const plan = path.join(work, 'plan.md'), play = path.join(work, 'play.json'); + fs.writeFileSync(plan, AUTOPLAN); + fs.writeFileSync(play, JSON.stringify(playWith(server.port!))); + const build = ['--platform', 'ios', '--commit', COMMIT, '--testflight', '17']; + const start = await cli('start', '--app', 'plantpal', '--plan', plan, '--play', play, ...build, '--builder', 'anthropic/claude-opus-5-5', '--checker', 'openai/gpt-6.2-sol'); + expect(start.code).toBe(0); + const dir = /^FIRST_USE_RUN: (.+)$/m.exec(start.stdout)![1]!; + expect(dir.startsWith(path.join(home, '.capy', 'drive', 'user-ada-example', 'first-use', 'plantpal') + path.sep)).toBe(true); + expect(start.stdout).toContain('FIRST_USE_FROZEN: 5 actions'); + + const early = await cli('message', '--run', dir, ...build); + expect(early.code).toBe(3); + expect(early.stdout).toBe(''); + expect(early.stderr).toContain('(FIRST_USE_REFUSED)'); + expect(early.stderr).toContain('action_1_not_played'); + + const brief = await cli('brief', '--run', dir); + expect(brief.stdout).toContain('# Cold first-use check: plantpal'); + expect(brief.stderr).toContain('DISPATCH: give this brief'); + + for (let a = 1; a <= 5; a++) { + const rec = await cli('record', '--run', dir, '--action', String(a), '--verdict', 'pass', '--evidence', shot(work, `a${a}.png`, `s${a}`), '--device', 'iPhone 17 Pro (cloud)', '--account', PLAY.account, '--by', 'openai/gpt-6.2-sol'); + expect(rec.code).toBe(0); + } + expect((await cli('predict', '--run', dir, '--score', '6', '--why', 'reminder works, adding is slow', '--by', 'openai/gpt-6.2-sol')).stdout).toContain('FIRST_USE_PREDICTED: 6'); + expect((await cli('links', '--run', dir)).code).toBe(1); + const links = await cli('links', '--run', dir, '--account', PLAY.account, '--device-class', 'ios'); + expect(links.code).toBe(0); + expect(links.stdout).toContain('LINK: live status=403 as=ios'); + + const check = await cli('check', '--run', dir, ...build); + expect(check.stdout).toMatch(/^FIRST_USE: pass app=plantpal build=c0ffee000000, TestFlight build 17 actions=5\/5 links=2\/2 checker=openai\/gpt-6.2-sol predicted=6$/m); + const msg = await cli('message', '--run', dir, ...build); + expect(msg.code).toBe(0); + expect(msg.stdout).toContain('10. **Reply word:** played'); + expect((await cli('check', '--run', dir, '--platform', 'ios', '--commit', COMMIT, '--testflight', '18')).code).toBe(3); + + expect((await cli('score', '--run', dir, '--score', '4', '--words', '4, Talk is slow', '--by', 'Example Captain')).code).toBe(0); + const show = await cli('show', '--run', dir, '--json'); + expect(JSON.parse(show.stdout)).toMatchObject({ passed: 5, predicted: 6, owner: { score: 4, words: '4, Talk is slow' }, gap: -2 }); + expect(realRecords()).toEqual(before); + }); + + test('a run outside the record root and a second user drive refuse', async () => { + const outside = fresh('outside'); + const r = await cli('show', '--run', outside); + expect(r.code).toBe(1); + expect(r.stderr).toContain('is outside the record root'); + fs.mkdirSync(path.join(home, '.capy', 'drive', 'user-bo-example'), { recursive: true }); + const two = await cli('root'); + expect(two.code).toBe(3); + expect(two.stderr).toContain('(FIRST_USE_NO_PRIVATE_DRIVE)'); + fs.rmSync(path.join(home, '.capy', 'drive', 'user-bo-example'), { recursive: true }); + }); +}); diff --git a/test/fixtures/first-use/autoplan-plan.md b/test/fixtures/first-use/autoplan-plan.md new file mode 100644 index 000000000..1479e515d --- /dev/null +++ b/test/fixtures/first-use/autoplan-plan.md @@ -0,0 +1,25 @@ +# Plantpal: a watering coach for houseplants (synthetic fixture) + +Made-up plan for test/first-use.test.ts. The owner, the app and every row are invented. + +## Implementation plan + +### Owner's words + +- Ada Example, day 0: "I keep forgetting which plant needs water" + +### Day one + +| action | frequency | source | feature | route | first build | check | +|---|---|---|---|---|---|---| +| adds her first three plants by photo | once | owner words 1 | Add plant | home screen, plus button | build 1 | three plants show on the home screen with names | +| sees which plant needs water today | daily | owner words 1 | Today list | root screen | build 1 | the plant due today is at the top, marked due | +| marks a plant as watered | daily | owner words 1 | Watered button | Today list, tap a plant | build 1 | the plant drops off today's list | +| gets a reminder at 8am | daily | calendar habit | Morning reminder | notification | build 1 | a notification arrives at 8:00 on the device | +| opens a plant's care card | weekly | owner words 1 | Care card | home screen, tap a plant | build 1 | the card shows light, water and the last watered date | +| shares a plant with her partner | assumed | assumed | Sharing | plant card, share | build 2 | the partner's phone shows the plant | + +### What it won't do yet + +- No Android build +- No plant disease diagnosis diff --git a/test/fixtures/first-use/one-page-plan.md b/test/fixtures/first-use/one-page-plan.md new file mode 100644 index 000000000..1bb418ecd --- /dev/null +++ b/test/fixtures/first-use/one-page-plan.md @@ -0,0 +1,17 @@ +# Day-one page: Plantpal (synthetic fixture, R107 style) + +The first five things the owner does on day one, each with a check that it works. Invented for tests. + +## Day one + +| Action | Feature | Route | First build | Check | Frequency | Source | +| --- | --- | --- | --- | --- | --- | --- | +| adds her first three plants by photo | Add plant | home screen, plus button | build 1 | three plants show on the home screen with names | once | owner words 1 | +| sees which plant needs water today | Today list | root screen | build 1 | the plant due today is at the top, marked due | daily | owner words 1 | +| marks a plant as watered | Watered button | Today list, tap a plant | build 1 | the plant drops off today's list | daily | owner words 1 | +| gets a reminder at 8am | Morning reminder | notification | build 1 | a notification arrives at 8:00 on the device | daily | calendar habit | +| opens a plant's care card | Care card | home screen, tap a plant | build 1 | the card shows light, water and the last watered date | weekly | owner words 1 | + +## Install + +Put build 1 on the owner's phone after the first PR. diff --git a/test/fixtures/first-use/play.json b/test/fixtures/first-use/play.json new file mode 100644 index 000000000..d4bcba83d --- /dev/null +++ b/test/fixtures/first-use/play.json @@ -0,0 +1,24 @@ +{ + "links": [ + { + "label": "TestFlight invite", + "url": "http://127.0.0.1:PORT/testflight" + }, + { + "label": "Account page", + "url": "http://127.0.0.1:PORT/account", + "login_gated": true + } + ], + "device": "iPhone 17 Pro on iOS 26", + "setup": "Install TestFlight from the App Store first.", + "account": "a fresh Apple ID with notifications allowed", + "what": "Plantpal tells you which houseplant needs water today.", + "start": "Open the TestFlight invite, tap Install, then open Plantpal.", + "controls": "Tap to open, swipe left on a plant to mark it watered.", + "minutes": 10, + "learn": "Whether the Today list is the first thing you want every morning.", + "report": "Reply in this thread.", + "quirks": "The first photo can take a few seconds to upload.", + "reply_word": "played" +} diff --git a/test/helpers/free-fixtures-data.ts b/test/helpers/free-fixtures-data.ts index 726a5baf1..e8a831859 100644 --- a/test/helpers/free-fixtures-data.ts +++ b/test/helpers/free-fixtures-data.ts @@ -151,6 +151,7 @@ export const FREE_FIXTURES: Readonly> = { 'test/fixtures/exercised-map-replay.json': ['scripts/exercised-map.ts'], 'test/fixtures/exit-propagation/**': ['test/exit-propagation.test.ts'], 'test/fixtures/factory-scorecard/**': ['test/factory-scorecard.test.ts'], + 'test/fixtures/first-use/**': ['test/first-use.test.ts'], 'test/fixtures/founder-resources-pool.txt': ['test/founder-resources-bin.test.ts'], 'test/fixtures/free-shard-capture.ts': ['test/test-free-shards-capture.test.ts'], 'test/fixtures/gh-poll/**': ['test/gh-poll.test.ts'],