tuffgal 0.1.0-alpha.0

package/src/runner/scheduler.ts

@@ -0,0 +1,223 @@
+import { normalisedNeeds } from '../schema/story.ts';
+import type { StoryFile } from '../schema/load.ts';
+import type { StoryResult, StoryStatus } from '../schema/result.ts';
+
+export interface ScheduledStory extends StoryFile {
+  needs: string[];
+  produces: string[];
+}
+
+export interface ScheduleSummary {
+  ready: ScheduledStory[];
+  blocked: ScheduledStory[];
+}
+
+/**
+ * Validates that every produced label is emitted by at most one story and
+ * that every `needs` label has a matching producer. Throws a descriptive
+ * error on any mismatch so a typo in a JSON file fails loudly at load time,
+ * not at run time.
+ */
+export function buildSchedule(stories: StoryFile[]): ScheduledStory[] {
+  const scheduled: ScheduledStory[] = stories.map((entry) => ({
+    ...entry,
+    needs: normalisedNeeds(entry.story),
+    produces: entry.story.produces ?? [],
+  }));
+
+  const producerByLabel = new Map<string, string>();
+  for (const item of scheduled) {
+    for (const label of item.produces) {
+      const previous = producerByLabel.get(label);
+      if (previous !== undefined) {
+        throw new SchedulerError(
+          `Label "${label}" is produced by both ${previous} and ${item.file}. Labels must be unique.`,
+        );
+      }
+      producerByLabel.set(label, item.file);
+    }
+  }
+
+  for (const item of scheduled) {
+    for (const label of item.needs) {
+      if (!producerByLabel.has(label)) {
+        throw new SchedulerError(
+          `${item.file} needs label "${label}" but no story produces it.`,
+        );
+      }
+    }
+  }
+
+  detectCycles(scheduled, producerByLabel);
+  return scheduled;
+}
+
+interface RunContext {
+  satisfied: Set<string>;
+  completed: Set<string>;
+  inFlight: Set<string>;
+  results: Map<string, StoryResult>;
+  skipped: Set<string>;
+}
+
+export type StoryRunner = (scheduled: ScheduledStory) => Promise<StoryResult>;
+
+/**
+ * Drains the dependency graph with up to `workerCount` concurrent runs.
+ * Stories whose `needs` are satisfied move into the ready pool; the
+ * scheduler keeps the pool full until everything has either completed or
+ * been transitively blocked by a failure. Stories blocked by failure receive
+ * a synthetic `failed` result with a descriptive message so the report
+ * shows the chain of effects, not a silent absence.
+ */
+export async function drainSchedule(
+  scheduled: ScheduledStory[],
+  workerCount: number,
+  runner: StoryRunner,
+  onStart: (item: ScheduledStory) => void,
+  onFinish: (item: ScheduledStory, result: StoryResult) => void,
+): Promise<StoryResult[]> {
+  const context: RunContext = {
+    satisfied: new Set(),
+    completed: new Set(),
+    inFlight: new Set(),
+    results: new Map(),
+    skipped: new Set(),
+  };
+  const ordered: ScheduledStory[] = [];
+
+  const allDone = (): boolean =>
+    scheduled.every((item) => context.results.has(item.file));
+
+  await new Promise<void>((resolveOuter, rejectOuter) => {
+    const fillSlots = (): void => {
+      while (context.inFlight.size < workerCount) {
+        const next = pickNextReady(scheduled, context);
+        if (!next) {
+          break;
+        }
+        context.inFlight.add(next.file);
+        onStart(next);
+        runner(next)
+          .then((result) => {
+            context.inFlight.delete(next.file);
+            context.results.set(next.file, result);
+            ordered.push(next);
+            if (result.status === 'failed') {
+              skipDependents(next, scheduled, context);
+            } else {
+              for (const label of next.produces) {
+                context.satisfied.add(label);
+              }
+            }
+            context.completed.add(next.file);
+            onFinish(next, result);
+            if (allDone()) {
+              resolveOuter();
+              return;
+            }
+            fillSlots();
+          })
+          .catch(rejectOuter);
+      }
+      if (context.inFlight.size === 0 && allDone()) {
+        resolveOuter();
+      }
+    };
+    fillSlots();
+  });
+
+  return ordered.map((item) => context.results.get(item.file)!);
+}
+
+function pickNextReady(
+  scheduled: ScheduledStory[],
+  context: RunContext,
+): ScheduledStory | undefined {
+  return scheduled.find(
+    (item) =>
+      !context.completed.has(item.file) &&
+      !context.inFlight.has(item.file) &&
+      !context.skipped.has(item.file) &&
+      item.needs.every((label) => context.satisfied.has(label)),
+  );
+}
+
+function skipDependents(
+  failed: ScheduledStory,
+  scheduled: ScheduledStory[],
+  context: RunContext,
+): void {
+  const failedLabels = new Set(failed.produces);
+  for (const item of scheduled) {
+    if (context.results.has(item.file) || context.skipped.has(item.file)) {
+      continue;
+    }
+    if (item.needs.some((label) => failedLabels.has(label))) {
+      context.skipped.add(item.file);
+      context.results.set(item.file, {
+        story: item.story.story,
+        file: item.file,
+        status: 'failed' as StoryStatus,
+        startedAt: new Date().toISOString(),
+        finishedAt: new Date().toISOString(),
+        durationMs: 0,
+        actions: [
+          {
+            action: '(blocked)',
+            status: 'skipped',
+            startedAt: new Date().toISOString(),
+            finishedAt: new Date().toISOString(),
+            durationMs: 0,
+            failureMessage: `blocked by failed prerequisite ${failed.file}`,
+          },
+        ],
+      });
+      context.completed.add(item.file);
+      // Propagate skip transitively — the now-skipped item's "produces"
+      // labels stay unsatisfied, so other consumers of the same label
+      // will be caught by the next loop iteration.
+      skipDependents(item, scheduled, context);
+    }
+  }
+}
+
+function detectCycles(
+  scheduled: ScheduledStory[],
+  producerByLabel: Map<string, string>,
+): void {
+  const visited = new Set<string>();
+  const onStack = new Set<string>();
+  const visit = (file: string): void => {
+    if (onStack.has(file)) {
+      throw new SchedulerError(
+        `Cycle detected in story dependencies involving ${file}`,
+      );
+    }
+    if (visited.has(file)) {
+      return;
+    }
+    onStack.add(file);
+    const item = scheduled.find((entry) => entry.file === file);
+    if (item) {
+      for (const label of item.needs) {
+        const upstream = producerByLabel.get(label);
+        if (upstream && upstream !== file) {
+          visit(upstream);
+        }
+      }
+    }
+    onStack.delete(file);
+    visited.add(file);
+  };
+  for (const item of scheduled) {
+    visit(item.file);
+  }
+}
+
+export class SchedulerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SchedulerError';
+  }
+}

