@1agh/maude 0.47.0 → 0.49.0

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;
+}

package/cli/commands/hub.test.mjs

@@ -32,7 +32,20 @@ function withDataDir(fn) {
 test('hub help prints subcommand summary on stdout', () => {
   const res = runCli(['hub', 'help']);
   assert.equal(res.status, 0, res.stderr);
-  assert.match(res.stdout, /maude hub <serve\|token\|status\|deploy>/);
+  // Every verb must appear in the usage header — a subcommand that exists but
+  // isn't listed is one nobody finds.
+  assert.match(res.stdout, /maude hub <[a-z|-]+> \[options\]/);
+  for (const verb of [
+    'serve',
+    'token',
+    'status',
+    'deploy',
+    'backup',
+    'restore-drill',
+    'asset-check',
+  ]) {
+    assert.ok(res.stdout.includes(verb), `usage must mention "${verb}"`);
+  }
   assert.match(res.stdout, /token generate --label NAME/);
   assert.match(res.stdout, /token rotate --label NAME/);
   assert.match(res.stdout, /deploy <fly\|docker>/);

package/cli/commands/init.mjs

@@ -1,8 +1,29 @@
-import { stat } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 import { copyTree } from '../lib/copy-tree.mjs';
 
+// Thin STATE.md written under --kg: the knowledge graph is the history authority,
+// so STATE.md shrinks to a human breadcrumb (Open fork #2 — stub, not removal).
+const KG_STATE_STUB = `# Workflow State
+
+> **kgai-active repo** — decision history + working context live in the knowledge graph, not this file.
+> The \`flow:workflow-state\` skill reads/writes the graph via \`flow:kgai-backend\`.
+
+**Status:** ready
+**Active plan:** —
+
+## Where the history went
+
+- **Decisions / "why is X so":** \`maude kg context --about "<area>"\`
+- **Recent movements:** \`maude kg query "MATCH (d:Decision) WHERE d.author='<you>' RETURN d.title, d.recorded_at ORDER BY d.recorded_at DESC LIMIT 10"\`
+- **Conflicts:** \`maude kg conflicts\`
+
+The old \`.ai/decisions/\` archive (if any) is preserved read-only — never auto-deleted.
+`;
+
 const PLACEHOLDER = 'PROJECT_NAME';
 // Files in the skeleton that contain the project-name placeholder and should
 // be templated on copy.
@@ -43,10 +64,12 @@ const CHANGELOG_STUBS = {
 const VALID_PROVIDERS = new Set(['changesets', 'git-cliff', 'conventional', 'custom', 'none']);
 
 export async function run({ args, pkgRoot }) {
-  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help'] });
+  const { flags } = parseArgs(args, { booleans: ['force', 'dry-run', 'help', 'kg'] });
   if (flags.help) {
     process.stdout.write(
-      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--force] [--dry-run]\n'
+      'maude init [--name <project>] [--provider <changesets|git-cliff|conventional|custom|none>] [--kg] [--force] [--dry-run]\n' +
+        '  --kg   opt into the kgai knowledge-graph backend: write a thin STATE.md pointer-stub\n' +
+        '         and bootstrap a local store via `kg init` (no-op when `kg` is not installed).\n'
     );
     return;
   }
@@ -136,10 +159,64 @@ export async function run({ args, pkgRoot }) {
     (await pathExists(resolve(cwd, 'CLAUDE.md'))) ||
     (await pathExists(resolve(cwd, '.claude', 'CLAUDE.md')));
 
+  // --kg (opt-in): the knowledge graph becomes the history authority. Replace the
+  // scaffolded STATE.md with a thin pointer-stub and bootstrap a local store.
+  // The `knowledgeGraph` config block stays ABSENT (bias-free skeleton ⇒ auto via
+  // the schema default — onboarding / `maude doctor --fix` fills store + scope).
+  if (flags.kg && !flags['dry-run']) {
+    const statePath = resolve(aiDir, 'state', 'STATE.md');
+    await writeFile(statePath, KG_STATE_STUB, 'utf8');
+    process.stdout.write('  kgai: wrote thin STATE.md pointer-stub (history lives in the graph)\n');
+    const kgBin = resolveKgBin();
+    if (kgBin) {
+      // No --root: kgai defaults the store to `<cwd>/.kgai/store` (which the
+      // resolver auto-detects and the gitignore block ignores). Passing --root
+      // would place the store's loose files at cwd root instead.
+      const r = spawnSync(kgBin, ['init'], {
+        cwd,
+        stdio: 'ignore',
+        env: kgInitEnv(),
+      });
+      process.stdout.write(
+        r.status === 0
+          ? '  kgai: bootstrapped local store via `kg init` (git-author actor captured)\n'
+          : '  kgai: `kg init` did not complete — run it manually (see docs/kgai-onboarding.md)\n'
+      );
+    } else {
+      process.stdout.write(
+        '  kgai: `kg` not installed — store not bootstrapped. See docs/kgai-onboarding.md.\n'
+      );
+    }
+    process.stdout.write(
+      '  kgai: set `knowledgeGraph.store` + `scope` per docs/kgai-onboarding.md\n'
+    );
+  } else if (flags.kg) {
+    process.stdout.write('  kgai: (dry-run) would write STATE.md stub + bootstrap the store\n');
+  }
+
   printSummary(result);
   printNextSteps(projectName, claudeMdExists);
 }
 
+/** KGAI_BIN (desktop-staged sidecar) → `kg` on PATH → null. Mirrors kg.mjs. */
+function resolveKgBin() {
+  if (process.env.KGAI_BIN && existsSync(process.env.KGAI_BIN)) return process.env.KGAI_BIN;
+  const probe = spawnSync('sh', ['-c', 'command -v kg'], { encoding: 'utf8' });
+  const found = (probe.stdout || '').trim();
+  return probe.status === 0 && found ? found : null;
+}
+
+/** Fold KGAI_LIB into DYLD_LIBRARY_PATH so a staged libkuzu resolves (desktop). */
+function kgInitEnv() {
+  const env = { ...process.env };
+  if (process.env.KGAI_LIB) {
+    env.DYLD_LIBRARY_PATH = [process.env.KGAI_LIB, process.env.DYLD_LIBRARY_PATH]
+      .filter(Boolean)
+      .join(':');
+  }
+  return env;
+}
+
 function isValidName(s) {
   return /^[a-z0-9._-]+$/i.test(s);
 }