tuffgal 0.1.0-alpha.9 → 0.2.0-alpha.2

package/CHANGELOG.md

@@ -6,7 +6,147 @@ this project uses [Pride Versioning](https://pridever.org) → `PROUD.DEFAULT.SH
 
 ## [Unreleased]
 
-_Nothing right now_
+_Nothing just yet_
+
+## [0.2.0-alpha.2] — 2026-07-12
+
+Report improvements. The HTML report picks up a breakpoint filter, sharper
+status filtering, and an interactive viewer redesigned around
+blink-comparing what changed.
+
+### Added
+
+- Breakpoint filter pills in the report summary
+- `npm run preview -- --interactive` renders sample report in interactive mode
+- `sizeMismatch` on `results.json` action results
+
+### Changed
+
+- A status-filtered story now shows only its matching actions
+- Candidate note names its referent
+- Redesigned interactive mode so resting state is the selected variant
+  - Press and hold the screenshot to flip to its baseline counterpart
+  - The Baseline/Actual/Diff chips are always visible
+  - The Showing caption tracks whatever is displayed
+- Resized-screenshot note folded into one accessible sentence
+- Summary status filters restyled as colorful pills
+
+### Fixed
+
+- A press-to-native-image-drag no longer leaves the preview stuck
+- Bulk expand/collapse no longer pre-expands hidden screenshot panels
+- "Expanded changed in 1 stories" pluralization in bulk-toggle announcement
+- `npm run preview` silently never rendered interactive mode
+
+## [0.2.0-alpha.1] — 2026-07-10
+
+CI-owned baselines. CI is now the sole writer of committed baselines. Local
+runs are advisory self-diffs. Committed visual changes are a PR review
+gate, approved from a CI candidate tree rather than by any local `approve`.
+
+### Added
+
+- Run modes. `tuffgal run` resolves `--ci` / `--local`
+  - Explicit flag wins
+  - With neither, CI when `$CI` is truth-y, else local
+- CI mode writes a self-contained candidate tree with a `results.json` copy
+  - Never writes committed baselines
+  - A missing baseline is `new` (candidate only)
+  - An orphaned one is `deleted`
+- `approve --from <dir>` promotes a CI candidate tree into `paths.baselines`
+  - The only code path that writes committed baselines
+  - Refuses any candidate whose `results.json` is not a clean CI run (`mode !== 'ci'` or `totals.failed > 0`)
+  - `--prune` retires baselines marked `deleted`
+- Environment manifest at `baselines/manifest.json`
+  - Written by `approve --from` and checked by `run --ci`
+  - Pixel-affecting mismatch still runs the comparison but banners the report and exits `3`
+- Local advisory mode compares against a git-ignored per-machine cache
+  - Plain `approve` now refreshes that cache
+- CI exit codes
+  - `2` (pending `new`/`changed`/`deleted` to approve)
+  - `3` (environment mismatch)
+  - Precedence `1` > `3` > `2`
+- `results.json` fields
+  - `mode`
+  - `environment` (`expected`/`actual`/`mismatch`/`mismatchKeys`)
+  - `deleted[]`
+  - `totals.deleted`
+  - `totals.new`
+- Report additions
+  - Environment-mismatch banner
+  - Deleted baselines section
+  - Per-action candidate + a11y-only-drift notes
+
+### Changed
+
+- **Breaking:** `tuffgal approve` no longer writes committed baselines
+  - Plain `approve` targets the local cache only
+  - Committed baselines are written solely by `approve --from` (CI/bot promo path)
+  - Local runs are advisory
+    - Exit `0` on visual drift
+    - Exit `1` on failed stories only
+    - Exit codes `2` and `3` are CI-mode only
+- In CI mode an accessibility-tree drift now gates status
+  - Pixels can match while the aria snapshot differs
+  - Flips the action to `changed`
+  - Stays advisory (informational) in local mode
+- Every committed baseline, candidate, and cache write is losslessly recompressed
+  - pngjs, deflate level 9 + adaptive filtering
+  - Never lossy, never quantized
+
+## [0.1.0-alpha.14] — 2026-07-04
+
+### Fixed
+
+A `viewport` capture no longer resets the page's scroll offset before shooting.
+
+## [0.1.0-alpha.13] — 2026-06-30
+
+### Changed
+
+HTML report filters have been merged with the summary row. Plus a few other
+miscellaneous UI/UX improvements.
+
+## [0.1.0-alpha.12] — 2026-06-27
+
+### Fixed
+
+`tuffgal` did nothing when launched through the installed `.bin` symlink,
+e.g. `npm run`, `npx`, or a bare `tuffgal`. The entry-point check compared
+the unresolved symlink path against the symlink-resolved module URL, so
+`main()` never ran. The script now resolves `argv[1]` through realpath
+before the comparison.
+
+## [0.1.0-alpha.11] — 2026-06-26
+
+### Added
+
+- Approve by breakpoint (e.g. `approve --desktop`, `approve --breakpoint <name>`)
+- Approve by story (e.g. `approve user-logs-in`)
+- `captureMode` config to limit screenshots to viewport-only or full page
+- Documentation for CLI and reports
+- `interactiveMode` config to view baseline/actual/diffs in a single-image view
+- New baselines can now be filtered in the HTML report
+- New baselines are now listed in the terminal summary report
+
+### Changed
+
+- Screenshots default to viewport-only (were previously full page)
+
+### Fixed
+
+- Multiple breakpoint runs no longer leak database state
+- Report filters now only show matching actions inside each story
+
+## [0.1.0-alpha.10] — 2026-06-22
+
+### Added
+
+- `${breakpoint}` interpolation token
+
+### Fixed
+
+- Per-breakpoint database isolation
 
 ## [0.1.0-alpha.9] — 2026-06-21
 
@@ -139,7 +279,14 @@ styling or interactivity.
 Initial public alpha. Tuffgal extracted from [Linklater](https://github.com/nschneble/linklater)'s
 in-tree visual testing workspace.
 
-[Unreleased]: https://github.com/nschneble/tuffgal/compare/v0.1.0-alpha.9...HEAD
+[Unreleased]: https://github.com/nschneble/tuffgal/compare/v0.2.0-alpha.2...HEAD
+[0.2.0-alpha.2]: https://github.com/nschneble/tuffgal/releases/tag/v0.2.0-alpha.2
+[0.2.0-alpha.1]: https://github.com/nschneble/tuffgal/releases/tag/v0.2.0-alpha.1
+[0.1.0-alpha.14]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.14
+[0.1.0-alpha.13]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.13
+[0.1.0-alpha.12]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.12
+[0.1.0-alpha.11]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.11
+[0.1.0-alpha.10]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.10
 [0.1.0-alpha.9]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.9
 [0.1.0-alpha.8]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.8
 [0.1.0-alpha.7]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.7

package/README.md

@@ -18,10 +18,79 @@ Tuffgal sits between component tests (which are fast but mocked) and
 end-to-end tests (which are real but verbose). You write **actions**
 (atomic user steps) and **stories** (chains of actions) as pure JSON. The
 harness runs them in a real browser, captures a screenshot after each
-story, and pixel-diffs against a baseline you commit alongside your code.
+action, and pixel-diffs against a committed baseline.
 
 When a screenshot changes, a human reviews the diff and decides what to do.
 
+## CI owns the baselines
+
+Committed baselines are the source of truth for what your UI is supposed to look
+like, and **CI is their only writer**. That makes a visual change a pull-request
+review gate, exactly like a code change: CI renders the current UI, diffs it
+against the committed baselines, and if anything drifted it fails the check and
+publishes the new screenshots as an artifact. A human looks at the diff and,
+if the change is intended, promotes those screenshots into the committed set. No
+local run can overwrite the baselines your reviewers rely on.
+
+A `tuffgal run` executes under one of two modes:
+
+- **CI mode** compares against the committed baselines (`paths.baselines`) and
+  never writes them. A missing baseline is `new`, an orphaned one is `deleted`,
+  and drift is `changed` — all of which are written into a self-contained
+  **candidate tree** under `<report>/candidates/` for approval, not committed in
+  place. CI mode gates: pending changes exit `2`.
+- **Local mode** is advisory. It compares against a gitignored, per-machine
+  cache (`paths.localCache`) so you can self-diff while you iterate, seeding a
+  missing entry on first sight. A local run **never reads or writes the
+  committed baselines**, and never fails your build on visual drift — it surfaces
+  the signal in the report and on stdout and **exits `0`**. Only a failed story
+  (a step that threw) exits `1`; the CI-gating codes `2` and `3` never fire
+  locally.
+
+Mode resolves from `--ci` / `--local` (an explicit flag always wins). With
+neither, Tuffgal picks CI when `$CI` is truthy and local otherwise, so the same
+`tuffgal run` does the right thing on a laptop and in a workflow.
+
+### Approving a visual change
+
+Two ways to accept a `changed`/`new` candidate into the committed baselines,
+both writing through the single `approve --from` promotion path:
+
+- **Download and commit.** Grab the `candidates` artifact CI uploaded, run
+  `tuffgal approve --from <dir>` against it, and commit the resulting baselines.
+  `--from` refuses any candidate that is not a clean CI run (`mode !== 'ci'` or a
+  failed story), so a local or broken run can never be promoted. Add `--prune`
+  to also retire baselines the run flagged as `deleted`.
+- **Comment on the PR.** The intended flow is a `@tuffgal approve` PR comment
+  that runs the same promotion on the CI side. The Action that handles this is a
+  downstream, not-yet-shipped repo, so treat this as the direction of travel
+  rather than a shipped button today.
+
+Plain `tuffgal approve` (no `--from`) targets your **local cache** only — it
+accepts your own self-diff so your next local run is clean. It does not touch the
+committed set.
+
+### The environment manifest
+
+`approve --from` also writes `baselines/manifest.json` recording the environment
+the promoted baselines were captured under (capture schema, browser version,
+platform, capture mode, breakpoints, device scale factor, frozen time). On the
+next `run --ci` Tuffgal checks the live capture environment against it. A
+pixel-affecting mismatch still runs the comparison, but banners the report and
+exits `3` — the signal is "expect a full re-approve", distinct from ordinary
+pending changes.
+
+### Exit codes
+
+| Code | Mode | Meaning                                                                   |
+| ---- | ---- | ------------------------------------------------------------------------- |
+| `0`  | both | Clean: no failures; in CI, no pending changes and the environment matched |
+| `1`  | both | One or more stories failed (a step threw). Highest precedence             |
+| `3`  | CI   | Committed environment manifest diverged from this run's environment       |
+| `2`  | CI   | Pending baseline changes to approve (`new`, `changed`, or `deleted`)      |
+
+Precedence is `1` > `3` > `2` > `0`. Local mode only ever exits `1` or `0`.
+
 ## What ships in v1
 
 - 9 step primitives composed into actions: `click`, `input`, `intercept`,
@@ -31,13 +100,17 @@ When a screenshot changes, a human reviews the diff and decides what to do.
   Tailwind widths. Pick which to run per project or per story. Each mode
   gets its own baseline and a per-mode group in the HTML report
 - DAG scheduler with `needs`/`produces` labels and parallel workers
-- SSIM-gated visual diff + pixelmatch overlay + a11y-tree snapshots
+- CI-owned baselines: CI is the sole writer, local runs are advisory self-diff,
+  approval flows through a CI candidate tree + environment manifest
+- SSIM-gated visual diff + pixelmatch overlay + a11y-tree snapshots (in CI an
+  a11y-tree drift also flips a pixel-passing action to `changed`)
 - Trace zip on failure (Playwright trace viewer)
 - Clock freeze (`page.clock.install`)
 - Storage-state persistence across stories
 - Static HTML reporter
 - V8 coverage (optional via `monocart-coverage-reports`)
-- Per-run DB reset + per-story fixture hooks (consumer-supplied via config)
+- Per-run DB reset + per-breakpoint fixture hooks (consumer-supplied via config),
+  plus a `${breakpoint}` interpolation token for per-mode test data
 - Process supervisor for dev-server hot-reload rot (it happens)
 
 ## What's explicitly out of scope (v1)
@@ -66,10 +139,12 @@ composite action.
 - [Authoring guide](docs/authoring.md)
 - [Changelog](CHANGELOG.md)
 - [CI integration](docs/ci.md)
+- [CLI reference](docs/cli.md)
 - [Config reference](docs/config.md)
 - [Migrating from Cypress](docs/migration-cypress.md)
 - [Migrating from Playwright](docs/migration-playwright.md)
 - [Product requirements](docs/prd-v1.md)
+- [Reporting data (results.json)](docs/reporting.md)
 - [Supervisor](docs/supervisor.md)
 
 ## License

package/dist/cli.d.ts

@@ -1,3 +1,53 @@
 #!/usr/bin/env node
+declare const COMMANDS: readonly ["approve", "help", "init", "run", "supervise"];
+type Command = (typeof COMMANDS)[number];
+interface ParsedArguments {
+    command: Command;
+    coverage: boolean;
+    headed: boolean;
+    manageServers: boolean;
+    healthcheckIntervalMs?: number;
+    idleLimitMs?: number;
+    maxRespawns?: number;
+    maxRuntimeMs?: number;
+    newOnly: boolean;
+    /**
+     * `approve --from <dir>`: promote a CI candidate tree into the committed
+     * baselines. The one command that writes `paths.baselines`.
+     */
+    from?: string;
+    /** `approve --prune`: delete orphaned baselines listed in the candidate results. */
+    prune: boolean;
+    /** `--ci` flag: force CI comparison mode. Mutually exclusive with `--local`. */
+    ci: boolean;
+    /** `--local` flag: force local (advisory) mode. Mutually exclusive with `--ci`. */
+    local: boolean;
+    storyFilter?: string;
+    /** Bare positional argument (e.g. `approve user-logs-in`). */
+    positional?: string;
+    /** `--breakpoint <name>` (repeatable) plus `--<name>` shorthands. */
+    breakpoints: string[];
+    workers?: number;
+}
+export declare function parseArguments(argv: string[]): ParsedArguments;
+/**
+ * Validates cross-command flag placement, returning the first error message or
+ * `undefined` when the flag set is legal for the parsed command. Pure (no
+ * `process.exit`) so the command × flag matrix is unit-testable in isolation;
+ * `main` calls it and routes any message through {@link failExit}. Covers the
+ * flags that only mean something on a specific subcommand:
+ *   - `--new-only`, `--breakpoint`/`--<name>`, and a bare positional narrow an
+ *     approval set — meaningless on any command but `approve`.
+ *   - `--from`/`--prune` promote a CI candidate tree — only on `approve`.
+ *   - `--ci`/`--local` pick the comparison contract — meaningful only on `run`.
+ *
+ * `approve` itself is two disjoint modes: plain (cache refresh, accepts the
+ * local-narrowing filters) and `--from` (baseline promotion, a whole-tree copy).
+ * The filters target the plain cache mode, so `--from` rejects them for v1 —
+ * partial `--from` approvals are a PRD backlog item. `--prune` is a `--from`
+ * modifier and is meaningless without it.
+ */
+export declare function validateCommandFlags(args: ParsedArguments): string | undefined;
+export declare function isMainEntry(moduleUrl: string, scriptPath: string | undefined): boolean;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAcA,QAAA,MAAM,QAAQ,0DAA2D,CAAC;AAC1E,KAAK,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAKzC,UAAU,eAAe;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,EAAE,EAAE,OAAO,CAAC;IACZ,mFAAmF;IACnF,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA8G9D;AA6ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,GACpB,MAAM,GAAG,SAAS,CAoCpB;AAoGD,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAWT"}

package/dist/cli.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { approveAll } from "./runner/approve.js";
+import { approveFrom } from "./runner/approveFrom.js";
 import { init } from "./commands/init.js";
-import { loadConfig } from "./config.js";
+import { BREAKPOINTS, loadConfig } from "./config.js";
+import { deriveExitCode } from "./runner/exitCode.js";
+import { resolveRunMode } from "./runner/mode.js";
 import { runAll } from "./runner/run.js";
+import { normaliseStoryArg } from "./runner/storyFilter.js";
 import { supervise } from "./commands/supervise.js";
 const COMMANDS = ['approve', 'help', 'init', 'run', 'supervise'];
-function parseArguments(argv) {
+/** Registry breakpoint names that double as `--<name>` approve shorthands. */
+const BREAKPOINT_FLAGS = Object.keys(BREAKPOINTS);
+export function parseArguments(argv) {
     const [command, ...rest] = argv;
     const parsed = {
         command: COMMANDS.includes(command)
@@ -15,6 +24,17 @@ function parseArguments(argv) {
         manageServers: false,
         coverage: false,
         newOnly: false,
+        prune: false,
+        ci: false,
+        local: false,
+        breakpoints: [],
+    };
+    const addBreakpoint = (name) => {
+        if (name === undefined || name === '') {
+            throw new Error('--breakpoint requires a mode name (e.g. desktop)');
+        }
+        if (!parsed.breakpoints.includes(name))
+            parsed.breakpoints.push(name);
     };
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
@@ -30,6 +50,23 @@ function parseArguments(argv) {
         else if (arg.startsWith('--story=')) {
             parsed.storyFilter = arg.slice('--story='.length);
         }
+        else if (arg === '--breakpoint') {
+            addBreakpoint(rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--breakpoint=')) {
+            addBreakpoint(arg.slice('--breakpoint='.length));
+        }
+        else if (arg.startsWith('--') &&
+            BREAKPOINT_FLAGS.includes(arg.slice(2))) {
+            addBreakpoint(arg.slice(2));
+        }
+        else if (!arg.startsWith('-')) {
+            if (parsed.positional !== undefined) {
+                throw new Error(`unexpected extra argument "${arg}" (already got "${parsed.positional}")`);
+            }
+            parsed.positional = arg;
+        }
         else if (arg === '--workers') {
             parsed.workers = numericFlag('--workers', rest[index + 1]);
             index += 1;
@@ -46,6 +83,22 @@ function parseArguments(argv) {
         else if (arg === '--new-only') {
             parsed.newOnly = true;
         }
+        else if (arg === '--from') {
+            parsed.from = stringFlag('--from', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--from=')) {
+            parsed.from = stringFlag('--from', arg.slice('--from='.length));
+        }
+        else if (arg === '--prune') {
+            parsed.prune = true;
+        }
+        else if (arg === '--ci') {
+            parsed.ci = true;
+        }
+        else if (arg === '--local') {
+            parsed.local = true;
+        }
         else if (arg === '--healthcheck-interval') {
             parsed.healthcheckIntervalMs = numericFlag('--healthcheck-interval', rest[index + 1]);
             index += 1;
@@ -93,13 +146,20 @@ function numericFlag(flag, raw) {
     }
     return value;
 }
+/** Parses a string-valued CLI flag, rejecting a missing/empty value. */
+function stringFlag(flag, raw) {
+    if (raw === undefined || raw === '' || raw.startsWith('-')) {
+        throw new Error(`${flag} requires a value (got "${raw ?? ''}")`);
+    }
+    return raw;
+}
 function printHelp() {
     process.stdout.write([
         'Usage: tuffgal <command> [options]',
         '',
         'Commands:',
         '  run                 Run every story under the configured stories directory.',
-        '  approve             Promote every "changed" actual to its baseline.',
+        '  approve             Refresh the local comparison cache from the last run.',
         '  init                Scaffold a tuffgal.config.ts in the current directory.',
         '  supervise           Long-running wrapper around devServers.command with',
         '                      healthcheck restart, idle auto-term, and wall-clock cap.',
@@ -107,13 +167,24 @@ function printHelp() {
         '',
         'Options:',
         '  --story <name>             Filter to a single story (filename or story text).',
+        '  --ci                       Force CI mode (compare vs committed baselines). Default when $CI is set.',
+        '  --local                    Force local advisory mode (self-diff vs per-machine cache).',
         '  --headed                   Show the browser while running.',
         '  --workers N                Override the worker pool size (default min(cpus/2, 4)).',
         '  --manage-servers           Spawn devServers.command, wait, run, then kill it.',
         '  --coverage                 Capture V8 JS + CSS coverage and emit a monocart report.',
         '',
-        'Approve options:',
-        '  --new-only                 Only promote new baselines; skip changed.',
+        'Approve options (local cache refresh):',
+        '  <story>                    Positional story to approve (name or path); same as --story.',
+        '  --new-only                 Only refresh new cache entries; skip changed.',
+        '  --breakpoint <name>        Only approve this mode; repeatable. Also --desktop/--mobile/etc.',
+        '',
+        'Approve options (CI baseline promotion):',
+        '  --from <dir>               Promote a CI candidate tree into the committed baselines.',
+        '                             The only command that writes paths.baselines. Rejects the',
+        '                             cache-refresh filters above (whole-tree copy).',
+        '  --prune                    With --from, delete orphaned baselines the candidate',
+        '                             run recorded as deleted. Requires --from.',
         '',
         'Supervise options:',
         '  --healthcheck-interval N   Probe interval in ms (default 30_000).',
@@ -122,14 +193,69 @@ function printHelp() {
         '  --max-respawns N           Respawn budget after unhealthy/exit (default 3).',
     ].join('\n') + '\n');
 }
+function failExit(message) {
+    process.stderr.write(`tuffgal error: ${message}\n`);
+    process.exit(1);
+}
+/**
+ * Validates cross-command flag placement, returning the first error message or
+ * `undefined` when the flag set is legal for the parsed command. Pure (no
+ * `process.exit`) so the command × flag matrix is unit-testable in isolation;
+ * `main` calls it and routes any message through {@link failExit}. Covers the
+ * flags that only mean something on a specific subcommand:
+ *   - `--new-only`, `--breakpoint`/`--<name>`, and a bare positional narrow an
+ *     approval set — meaningless on any command but `approve`.
+ *   - `--from`/`--prune` promote a CI candidate tree — only on `approve`.
+ *   - `--ci`/`--local` pick the comparison contract — meaningful only on `run`.
+ *
+ * `approve` itself is two disjoint modes: plain (cache refresh, accepts the
+ * local-narrowing filters) and `--from` (baseline promotion, a whole-tree copy).
+ * The filters target the plain cache mode, so `--from` rejects them for v1 —
+ * partial `--from` approvals are a PRD backlog item. `--prune` is a `--from`
+ * modifier and is meaningless without it.
+ */
+export function validateCommandFlags(args) {
+    if (args.command !== 'approve') {
+        if (args.newOnly) {
+            return '--new-only is only valid with the `approve` subcommand';
+        }
+        if (args.breakpoints.length > 0) {
+            return '--breakpoint (and --desktop/--mobile/…) is only valid with the `approve` subcommand';
+        }
+        if (args.positional !== undefined) {
+            return `unexpected argument "${args.positional}"`;
+        }
+        if (args.from !== undefined) {
+            return '--from is only valid with the `approve` subcommand';
+        }
+        if (args.prune) {
+            return '--prune is only valid with the `approve` subcommand';
+        }
+    }
+    if (args.prune && args.from === undefined) {
+        return '--prune requires --from (it prunes orphans listed in the candidate results)';
+    }
+    if (args.from !== undefined) {
+        if (args.storyFilter !== undefined || args.positional !== undefined) {
+            return '--from cannot be combined with a story filter (--from promotes the whole candidate tree)';
+        }
+        if (args.newOnly) {
+            return '--from cannot be combined with --new-only';
+        }
+        if (args.breakpoints.length > 0) {
+            return '--from cannot be combined with --breakpoint';
+        }
+    }
+    if (args.command !== 'run' && (args.ci || args.local)) {
+        return '--ci and --local are only valid with the `run` subcommand';
+    }
+    return undefined;
+}
 async function main() {
     const args = parseArguments(process.argv.slice(2));
-    if (args.newOnly &&
-        (args.command === 'run' ||
-            args.command === 'supervise' ||
-            args.command === 'init')) {
-        process.stderr.write('tuffgal error: --new-only is only valid with the `approve` subcommand\n');
-        process.exit(1);
+    const flagError = validateCommandFlags(args);
+    if (flagError) {
+        failExit(flagError);
     }
     if (args.command === 'help') {
         printHelp();
@@ -141,21 +267,58 @@ async function main() {
     }
     const config = await loadConfig(process.cwd());
     if (args.command === 'run') {
+        let mode;
+        try {
+            mode = resolveRunMode({
+                ci: args.ci,
+                local: args.local,
+                env: process.env,
+            });
+        }
+        catch (error) {
+            failExit(error instanceof Error ? error.message : String(error));
+        }
         const result = await runAll(config, {
             storyFilter: args.storyFilter,
             headed: args.headed,
             workers: args.workers,
             manageServers: args.manageServers,
             coverage: args.coverage,
+            mode,
         });
-        process.exit(result.totals.failed > 0 ? 1 : 0);
+        process.exit(deriveExitCode(mode, result.totals, result.environment?.mismatch ?? false));
     }
     if (args.command === 'approve') {
+        if (args.from !== undefined) {
+            // Baseline-promotion mode: promote a CI candidate tree into the committed
+            // baselines. `validateCommandFlags` has already rejected the local-mode
+            // filters, so nothing here narrows the tree.
+            try {
+                const summary = await approveFrom(config, {
+                    from: resolve(process.cwd(), args.from),
+                    prune: args.prune,
+                });
+                process.stdout.write(`\nPromoted ${summary.written} baselines; pruned ${summary.pruned} orphans.\n`);
+            }
+            catch (error) {
+                failExit(error instanceof Error ? error.message : String(error));
+            }
+            return;
+        }
+        // A story may be named positionally (`approve user-logs-in`) or via
+        // `--story`, but not both.
+        if (args.positional !== undefined && args.storyFilter !== undefined) {
+            failExit('name a story positionally or with --story, not both');
+        }
+        const storyFilter = args.positional !== undefined
+            ? normaliseStoryArg(args.positional)
+            : args.storyFilter;
         const summary = await approveAll(config, {
-            storyFilter: args.storyFilter,
+            storyFilter,
             newOnly: args.newOnly,
+            breakpoints: args.breakpoints,
         });
-        process.stdout.write(`\nApproved ${summary.approved} baselines; skipped ${summary.skipped} actions.\n`);
+        process.stdout.write(`\nRefreshed ${summary.approved} cache entries; skipped ${summary.skipped} actions.\n`);
     }
     if (args.command === 'supervise') {
         await supervise(config, {
@@ -166,8 +329,31 @@ async function main() {
         });
     }
 }
-main().catch((error) => {
-    process.stderr.write(`tuffgal error: ${error instanceof Error ? error.message : String(error)}\n`);
-    process.exit(1);
-});
+// Only drive the CLI when run as the entry point. Importing this module (e.g.
+// from a unit test exercising `parseArguments`) must not kick off a real run.
+//
+// `argv[1]` must be resolved through realpath before comparing: when installed,
+// the `tuffgal` command is a symlink (`node_modules/.bin/tuffgal` ->
+// `../tuffgal/dist/cli.js`). Node leaves that symlink unresolved in `argv[1]`
+// but resolves it in `import.meta.url`, so a raw comparison never matches and
+// `main()` silently never runs. Resolving both sides to the real file fixes it.
+export function isMainEntry(moduleUrl, scriptPath) {
+    if (!scriptPath) {
+        return false;
+    }
+    let resolvedPath;
+    try {
+        resolvedPath = realpathSync(scriptPath);
+    }
+    catch {
+        resolvedPath = scriptPath;
+    }
+    return moduleUrl === pathToFileURL(resolvedPath).href;
+}
+if (isMainEntry(import.meta.url, process.argv[1])) {
+    main().catch((error) => {
+        process.stderr.write(`tuffgal error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=cli.js.map