package/src/runner/steps/click.ts

@@ -0,0 +1,16 @@
+import type { Page } from 'playwright';
+import type { Hint } from '../../schema/action.ts';
+import { LocatorNotFoundError, resolveLocator } from '../resolveLocator.ts';
+
+export async function runClick(
+  page: Page,
+  hint: Hint,
+  timeoutMs: number,
+): Promise<void> {
+  const locator = resolveLocator(page, hint).first();
+  try {
+    await locator.click({ timeout: timeoutMs });
+  } catch (error) {
+    throw new LocatorNotFoundError(hint, error);
+  }
+}

package/src/runner/steps/input.ts

@@ -0,0 +1,17 @@
+import type { Page } from 'playwright';
+import type { Hint } from '../../schema/action.ts';
+import { LocatorNotFoundError, resolveLocator } from '../resolveLocator.ts';
+
+export async function runInput(
+  page: Page,
+  hint: Hint,
+  value: string,
+  timeoutMs: number,
+): Promise<void> {
+  const locator = resolveLocator(page, hint).first();
+  try {
+    await locator.fill(value, { timeout: timeoutMs });
+  } catch (error) {
+    throw new LocatorNotFoundError(hint, error);
+  }
+}

package/src/runner/steps/intercept.ts

@@ -0,0 +1,28 @@
+import type { Page } from 'playwright';
+
+/**
+ * Installs a network intercept on the page. `pattern` is a Playwright URL
+ * glob (e.g. `**\/api/links`). An optional `method` filter scopes the route
+ * so a story can simulate a single failing endpoint (POST /api/links) without
+ * breaking sibling requests on the same path (GET /api/links). The intercept
+ * stays active for the remainder of the story.
+ */
+export async function runIntercept(
+  page: Page,
+  pattern: string,
+  respond: { status: number; body?: unknown },
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+): Promise<void> {
+  await page.route(pattern, async (route) => {
+    if (method && route.request().method() !== method) {
+      await route.fallback();
+      return;
+    }
+    const body = respond.body === undefined ? '' : JSON.stringify(respond.body);
+    await route.fulfill({
+      status: respond.status,
+      contentType: 'application/json',
+      body,
+    });
+  });
+}

