tuffgal 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Schneble
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# Tuffgal
+
+![GitHub License](https://img.shields.io/github/license/nschneble/tuffgal)
+
+> JSON-driven visual regression for web apps. Authoring stays declarative,
+> screenshots become a committable build artifact.
+
+<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).
+
+Public API is unstable until `v1.0.0`.
+
+## The idea
+
+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.
+
+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
+- 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
+- V8 coverage (optional via `monocart-coverage-reports`)
+- Per-story DB reset + fixture hooks (consumer-supplied via config)
+- Process supervisor for dev-server hot-reload rot (it happens)
+
+## What's explicitly out of scope (v1)
+
+- AI fuzzy locator matching (deferred to v1.1, BYOLLM)
+- Hosted SaaS / cloud runs
+- Native mobile (Playwright cannot drive it)
+- WebDriver / Puppeteer substrate
+- Supporting browsers other than Chromium
+
+## Quick start (when alpha releases)
+
+```bash
+npm install -D tuffgal
+npx tuffgal init  # scaffolds tuffgal.config.ts
+npx tuffgal run   # runs all stories
+```
+
+## Documentation
+
+- [App contract](docs/app-contract.md)
+- [Authoring guide](docs/authoring.md)
+- [CI integration](docs/ci.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)
+- [Supervisor](docs/supervisor.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Roadmap
+
+| Milestone                  | Status   |
+| -------------------------- | -------- |
+| Repo bootstrap             | ✅       |
+| Core extraction            | ✅       |
+| Bridges                    | ✅       |
+| Linklater migration        | ✅       |
+| GitHub Action              | 🚧       |
+| `v0.1.0-alpha` npm publish | 🚧       |
+| `v1.0.0` public launch     | ⏳       |
+| `v1.1.0` AI fuzzy matching | Deferred |
+
+## Acknowledgements
+
+The Tuffgal logo is an illustration by [Art Attack](https://unsplash.com/@artattackzone) on [Unsplash](https://unsplash.com/illustrations/a-woman-with-two-dumbs-in-her-hands-0GxJHpQzVvs).

package/bin/tuffgal.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env -S node --experimental-strip-types
+import '../src/cli.ts';

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "tuffgal",
+  "version": "0.1.0-alpha.0",
+  "description": "JSON-driven visual regression for web apps.",
+  "license": "MIT",
+  "author": "Nick Schneble",
+  "homepage": "https://github.com/nschneble/tuffgal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nschneble/tuffgal.git"
+  },
+  "scripts": {
+    "build": "echo \"no build step until v0.1.0-alpha\" && exit 0",
+    "format": "prettier --write \"**/*.{ts,tsx,json,md}\"",
+    "install:browsers": "playwright install chromium",
+    "lint": "eslint \"src/**/*.ts\" \"bin/**/*.mjs\" --max-warnings=0",
+    "prepublishOnly": "npm run lint && npm run typecheck",
+    "test": "echo \"no tests yet\" && exit 0",
+    "typecheck": "tsc --noEmit"
+  },
+  "bin": {
+    "tuffgal": "./bin/tuffgal.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/nschneble/tuffgal/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "bin/",
+    "LICENSE",
+    "README.md",
+    "src/"
+  ],
+  "keywords": [
+    "playwright",
+    "screenshots",
+    "snapshot-testing",
+    "ssim",
+    "testing",
+    "ui-testing",
+    "visual-regression"
+  ],
+  "main": "./src/index.ts",
+  "type": "module",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "monocart-coverage-reports": "^2.12.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.49.0",
+    "pngjs": "^7.0.0",
+    "ssim.js": "^3.5.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.7.4",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.49.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { init } from './commands/init.ts';
+import { supervise } from './commands/supervise.ts';
+import { loadConfig } from './config.ts';
+import { approveAll } from './runner/approve.ts';
+import { runAll } from './runner/run.ts';
+
+interface ParsedArguments {
+  command: 'run' | 'approve' | 'init' | 'supervise' | 'help';
+  storyFilter?: string;
+  headed: boolean;
+  workers?: number;
+  manageServers: boolean;
+  coverage: boolean;
+  healthcheckIntervalMs?: number;
+  idleLimitMs?: number;
+  maxRuntimeMs?: number;
+  maxRespawns?: number;
+}
+
+function parseArguments(argv: string[]): ParsedArguments {
+  const [command, ...rest] = argv;
+  const parsed: ParsedArguments = {
+    command:
+      command === 'run' ||
+      command === 'approve' ||
+      command === 'init' ||
+      command === 'supervise' ||
+      command === 'help'
+        ? command
+        : 'help',
+    headed: false,
+    manageServers: false,
+    coverage: 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 = Number(rest[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--workers=')) {
+      parsed.workers = Number(arg.slice('--workers='.length));
+    } else if (arg === '--manage-servers') {
+      parsed.manageServers = true;
+    } else if (arg === '--coverage') {
+      parsed.coverage = true;
+    } else if (arg === '--healthcheck-interval') {
+      parsed.healthcheckIntervalMs = Number(rest[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--healthcheck-interval=')) {
+      parsed.healthcheckIntervalMs = Number(
+        arg.slice('--healthcheck-interval='.length),
+      );
+    } else if (arg === '--idle-limit') {
+      parsed.idleLimitMs = Number(rest[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--idle-limit=')) {
+      parsed.idleLimitMs = Number(arg.slice('--idle-limit='.length));
+    } else if (arg === '--max-runtime') {
+      parsed.maxRuntimeMs = Number(rest[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--max-runtime=')) {
+      parsed.maxRuntimeMs = Number(arg.slice('--max-runtime='.length));
+    } else if (arg === '--max-respawns') {
+      parsed.maxRespawns = Number(rest[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--max-respawns=')) {
+      parsed.maxRespawns = Number(arg.slice('--max-respawns='.length));
+    }
+  }
+  return parsed;
+}
+
+function printHelp(): void {
+  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.',
+      '',
+      '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(): Promise<void> {
+  const args = parseArguments(process.argv.slice(2));
+  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.stdout.write(
+      `\nTotals: ${result.totals.passed} pass · ${result.totals.changed} changed · ${result.totals.failed} failed\n`,
+    );
+    process.exit(result.totals.failed > 0 ? 1 : 0);
+  }
+  if (args.command === 'approve') {
+    const summary = await approveAll(config, {
+      storyFilter: args.storyFilter,
+    });
+    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);
+});

package/src/commands/init.ts

@@ -0,0 +1,140 @@
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+const CONFIG_FILES = ['tuffgal.config.ts', 'tuffgal.config.js'];
+
+const CONFIG_TEMPLATE = `import { defineConfig } from 'tuffgal';
+
+/**
+ * Tuffgal config. The full field reference lives at
+ * https://github.com/nschneble/tuffgal/blob/main/docs/config.md.
+ *
+ * Required: \`paths\` and \`baseUrl\`. Everything else is optional with
+ * sensible defaults.
+ */
+export default defineConfig({
+  paths: {
+    actions: 'tuffgal/actions',
+    stories: 'tuffgal/stories',
+    baselines: 'tuffgal/baselines',
+    report: 'tuffgal/report',
+    authState: 'tuffgal/.auth',
+  },
+
+  baseUrl: process.env.APP_BASE_URL ?? 'http://localhost:5173',
+
+  // Uncomment if your app makes API calls under a different origin. Used
+  // by intercept patterns to scope routes to API traffic.
+  // apiHost: 'http://localhost:3000',
+
+  // localStorage keys to persist across stories. Cookie-based apps may
+  // leave this empty — cookies always persist via Playwright storage state.
+  // storageStatePins: ['session_token'],
+
+  viewport: { width: 1280, height: 800 },
+  defaultTimeoutMs: 10_000,
+  navigationTimeoutMs: 15_000,
+  frozenTime: '2026-01-15T12:00:00.000Z',
+
+  // Database bridge — wire to your reset + fixture functions. Skip the
+  // entire block for static sites. See examples/postgres-prisma/ for a
+  // working recipe.
+  // database: {
+  //   reset: async () => { /* truncate + reseed */ },
+  //   fixtures: {
+  //     'example-rows': async () => { /* idempotent inserts */ },
+  //   },
+  // },
+
+  // Dev-server bridge. Used by \`--manage-servers\` and \`tuffgal supervise\`.
+  // Omit when you run servers yourself.
+  // devServers: {
+  //   command: 'npm run dev:test',
+  //   healthCheck: [
+  //     { url: 'http://localhost:3000', timeoutMs: 120_000 },
+  //     { url: 'http://localhost:5173', timeoutMs: 120_000 },
+  //   ],
+  // },
+});
+`;
+
+const GITKEEP_SUBDIRECTORIES = [
+  '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)
+ *   - 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 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.`,
+      );
+    }
+  }
+
+  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;
+  }
+}