@crvouga/atlas 0.0.0-stage → 0.2.0

package/packages/visualizer/vite/atlas-files.test.ts

@@ -0,0 +1,119 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterAll, describe, expect, it } from 'bun:test';
+
+import { DEFAULT_FIXTURE, FIXTURES_ROOT, isSpecFile, listSpecFiles, publicReportSources, resolveReportSources, resolveRoots, safeJoin, summarizeRun } from './atlas-files';
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), 'atlas-files-'));
+afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+function touch(file: string, text = '') {
+  mkdirSync(path.dirname(path.join(tmp, file)), { recursive: true });
+  writeFileSync(path.join(tmp, file), text);
+}
+
+describe('resolveRoots', () => {
+  const project = path.join(tmp, 'project');
+  mkdirSync(path.join(project, 'specs'), { recursive: true });
+
+  it.each<[string, NodeJS.ProcessEnv, string, string]>([
+    ['relative roots against INIT_CWD', { INIT_CWD: project, ATLAS_SPECS_ROOT: 'charts', ATLAS_RUNS_ROOT: 'out/runs' }, 'charts', 'out/runs'],
+    ['absolute roots as they are', { INIT_CWD: '/elsewhere', ATLAS_SPECS_ROOT: path.join(project, 'a'), ATLAS_RUNS_ROOT: path.join(project, 'b') }, 'a', 'b'],
+    ['specs/ and atlas-runs/ where pnpm ran', { INIT_CWD: project }, 'specs', 'atlas-runs'],
+    ['only the runs root', { INIT_CWD: project, ATLAS_RUNS_ROOT: 'r' }, 'specs', 'r']
+  ])('resolves %s', (_label, env, specs, runs) => {
+    expect(resolveRoots(env, '/not/used')).toMatchObject({ specs: path.join(project, specs), runs: path.join(project, runs), label: 'configured' });
+  });
+
+  it('falls back to the current directory without INIT_CWD', () => {
+    expect(resolveRoots({ ATLAS_SPECS_ROOT: 'x' }, project).specs).toBe(path.join(project, 'x'));
+  });
+
+  it('shows the example when nothing is configured and there is no specs/ directory', () => {
+    const roots = resolveRoots({ INIT_CWD: path.join(tmp, 'empty') });
+    expect(roots.specs).toBe(path.join(FIXTURES_ROOT, DEFAULT_FIXTURE, 'specs'));
+    expect(roots.label).toMatch(/^example/);
+  });
+
+  it('reads a named fixture and rejects an unknown one', () => {
+    expect(resolveRoots({ ATLAS_FIXTURE: 'spec-only' }).specs).toBe(path.join(FIXTURES_ROOT, 'spec-only', 'specs'));
+    expect(() => resolveRoots({ ATLAS_FIXTURE: 'nope' })).toThrow(/No fixture called "nope"/);
+  });
+});
+
+describe('listSpecFiles', () => {
+  touch('specs/atlas.yaml');
+  touch('specs/README.md');
+  touch('specs/a/chart.scxml');
+  touch('specs/a/journeys.yaml');
+  touch('specs/a/chart.layout.json');
+  touch('specs/b/machine.yaml');
+  touch('specs/b/open-questions.md');
+  touch('specs/c/journeys.yaml');
+  touch('specs/node_modules/x/machine.yaml');
+
+  it('lists charts in both formats, and all specification documents even without a chart', () => {
+    expect(listSpecFiles(path.join(tmp, 'specs'))).toEqual([
+      'README.md',
+      'a/chart.layout.json',
+      'a/chart.scxml',
+      'a/journeys.yaml',
+      'atlas.yaml',
+      'b/machine.yaml',
+      'b/open-questions.md',
+      'c/journeys.yaml'
+    ]);
+  });
+
+  it.each<[string, boolean]>([
+    ['x.scxml', true],
+    ['x.machine.json', true],
+    ['machine.yml', true],
+    ['journeys.yaml', true],
+    ['x.yaml', true],
+    ['notes.md', true],
+    ['domain/behavior.feature', true],
+    ['domain/model.qnt', true],
+    ['domain/access.dmn', true],
+    ['domain/schema.als', true]
+  ])('%s is a spec file: %s', (file, expected) => {
+    expect(isSpecFile(file)).toBe(expected);
+  });
+});
+
+describe('safeJoin', () => {
+  it.each<[string, boolean]>([
+    ['a/b.json', true],
+    ['../secret', false],
+    ['%2e%2e/secret', false],
+    ['%E0%A4%A', false]
+  ])('%s stays inside the root: %s', (relative, inside) => {
+    expect(safeJoin('/root', relative) !== null).toBe(inside);
+  });
+});
+
+describe('report sources and snapshots', () => {
+  it('resolves extra directories relative to the source configuration and preserves remote backends', () => {
+    touch('config/sources.json', JSON.stringify({ schemaVersion: 1, sources: [
+      { id: 'web', label: 'Web runs', type: 'directory', runs: '../web-runs' },
+      { id: 'ci', label: 'CI', type: 'api', baseUrl: 'https://ci.example.test/atlas/', eventsUrl: 'https://ci.example.test/events' }
+    ] }));
+    const sources = resolveReportSources({ specs: '/specs', runs: '/runs', label: 'test' }, { ATLAS_SOURCES_FILE: path.join(tmp, 'config/sources.json') });
+    expect(sources[1]).toMatchObject({ runs: path.join(tmp, 'web-runs') });
+    expect(publicReportSources(sources)[1]).toMatchObject({ live: true, baseUrl: '/__atlas/sources/web/' });
+    expect(publicReportSources(sources)[2]).toMatchObject({ type: 'api', baseUrl: 'https://ci.example.test/atlas/' });
+  });
+
+  it('summarizes readable running snapshots with execution progress', () => {
+    touch('live/live-run/manifest.json', JSON.stringify({ run: { finishedAt: null, progress: { totalPaths: 3, completedPaths: 1, activePaths: ['path-2'], updatedAt: '2026-10-09T10:00:00Z' } } }));
+    expect(summarizeRun(path.join(tmp, 'live'), 'live-run')).toMatchObject({ progress: 'running', hasManifest: true, execution: { totalPaths: 3, completedPaths: 1, activePaths: ['path-2'] } });
+  });
+
+  it.each(['null', '[]', '"invalid"'])('isolates a malformed manifest envelope: %s', (raw) => {
+    touch('bad/bad-run/manifest.json', raw);
+    expect(() => summarizeRun(path.join(tmp, 'bad'), 'bad-run')).not.toThrow();
+    expect(summarizeRun(path.join(tmp, 'bad'), 'bad-run')?.hasManifest).toBe(false);
+  });
+});