package/src/runner/steps/navigate.ts

@@ -0,0 +1,14 @@
+import type { Page } from 'playwright';
+import type { ResolvedConfig } from '../../config.ts';
+
+export async function runNavigate(
+  page: Page,
+  path: string,
+  config: ResolvedConfig,
+): Promise<void> {
+  const url = new URL(path, config.baseUrl).toString();
+  await page.goto(url, {
+    timeout: config.navigationTimeoutMs,
+    waitUntil: 'networkidle',
+  });
+}

package/src/runner/steps/read.ts

@@ -0,0 +1,20 @@
+import type { Page } from 'playwright';
+import type { Hint } from '../../schema/action.ts';
+import { LocatorNotFoundError, resolveLocator } from '../resolveLocator.ts';
+
+/**
+ * Synchronous existence check. Resolves the hint to a Playwright locator
+ * and asserts that exactly one matching element is currently attached. Use
+ * after a click or input that should leave a known element on screen.
+ */
+export async function runRead(page: Page, hint: Hint): Promise<void> {
+  const locator = resolveLocator(page, hint).first();
+  try {
+    const count = await locator.count();
+    if (count === 0) {
+      throw new Error('no matching element');
+    }
+  } catch (error) {
+    throw new LocatorNotFoundError(hint, error);
+  }
+}

package/src/runner/steps/scroll.ts

@@ -0,0 +1,12 @@
+import type { Page } from 'playwright';
+
+const DEFAULT_AMOUNT = 600;
+
+export async function runScroll(
+  page: Page,
+  direction: 'up' | 'down',
+  amount: number | undefined,
+): Promise<void> {
+  const delta = (amount ?? DEFAULT_AMOUNT) * (direction === 'up' ? -1 : 1);
+  await page.mouse.wheel(0, delta);
+}

package/src/runner/steps/type.ts

@@ -0,0 +1,11 @@
+import type { Page } from 'playwright';
+
+/**
+ * Page-level keyboard input. Delegates straight to Playwright's
+ * `keyboard.press`, which understands single keys, named keys, and
+ * combinations alike. Examples: "A", "Escape", "Shift+A",
+ * "Control+Enter".
+ */
+export async function runType(page: Page, value: string): Promise<void> {
+  await page.keyboard.press(value);
+}

package/src/runner/steps/wait.ts

@@ -0,0 +1,5 @@
+import type { Page } from 'playwright';
+
+export async function runWait(page: Page, ms: number): Promise<void> {
+  await page.waitForTimeout(ms);
+}

package/src/runner/steps/waitFor.ts

@@ -0,0 +1,16 @@
+import type { Page } from 'playwright';
+import type { Hint } from '../../schema/action.ts';
+import { LocatorNotFoundError, resolveLocator } from '../resolveLocator.ts';
+
+export async function runWaitFor(
+  page: Page,
+  hint: Hint,
+  timeoutMs: number,
+): Promise<void> {
+  const locator = resolveLocator(page, hint).first();
+  try {
+    await locator.waitFor({ state: 'visible', timeout: timeoutMs });
+  } catch (error) {
+    throw new LocatorNotFoundError(hint, error);
+  }
+}

