@cs4alhaider/screenbook 0.1.0

package/cli/screenbook.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/* ScreenBook CLI — init · serve · manifest · validate · screenshot · mcp.
+   Shares engine/core/ with the MCP server (EN-18). */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exists, writeJSON, writeAtomic, mkdirp, today } from '../core/fsx.js';
+import { resolveRoot, regenAllManifests, staticValidate, getScreen, addApp } from '../core/project.js';
+import { startServer } from '../core/serve.js';
+import * as T from './templates.js';
+
+const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const VERSION = '0.1.0';
+
+/* ---------------- arg parsing ---------------- */
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+const positional = [];
+const flags = {};
+for (let i = 1; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith('--')) {
+    const eq = a.indexOf('=');
+    if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+    else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) flags[a.slice(2)] = argv[++i];
+    else flags[a.slice(2)] = true;
+  } else {
+    positional.push(a);
+  }
+}
+
+const ok = (s) => `\x1b[32m${s}\x1b[0m`;
+const bad = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+async function requireRoot() {
+  const root = await resolveRoot(positional[0]);
+  if (!root) {
+    console.error(bad(`No app.config.json found${positional[0] ? ` in ${positional[0]}` : ' here'}.`));
+    console.error(`Run ${bold('screenbook init')} to scaffold a project, or pass the project directory.`);
+    process.exit(2);
+  }
+  return root;
+}
+
+/* ---------------- commands ---------------- */
+
+async function cmdInit() {
+  const dir = path.resolve(positional[0] || '.');
+  const configPath = path.join(dir, 'app.config.json');
+  if (await exists(configPath) && !flags.force) {
+    console.error(bad(`app.config.json already exists in ${dir} — refusing to overwrite (use --force).`));
+    process.exit(2);
+  }
+  const name = flags.name || path.basename(dir);
+  const day = today();
+
+  await mkdirp(path.join(dir, 'features/welcome/screens'));
+  await mkdirp(path.join(dir, 'features/welcome/data'));
+  await mkdirp(path.join(dir, 'themes'));
+  await mkdirp(path.join(dir, 'review'));
+
+  await writeJSON(configPath, T.APP_CONFIG(name));
+  await writeJSON(path.join(dir, 'themes/default.json'), T.DEFAULT_THEME);
+  await writeJSON(path.join(dir, 'review/comments.json'), { comments: [] });
+  await writeJSON(path.join(dir, 'features/welcome/feature.json'), T.WELCOME_FEATURE);
+  await writeJSON(path.join(dir, 'features/welcome/data/seed.json'), T.WELCOME_SEED);
+  await writeJSON(path.join(dir, 'features/welcome/data/scenarios.json'), T.WELCOME_SCENARIOS);
+  await writeJSON(path.join(dir, 'features/welcome/flows.json'), T.WELCOME_FLOWS);
+  await writeAtomic(path.join(dir, 'features/welcome/screens/010-hello.html'), T.WELCOME_SCREEN(day));
+
+  /* agent onboarding ships with the product (EN-32) */
+  const claudeMd = path.join(dir, 'CLAUDE.md');
+  if (!(await exists(claudeMd))) {
+    const contract = await readTextSafe(path.join(ENGINE_DIR, 'CLAUDE.md'));
+    if (contract) await writeAtomic(claudeMd, contract);
+  }
+  const skillSrc = path.join(ENGINE_DIR, 'skill');
+  if (await exists(skillSrc)) {
+    await copyDir(skillSrc, path.join(dir, '.claude/skills/screenbook'));
+  }
+
+  await regenAllManifests(dir);
+
+  /* `init --app <path>`: register an existing SPA in this folder as an
+     embedded app in the same breath (Abdullah's flow: point ScreenBook at
+     any folder that already contains an app). */
+  if (flags.app) {
+    const rel = path.relative(dir, path.resolve(flags.app)) || flags.app;
+    const r = await addApp(dir, {
+      src: rel.split(path.sep).join('/'),
+      driver: !flags.cooperative
+    });
+    console.log(ok(`✓ app registered: ${r.feature.id}`) + dim(` → ${r.feature.src}`));
+    if (r.driver) console.log(`  fill in ${bold(r.driver)} to teach ScreenBook the app's internals`);
+  }
+
+  console.log(ok(`✓ ScreenBook project scaffolded in ${dir}`));
+  console.log(`  app.config.json · themes/default.json · features/welcome/ · review/`);
+  console.log(`  CLAUDE.md + .claude/skills/screenbook/ ${dim('(agent authoring contract)')}`);
+  if (!(await exists(path.join(dir, 'engine')))) {
+    console.log(dim(`  note: no engine/ folder here — ${bold('screenbook serve')} mounts it automatically;`));
+    console.log(dim(`  copy the engine folder in when you want plain static servers to work too.`));
+  }
+  console.log(`\nNext: ${bold(`screenbook serve ${positional[0] || '.'}`)}  → http://127.0.0.1:4600`);
+}
+
+async function readTextSafe(p) {
+  try { return await (await import('node:fs/promises')).readFile(p, 'utf8'); }
+  catch { return null; }
+}
+
+async function copyDir(src, dest) {
+  const fs = await import('node:fs/promises');
+  await fs.mkdir(dest, { recursive: true });
+  await fs.cp(src, dest, { recursive: true, force: true });
+}
+
+async function cmdServe() {
+  const root = await requireRoot();
+  const port = parseInt(flags.port || '4600', 10);
+  const srv = await startServer({ root, engineDir: ENGINE_DIR, port });
+  console.log(bold(`⧉ ScreenBook`) + ` serving ${dim(root)}`);
+  console.log(`  studio   ${ok(srv.url + '/engine/index.html')}`);
+  console.log(`  selftest ${dim(srv.url + '/engine/index.html?selftest=1')}`);
+  console.log(`  live reload + manifest refresh + review sync ${ok('on')} ${dim('(no-cache always)')}`);
+}
+
+async function cmdManifest() {
+  const root = await requireRoot();
+  const results = await regenAllManifests(root);
+  for (const r of results) {
+    const flag = r.written ? ok('regenerated') : dim('unchanged');
+    console.log(`  ${r.feature.padEnd(24)} ${String(r.screens).padStart(3)} screens  ${flag}`);
+    for (const p of r.problems) console.log(bad(`    ! ${p.screen}: ${p.error}`));
+  }
+  if (!results.length) console.log(dim('  no features found'));
+}
+
+async function cmdValidate() {
+  const root = await requireRoot();
+  const report = { root, static: null, browser: null };
+
+  const s = await staticValidate(root);
+  report.static = s;
+  if (!flags.json) {
+    console.log(bold('Static checks'));
+    for (const e of s.errors) console.log(bad(`  ✕ ${e}`));
+    for (const w of s.warnings) console.log(`  ⚠︎ ${w}`);
+    console.log(s.ok ? ok(`  ✓ static checks clean (${s.warnings.length} warning${s.warnings.length === 1 ? '' : 's'})`) : bad(`  ${s.errors.length} error(s)`));
+  }
+
+  let browserOk = true;
+  if (!flags.static) {
+    const { runBrowserSelftest } = await import('../core/browser.js');
+    if (!flags.json) console.log(bold('Browser self-test') + dim(' (every screen × theme × light/dark × ltr/rtl)'));
+    try {
+      const r = await runBrowserSelftest({ root, engineDir: ENGINE_DIR });
+      report.browser = r;
+      browserOk = r.ok;
+      if (!flags.json) {
+        for (const row of r.rows.filter((x) => !x.ok)) {
+          console.log(bad(`  ✕ ${row.feature}/${row.screen}  ${dim(`${row.theme}·${row.mode}·${row.dir}`)}  ${row.fail}`));
+        }
+        for (const e of r.shellErrors) console.log(bad(`  ✕ shell: ${e}`));
+        console.log(r.ok
+          ? ok(`  ✓ ${r.passed}/${r.total} render checks green across ${r.screens} screens`)
+          : bad(`  ${r.failed} failing / ${r.total}`));
+      }
+    } catch (err) {
+      browserOk = false;
+      report.browser = { ok: false, error: String(err.message) };
+      if (!flags.json) console.log(bad(`  ✕ ${err.message}`));
+    }
+  }
+
+  const allOk = s.ok && browserOk;
+  if (flags.json) console.log(JSON.stringify({ ok: allOk, ...report }, null, 2));
+  else console.log(allOk ? ok(bold('VALIDATE: GREEN')) : bad(bold('VALIDATE: FAILING')));
+  process.exit(allOk ? 0 : 1);
+}
+
+async function cmdMcp() {
+  /* Start the stdio MCP server in-process. Everything after `mcp` stays on
+     process.argv, so server.js picks up --root itself. NOTHING may print to
+     stdout here — that's the JSON-RPC channel; the server logs to stderr. */
+  if (!flags.root && positional[0]) {
+    process.argv.push('--root', positional[0]);   // allow `screenbook mcp <dir>` too
+  }
+  await import('../mcp/server.js');
+}
+
+async function cmdApp() {
+  const sub = positional[0];
+  if (sub !== 'add') {
+    console.error(bad('usage: screenbook app add <src> [dir] [--id x] [--title "X"] [--icon 🧩] [--device ios|android|web|none] [--chrome self|engine] [--cooperative]'));
+    process.exit(2);
+  }
+  const srcArg = positional[1];
+  if (!srcArg) {
+    console.error(bad('missing <src> — project-relative path to the app\'s index.html'));
+    process.exit(2);
+  }
+  positional.splice(0, 2, positional[2]);   // remaining positional = project dir
+  const root = await requireRoot();
+  const rel = path.isAbsolute(srcArg)
+    ? path.relative(root, srcArg).split(path.sep).join('/')
+    : srcArg;
+  const r = await addApp(root, {
+    src: rel,
+    id: flags.id,
+    title: flags.title,
+    icon: flags.icon,
+    device: flags.device,
+    chrome: flags.chrome,
+    driver: !flags.cooperative
+  });
+  console.log(ok(`✓ app feature "${r.feature.id}" registered`) + dim(` → ${r.feature.src}`));
+  if (r.driver) {
+    console.log(`  next: fill in ${bold(r.driver)} (screens/go/set) — the app's own files stay untouched`);
+  } else {
+    console.log(`  cooperative mode: the app must include ${bold('engine/app-bridge.js')} and call ${bold('AppBridge.register(…)')}`);
+  }
+}
+
+async function cmdScreenshot() {
+  const root = await requireRoot();
+  const spec = flags.screen;
+  if (!spec || !spec.includes('/')) {
+    console.error(bad('usage: screenbook screenshot [dir] --screen <feature>/<screen> [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id] [--lang xx] [--out dir]'));
+    process.exit(2);
+  }
+  const [feature, screen] = spec.split('/');
+  await getScreen(root, feature, screen);   // fail fast if missing
+
+  const modes = String(flags.mode || 'light').split(',');
+  const dirs = String(flags.dir || 'ltr').split(',');
+  const combos = [];
+  for (const mode of modes) {
+    for (const d of dirs) {
+      combos.push({
+        feature, screen, mode, dir: d,
+        scenario: flags.scenario, theme: flags.theme, lang: flags.lang
+      });
+    }
+  }
+  const outDir = path.resolve(flags.out || path.join(root, 'review', 'screenshots'));
+  const { screenshot } = await import('../core/browser.js');
+  const files = await screenshot({ root, engineDir: ENGINE_DIR, combos, outDir });
+  for (const f of files) console.log(ok(`  ✓ ${f}`));
+}
+
+function help() {
+  console.log(`${bold('screenbook')} ${VERSION} — static prototype studio
+
+  ${bold('init')} [dir] [--name X] [--force]     scaffold a consumer project (+ CLAUDE.md + skill)
+             [--app <src>] also register an existing SPA in that folder as an embedded app
+  ${bold('app add')} <src> [dir] [--id --title --icon --device --chrome self|engine --cooperative]
+                                        embed an existing single-page app (driver scaffolded unless --cooperative)
+  ${bold('serve')} [dir] [--port 4600]           static server · live reload · manifest refresh · review sync
+  ${bold('manifest')} [dir]                      rescan screens → regenerate features/*/manifest.json
+  ${bold('validate')} [dir] [--static] [--json]  static checks + headless browser self-test
+  ${bold('mcp')} [--root dir]                    start the stdio MCP server (for agents):
+                                        claude mcp add screenbook -- npx -y @cs4alhaider/screenbook mcp --root .
+  ${bold('screenshot')} [dir] --screen f/s       PNG of a screen in its device frame
+             [--mode light,dark] [--dir ltr,rtl] [--scenario id] [--theme id] [--lang xx] [--out dir]
+
+  Projects are folders with app.config.json + features/ + themes/ (see engine/CLAUDE.md).`);
+}
+
+const commands = {
+  init: cmdInit,
+  serve: cmdServe,
+  manifest: cmdManifest,
+  validate: cmdValidate,
+  screenshot: cmdScreenshot,
+  app: cmdApp,
+  mcp: cmdMcp,
+  help,
+  '--help': help,
+  version: () => console.log(VERSION),
+  '--version': () => console.log(VERSION)
+};
+
+Promise.resolve((commands[command] || help)()).catch((err) => {
+  console.error(bad(`✕ ${err.message}`));
+  process.exit(1);
+});

