tuffgal 0.1.0-alpha.0 → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,174 @@
+# 🪵 Changelog
+
+**All notable project changes will be documented in this file.** The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project uses [Pride Versioning](https://pridever.org) → `PROUD.DEFAULT.SHAME`
+
+## [Unreleased]
+
+_Nothing right now_
+
+## [0.1.0-alpha.10] — 2026-06-22
+
+### Fixed
+
+- **Per-breakpoint database isolation.** alpha.9 ran each breakpoint in its own
+  browser context but applied a story's fixtures only once, before the
+  breakpoint loop — so a story that mutated server state passed at the first
+  mode and then ran the next mode against the mutated rows (a registered user
+  collided on the second mode, an already-read link no longer showed as unread,
+  an emptied list had nothing left to empty). Fixtures are now re-applied before
+  **every** breakpoint, resetting that state to a known baseline per mode.
+  Fixtures are idempotent, so non-mutating stories are unaffected.
+
+### Added
+
+- **`${breakpoint}` interpolation token.** The current mode name is exposed to
+  action interpolation as `${breakpoint}`, so a story can key data it creates
+  through the app (with no backing fixture to reset) per mode — e.g.
+  `fresh+${breakpoint}@example.test` registers a distinct user at each viewport
+  instead of colliding on a shared value. A story parameter literally named
+  `breakpoint` overrides the injected value.
+
+## [0.1.0-alpha.9] — 2026-06-21
+
+### Added
+
+- Breakpoint modes, replacing the single `viewport` config
+  - `mobile` 375×667 / `tablet` 768×1024 / `laptop` 1024×768 / `desktop` 1280×800
+  - Each mode runs in its own browser context + produces its own baselines
+  - Each `config.breakpoints` entry is a bare name (registry dimensions) or `{ name, width?, height? }` to override that mode's size; an omitted axis inherits the registry default
+  - Order preserved; when a name repeats, the first entry wins
+  - Omit `breakpoints` to run a single `desktop` mode (1280×800)
+  - Per-story `breakpoints` field, same shape, that **replaces** the project's modes for that story — a story may run a mode the project does not configure, and its overrides resolve against the registry
+  - Breakpoint grouping in the HTML report, each group labelled with the real capture size; a single-mode story renders as a flat list with no breakpoint chrome
+  - Pre-breakpoint baselines at `<action>/0.png` are read as fallbacks until promoted
+
+### Removed
+
+**Breaking:** `viewport` config field + per-story `viewport` override. Set
+a single mode's size with `breakpoints: [{ name: 'desktop', width, height }]`
+instead.
+
+## [0.1.0-alpha.8] — 2026-06-20
+
+### Fixed
+
+- Reset page scroll to origin before each full-page capture, so `position: sticky` and `fixed` elements no longer render shifted by `scrollY`
+
+## [0.1.0-alpha.7] — 2026-06-20
+
+### Added
+
+- Add `npm run preview` to render a sample HTML report
+
+### Changed
+
+- Capitalize the report title to "Tuffgal report" and show a friendlier timestamp
+- Convey story status as a colored, marked story name instead of a badge
+- Make the whole action row clickable to toggle screenshots
+- Move the expand/collapse buttons to the right of the filters; the story-count status now sits beside the filters, with filter-aware labels
+- Rename "pass" terminology to "passed" throughout the HTML report
+- Show the status badge as plain text (no glyphs)
+- Validate the consumer config before resolving it, failing with the config file path instead of an opaque `TypeError`
+
+### Fixed
+
+- Guard the diff core against non-RGBA PNG pixel formats so a format change fails loudly instead of scoring garbage
+- Memoize coverage init so concurrent workers no longer orphan the HTML report
+- Raise subtle-text contrast to clear WCAG 1.4.3 (4.5:1) in both light and dark themes
+- Reject non-finite or non-positive numeric CLI flags at parse time (e.g. `--idle-limit foo` no longer busy-loops the supervisor)
+- Render the HTML report's default screenshot server-side so screenshots still show when JavaScript fails or is disabled
+- Serialize per-baseline writes so stories sharing an action no longer race to create the same baseline under `--workers > 1`
+
+### Removed
+
+- Drop redundant "Failures" section at the bottom of the HTML report
+- Stop linking to Playwright trace in the HTML report
+
+## [0.1.0-alpha.6] — 2026-06-11
+
+### Added
+
+- Add per-story overrides for browser `viewport` optional config field
+- Add `tuffgal approve --new-only` flag to limit baselines to new stories
+- Allow reports to be filtered by passed, changed, or failed
+- Allow reports to expand/contract all screenshots
+
+### Changed
+
+- Edit `tuffgal run` output to group changed, failed at end w/ report link
+- Skip npm release if no version bump
+
+## [0.1.0-alpha.5] — 2026-06-11
+
+### Added
+
+`navigate` step accepts an optional `waitUntil` field (`'load' |
+'domcontentloaded' | 'networkidle' | 'commit'`) that overrides Playwright's
+`page.goto` ready signal on a per-step basis. Defaults to `'networkidle'`.
+Use `'domcontentloaded'` for dev-mode pages with long-tail external fetches
+that prevent `networkidle` from settling.
+
+## [0.1.0-alpha.4] — 2026-06-06
+
+### Added
+
+- `tuffgal approve` now updates the a11y snapshot at the same time as the screenshot
+- `--story` works the same way on both `tuffgal run` and `tuffgal approve`
+- Two stories with the same filename in different folders is now an error
+
+### Changed
+
+- Stories that get skipped b/c a prereq failed now show up in the run report + totals
+- Screenshot comparison uses SSIM only
+- README and `docs/` pages now match how the code actually works lol
+
+### Removed
+
+- **Breaking:** Removed the legacy `diff.maxDiffRatio` setting
+- **Breaking:** Dropped the `ci` block from `TuffgalConfig` and the public API
+- Removed stale `bin/**` and `schema/**` paths
+
+## [0.1.0-alpha.3] — 2026-06-06
+
+Grants clipboard permissions in browser contexts.
+
+Without `permissions: ['clipboard-read', 'clipboard-write']` Playwright
+default-denies clipboard API access, which breaks any story using the Web
+Clipboard API.
+
+## [0.1.0-alpha.2] — 2026-06-04
+
+`npm run build` now copies `src/reporter/assets/{report.css,report.js}`
+into `dist/reporter/assets/`. Earlier alpha builds shipped without the
+reporter's static assets, so the generated HTML report rendered without
+styling or interactivity.
+
+## [0.1.0-alpha.1] — 2026-06-04
+
+### Changed
+
+- Package now ships compiled `dist/` instead of raw `.ts` sources
+- CLI entry point is `./dist/cli.js`
+
+### Fixed
+
+- Corrected `bin` extension and publish flags for the alpha channel
+
+## [0.1.0-alpha.0] — 2026-06-04
+
+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
+[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
+[0.1.0-alpha.6]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.6
+[0.1.0-alpha.5]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.5
+[0.1.0-alpha.4]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.4
+[0.1.0-alpha.3]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.3
+[0.1.0-alpha.2]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.2
+[0.1.0-alpha.1]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.1
+[0.1.0-alpha.0]: https://github.com/nschneble/tuffgal/releases/tag/v0.1.0-alpha.0

package/README.md

@@ -1,14 +1,14 @@
 # Tuffgal
 
-![GitHub License](https://img.shields.io/github/license/nschneble/tuffgal)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-> JSON-driven visual regression for web apps. Authoring stays declarative,
-> screenshots become a committable build artifact.
+JSON-driven visual regression testing for web apps.
 
 <img src="tuffgal.png" alt="Tuffgal" />
 
-**Status:** Pre-release. `v0.1.0-alpha` in active extraction from the
-`apps/testing-ui` workspace in [Linklater](https://github.com/nschneble/linklater).
+**Status:** Pre-1.0. Published on npm as `tuffgal@0.1.0-alpha.{n}` with
+provenance. [Linklater](https://github.com/nschneble/linklater) is the
+pilot consumer.
 
 Public API is unstable until `v1.0.0`.
 
@@ -24,17 +24,21 @@ When a screenshot changes, a human reviews the diff and decides what to do.
 
 ## What ships in v1
 
-- 10 step primitives as action verbs: `click`, `input`, `intercept`,
-  `navigate`, `read`, `scroll`, `type`, `wait`, `waitFor`, and `screenshot`
-  as the implicit capture point
+- 9 step primitives composed into actions: `click`, `input`, `intercept`,
+  `navigate`, `read`, `scroll`, `type`, `wait`, `waitFor`
+- An implicit screenshot at the end of every action
+- Named breakpoint modes (`mobile`, `tablet`, `laptop`, `desktop`) keyed to
+  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
 - Trace zip on failure (Playwright trace viewer)
 - Clock freeze (`page.clock.install`)
 - Storage-state persistence across stories
-- Static HTML reporter + optional SARIF for GitHub code scanning
+- Static HTML reporter
 - V8 coverage (optional via `monocart-coverage-reports`)
-- Per-story DB reset + 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)
@@ -45,18 +49,23 @@ When a screenshot changes, a human reviews the diff and decides what to do.
 - WebDriver / Puppeteer substrate
 - Supporting browsers other than Chromium
 
-## Quick start (when alpha releases)
+## Quick start
 
 ```bash
-npm install -D tuffgal
+npm install -D tuffgal@alpha
 npx tuffgal init  # scaffolds tuffgal.config.ts
 npx tuffgal run   # runs all stories
 ```
 
+For CI on GitHub Actions, use the companion
+[`nschneble/tuffgal-action`](https://github.com/nschneble/tuffgal-action)
+composite action.
+
 ## Documentation
 
 - [App contract](docs/app-contract.md)
 - [Authoring guide](docs/authoring.md)
+- [Changelog](CHANGELOG.md)
 - [CI integration](docs/ci.md)
 - [Config reference](docs/config.md)
 - [Migrating from Cypress](docs/migration-cypress.md)
@@ -76,8 +85,8 @@ MIT. See [LICENSE](LICENSE).
 | Core extraction            | ✅       |
 | Bridges                    | ✅       |
 | Linklater migration        | ✅       |
-| GitHub Action              | 🚧       |
-| `v0.1.0-alpha` npm publish | 🚧       |
+| GitHub Action              | ✅       |
+| `v0.1.0-alpha` npm publish | ✅       |
 | `v1.0.0` public launch     | ⏳       |
 | `v1.1.0` AI fuzzy matching | Deferred |
 

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import { approveAll } from "./runner/approve.js";
+import { init } from "./commands/init.js";
+import { loadConfig } from "./config.js";
+import { runAll } from "./runner/run.js";
+import { supervise } from "./commands/supervise.js";
+const COMMANDS = ['approve', 'help', 'init', 'run', 'supervise'];
+function parseArguments(argv) {
+    const [command, ...rest] = argv;
+    const parsed = {
+        command: COMMANDS.includes(command)
+            ? command
+            : 'help',
+        headed: false,
+        manageServers: false,
+        coverage: false,
+        newOnly: false,
+    };
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === undefined)
+            continue;
+        if (arg === '--headed') {
+            parsed.headed = true;
+        }
+        else if (arg === '--story') {
+            parsed.storyFilter = rest[index + 1];
+            index += 1;
+        }
+        else if (arg.startsWith('--story=')) {
+            parsed.storyFilter = arg.slice('--story='.length);
+        }
+        else if (arg === '--workers') {
+            parsed.workers = numericFlag('--workers', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--workers=')) {
+            parsed.workers = numericFlag('--workers', arg.slice('--workers='.length));
+        }
+        else if (arg === '--manage-servers') {
+            parsed.manageServers = true;
+        }
+        else if (arg === '--coverage') {
+            parsed.coverage = true;
+        }
+        else if (arg === '--new-only') {
+            parsed.newOnly = true;
+        }
+        else if (arg === '--healthcheck-interval') {
+            parsed.healthcheckIntervalMs = numericFlag('--healthcheck-interval', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--healthcheck-interval=')) {
+            parsed.healthcheckIntervalMs = numericFlag('--healthcheck-interval', arg.slice('--healthcheck-interval='.length));
+        }
+        else if (arg === '--idle-limit') {
+            parsed.idleLimitMs = numericFlag('--idle-limit', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--idle-limit=')) {
+            parsed.idleLimitMs = numericFlag('--idle-limit', arg.slice('--idle-limit='.length));
+        }
+        else if (arg === '--max-runtime') {
+            parsed.maxRuntimeMs = numericFlag('--max-runtime', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--max-runtime=')) {
+            parsed.maxRuntimeMs = numericFlag('--max-runtime', arg.slice('--max-runtime='.length));
+        }
+        else if (arg === '--max-respawns') {
+            parsed.maxRespawns = numericFlag('--max-respawns', rest[index + 1]);
+            index += 1;
+        }
+        else if (arg.startsWith('--max-respawns=')) {
+            parsed.maxRespawns = numericFlag('--max-respawns', arg.slice('--max-respawns='.length));
+        }
+    }
+    return parsed;
+}
+/**
+ * Parses a numeric CLI flag, rejecting anything non-finite or <= 0. Without
+ * this, `--idle-limit foo` became `NaN` and flowed into `setTimeout(…, NaN)`,
+ * which behaves as `0` and busy-loops the supervisor's healthcheck. Fail loudly
+ * at parse time instead.
+ */
+function numericFlag(flag, raw) {
+    const value = Number(raw);
+    if (raw === undefined ||
+        raw === '' ||
+        !Number.isFinite(value) ||
+        value <= 0) {
+        throw new Error(`${flag} requires a positive number (got "${raw ?? ''}")`);
+    }
+    return value;
+}
+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.',
+        '  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.',
+        '  help                Show this message.',
+        '',
+        'Options:',
+        '  --story <name>             Filter to a single story (filename or story text).',
+        '  --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.',
+        '',
+        'Supervise options:',
+        '  --healthcheck-interval N   Probe interval in ms (default 30_000).',
+        '  --idle-limit N             Ms with no `tuffgal run` heartbeat before exit (default 600_000).',
+        '  --max-runtime N            Wall-clock cap in ms (default 3_600_000).',
+        '  --max-respawns N           Respawn budget after unhealthy/exit (default 3).',
+    ].join('\n') + '\n');
+}
+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);
+    }
+    if (args.command === 'help') {
+        printHelp();
+        return;
+    }
+    if (args.command === 'init') {
+        await init({ cwd: process.cwd() });
+        return;
+    }
+    const config = await loadConfig(process.cwd());
+    if (args.command === 'run') {
+        const result = await runAll(config, {
+            storyFilter: args.storyFilter,
+            headed: args.headed,
+            workers: args.workers,
+            manageServers: args.manageServers,
+            coverage: args.coverage,
+        });
+        process.exit(result.totals.failed > 0 ? 1 : 0);
+    }
+    if (args.command === 'approve') {
+        const summary = await approveAll(config, {
+            storyFilter: args.storyFilter,
+            newOnly: args.newOnly,
+        });
+        process.stdout.write(`\nApproved ${summary.approved} baselines; skipped ${summary.skipped} actions.\n`);
+    }
+    if (args.command === 'supervise') {
+        await supervise(config, {
+            healthcheckIntervalMs: args.healthcheckIntervalMs,
+            idleLimitMs: args.idleLimitMs,
+            maxRuntimeMs: args.maxRuntimeMs,
+            maxRespawns: args.maxRespawns,
+        });
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`tuffgal error: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/init.d.ts

@@ -0,0 +1,17 @@
+export interface InitOptions {
+    cwd: string;
+}
+/**
+ * Scaffolds a starter Tuffgal layout in the given directory:
+ *   - tuffgal.config.ts        (commented template)
+ *   - tuffgal/actions/.gitkeep
+ *   - tuffgal/stories/.gitkeep
+ *   - tuffgal/baselines/.gitkeep
+ *   - tuffgal/.gitignore       (ignores .auth/ and report/)
+ *
+ * Refuses to overwrite an existing tuffgal.config.{ts,js}. Existing
+ * scaffolded directories are left alone — a second \`init\` is safe to run
+ * after manually deleting just the config.
+ */
+export declare function init(options: InitOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA+EA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C9D"}

package/{src/commands/init.ts → dist/commands/init.js}

@@ -1,8 +1,7 @@
-import { mkdir, writeFile, access } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-
+import { pathExists } from "../util.js";
 const CONFIG_FILES = ['tuffgal.config.ts', 'tuffgal.config.js'];
-
 const CONFIG_TEMPLATE = `import { defineConfig } from 'tuffgal';
 
 /**
@@ -31,7 +30,14 @@ export default defineConfig({
   // leave this empty — cookies always persist via Playwright storage state.
   // storageStatePins: ['session_token'],
 
-  viewport: { width: 1280, height: 800 },
+  // Breakpoint modes to run, keyed to Tailwind widths:
+  //   mobile 375x667 · tablet 768x1024 · laptop 1024x768 · desktop 1280x800
+  // Each mode gets its own baseline + a group in the report. Omit to run a
+  // single \`desktop\` mode (1280x800). Override a mode's size with an object,
+  // e.g. { name: 'desktop', width: 1440, height: 900 }. A story can run its own
+  // modes via its own \`breakpoints\` field, which replace these for that story.
+  // breakpoints: ['mobile', 'tablet', 'laptop', 'desktop'],
+
   defaultTimeoutMs: 10_000,
   navigationTimeoutMs: 15_000,
   frozenTime: '2026-01-15T12:00:00.000Z',
@@ -57,22 +63,15 @@ export default defineConfig({
   // },
 });
 `;
-
 const GITKEEP_SUBDIRECTORIES = [
-  'tuffgal/actions',
-  'tuffgal/stories',
-  'tuffgal/baselines',
+    'tuffgal/actions',
+    'tuffgal/stories',
+    'tuffgal/baselines',
 ];
-
 const REPORT_GITIGNORE = `# Generated by Tuffgal — do not commit.
 .auth/
 report/
 `;
-
-export interface InitOptions {
-  cwd: string;
-}
-
 /**
  * Scaffolds a starter Tuffgal layout in the given directory:
  *   - tuffgal.config.ts        (commented template)
@@ -85,56 +84,39 @@ export interface InitOptions {
  * scaffolded directories are left alone — a second \`init\` is safe to run
  * after manually deleting just the config.
  */
-export async function init(options: InitOptions): Promise<void> {
-  const { cwd } = options;
-
-  for (const candidate of CONFIG_FILES) {
-    if (await pathExists(join(cwd, candidate))) {
-      throw new Error(
-        `${candidate} already exists at ${cwd}. Refusing to overwrite. ` +
-          `Delete it manually if you want to start over.`,
-      );
+export async function init(options) {
+    const { cwd } = options;
+    for (const candidate of CONFIG_FILES) {
+        if (await pathExists(join(cwd, candidate))) {
+            throw new Error(`${candidate} already exists at ${cwd}. Refusing to overwrite. ` +
+                `Delete it manually if you want to start over.`);
+        }
     }
-  }
-
-  const configPath = join(cwd, 'tuffgal.config.ts');
-  await writeFile(configPath, CONFIG_TEMPLATE, 'utf8');
-  process.stdout.write(`Wrote ${relative(cwd, configPath) || 'tuffgal.config.ts'}\n`);
-
-  for (const subdirectory of GITKEEP_SUBDIRECTORIES) {
-    const absolute = join(cwd, subdirectory);
-    await mkdir(absolute, { recursive: true });
-    const gitkeep = join(absolute, '.gitkeep');
-    if (!(await pathExists(gitkeep))) {
-      await writeFile(gitkeep, '', 'utf8');
-      process.stdout.write(`Wrote ${relative(cwd, gitkeep)}\n`);
+    const configPath = join(cwd, 'tuffgal.config.ts');
+    await writeFile(configPath, CONFIG_TEMPLATE, 'utf8');
+    process.stdout.write(`Wrote ${relative(cwd, configPath) || 'tuffgal.config.ts'}\n`);
+    for (const subdirectory of GITKEEP_SUBDIRECTORIES) {
+        const absolute = join(cwd, subdirectory);
+        await mkdir(absolute, { recursive: true });
+        const gitkeep = join(absolute, '.gitkeep');
+        if (!(await pathExists(gitkeep))) {
+            await writeFile(gitkeep, '', 'utf8');
+            process.stdout.write(`Wrote ${relative(cwd, gitkeep)}\n`);
+        }
     }
-  }
-
-  const gitignorePath = join(cwd, 'tuffgal', '.gitignore');
-  if (!(await pathExists(gitignorePath))) {
-    await writeFile(gitignorePath, REPORT_GITIGNORE, 'utf8');
-    process.stdout.write(`Wrote ${relative(cwd, gitignorePath)}\n`);
-  }
-
-  process.stdout.write(
-    [
-      '',
-      'Tuffgal scaffold ready. Next steps:',
-      '  1. Edit tuffgal.config.ts to point at your dev server.',
-      '  2. Write your first action under tuffgal/actions/.',
-      '  3. Write your first story under tuffgal/stories/.',
-      '  4. Run `npx tuffgal run` to capture baselines.',
-      '',
-    ].join('\n'),
-  );
-}
-
-async function pathExists(absolute: string): Promise<boolean> {
-  try {
-    await access(absolute);
-    return true;
-  } catch {
-    return false;
-  }
+    const gitignorePath = join(cwd, 'tuffgal', '.gitignore');
+    if (!(await pathExists(gitignorePath))) {
+        await writeFile(gitignorePath, REPORT_GITIGNORE, 'utf8');
+        process.stdout.write(`Wrote ${relative(cwd, gitignorePath)}\n`);
+    }
+    process.stdout.write([
+        '',
+        'Tuffgal scaffold ready. Next steps:',
+        '  1. Edit tuffgal.config.ts to point at your dev server.',
+        '  2. Write your first action under tuffgal/actions/.',
+        '  3. Write your first story under tuffgal/stories/.',
+        '  4. Run `npx tuffgal run` to capture baselines.',
+        '',
+    ].join('\n'));
 }
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,YAAY,GAAG,CAAC,mBAAmB,EAAE,mBAAmB,CAAC,CAAC;AAEhE,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DvB,CAAC;AAEF,MAAM,sBAAsB,GAAG;IAC7B,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;CACpB,CAAC;AAEF,MAAM,gBAAgB,GAAG;;;CAGxB,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAoB;IAC7C,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAExB,KAAK,MAAM,SAAS,IAAI,YAAY,EAAE,CAAC;QACrC,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACb,GAAG,SAAS,sBAAsB,GAAG,2BAA2B;gBAC9D,+CAA+C,CAClD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAClD,MAAM,SAAS,CAAC,UAAU,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,SAAS,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,mBAAmB,IAAI,CAC9D,CAAC;IAEF,KAAK,MAAM,YAAY,IAAI,sBAAsB,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACzC,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YACjC,MAAM,SAAS,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;QACvC,MAAM,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;QACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;QACE,EAAE;QACF,qCAAqC;QACrC,0DAA0D;QAC1D,sDAAsD;QACtD,qDAAqD;QACrD,kDAAkD;QAClD,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC"}

package/dist/commands/supervise.d.ts

@@ -0,0 +1,40 @@
+import type { ResolvedConfig } from '../config.ts';
+export interface SuperviseOptions {
+    /** Milliseconds between port + heartbeat probes. Default 30_000. */
+    healthcheckIntervalMs?: number;
+    /**
+     * Window with no `tuffgal run` heartbeat before the supervisor self-
+     * terminates. Default 10 minutes. The heartbeat file lives at
+     * `config.paths.report/.heartbeat` and is touched by every `tuffgal
+     * run` invocation.
+     */
+    idleLimitMs?: number;
+    /** Wall-clock cap, end-to-end. Default 60 minutes. */
+    maxRuntimeMs?: number;
+    /**
+     * How many times the supervisor may respawn `devServers.command` after
+     * an unhealthy probe or unexpected exit before giving up. Default 3.
+     */
+    maxRespawns?: number;
+}
+/**
+ * Long-running supervisor around `config.devServers.command`. Solves
+ * three problems observed during heavy harness iteration:
+ *
+ *   1. Hot-reload rot — after many file-watch restarts the framework
+ *      drifts into a broken state. Supervisor probes every declared
+ *      healthcheck URL and restarts the whole tree on failure.
+ *   2. Forgotten dev servers — supervisor self-terminates after a
+ *      wall-clock cap and after an idle window with no heartbeat from
+ *      `tuffgal run`.
+ *   3. Manual signal management — SIGINT/SIGTERM teardown kills the
+ *      whole detached process group, not just the shell wrapper.
+ *
+ * Each invocation of `tuffgal run` writes
+ * `config.paths.report/.heartbeat` (ISO timestamp). Supervisor reads
+ * its mtime every healthcheck. If `Date.now() - mtime > idleLimitMs`,
+ * supervisor shuts down. Missing heartbeat file is treated as "no runs
+ * yet", not stale, so a fresh shell does not self-terminate immediately.
+ */
+export declare function supervise(config: ResolvedConfig, options?: SuperviseOptions): Promise<void>;
+//# sourceMappingURL=supervise.d.ts.map