package/src/schema/action.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+
+/**
+ * Locator hint. The runner uses these to resolve a Playwright `Locator`. The
+ * MVP resolver tries role + name, then accessible text, then an explicit
+ * selector. `position` is reserved for an AI fallback that picks the right
+ * candidate when more than one element matches.
+ */
+export const hintSchema = z.object({
+  text: z.string().min(1).optional(),
+  role: z
+    .enum([
+      'alert',
+      'banner',
+      'button',
+      'checkbox',
+      'combobox',
+      'dialog',
+      'form',
+      'heading',
+      'link',
+      'list',
+      'listitem',
+      'main',
+      'menu',
+      'menuitem',
+      'navigation',
+      'option',
+      'progressbar',
+      'radio',
+      'region',
+      'row',
+      'searchbox',
+      'status',
+      'switch',
+      'tab',
+      'table',
+      'textbox',
+    ])
+    .optional(),
+  selector: z.string().min(1).optional(),
+  position: z.enum(['header', 'main', 'footer', 'modal']).optional(),
+});
+
+export type Hint = z.infer<typeof hintSchema>;
+
+export const stepSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('navigate'),
+    path: z.string().startsWith('/'),
+  }),
+  z.object({
+    kind: z.literal('click'),
+    hint: hintSchema,
+  }),
+  z.object({
+    kind: z.literal('input'),
+    hint: hintSchema,
+    value: z.string(),
+  }),
+  z.object({
+    kind: z.literal('scroll'),
+    direction: z.enum(['up', 'down']),
+    amount: z.number().int().positive().optional(),
+  }),
+  z.object({
+    kind: z.literal('intercept'),
+    pattern: z.string().min(1),
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
+    respond: z.object({
+      status: z.number().int().min(100).max(599),
+      body: z.unknown().optional(),
+    }),
+  }),
+  z.object({
+    kind: z.literal('waitFor'),
+    hint: hintSchema,
+  }),
+  /**
+   * Instant assertion that a hint resolves to an attached element. Unlike
+   * `waitFor`, does not poll — the element must already be present when
+   * the step runs. Use as a mid-flow checkpoint after a click/input that
+   * synchronously updates the DOM.
+   */
+  z.object({
+    kind: z.literal('read'),
+    hint: hintSchema,
+  }),
+  /**
+   * Keyboard input directed at the page (not an input field). Passed
+   * straight to Playwright's `keyboard.press`, so single keys ("A"),
+   * named keys ("Escape", "Tab"), and combinations ("Shift+A",
+   * "Control+Enter") all work. Use for hotkeys, modal dismissal, focus
+   * cycling.
+   */
+  z.object({
+    kind: z.literal('type'),
+    value: z.string().min(1),
+  }),
+  /**
+   * Pauses the action for the given number of milliseconds. Use to absorb
+   * staggered enter animations or React-lazy chunk loads that happen after
+   * `expect.anyOf` resolves but before paint settles. Staggered enter
+   * animations and lazy-loaded chunks are the recurring offenders.
+   * Bounded at 5 seconds to discourage hiding genuine flakes.
+   */
+  z.object({
+    kind: z.literal('wait'),
+    ms: z.number().int().min(0).max(5000),
+  }),
+]);
+
+export type Step = z.infer<typeof stepSchema>;
+
+export const actionSchema = z.object({
+  action: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9-]+$/, 'action names must be lowercase-kebab'),
+  parameters: z.array(z.string().min(1)).optional(),
+  steps: z.array(stepSchema).min(1),
+  screenshot: z.boolean().default(true),
+  /**
+   * Hints whose matching elements are blacked out before the screenshot is
+   * captured. Use sparingly to neutralise non-deterministic content (relative
+   * timestamps, randomised suggestions, animated counters) so the diff layer
+   * only flags meaningful changes.
+   */
+  mask: z.array(hintSchema).optional(),
+  /**
+   * Success criteria the harness polls before capturing the screenshot. The
+   * action is only "done" once at least one of the listed hints is visible.
+   * Eliminates the entire class of "screenshot snapped mid-render" flakes.
+   */
+  expect: z
+    .object({
+      anyOf: z.array(hintSchema).min(1),
+      timeoutMs: z.number().int().positive().optional(),
+    })
+    .optional(),
+  /**
+   * Bounded retry budget for individual steps. Wraps each step's dispatch so
+   * a transient LocatorNotFoundError (UI not yet hydrated) does not fail the
+   * action immediately. Steps that succeed on the first try cost no retry.
+   */
+  retry: z
+    .object({
+      attempts: z.number().int().min(1).max(5).default(2),
+      backoffMs: z.number().int().min(0).default(200),
+    })
+    .optional(),
+  diff: z
+    .object({
+      /**
+       * Pixelmatch per-pixel similarity. Tighter values flag more pixels
+       * as changed; loosens anti-aliasing tolerance as it grows. Only
+       * controls how the diff PNG is computed — it does not gate the
+       * action's pass/changed status.
+       */
+      pixelThreshold: z.number().min(0).max(1).default(0.1),
+      /**
+       * Mean SSIM score threshold. Action passes when the score is at
+       * least this high. 1.0 = identical; 0.99 = the new default and
+       * roughly corresponds to "no perceptible change."
+       */
+      ssimThreshold: z.number().min(0).max(1).default(0.99),
+      /**
+       * Legacy pixelmatch-ratio gate. Retained for backward compat with
+       * actions that pre-date SSIM. If set, both gates must pass.
+       */
+      maxDiffRatio: z.number().min(0).max(1).optional(),
+    })
+    .optional(),
+});
+
+export type Action = z.infer<typeof actionSchema>;