package/packages/visualizer/vite/atlas-files.ts

@@ -0,0 +1,199 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { isStatechartFile, ReportSourcesSchema, RunInfoSchema, type Count, type RemoteReportSource, type ReportSource, type RunSummary, type SpecIndex } from '@crvouga/atlas/schema';
+
+export const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const FIXTURES_ROOT = path.join(APP_ROOT, 'fixtures');
+
+/** The fixture shown when no specs directory is configured and none exists where pnpm ran. */
+export const DEFAULT_FIXTURE = 'full';
+export const DEFAULT_SPECS_DIR = 'specs';
+export const DEFAULT_RUNS_DIR = 'atlas-runs';
+
+export type AtlasRoots = { specs: string; runs: string; label: string };
+
+export function resolveReportSources(roots: AtlasRoots, env: NodeJS.ProcessEnv = process.env): ReportSource[] {
+  const workspace: ReportSource = { id: 'workspace', label: 'Workspace runs', type: 'directory', runs: roots.runs };
+  if (!env.ATLAS_SOURCES_FILE) return [workspace];
+  const file = path.resolve(env.INIT_CWD || process.cwd(), env.ATLAS_SOURCES_FILE);
+  const parsed = ReportSourcesSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+  if (parsed.sources.some((source) => source.id === workspace.id)) throw new Error('The source id "workspace" is reserved for --runs.');
+  return [workspace, ...parsed.sources.map((source) => source.type === 'directory' ? { ...source, runs: path.resolve(path.dirname(file), source.runs) } : source)];
+}
+
+export function publicReportSources(sources: ReportSource[], base = '/__atlas/'): RemoteReportSource[] {
+  return sources.map((source) => source.type === 'directory'
+    ? { id: source.id, label: source.label, type: 'http', live: true, baseUrl: source.id === 'workspace' ? base : `${base}sources/${source.id}/` }
+    : source);
+}
+
+/** A chart in either open format: W3C SCXML or XState machine config. */
+export function isChartFile(file: string) {
+  return /\.scxml$/i.test(file) || /(^|\/)([\w.-]+\.)?machine\.(ya?ml|json)$/.test(file);
+}
+
+/** Every file the visualizer reads from a specs directory: charts, journeys, notes, layouts. */
+export function isSpecFile(file: string) {
+  return isChartFile(file) || isStatechartFile(file) || /\.(feature|qnt|dmn|als|md|ya?ml|json|xml|csv|txt)$/i.test(file);
+}
+
+export function fixtureRoots(name: string): AtlasRoots {
+  const dir = path.join(FIXTURES_ROOT, name);
+  if (!existsSync(dir)) {
+    const known = existsSync(FIXTURES_ROOT) ? readdirSync(FIXTURES_ROOT).filter((n) => !n.startsWith('.')).join(', ') : 'none';
+    throw new Error(`No fixture called "${name}". Fixtures: ${known}`);
+  }
+  return { specs: path.join(dir, 'specs'), runs: path.join(dir, 'runs'), label: `fixture: ${name}` };
+}
+
+/**
+ * Where the dev server and the publish script read from, in order: a named fixture
+ * (`ATLAS_FIXTURE`), explicit roots (`ATLAS_SPECS_ROOT`, `ATLAS_RUNS_ROOT`), then `specs/` and
+ * `atlas-runs/` where the command was run. Relative paths resolve against `INIT_CWD` (where pnpm
+ * was run) or the current directory. With nothing configured and no `specs/` there, the bundled
+ * example fixture is shown.
+ */
+export function resolveRoots(env: NodeJS.ProcessEnv = process.env, cwd = process.cwd()): AtlasRoots {
+  if (env.ATLAS_FIXTURE) return fixtureRoots(env.ATLAS_FIXTURE);
+  const base = env.INIT_CWD || cwd;
+  const specsSet = Boolean(env.ATLAS_SPECS_ROOT);
+  const specs = path.resolve(base, env.ATLAS_SPECS_ROOT || DEFAULT_SPECS_DIR);
+  const runs = path.resolve(base, env.ATLAS_RUNS_ROOT || DEFAULT_RUNS_DIR);
+  if (!specsSet && !env.ATLAS_RUNS_ROOT && !existsSync(specs)) {
+    return { ...fixtureRoots(DEFAULT_FIXTURE), label: `example (no ${DEFAULT_SPECS_DIR}/ in ${base}; set ATLAS_SPECS_ROOT)` };
+  }
+  return { specs, runs, label: 'configured' };
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.cache']);
+
+/**
+ * Spec documents under the specs root, relative and with forward slashes.
+ * Documents remain discoverable even when no statechart exists beside them.
+ */
+export function listSpecFiles(specsRoot: string): string[] {
+  if (!existsSync(specsRoot)) return [];
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    const files = entries.filter((name) => isSpecFile(name) && statSafe(path.join(dir, name))?.isFile());
+    const rel = path.relative(specsRoot, dir).split(path.sep).join('/');
+    for (const name of files) {
+      const file = rel ? `${rel}/${name}` : name;
+      out.push(file);
+    }
+    for (const name of entries) {
+      if (name.startsWith('.') || SKIP_DIRS.has(name)) continue;
+      if (statSafe(path.join(dir, name))?.isDirectory()) walk(path.join(dir, name));
+    }
+  };
+  walk(specsRoot);
+  return out.sort();
+}
+
+function statSafe(file: string) {
+  try {
+    return statSync(file);
+  } catch {
+    return null;
+  }
+}
+
+export function specIndex(specsRoot: string, ref: string | null = null): SpecIndex {
+  return { schemaVersion: 1, generatedAt: new Date().toISOString(), ref, files: listSpecFiles(specsRoot) };
+}
+
+/** A manifest that doesn't parse yet is taken as still being written for this long. */
+const STILL_WRITING_MS = 60_000;
+
+function startedAtFromId(id: string, fallback: Date) {
+  const m = id.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/);
+  return m ? `${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z` : fallback.toISOString();
+}
+
+function asCount(value: unknown): Count | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const v = value as Record<string, unknown>;
+  const n = (k: string) => (typeof v[k] === 'number' ? (v[k] as number) : 0);
+  return { total: n('total'), passed: n('passed'), failed: n('failed'), flaky: n('flaky'), notReached: n('notReached') };
+}
+
+function object(value: unknown) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+/** A run directory's summary: complete once its manifest is readable, running before that. */
+export function summarizeRun(runsRoot: string, id: string): RunSummary | null {
+  const dir = path.join(runsRoot, id);
+  const stat = statSafe(dir);
+  if (!stat?.isDirectory()) return null;
+  const manifestFile = path.join(dir, 'manifest.json');
+  const running: RunSummary = { id, startedAt: startedAtFromId(id, stat.birthtime), mode: id.endsWith('showcase') ? 'showcase' : 'fast', progress: 'running', hasManifest: false };
+  if (!existsSync(manifestFile)) return running;
+  let manifest: Record<string, unknown>;
+  try {
+    const raw: unknown = JSON.parse(readFileSync(manifestFile, 'utf8'));
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { ...running, progress: 'complete' };
+    manifest = object(raw);
+  } catch {
+    const ageMs = Date.now() - (statSafe(manifestFile)?.mtimeMs ?? 0);
+    return ageMs < STILL_WRITING_MS ? running : { ...running, progress: 'complete' };
+  }
+  const run = object(manifest.run);
+  const coverage = object(object(manifest.coverage).overall);
+  const paths = Array.isArray(manifest.journeys)
+    ? manifest.journeys.map(object)
+    : Array.isArray(manifest.paths)
+      ? manifest.paths.map(object).filter((p) => p.kind === 'journey')
+      : [];
+  const journeys: Count = { total: paths.length, passed: 0, failed: 0, flaky: 0, notReached: 0 };
+  for (const p of paths) {
+    if (p.status === 'passed') journeys.passed++;
+    else if (p.status === 'failed') journeys.failed++;
+    else if (p.status === 'flaky') journeys.flaky++;
+    else journeys.notReached++;
+  }
+  return {
+    id,
+    startedAt: typeof run.startedAt === 'string' ? run.startedAt : running.startedAt,
+    mode: typeof run.mode === 'string' ? run.mode : running.mode,
+    commit: typeof run.commit === 'string' ? run.commit : null,
+    branch: typeof run.branch === 'string' ? run.branch : null,
+    durationMs: typeof run.durationMs === 'number' ? run.durationMs : undefined,
+    specVersion: typeof run.specVersion === 'string' ? run.specVersion : undefined,
+    progress: typeof run.finishedAt === 'string' || run.finishedAt === undefined ? 'complete' : 'running',
+    execution: RunInfoSchema.shape.progress.safeParse(run.progress).data,
+    hasManifest: true,
+    coverage: Object.keys(coverage).length ? { states: asCount(coverage.states), transitions: asCount(coverage.transitions) } : undefined,
+    journeys
+  };
+}
+
+export function runsIndex(runsRoot: string, keep = Number.POSITIVE_INFINITY) {
+  const ids = existsSync(runsRoot) ? readdirSync(runsRoot).filter((name) => !name.startsWith('.')) : [];
+  const runs = ids
+    .map((id) => summarizeRun(runsRoot, id))
+    .filter((r): r is RunSummary => r !== null)
+    .sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt))
+    .slice(0, keep);
+  return { generatedAt: new Date().toISOString(), runs };
+}
+
+/** `root/relative`, or null when the relative path tries to leave the root. */
+export function safeJoin(root: string, relative: string) {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(relative).replace(/^\/+/, '');
+  } catch {
+    return null;
+  }
+  const full = path.resolve(root, decoded);
+  return full === root || full.startsWith(`${root}${path.sep}`) ? full : null;
+}

