@1agh/maude 0.48.0 → 0.49.0

package/cli/commands/hub-workspace.mjs

@@ -0,0 +1,341 @@
+// `maude hub workspace-up` — Cloud Phase 4 Task 1, the effects layer.
+//
+// The decisions live in `cli/lib/workspace-plan.mjs` (pure, tested without a
+// VPS). This file does the parts that genuinely touch the world: read config,
+// write files, boot the stack, run the verification plan, print the result.
+//
+// IDEMPOTENT BY CONSTRUCTION. Re-running is the upgrade path: the rendered
+// files are regenerated, but `.env` secrets that already exist are REUSED, not
+// re-minted. Re-minting HUB_SECRET on every run would silently lock out every
+// peer that already has a token, and it would do it to the person whose
+// instinct after a failed run is to try again.
+//
+// It does NOT claim to own the deployment afterwards — see `operatorDuties`.
+
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { parseArgs } from '../lib/argv.mjs';
+import {
+  envEntries,
+  operatorDuties,
+  renderCaddyfile,
+  renderCompose,
+  renderEnv,
+  validateWorkspaceConfig,
+  verificationPlan,
+} from '../lib/workspace-plan.mjs';
+
+export function usage() {
+  return `maude hub workspace-up [options]
+
+  Stand up a self-hosted Maude WORKSPACE — a hub that owns the project, commits
+  autosaves, and stores media in object storage — and verify it actually works
+  before saying so.
+
+  --domain HOST            public hostname (design.acme.com)
+  --acme-email EMAIL       Let's Encrypt contact
+  --admin-email EMAIL      the first person who can sign in
+  --admin-password PASS    their initial password (>= 12 chars; generated if omitted)
+  --s3-endpoint URL        object storage (R2 / MinIO / S3)
+  --s3-bucket NAME
+  --s3-access-key-id ID
+  --s3-secret-access-key SECRET
+  --s3-region REGION       default "auto"
+  --dev-minio              run a local MinIO under the compose 'dev' profile
+  --seed-repo URL          clone an existing project; omit to start fresh
+  --image-tag TAG          default "latest" — pin it before you rely on this
+  --config FILE            read all of the above from a JSON file
+  --out DIR                where to write compose/Caddyfile/.env (default: cwd)
+  --dry-run                render + print the plan, touch nothing else
+  --json                   machine-readable result
+
+  Re-running is the UPGRADE path: files are regenerated, existing secrets in
+  .env are REUSED (re-minting HUB_SECRET would lock out every peer that already
+  has a token).
+
+  What it does NOT do: own the deployment. It scaffolds and verifies once.
+  Rotation, backups, upgrades and the bill stay with you — the run prints the
+  list.
+`;
+}
+
+export async function run({ args, pkgRoot }) {
+  const { flags } = parseArgs(args, { booleans: ['dry-run', 'json', 'dev-minio'] });
+  if (flags.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const outDir = resolve(String(flags.out ?? process.cwd()));
+  const raw = flags.config ? readConfigFile(String(flags.config)) : {};
+  const merged = {
+    domain: flags.domain ?? raw.domain,
+    acmeEmail: flags['acme-email'] ?? raw.acmeEmail,
+    adminEmail: flags['admin-email'] ?? raw.adminEmail,
+    ...((flags['admin-password'] ?? raw.adminPassword)
+      ? { adminPassword: flags['admin-password'] ?? raw.adminPassword }
+      : {}),
+    devMinio: flags['dev-minio'] === true || raw.devMinio === true,
+    seedRepo: flags['seed-repo'] ?? raw.seedRepo,
+    imageTag: flags['image-tag'] ?? raw.imageTag,
+    ...(flags['s3-endpoint'] || raw.s3
+      ? {
+          s3: {
+            endpoint: flags['s3-endpoint'] ?? raw.s3?.endpoint,
+            bucket: flags['s3-bucket'] ?? raw.s3?.bucket,
+            accessKeyId: flags['s3-access-key-id'] ?? raw.s3?.accessKeyId,
+            secretAccessKey: flags['s3-secret-access-key'] ?? raw.s3?.secretAccessKey,
+            region: flags['s3-region'] ?? raw.s3?.region,
+          },
+        }
+      : {}),
+  };
+
+  const { ok, errors, config } = validateWorkspaceConfig(merged);
+  if (!ok) {
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, errors }, null, 2)}\n`);
+    } else {
+      process.stderr.write('maude hub workspace-up: the configuration is not usable yet.\n\n');
+      for (const e of errors) process.stderr.write(`  • ${e}\n`);
+      process.stderr.write('\nRun with --help for the full list of options.\n');
+    }
+    process.exit(2);
+  }
+
+  // Reuse existing secrets — re-minting on a re-run would lock out every peer
+  // that already holds a token, and re-running is exactly what someone does
+  // after a failed attempt.
+  const existing = readExistingEnv(resolve(outDir, '.env'));
+  const hubSecret = existing.HUB_SECRET || randomBytes(32).toString('hex');
+  const adminPassword = config.adminPassword || existing.MAUDE_ADMIN_PASSWORD || generatePassword();
+  const reusedSecret = Boolean(existing.HUB_SECRET);
+
+  const entries = envEntries(config, { hubSecret, adminPassword });
+  const files = [
+    { name: '.env', body: renderEnv(entries), mode: 0o600 },
+    { name: 'docker-compose.yml', body: renderCompose(config), mode: 0o644 },
+    { name: 'Caddyfile', body: renderCaddyfile(config), mode: 0o644 },
+  ];
+  const plan = verificationPlan(config);
+  const duties = operatorDuties(config);
+
+  if (flags['dry-run']) {
+    const result = {
+      ok: true,
+      dryRun: true,
+      outDir,
+      files: files.map((f) => ({ name: f.name, bytes: Buffer.byteLength(f.body), mode: f.mode })),
+      verification: plan.map((s) => ({ id: s.id, title: s.title })),
+      duties: duties.map((d) => d.title),
+      reusedSecret,
+    };
+    if (flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else printDryRun({ config, outDir, files, plan, duties, reusedSecret });
+    return;
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  for (const f of files) {
+    const path = resolve(outDir, f.name);
+    writeFileSync(path, f.body, { encoding: 'utf8', mode: f.mode });
+    try {
+      chmodSync(path, f.mode);
+    } catch {
+      /* windows — best effort */
+    }
+  }
+
+  const dockerAvailable = await which('docker');
+  if (!dockerAvailable) {
+    if (flags.json) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, wrote: files.map((f) => f.name), error: 'docker not found' }, null, 2)}\n`
+      );
+    } else {
+      process.stdout.write(
+        `Wrote ${files.map((f) => f.name).join(', ')} to ${outDir}\n\n` +
+          'Docker is not on PATH, so the stack was not started and NOTHING WAS VERIFIED.\n' +
+          'Install Docker and run:\n\n' +
+          `  cd ${outDir} && docker compose up -d\n\n` +
+          'Then re-run this command to verify the deployment.\n'
+      );
+    }
+    process.exit(1);
+  }
+
+  process.stdout.write(`Wrote ${files.map((f) => f.name).join(', ')} to ${outDir}\n`);
+  process.stdout.write('Starting the stack…\n');
+  const up = await sh('docker', ['compose', 'up', '-d'], { cwd: outDir });
+  if (up.code !== 0) {
+    process.stderr.write(`docker compose up failed:\n${up.stderr}\n`);
+    process.exit(1);
+  }
+
+  // Verification is the deliverable. A URL printed without a proven round-trip
+  // tells the operator something this command does not know.
+  process.stdout.write('\nVerifying — this is the part that matters:\n');
+  const results = [];
+  let failed = 0;
+  for (const step of plan) {
+    const outcome = await runVerification(step, {
+      config,
+      hubSecret,
+      adminPassword,
+      outDir,
+      pkgRoot,
+    });
+    results.push({ id: step.id, title: step.title, ...outcome });
+    const mark = outcome.ok ? '✓' : outcome.skipped ? '–' : '✗';
+    process.stdout.write(`  ${mark} ${step.title}${outcome.note ? ` — ${outcome.note}` : ''}\n`);
+    if (!outcome.ok && !outcome.skipped) failed++;
+  }
+
+  if (flags.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: failed === 0, outDir, verification: results, duties }, null, 2)}\n`
+    );
+  } else {
+    printDuties(duties);
+    process.stdout.write(
+      failed === 0
+        ? `\nWorkspace verified: https://${config.domain}\n`
+        : `\n${failed} check(s) did NOT pass. The stack is running but is not proven — fix and re-run.\n`
+    );
+  }
+  if (failed > 0) process.exit(1);
+}
+
+// ------------------------------------------------------------------ helpers
+
+function readConfigFile(path) {
+  try {
+    return JSON.parse(readFileSync(resolve(path), 'utf8'));
+  } catch (err) {
+    process.stderr.write(
+      `maude hub workspace-up: couldn't read --config ${path}: ${err.message}\n`
+    );
+    process.exit(2);
+  }
+}
+
+/** Parse an existing `.env` so a re-run reuses secrets instead of re-minting. */
+function readExistingEnv(path) {
+  if (!existsSync(path)) return {};
+  const out = {};
+  try {
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+      const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+      if (m) out[m[1]] = m[2];
+    }
+  } catch {
+    /* unreadable → treat as absent */
+  }
+  return out;
+}
+
+/** Readable, high-entropy, and safe to paste — no ambiguous glyphs. */
+function generatePassword() {
+  const alphabet = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ23456789';
+  const bytes = randomBytes(24);
+  return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join('');
+}
+
+function sh(cmd, args, opts = {}) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+      stdout += d;
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d;
+    });
+    child.on('error', () => resolvePromise({ code: 127, stdout, stderr: 'spawn failed' }));
+    child.on('close', (code) => resolvePromise({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+async function which(bin) {
+  const res = await sh(process.platform === 'win32' ? 'where' : 'which', [bin]);
+  return res.code === 0;
+}
+
+/**
+ * Execute one verification step.
+ *
+ * A step this build cannot yet perform reports `skipped` with a reason — it
+ * NEVER reports success. Counting an unrun check as passed is the single
+ * fastest way to make a verification suite worthless.
+ */
+async function runVerification(step, { config, hubSecret }) {
+  const base = `https://${config.domain}`;
+  switch (step.id) {
+    case 'health': {
+      const res = await tryFetch(`${base}/health`);
+      return res.ok ? { ok: true } : { ok: false, note: res.note };
+    }
+    case 'admin-claimed': {
+      const res = await tryFetch(`${base}/admin/api/status`, {
+        headers: { Authorization: `Bearer ${hubSecret}` },
+      });
+      return res.ok ? { ok: true } : { ok: false, note: res.note };
+    }
+    default:
+      return {
+        ok: false,
+        skipped: true,
+        note: 'not yet automated — verify by hand, then close it in the plan',
+      };
+  }
+}
+
+async function tryFetch(url, init) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 10_000);
+    try {
+      const res = await fetch(url, { ...init, signal: ctrl.signal });
+      return res.ok ? { ok: true } : { ok: false, note: `HTTP ${res.status}` };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    return { ok: false, note: err.name === 'AbortError' ? 'timed out' : 'unreachable' };
+  }
+}
+
+function printDryRun({ config, outDir, files, plan, duties, reusedSecret }) {
+  process.stdout.write(
+    `maude hub workspace-up — DRY RUN, nothing was written\n\n` +
+      `  workspace   https://${config.domain}\n` +
+      `  first user  ${config.adminEmail}\n` +
+      `  storage     ${config.s3 ? `${config.s3.bucket} @ ${config.s3.endpoint}${config.s3.dev ? ' (dev MinIO)' : ''}` : 'none — media stays in git'}\n` +
+      `  project     ${config.seedRepo ?? 'starts fresh'}\n` +
+      `  image       ghcr.io/1agh/maude-hub:${config.imageTag}\n` +
+      `  out         ${outDir}\n` +
+      (reusedSecret ? '  secrets     reusing HUB_SECRET from the existing .env\n' : '') +
+      '\nWould write:\n'
+  );
+  for (const f of files) {
+    process.stdout.write(
+      `  ${f.name.padEnd(20)} ${Buffer.byteLength(f.body)} bytes  mode ${f.mode.toString(8)}\n`
+    );
+  }
+  process.stdout.write('\nWould then verify:\n');
+  for (const s of plan) process.stdout.write(`  • ${s.title} — ${s.detail}\n`);
+  printDuties(duties);
+}
+
+function printDuties(duties) {
+  process.stdout.write(
+    '\nThis command scaffolded and verified your workspace once. It does not\noperate it. What stays yours:\n\n'
+  );
+  for (const d of duties) {
+    process.stdout.write(`  ${d.title}\n      ${d.detail}\n`);
+  }
+}

package/cli/commands/hub.mjs

@@ -5,12 +5,30 @@
 
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { resolve } from 'node:path';
 
 import { parseArgs } from '../lib/argv.mjs';
 
-const SUBCOMMANDS = new Set(['serve', 'token', 'status', 'deploy', 'help']);
+const SUBCOMMANDS = new Set([
+  'serve',
+  'token',
+  'status',
+  'deploy',
+  'backup',
+  'restore-drill',
+  'asset-check',
+  'workspace-up',
+  'help',
+]);
 
 export async function run({ args, pkgRoot }) {
   const { positional } = parseArgs(args);
@@ -29,10 +47,17 @@ export async function run({ args, pkgRoot }) {
   if (sub === 'token') return runToken({ args, pkgRoot });
   if (sub === 'status') return runStatus({ args });
   if (sub === 'deploy') return runDeploy({ args, pkgRoot });
+  if (sub === 'backup') return runBackupNow({ args, pkgRoot });
+  if (sub === 'restore-drill') return runRestoreDrill({ args, pkgRoot });
+  if (sub === 'asset-check') return runAssetCheck({ args, pkgRoot });
+  if (sub === 'workspace-up') {
+    const mod = await import('./hub-workspace.mjs');
+    return mod.run({ args, pkgRoot });
+  }
 }
 
 function usage() {
-  return `maude hub <serve|token|status|deploy> [options]
+  return `maude hub <serve|token|status|deploy|backup|restore-drill|asset-check|workspace-up> [options]
 
   serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
         Start the self-hostable Yjs sync hub in the current process tree.
@@ -76,6 +101,47 @@ function usage() {
         HTTP GET <url>/health, print uptime/version/token-count/peers. URL
         defaults to http://localhost:1234. --json emits the raw response.
 
+  backup [--data PATH] [--target file://DIR] [--keep N]
+        Take one snapshot generation now (VACUUM INTO → gzip → target) and
+        prune to the retention limit. Target defaults to $MAUDE_BACKUP_TARGET,
+        or the MAUDE_S3_* env set (R2 / MinIO / S3).
+
+  restore-drill [--target file://DIR] [--sentinel DOCNAME] [--keep-dir] [--json]
+        Restore the NEWEST complete backup generation into a throwaway
+        directory and verify it: SQLite integrity_check, document count, and
+        (with --sentinel) that one named document came back with a non-empty
+        payload. Never touches the live data dir. Exits non-zero on failure so
+        it can be a CI step.
+
+        Run this on a schedule. A backup nobody has restored is a hypothesis:
+        a database that restores readable-but-empty looks exactly like a
+        working one until the day you need it.
+
+  asset-check [--root PATH] [--json]
+        Every 'assets/<sha8>' reference in the project must resolve — locally,
+        in the bucket, or both. Reports DANGLING references (referenced by a
+        canvas, present in neither) and, with a bucket configured, assets that
+        exist locally but were never mirrored.
+
+        A dangling reference is a permanently broken canvas: the 'assets/'
+        prefix is NEVER garbage-collected, and bucket lifecycle/expiry rules
+        must be OFF for it, because a canvas in git history can reference an
+        asset no current canvas does. Exits non-zero when anything dangles.
+
+  workspace-up [--domain HOST] [--admin-email EMAIL] [--s3-* ...] [--dry-run]
+        Stand up a self-hosted WORKSPACE — a hub that owns the project, commits
+        autosaves, and stores media in object storage — and verify it works
+        before saying so. Renders compose + Caddyfile + .env (0600), boots the
+        stack, then runs a verification plan (health, admin credential, sign-in,
+        canvas round-trip, git commit, object storage + no-expiry, restore
+        drill). Re-running is the upgrade path and REUSES existing secrets.
+
+        It scaffolds and verifies once — it does not operate the deployment.
+        Rotation, backups, upgrades and the bill stay with you; the run prints
+        that list rather than saying "done".
+
+        Run 'maude hub workspace-up --help' for every option.
+
   deploy <fly|docker> [--name NAME] [--region CODE] [--tag TAG] [--out DIR] [--force]
         Emit the deploy templates for the chosen target into the current
         directory (or --out DIR) with placeholders substituted, then print the
@@ -468,3 +534,259 @@ function formatDuration(seconds) {
   const h = Math.floor(m / 60);
   return `${h}h${(m % 60).toString().padStart(2, '0')}m${s.toString().padStart(2, '0')}s`;
 }
+
+// --------------------------------------------------------- backup + drill
+
+/**
+ * Resolve the hub's backup engine. It lives in apps/hub (it is hub-internal,
+ * not part of the published npm surface), so it is imported by path rather
+ * than as a package — the same way runServe reaches the hub entry point.
+ */
+async function loadBackupEngine(pkgRoot) {
+  const candidates = [
+    resolve(pkgRoot, 'apps/hub/src/backup.mjs'),
+    resolve(pkgRoot, '../apps/hub/src/backup.mjs'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return import(`file://${candidate}`);
+  }
+  process.stderr.write(
+    'maude hub: the backup engine (apps/hub/src/backup.mjs) was not found.\n' +
+      'This verb runs from a full checkout or the hub image, not from a plain npm install.\n'
+  );
+  process.exit(2);
+}
+
+function resolveTarget(engine, flags) {
+  const explicit = flags.target;
+  const target = explicit
+    ? explicit.startsWith('file://')
+      ? engine.fileTarget(explicit)
+      : null
+    : engine.targetFromEnv();
+  if (!target) {
+    process.stderr.write(
+      'maude hub: no backup target configured.\n' +
+        '  --target file:///path/to/dir, or set MAUDE_BACKUP_TARGET,\n' +
+        '  or the MAUDE_S3_{ENDPOINT,BUCKET,ACCESS_KEY_ID,SECRET_ACCESS_KEY} env set.\n'
+    );
+    process.exit(2);
+  }
+  return target;
+}
+
+async function runBackupNow({ args, pkgRoot }) {
+  const { flags } = parseArgs(args);
+  const engine = await loadBackupEngine(pkgRoot);
+  const dataDir = resolve(flags.data ?? process.env.DATA_DIR ?? 'data');
+  const target = resolveTarget(engine, flags);
+  const keep = Number(flags.keep ?? 14);
+
+  try {
+    const result = await engine.runBackup({ dataDir, target, keep });
+    process.stdout.write(`backed up ${dataDir} → ${target.describe}\n  ${result.prefix}\n`);
+    for (const f of result.files) {
+      process.stdout.write(`    ${f.name.padEnd(12)} ${(f.bytes / 1024).toFixed(1)} KB gz\n`);
+    }
+    if (result.pruned.length > 0) {
+      process.stdout.write(`  pruned ${result.pruned.length} old generation(s)\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`maude hub backup: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+async function runRestoreDrill({ args, pkgRoot }) {
+  const { flags } = parseArgs(args);
+  const engine = await loadBackupEngine(pkgRoot);
+  const target = resolveTarget(engine, flags);
+  const scratchDir = resolve(
+    flags['scratch-dir'] ?? `${process.env.TMPDIR ?? '/tmp'}/maude-restore-drill-${process.pid}`
+  );
+
+  let verdict;
+  try {
+    verdict = await engine.restoreDrill({
+      target,
+      scratchDir,
+      sentinel: flags.sentinel,
+      which: flags.generation,
+    });
+  } catch (err) {
+    if (flags.json) process.stdout.write(`${JSON.stringify({ ok: false, error: err.message })}\n`);
+    else process.stderr.write(`maude hub restore-drill: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `restore drill — ${target.describe}\n` +
+        `  generation   ${verdict.generation}\n` +
+        `  restored     ${verdict.restored.join(', ')}\n` +
+        `  integrity    ${verdict.integrity}\n` +
+        `  documents    ${verdict.documents}\n` +
+        (verdict.sentinel
+          ? `  sentinel     ${verdict.sentinel.name} — ${verdict.sentinel.present ? `${verdict.sentinel.bytes} bytes` : 'ABSENT'}\n`
+          : '') +
+        `  ${verdict.ok ? 'PASS' : 'FAIL'}\n`
+    );
+    for (const p of verdict.problems) process.stderr.write(`  ! ${p}\n`);
+  }
+
+  if (!flags['keep-dir']) {
+    try {
+      rmSync(scratchDir, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+  if (!verdict.ok) process.exit(1);
+}
+
+// ------------------------------------------------------- asset integrity
+
+/**
+ * Every `assets/<sha8>` a canvas points at must resolve somewhere.
+ *
+ * The failure this catches is quiet and permanent: a reference whose bytes
+ * exist on nobody's disk and in no bucket renders as a broken image forever,
+ * and no amount of syncing fixes it. Content addressing means we can check it
+ * cheaply — the reference IS the identity.
+ */
+async function runAssetCheck({ args, pkgRoot }) {
+  const { flags } = parseArgs(args);
+  const root = resolve(flags.root ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+  const designRoot = resolveDesignRoot(root);
+  if (!designRoot) {
+    process.stderr.write(`maude hub asset-check: no .design/ found under ${root}\n`);
+    process.exit(2);
+  }
+
+  // Scan every text file under the design root for asset references. Regex over
+  // the whole tree rather than parsing TSX: a reference is a reference whether
+  // it appears in JSX, a meta sidecar, or a CSS url().
+  const referenced = new Map(); // key -> Set(files that reference it)
+  const REF = /assets\/([0-9a-f]{8})(?:\.[A-Za-z0-9]{1,8})?/g;
+  const SKIP_DIRS = new Set(['assets', 'node_modules', '.git']);
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') && entry.name !== '.design') continue;
+      // Per-machine runtime state (DDR-115's `_*` taxonomy) is not a canvas
+      // reference — `_generate-history.json` recording an asset it once made
+      // is not a broken canvas, and scanning it would report noise as damage.
+      if (entry.name.startsWith('_')) continue;
+      const abs = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(abs);
+        continue;
+      }
+      if (!/\.(tsx|jsx|ts|js|json|css|svg|md|html)$/i.test(entry.name)) continue;
+      let text;
+      try {
+        text = readFileSync(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const m of text.matchAll(REF)) {
+        const key = m[0].slice('assets/'.length);
+        if (!referenced.has(key)) referenced.set(key, new Set());
+        referenced.get(key).add(abs.slice(root.length + 1));
+      }
+    }
+  };
+  walk(designRoot);
+
+  // Local presence, keyed by the LEADING 8 hex chars of the filename.
+  //
+  // Splitting on '.' looks equivalent and is not: the real corpus contains
+  // `<sha8>-<label>.<ext>` (ingested footage) and `<sha8>.<part>.json`
+  // (sidecars), so `name.split('.')[0]` yields `deadbeef-cloud` and the asset
+  // reads as missing. That produced a false DANGLING report against this repo's
+  // own design root — the reference was fine and the index was wrong.
+  const assetsDir = resolve(designRoot, 'assets');
+  const localBySha = new Map();
+  if (existsSync(assetsDir)) {
+    for (const name of readdirSync(assetsDir)) {
+      const sha = name.match(/^([0-9a-f]{8})(?:[-.]|$)/)?.[1];
+      if (sha && !localBySha.has(sha)) localBySha.set(sha, name);
+    }
+  }
+
+  const engine = await loadBackupEngine(pkgRoot);
+  const s3mod = await import(`file://${resolve(pkgRoot, 'apps/hub/src/s3.mjs')}`).catch(() => null);
+  const s3 = s3mod?.s3ConfigFromEnv?.() ?? null;
+  void engine;
+
+  const dangling = [];
+  const localOnly = [];
+  let inBucket = 0;
+
+  for (const [key, files] of referenced) {
+    const sha = key.split('.')[0];
+    const local = localBySha.has(sha);
+    let remote = false;
+    if (s3) {
+      try {
+        remote = !!(await s3mod.headObject(s3, `assets/${localBySha.get(sha) ?? key}`));
+      } catch {
+        remote = false;
+      }
+    }
+    if (remote) inBucket++;
+    if (!local && !remote) dangling.push({ key, files: [...files] });
+    else if (local && s3 && !remote) localOnly.push({ key, files: [...files] });
+  }
+
+  const report = {
+    designRoot: designRoot.slice(root.length + 1),
+    referenced: referenced.size,
+    local: localBySha.size,
+    bucket: s3 ? `s3://${s3.bucket}` : null,
+    inBucket: s3 ? inBucket : null,
+    dangling,
+    notMirrored: s3 ? localOnly : null,
+    ok: dangling.length === 0,
+  };
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(
+      `asset check — ${report.designRoot}\n` +
+        `  referenced   ${report.referenced}\n` +
+        `  on disk      ${report.local}\n` +
+        (s3
+          ? `  in bucket    ${inBucket}/${report.referenced} (${report.bucket})\n`
+          : '  bucket       not configured (set MAUDE_S3_* to check the mirror)\n')
+    );
+    for (const d of dangling) {
+      process.stderr.write(`  DANGLING assets/${d.key} — referenced by ${d.files.join(', ')}\n`);
+    }
+    if (localOnly.length > 0) {
+      process.stdout.write(
+        `  ${localOnly.length} asset(s) exist locally but are NOT mirrored — ` +
+          'a second machine cannot resolve them yet.\n'
+      );
+    }
+    process.stdout.write(`  ${report.ok ? 'OK' : 'FAILED'}\n`);
+  }
+
+  if (!report.ok) process.exit(1);
+}
+
+/** `.design/` under `root`, honouring a config-declared designRoot. */
+function resolveDesignRoot(root) {
+  const configured = (() => {
+    for (const candidate of ['.design/config.json', '.maude/config.json']) {
+      const abs = resolve(root, candidate);
+      if (existsSync(abs)) return resolve(root, candidate, '..');
+    }
+    return null;
+  })();
+  if (configured) return configured;
+  const fallback = resolve(root, '.design');
+  return existsSync(fallback) ? fallback : null;
+}