package/src/schema/load.ts

@@ -0,0 +1,94 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { join } from 'node:path';
+import { actionSchema, type Action } from './action.ts';
+import { storySchema, type Story } from './story.ts';
+
+/**
+ * Loads every action JSON file under the configured actions directory and
+ * returns a name -> Action map. Throws a typed `LoadError` on the first
+ * parse failure so the CLI can print the file path next to the validation
+ * error.
+ */
+export async function loadActions(
+  actionsDir: string,
+): Promise<Map<string, Action>> {
+  const files = await readJsonFiles(actionsDir);
+  const actions = new Map<string, Action>();
+  for (const { path, contents } of files) {
+    const parsed = actionSchema.safeParse(contents);
+    if (!parsed.success) {
+      throw new LoadError(path, parsed.error.message);
+    }
+    if (actions.has(parsed.data.action)) {
+      throw new LoadError(
+        path,
+        `duplicate action name "${parsed.data.action}"`,
+      );
+    }
+    actions.set(parsed.data.action, parsed.data);
+  }
+  return actions;
+}
+
+export interface StoryFile {
+  file: string;
+  story: Story;
+}
+
+export async function loadStories(storiesDir: string): Promise<StoryFile[]> {
+  const files = await readJsonFiles(storiesDir);
+  const stories: StoryFile[] = [];
+  for (const { path, contents } of files) {
+    const parsed = storySchema.safeParse(contents);
+    if (!parsed.success) {
+      throw new LoadError(path, parsed.error.message);
+    }
+    stories.push({ file: basename(path), story: parsed.data });
+  }
+  return stories;
+}
+
+interface JsonFile {
+  path: string;
+  contents: unknown;
+}
+
+async function readJsonFiles(directory: string): Promise<JsonFile[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const subdirectories = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+  const jsonNames = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort();
+  const files: JsonFile[] = [];
+  for (const name of jsonNames) {
+    const path = join(directory, name);
+    const raw = await readFile(path, 'utf8');
+    try {
+      files.push({ path, contents: JSON.parse(raw) });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'invalid JSON';
+      throw new LoadError(path, message);
+    }
+  }
+  for (const subdirectory of subdirectories) {
+    const nested = await readJsonFiles(join(directory, subdirectory));
+    files.push(...nested);
+  }
+  return files;
+}
+
+export class LoadError extends Error {
+  readonly path: string;
+  readonly reason: string;
+  constructor(path: string, reason: string) {
+    super(`Failed to load ${path}: ${reason}`);
+    this.name = 'LoadError';
+    this.path = path;
+    this.reason = reason;
+  }
+}