package/packages/visualizer/vite/publish.test.ts

@@ -0,0 +1,52 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterAll, describe, expect, it } from 'bun:test';
+
+import { publishData } from './publish';
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), 'atlas-publish-'));
+afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+function report(root: string, id: string, passed: boolean, finishedAt: string | null = null) {
+  mkdirSync(path.join(root, id, 'media'), { recursive: true });
+  writeFileSync(
+    path.join(root, id, 'manifest.json'),
+    JSON.stringify({ schemaVersion: 1, run: { id, startedAt: '2026-10-09T10:00:00Z', finishedAt }, privacy: { passed, findings: [] } })
+  );
+  writeFileSync(path.join(root, id, 'media', 'screen.png'), 'synthetic');
+  mkdirSync(path.join(root, id, '.work'), { recursive: true });
+  writeFileSync(path.join(root, id, '.work', 'private'), 'scratch');
+}
+
+describe('publishing multiple sources', () => {
+  it('publishes privacy-checked running snapshots and extra directories with relative backend locations', () => {
+    const roots = { specs: path.join(tmp, 'specs'), runs: path.join(tmp, 'runs'), label: 'test' };
+    mkdirSync(roots.specs, { recursive: true });
+    writeFileSync(path.join(roots.specs, 'machine.json'), '{}');
+    const extra = path.join(tmp, 'extra');
+    report(roots.runs, 'live', true);
+    report(roots.runs, 'unsafe', false, '2026-10-09T10:01:00Z');
+    report(extra, 'same', true, '2026-10-09T10:01:00Z');
+    const out = path.join(tmp, 'data');
+    const result = publishData({
+      roots,
+      out,
+      sources: [
+        { id: 'workspace', label: 'Workspace', type: 'directory', runs: roots.runs },
+        { id: 'mobile', label: 'Mobile', type: 'directory', runs: extra },
+        { id: 'ci', label: 'CI', type: 'api', baseUrl: 'https://ci.example.test/reports/' }
+      ]
+    });
+    expect(result.published).toEqual(['live', 'mobile/same']);
+    expect(result.skipped).toEqual(['unsafe']);
+    expect(JSON.parse(readFileSync(path.join(out, 'runs/index.json'), 'utf8')).runs[0]).toMatchObject({ id: 'live', progress: 'running' });
+    expect(existsSync(path.join(out, 'runs/live/.work'))).toBe(false);
+    expect(existsSync(path.join(out, 'runs/unsafe'))).toBe(false);
+    expect(existsSync(path.join(out, 'backends/mobile/runs/same/media/screen.png'))).toBe(true);
+    const sources = JSON.parse(readFileSync(path.join(out, 'sources.json'), 'utf8')).sources;
+    expect(sources[0]).toMatchObject({ baseUrl: './' });
+    expect(sources[1]).toMatchObject({ baseUrl: './backends/mobile/' });
+    expect(sources[2]).toMatchObject({ type: 'api', baseUrl: 'https://ci.example.test/reports/' });
+  });
+});