package/cli/templates.js

@@ -0,0 +1,139 @@
+/* Templates written by `screenbook init` into a fresh consumer project. */
+
+export const APP_CONFIG = (name) => ({
+  name,
+  defaultFeature: 'welcome',
+  features: ['welcome'],
+  devices: ['ios', 'android', 'web'],
+  themes: ['default'],
+  languages: ['en'],
+  defaultLanguage: 'en'
+});
+
+export const DEFAULT_THEME = {
+  id: 'default',
+  title: 'Starter',
+  modes: {
+    light: {
+      color: {
+        accent: '#5B5BD6', bg: '#F4F3F0', card: '#FFFFFF',
+        ink: '#211E1A', 'ink-2': '#6F6A61', line: '#E3DFD7'
+      },
+      font: {
+        sans: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+        serif: "ui-serif, 'New York', Georgia, serif"
+      },
+      radius: { card: '18px', chip: '999px' },
+      space: { page: '16px' }
+    },
+    dark: {
+      color: {
+        accent: '#8484F0', bg: '#161519', card: '#211F26',
+        ink: '#EDEBF3', 'ink-2': '#A7A3B0', line: '#2E2D34'
+      }
+    }
+  }
+};
+
+export const WELCOME_FEATURE = {
+  id: 'welcome',
+  title: 'Welcome',
+  icon: '👋',
+  description: 'A first screen to copy from — delete once real features exist.',
+  order: 1
+};
+
+export const WELCOME_SEED = {
+  app: { name: 'My product' },
+  user: { firstName: 'Sara', plan: 'trial', trialEndsOn: '{{today+14}}' }
+};
+
+export const WELCOME_SCENARIOS = {
+  list: [
+    { id: 'default', icon: '🧪', title: 'Trial user', description: 'Baseline seed — trial ends in two weeks.' },
+    {
+      id: 'expired', icon: '⏰', title: 'Trial expired', description: 'The nudge state.',
+      patch: { user: { plan: 'expired', trialEndsOn: '{{today-1}}' } }
+    }
+  ]
+};
+
+export const WELCOME_FLOWS = {
+  list: [
+    {
+      id: 'tour', title: 'Starter tour', icon: '✨',
+      description: 'Shows how flows step through screens with notes.',
+      steps: [
+        { screen: '010-hello', note: 'Every flow step can pin a scenario, show a note, and move the story forward.' }
+      ]
+    }
+  ]
+};
+
+export const WELCOME_SCREEN = (today) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Hello ScreenBook</title>
+  <script type="application/json" id="screen-meta">
+  {
+    "title": "Hello",
+    "description": "Starter screen — shows tokens, data binding and navigation.",
+    "order": 10,
+    "device": "ios",
+    "status": "draft",
+    "tags": ["starter"],
+    "updated": "${today}"
+  }
+  </script>
+  <script src="../../../engine/bridge.js"></script>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; min-height: 100vh;
+      padding: calc(var(--safe-top, 0px) + 24px) var(--space-page, 16px) calc(var(--safe-bottom, 0px) + 24px);
+      background: var(--color-bg); color: var(--color-ink);
+      font-family: var(--font-sans);
+    }
+    .card {
+      background: var(--color-card); border: 1px solid var(--color-line);
+      border-radius: var(--radius-card); padding: 20px; margin-top: 16px;
+    }
+    h1 { font-family: var(--font-serif); font-size: 30px; margin: 8px 0 4px; }
+    .muted { color: var(--color-ink-2); font-size: 14px; line-height: 1.5; }
+    .cta {
+      display: inline-block; margin-top: 14px; padding: 12px 18px; border: 0;
+      border-radius: var(--radius-chip); background: var(--color-accent); color: #fff;
+      font-size: 15px; font-weight: 700; cursor: pointer;
+    }
+  </style>
+</head>
+<body>
+  <h1>Hello 👋</h1>
+  <p class="muted">This screen is a full standalone HTML document. Open it directly, or through the ScreenBook shell.</p>
+  <div class="card">
+    <div id="who" style="font-weight:700"></div>
+    <div class="muted" id="plan"></div>
+    <button class="cta" id="cta">Try Engine.toast</button>
+  </div>
+  <script>
+    Engine.ready(function (d) {
+      document.getElementById('who').textContent =
+        (d.user ? d.user.firstName : 'Friend') + ' · ' + (d.app ? d.app.name : 'your product');
+      document.getElementById('plan').textContent =
+        d.user && d.user.plan === 'expired'
+          ? 'Trial expired on ' + d.user.trialEndsOn + ' — try the ⏰ scenario dropdown!'
+          : 'Trial until ' + (d.user ? d.user.trialEndsOn : '…') + ' — dates come from {{today+14}} tokens.';
+      document.getElementById('cta').addEventListener('click', function () {
+        Engine.toast('Tokens, data, state — all live ✦');
+      });
+    });
+  </script>
+</body>
+</html>
+`;
+
+export const GITIGNORE = `node_modules/
+.DS_Store
+`;

package/core/browser.js

@@ -0,0 +1,108 @@
+/* Headless-browser half of validation + screenshots.
+   Playwright is a dev dependency of the CLI, never of the viewer (EN-28).
+   Resolution order: playwright → playwright-core driving the system Chrome. */
+
+import path from 'node:path';
+import { startServer } from './serve.js';
+import { mkdirp } from './fsx.js';
+
+async function launch() {
+  let lastErr;
+  for (const [pkg, opts] of [
+    ['playwright', { headless: true }],
+    ['playwright-core', { headless: true, channel: 'chrome' }],
+    ['playwright-core', { headless: true, channel: 'chromium' }]
+  ]) {
+    try {
+      const mod = await import(pkg);
+      return await mod.chromium.launch(opts);
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw new Error(
+    `No headless browser available. Install one inside engine/:\n` +
+    `  npm i -D playwright-core   (uses your installed Chrome)\n` +
+    `  npm i -D playwright && npx playwright install chromium   (self-contained)\n` +
+    `Underlying error: ${lastErr?.message}`
+  );
+}
+
+async function withPage({ root, engineDir }, fn) {
+  const srv = await startServer({ root, engineDir, port: 0, quiet: true });
+  const browser = await launch();
+  try {
+    const page = await browser.newPage({ viewport: { width: 1400, height: 1000 }, deviceScaleFactor: 2 });
+    return await fn(page, srv.url);
+  } finally {
+    await browser.close();
+    await srv.close();
+  }
+}
+
+/* Run the shell's ?selftest=1 headlessly; also fails on shell-level errors. */
+export async function runBrowserSelftest({ root, engineDir, timeout = 180000 }) {
+  return withPage({ root, engineDir }, async (page, base) => {
+    const shellErrors = [];
+    /* contract-optional project files 404 legitimately (flows.json, seed.json, …) —
+       Chrome still logs those as console errors; they are not failures */
+    const OPTIONAL_404 = /\/(flows|scenarios|seed|manifest|feature|app\.config|comments)\.json$|\/themes\/[^/]+\.json$/;
+    page.on('pageerror', (err) => shellErrors.push(String(err.message || err)));
+    page.on('console', (msg) => {
+      if (msg.type() !== 'error') return;
+      const text = msg.text();
+      const src = msg.location()?.url || '';
+      if (/Failed to load resource/.test(text) && OPTIONAL_404.test(src.split('?')[0])) return;
+      /* screen/app-side errors are captured (and filtered) in-page by the
+         bridges and become per-row failures; this listener only polices the
+         SHELL itself — engine-owned sources. The two bridge files are the
+         console-wrap passthrough for screen/app errors, so they don't count. */
+      if (src && !/\/engine\//.test(src)) return;
+      if (/\/engine\/(bridge|app-bridge)\.js/.test(src)) return;
+      shellErrors.push(text);
+    });
+
+    await page.goto(`${base}/engine/index.html?selftest=1`, { waitUntil: 'domcontentloaded' });
+    await page.waitForFunction('window.__selftestDone === true', null, { timeout });
+    const result = await page.evaluate('window.__selftestResult');
+    result.shellErrors = shellErrors;
+    result.ok = result.failed === 0 && shellErrors.length === 0;
+    return result;
+  });
+}
+
+/*
+ * Screenshot a screen inside its real device frame via the shell's solo mode.
+ * combo: { feature, screen, theme, mode, dir, lang, scenario }
+ */
+export async function screenshot({ root, engineDir, combos, outDir }) {
+  await mkdirp(outDir);
+  const files = [];
+  return withPage({ root, engineDir }, async (page, base) => {
+    for (const c of combos) {
+      const params = new URLSearchParams();
+      if (c.scenario && c.scenario !== 'default') params.set('scenario', c.scenario);
+      if (c.mode && c.mode !== 'light') params.set('mode', c.mode);
+      if (c.theme) params.set('theme', c.theme);
+      if (c.dir && c.dir !== 'ltr') params.set('dir', c.dir);
+      if (c.lang) params.set('lang', c.lang);
+      const q = params.toString();
+      const url = `${base}/engine/index.html?solo=1#${encodeURIComponent(c.feature)}/${encodeURIComponent(c.screen)}${q ? `?${q}` : ''}`;
+
+      await page.goto('about:blank');
+      await page.goto(url, { waitUntil: 'domcontentloaded' });
+      await page.waitForSelector('.stage .device', { timeout: 20000 });
+      await page.waitForSelector('.load-veil.is-hidden', { state: 'attached', timeout: 20000 });
+      await page.waitForTimeout(250);
+
+      const device = page.locator('.stage .device');
+      const name = [c.feature, c.screen, c.theme, c.mode, c.dir, c.scenario]
+        .filter((x) => x && x !== 'default')
+        .join('_') + '.png';
+      const file = path.join(outDir, name.replace(/[^a-z0-9._-]+/gi, '-'));
+      await device.screenshot({ path: file });
+      files.push(file);
+    }
+    return files;
+  });
+}