package/packages/visualizer/vite/publish.ts

@@ -0,0 +1,99 @@
+import { execSync } from 'node:child_process';
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type { ReportSource, RunSummary } from '@crvouga/atlas/schema';
+
+import { listSpecFiles, resolveReportSources, runsIndex, summarizeRun, type AtlasRoots } from './atlas-files';
+
+export type PublishOptions = {
+  roots: AtlasRoots;
+  /** The directory the static site reads as its data base URL (`./data/` by default). */
+  out: string;
+  /** How many of the newest complete runs to publish. */
+  keep?: number;
+  /** The branch or commit the specs came from; the git HEAD of the specs directory when omitted. */
+  ref?: string | null;
+  sources?: ReportSource[];
+};
+
+export type PublishResult = { files: string[]; published: string[]; skipped: string[] };
+
+function gitRef(cwd: string) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function safeManifest(manifestFile: string) {
+  try {
+    const text = readFileSync(manifestFile, 'utf8');
+    const manifest = JSON.parse(text) as { privacy?: { passed?: unknown } };
+    return manifest?.privacy?.passed === true ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+function publishRuns(root: string, out: string, keep: number) {
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+  const published: RunSummary[] = [];
+  const skipped: string[] = [];
+  for (const run of runsIndex(root).runs) {
+    if (published.length >= keep) break;
+    const manifest = safeManifest(path.join(root, run.id, 'manifest.json'));
+    if (!manifest) {
+      skipped.push(run.id);
+      continue;
+    }
+    const target = path.join(out, run.id);
+    cpSync(path.join(root, run.id), target, {
+      recursive: true,
+      filter: (file) => !path.relative(path.join(root, run.id), file).split(path.sep).some((part) => part.startsWith('.'))
+    });
+    writeFileSync(path.join(target, 'manifest.json'), manifest);
+    published.push(summarizeRun(out, run.id) ?? run);
+  }
+  writeFileSync(path.join(out, 'index.json'), `${JSON.stringify({ generatedAt: new Date().toISOString(), runs: published }, null, 2)}\n`);
+  return { published: published.map((run) => run.id), skipped };
+}
+
+/**
+ * Lays out the spec and the newest runs for a static host, in the layout the static adapter
+ * reads: `specs/index.json`, `specs/<path>`, `runs/index.json`, `runs/<id>/...`. Only `specs/`
+ * and `runs/` under `out` are replaced. A run whose privacy check failed or is missing is never
+ * published.
+ */
+export function publishData({ roots, out, keep = 30, ref, sources = resolveReportSources(roots) }: PublishOptions): PublishResult {
+  const specsOut = path.join(out, 'specs');
+  const runsOut = path.join(out, 'runs');
+  rmSync(specsOut, { recursive: true, force: true });
+  rmSync(runsOut, { recursive: true, force: true });
+  mkdirSync(specsOut, { recursive: true });
+  mkdirSync(runsOut, { recursive: true });
+
+  const files = listSpecFiles(roots.specs);
+  for (const file of files) {
+    const target = path.join(specsOut, file);
+    mkdirSync(path.dirname(target), { recursive: true });
+    cpSync(path.join(roots.specs, file), target);
+  }
+  const index = { schemaVersion: 1, generatedAt: new Date().toISOString(), ref: ref === undefined ? gitRef(roots.specs) : ref, files };
+  writeFileSync(path.join(specsOut, 'index.json'), `${JSON.stringify(index, null, 2)}\n`);
+
+  const result = publishRuns(roots.runs, runsOut, keep);
+  const descriptors = sources.map((source) => {
+    if (source.type !== 'directory') return { ...source, live: false };
+    if (source.id !== 'workspace') {
+      const published = publishRuns(source.runs, path.join(out, 'backends', source.id, 'runs'), keep);
+      result.published.push(...published.published.map((id) => `${source.id}/${id}`));
+      result.skipped.push(...published.skipped.map((id) => `${source.id}/${id}`));
+    }
+    return { id: source.id, label: source.label, type: 'http', baseUrl: source.id === 'workspace' ? './' : `./backends/${source.id}/` };
+  });
+  writeFileSync(path.join(out, 'sources.json'), `${JSON.stringify({ schemaVersion: 1, sources: descriptors }, null, 2)}\n`);
+  return { files, ...result };
+}

package/packages/visualizer/vite/reports-dev-plugin.ts

@@ -0,0 +1,82 @@
+// @io-wall-ok — Vite dev server mounts the reports API on the page origin
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Plugin, ViteDevServer } from 'vite';
+
+export function isReportsApiPath(url: string | undefined): boolean {
+  const path = (url ?? '').split('?')[0] ?? '';
+  return path === '/api/reports' || path.startsWith('/api/reports/');
+}
+
+export function reportsDevPlugin(args: {
+  readonly repoRoot: string;
+  readonly appModule: string;
+}): Plugin {
+  return {
+    name: 'atlas-reports-dev',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if (!isReportsApiPath(req.url)) {
+          next();
+          return;
+        }
+        void writeReports(req, res, server, args).catch((err: unknown) => {
+          if (res.headersSent || res.writableEnded) return;
+          res.statusCode = 500;
+          res.end(err instanceof Error ? err.message : 'reports failed');
+        });
+      });
+    },
+  };
+}
+
+async function writeReports(
+  req: IncomingMessage,
+  res: ServerResponse,
+  server: ViteDevServer,
+  args: { readonly repoRoot: string; readonly appModule: string }
+): Promise<void> {
+  const host = req.headers.host ?? 'localhost';
+  const app = (await server.ssrLoadModule(args.appModule)) as {
+    reportsDevFetch: (request: Request, repoRoot: string) => Promise<Response>;
+  };
+  const response = await app.reportsDevFetch(
+    new Request(`http://${host}${req.url ?? '/api/reports'}`, {
+      method: req.method ?? 'GET',
+      headers: requestHeaders(req),
+    }),
+    args.repoRoot
+  );
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    if (key === 'transfer-encoding' || key === 'content-length') return;
+    res.setHeader(key, value);
+  });
+  if (response.body === null) {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  req.on('close', () => {
+    void reader.cancel();
+  });
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value !== undefined && !res.write(value)) {
+      await new Promise<void>((resolveDrain) => {
+        res.once('drain', () => resolveDrain());
+      });
+    }
+  }
+  res.end();
+}
+
+function requestHeaders(req: IncomingMessage): Headers {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') headers.set(key, value);
+    else if (Array.isArray(value)) headers.set(key, value.join(', '));
+  }
+  return headers;
+}

package/packages/visualizer/vite.config.ts

@@ -0,0 +1,13 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+import { reportsDevPlugin } from './vite/reports-dev-plugin';
+import { atlasDevPlugin } from './vite/atlas-dev-plugin';
+
+export default defineConfig({
+  base: './',
+  plugins: [react(), atlasDevPlugin(), ...(process.env.ATLAS_REPORTS_MODULE ? [reportsDevPlugin({ repoRoot: process.env.INIT_CWD || process.cwd(), appModule: process.env.ATLAS_REPORTS_MODULE })] : [])],
+  worker: { format: 'es' },
+  server: { port: Number(process.env.PORT ?? 5180), strictPort: false },
+  build: { outDir: 'dist', emptyOutDir: true, chunkSizeWarningLimit: 2_500 }
+});

package/packages/vitest/README.md

@@ -0,0 +1,58 @@
+# @crvouga/atlas/vitest
+
+Run an [Atlas](../../README.md) config as a test suite in Vitest, `bun test` or any Jest-style
+runner: one test that the charts are executable, then one test per planned path. The runner's own
+`describe`, `it`, `beforeAll` and `expect` are passed in, so with Bun import them from `bun:test`
+instead of `vitest` and install nothing else.
+
+```sh
+bun add -d @crvouga/atlas vitest
+```
+
+## Use
+
+```ts
+// door.test.ts
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from '@crvouga/atlas';
+import { describeAtlas, functionDriver } from '@crvouga/atlas/vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { Door } from './door';
+
+const config = defineConfig<Door>({
+  specs: fileURLToPath(new URL('./specs', import.meta.url)),
+  driver: functionDriver(() => new Door()),
+  implementation: {
+    setup: async () => undefined,
+    events: {
+      Opens: { kind: 'user', how: 'door.open()', run: async (door) => door.open() },
+      Closes: { kind: 'user', how: 'door.close()', run: async (door) => door.close() }
+    },
+    states: {
+      Closed: { recognize: async (door) => ({ matched: !door.isOpen, signals: [] }) },
+      Open: { recognize: async (door) => ({ matched: door.isOpen, signals: [] }) }
+    }
+  }
+});
+
+describeAtlas(config, { describe, it, beforeAll, expect });
+```
+
+The whole plan runs once in `beforeAll` (so all paths share one manifest), and each test reports its
+own path: a failed path fails its test with the runner's message; a path that could not be reached
+because of a blocked event passes quietly and shows up in the manifest as `not-reached`.
+
+`describeAtlas(config, suite, options)` accepts the `atlas run` options (`mode`, `paths`, `retry`,
+`output`, `log`) plus `baseDirectory` (where relative config paths resolve) and `timeoutMs` for the
+`beforeAll` (30 minutes by default).
+
+`functionDriver(create)` is re-exported from `@crvouga/atlas`: it drives anything you can reach from
+Node (a domain model, an API client, a CLI), with a fresh context from `create` for every path
+attempt. Running the same spec through a browser driver and through `functionDriver` is a cheap way
+to keep a model and its UI in agreement.
+
+## License
+
+MIT