package/core/fsx.js

@@ -0,0 +1,71 @@
+/* Atomic, read-then-write file helpers. Every write in the CLI/MCP goes
+   through here — the predecessor lost index.html twice to naive writes. */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+export async function readText(p) {
+  return fs.readFile(p, 'utf8');
+}
+
+export async function readJSON(p, fallback = undefined) {
+  try {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+  } catch (err) {
+    if (fallback !== undefined && (err.code === 'ENOENT')) return fallback;
+    if (err instanceof SyntaxError) {
+      throw new Error(`${p} is not valid JSON: ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+/* Write via temp file + rename (atomic on POSIX). Creates parent dirs. */
+export async function writeAtomic(p, content) {
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  const tmp = `${p}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  try {
+    await fs.writeFile(tmp, content, 'utf8');
+    await fs.rename(tmp, p);
+  } catch (err) {
+    try { await fs.unlink(tmp); } catch { /* already gone */ }
+    throw err;
+  }
+}
+
+export async function writeJSON(p, value) {
+  await writeAtomic(p, JSON.stringify(value, null, 2) + '\n');
+}
+
+/* Write only when content actually changed. Returns true if written. */
+export async function writeJSONIfChanged(p, value) {
+  const next = JSON.stringify(value, null, 2) + '\n';
+  try {
+    const cur = await fs.readFile(p, 'utf8');
+    if (cur === next) return false;
+  } catch { /* new file */ }
+  await writeAtomic(p, next);
+  return true;
+}
+
+export async function listDir(p) {
+  try { return await fs.readdir(p, { withFileTypes: true }); }
+  catch { return []; }
+}
+
+export async function remove(p) {
+  await fs.rm(p, { force: true });
+}
+
+export async function mkdirp(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+export function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}