@1agh/maude 0.22.2 → 0.24.0

package/README.md

@@ -11,7 +11,7 @@ A personal marketplace of Claude Code plugins. Two plugins today, plus a `maude`
 
 | Plugin | What it does |
 | ------ | ------------ |
-| **`design`** | Canvas-first iteration on HTML/JSX mocks under `.design/` — element selection via Cmd+Click, auto-managed dev server, chained UX/DS critique. |
+| **`design`** | Canvas-first iteration on TSX/JSX mocks under `.design/` — element selection via Cmd+Click, auto-managed dev server, chained UX/DS critique. |
 | **`flow`** | Generic agentic workflow loop with a second-brain `.ai/` workspace. `/flow:plan`, `/flow:execute`, `/flow:utils-verify`, `/flow:validate`, `/flow:done`, `/flow:init`, `/flow:record-ddr`, `/flow:scenario`, …. Project-agnostic via `<project>` placeholders + per-repo `.ai/workflows.config.json`. |
 
 Plus the **`maude`** CLI — `maude init` scaffolds a fresh `.ai/` workspace from the flow plugin skeleton; `maude design serve` boots the design dev server. The legacy `mdcc` alias still works (prints a deprecation warning) and will be removed in v0.17.x.
@@ -66,6 +66,35 @@ Then inside Claude Code (with `flow@maude` installed):
 
 `/init` writes the `CLAUDE.md` Claude auto-loads every session (conventions, build commands, gotchas). `/flow:init` handles the structured workspace config — they're complementary, not duplicates.
 
+### Health check — `maude doctor`
+
+`maude doctor` reports missing dependencies, config schema errors, stack drift, and missing quality-gate declarations in one shot. `--fix` applies safe auto-fixes (prompts per dependency install; never overwrites existing user config values). `--json` for programmatic consumers. Run it after stack changes or before opening a PR.
+
+```sh
+maude doctor          # full health check (deps + config + quality)
+maude doctor --fix    # install missing deps (per-item prompt) + apply safe config fixes
+maude doctor --json   # machine-readable envelope
+```
+
+**Quality gates** are declared in `.ai/workflows.config.json` under the top-level `quality` map — a flat `gate → shell command` mapping (e.g. `{ "lint": "pnpm lint", "tests": "pnpm test" }`). Flow commands (`/flow:validate`, `/flow:utils-verify`, `/flow:quick`) read it directly and run each via `eval`. There is **no `maude quality run` wrapper** — `pnpm <script>` is already the runner. Hook it into your own pre-commit tool with a one-liner: `eval $(jq -r '.quality.lint' .ai/workflows.config.json)`. Populate the block by running `maude doctor --fix` once your `package.json` scripts exist (additive — it never overwrites a command you tuned).
+
+### Sidecar cache — `maude cache`
+
+Flow + design commands reuse expensive cross-session work through a small sidecar cache at `.ai/cache/` ([DDR-061](.ai/decisions/DDR-061-sidecar-cache-monitor-background-orchestration.md)): domain research (skips 30–90 s of WebSearch on a same-domain brief), codebase-intelligence scans (skips rescan when the tree is unchanged), parsed design-system vocabulary, and security-review reuse (one shared 1-hour window across `/flow:validate`, `/flow:done`, `/flow:validate-security`). Correctness comes first — most layers are content-addressed (a changed input changes the key → guaranteed miss), and a stale entry is never served speculatively.
+
+```sh
+maude cache list              # layers, entry counts, sizes, last-write time
+maude cache stats             # hit/miss counters + hit-rate per layer
+maude cache inspect <layer>   # list a layer's entries; add a <key> to print one
+maude cache clear [layer]     # wipe one layer (or everything)
+```
+
+The `research/domain` and `codebase-intelligence` layers are **committed** (deterministic on a given tree, so collaborators share the hit); the per-brief, design-context, security, and scenario layers are gitignored. `maude init` drops a `.ai/.gitignore` that encodes the split.
+
+### Plugins call `maude` for executable logic
+
+Plugin slash-commands reach all executable logic through the on-PATH `maude` binary — never a relative `cli/lib/*.mjs` path or a raw `$CLAUDE_PLUGIN_ROOT/dev-server/bin/*.sh` invocation ([DDR-062](.ai/decisions/DDR-062-plugins-reach-executable-logic-via-maude.md)). The marketplace copies each plugin alone (no sibling `cli/`, no `dev-server/`), and a flow command's `$CLAUDE_PLUGIN_ROOT` points at the flow plugin (which has no dev-server at all) — so the only contract that holds across every install shape is `maude`, which resolves bundled helpers from its own package root. Cache/preflight go via `maude cache …` / `maude preflight …`; the design dev-server's bash helpers go via **`maude design <verb>`** (`screenshot`, `server-up`, `prep`, `slug`, `smoke`, `runtime-health`, …) — see `maude design help`. Keep the global `maude` current; a stale binary means stale helpers.
+
 ## Runtime requirements
 
 - **Node ≥ 20** — for the dev server and CLI. Zero npm runtime deps.
@@ -79,6 +108,10 @@ Two clean paths, no middle ground ([DDR-047](.ai/decisions/DDR-047-collab-scope-
 - **v1.0 — git handoff OR loopback multi-tab.** Push / pull is the cross-machine story. On a single machine, two browser tabs (or two Claude Code instances editing the same repo) sync cursors, comments, and annotations live over loopback WebSocket. The dev server refuses any non-loopback `host` header on the collab WS endpoint.
 - **v1.1 — deploy a hub** (Phase 9, in-flight). Cross-machine live collab needs a hub binary you deploy yourself. No tunnel mode; no shared cloud.
 
+## Security
+
+Solo mode (the default) is fully local — no accounts, no telemetry, no network trust surface, and the canvas sandbox is on by default. Linked (hub) mode is opt-in and carries a documented trust model with disclosed, bounded residuals (hub-pushed content is treated as untrusted input). The full account — what runs where, what the canvas sandbox does and doesn't close, `.tsx` sync's double opt-in, untrusted-context handling — is at [`/docs/security`](https://maude.iagh.cz/docs/security) (source: [`site/content/docs/security.mdx`](./site/content/docs/security.mdx)). To **report** a vulnerability, see [SECURITY.md](./SECURITY.md).
+
 ## What's where
 
 User-facing docs live in two places — the README points you the right way:

package/cli/bin/maude.mjs

@@ -13,7 +13,10 @@ const PKG_ROOT = resolve(CLI_ROOT, '..');
 const COMMANDS = {
   init: () => import('../commands/init.mjs'),
   config: () => import('../commands/config.mjs'),
+  cache: () => import('../commands/cache.mjs'),
+  preflight: () => import('../commands/preflight.mjs'),
   design: () => import('../commands/design.mjs'),
+  'scenario-report': () => import('../commands/scenario-report.mjs'),
   doctor: () => import('../commands/doctor.mjs'),
   help: () => import('../commands/help.mjs'),
   hub: () => import('../commands/hub.mjs'),

package/cli/commands/cache.mjs

@@ -0,0 +1,181 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from '../lib/argv.mjs';
+import { check, clear, entries, list, recordAccess, stats, write } from '../lib/cache.mjs';
+
+// `maude cache <get|put|list|stats|inspect|clear>` — inspect and manage the
+// sidecar cache layer (cli/lib/cache.mjs, Phase C / DDR-061).
+//
+// get/put are the PROGRAMMATIC surface that plugin slash-commands + agents call.
+// The only cache entry point reachable from a plugin across install shapes is the
+// `maude` binary on PATH (a declared plugin dependency) — NOT a relative path to
+// cli/lib/cache.mjs, which the marketplace never copies beside a plugin (each
+// plugin is copied alone into cache/<marketplace>/<plugin>/<version>/). See DDR-061.
+
+export async function run({ args }) {
+  const { positional, flags } = parseArgs(args);
+  const sub = positional[0];
+
+  if (!sub || sub === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (sub === 'get') return cmdGet(positional[1], positional[2], flags);
+  if (sub === 'put') return cmdPut(positional[1], positional[2], positional[3], flags);
+  if (sub === 'list') return cmdList();
+  if (sub === 'stats') return cmdStats();
+  if (sub === 'inspect') return cmdInspect(positional[1], positional[2]);
+  if (sub === 'clear') return cmdClear(positional[1]);
+
+  process.stderr.write(`maude cache: unknown subcommand "${sub}"\n${usage()}`);
+  process.exit(2);
+}
+
+function usage() {
+  return `maude cache <get|put|list|stats|inspect|clear> [args]
+
+  cache get <layer> <key> [--ttl-ms N]   Print the cached value (compact JSON) on a
+                                         fresh hit, exit 0. On miss/stale: no stdout,
+                                         exit 1. (Omit --ttl-ms for SHA-keyed layers.)
+  cache put <layer> <key> [file] [--meta JSON]
+                                         Write a value (from <file> or stdin) into the cache.
+  cache list                    Layers with entry counts, sizes, last-write time.
+  cache stats                   Hit/miss counters and hit-rate per layer.
+  cache inspect <layer> [key]   List entries in a layer; with <key>, print one entry.
+  cache clear [layer[/key]]     Wipe one layer (or single entry), or everything.
+
+  Layers: research/domain, research/project, codebase-intelligence,
+          design-context, security, scenario, validate.
+`;
+}
+
+// Programmatic read for slash-commands: stdout = compact JSON value on a fresh
+// hit (exit 0); silent + exit 1 on miss or past-TTL, so bash `&&`/`||` branches.
+function cmdGet(layer, key, flags) {
+  if (!layer || !key) throw new Error('maude cache get <layer> <key> [--ttl-ms N]');
+  const hit = check(layer, key);
+  const ttlMs = flags['ttl-ms'] != null ? Number(flags['ttl-ms']) : Number.POSITIVE_INFINITY;
+  const fresh = hit && hit.ageMs <= ttlMs;
+  recordAccess(layer, fresh ? 'hit' : 'miss'); // feed `maude cache stats`
+  if (!fresh) {
+    process.exitCode = 1; // miss / stale — no stdout
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(hit.value)}\n`);
+}
+
+// Programmatic write for slash-commands. Value JSON comes from <file> or stdin.
+function cmdPut(layer, key, file, flags) {
+  if (!layer || !key) throw new Error('maude cache put <layer> <key> [file] [--meta JSON]');
+  const raw = file ? readFileSync(file, 'utf8') : readFileSync(0, 'utf8');
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('maude cache put: input is not valid JSON');
+  }
+  const meta = flags.meta ? JSON.parse(flags.meta) : {};
+  const { path } = write(layer, key, value, meta);
+  process.stderr.write(`cached ${layer}/${key} → ${path}\n`);
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function fmtAge(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}
+
+function cmdList() {
+  const layers = list();
+  if (layers.length === 0) {
+    process.stdout.write('cache is empty (no entries written yet)\n');
+    return;
+  }
+  process.stdout.write('LAYER                     ENTRIES   SIZE      LAST WRITE\n');
+  for (const l of layers) {
+    process.stdout.write(
+      `${l.layer.padEnd(25)} ${String(l.entries).padStart(7)}   ${fmtBytes(l.bytes).padEnd(9)} ${fmtAge(Date.now() - l.newest)}\n`
+    );
+  }
+}
+
+function cmdStats() {
+  const s = stats();
+  const allLayers = new Set([...Object.keys(s.hits), ...Object.keys(s.misses)]);
+  if (allLayers.size === 0) {
+    process.stdout.write('no cache activity recorded yet\n');
+    return;
+  }
+  process.stdout.write('LAYER                       HITS   MISSES   HIT-RATE\n');
+  for (const layer of [...allLayers].sort()) {
+    const hits = s.hits[layer] || 0;
+    const misses = s.misses[layer] || 0;
+    const total = hits + misses;
+    const rate = total ? `${Math.round((hits / total) * 100)}%` : '—';
+    process.stdout.write(
+      `${layer.padEnd(25)} ${String(hits).padStart(6)}  ${String(misses).padStart(7)}   ${rate.padStart(8)}\n`
+    );
+  }
+  if (s.since) process.stdout.write(`\nsince ${new Date(s.since).toISOString()}\n`);
+}
+
+function cmdInspect(layer, key) {
+  if (!layer) throw new Error('maude cache inspect <layer> [key]');
+  if (key) {
+    const hit = check(layer, key);
+    if (!hit) {
+      process.stderr.write(`(no entry ${layer}/${key})\n`);
+      process.exit(1);
+    }
+    process.stdout.write(
+      `${layer}/${key}\n  written: ${new Date(hit.writtenAt).toISOString()} (${fmtAge(hit.ageMs)})\n  meta: ${JSON.stringify(hit.meta)}\n\n${JSON.stringify(hit.value, null, 2)}\n`
+    );
+    return;
+  }
+  const list_ = entries(layer);
+  if (list_.length === 0) {
+    process.stdout.write(`(layer "${layer}" is empty)\n`);
+    return;
+  }
+  process.stdout.write(`${layer} — ${list_.length} entr${list_.length === 1 ? 'y' : 'ies'}\n`);
+  for (const e of list_) {
+    process.stdout.write(
+      `  ${e.key.padEnd(40)} ${fmtBytes(e.bytes).padEnd(9)} ${fmtAge(e.ageMs)}\n`
+    );
+  }
+}
+
+function cmdClear(target) {
+  if (!target) {
+    const { removed } = clear();
+    process.stdout.write(
+      `cleared entire cache (${removed} top-level item${removed === 1 ? '' : 's'})\n`
+    );
+    return;
+  }
+  // `layer/key` clears a single entry; bare `layer` clears the whole layer.
+  const slash = target.lastIndexOf('/');
+  if (slash > 0) {
+    const layer = target.slice(0, slash);
+    const key = target.slice(slash + 1);
+    // Only treat as entry-clear if the entry actually exists; otherwise treat
+    // the whole path as a (nested) layer to wipe.
+    if (check(layer, key)) {
+      clear(layer, key);
+      process.stdout.write(`cleared ${layer}/${key}\n`);
+      return;
+    }
+  }
+  const { removed } = clear(target);
+  if (removed) process.stdout.write(`cleared layer "${target}"\n`);
+  else process.stdout.write(`nothing to clear at "${target}"\n`);
+}

package/cli/commands/cache.test.mjs

@@ -0,0 +1,166 @@
+// `maude cache` CLI end-to-end via spawnSync — seeds a temp cache dir through
+// the cache lib, then exercises list / stats / inspect / clear over the bin.
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { getOrCompute, write } from '../lib/cache.mjs';
+
+const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+
+function runCli(args, cacheDir) {
+  return spawnSync(process.execPath, [BIN, 'cache', ...args], {
+    encoding: 'utf8',
+    env: { ...process.env, MAUDE_CACHE_DIR: cacheDir },
+  });
+}
+
+async function withCache(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-cli-cache-'));
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('cache help prints subcommand summary', async () => {
+  await withCache((dir) => {
+    const res = runCli(['help'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /maude cache <get\|put\|list\|stats\|inspect\|clear>/);
+  });
+});
+
+test('cache list reports "empty" before any writes', async () => {
+  await withCache((dir) => {
+    const res = runCli(['list'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /cache is empty/);
+  });
+});
+
+test('cache list shows seeded layers with entry counts', async () => {
+  await withCache((dir) => {
+    write('research/domain', 'finance.aaa', { mood: 1 }, {}, { cacheDir: dir });
+    write('research/domain', 'finance.bbb', { mood: 2 }, {}, { cacheDir: dir });
+    write('codebase-intelligence', 'sha123', { files: 9 }, {}, { cacheDir: dir });
+    const res = runCli(['list'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /research\s+2/);
+    assert.match(res.stdout, /codebase-intelligence\s+1/);
+  });
+});
+
+test('cache stats reports hit-rate after getOrCompute activity', async () => {
+  await withCache(async (dir) => {
+    const base = {
+      cacheDir: dir,
+      layer: 'codebase-intelligence',
+      key: 'k',
+      ttlMs: 60_000,
+      compute: () => ({ v: 1 }),
+    };
+    await getOrCompute(base); // miss
+    await getOrCompute(base); // hit
+    const res = runCli(['stats'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /codebase-intelligence/);
+    assert.match(res.stdout, /50%/);
+  });
+});
+
+test('cache inspect lists entries, and prints one entry by key', async () => {
+  await withCache((dir) => {
+    write('design-context', 'ds/tok1', { tokens: 42 }, { dsName: 'ds' }, { cacheDir: dir });
+    const listRes = runCli(['inspect', 'design-context'], dir);
+    assert.equal(listRes.status, 0, listRes.stderr);
+    assert.match(listRes.stdout, /ds\/tok1/);
+
+    const oneRes = runCli(['inspect', 'design-context', 'ds/tok1'], dir);
+    assert.equal(oneRes.status, 0, oneRes.stderr);
+    assert.match(oneRes.stdout, /"tokens": 42/);
+  });
+});
+
+test('cache clear <layer> wipes only that layer', async () => {
+  await withCache((dir) => {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir: dir });
+    write('codebase-intelligence', 'b', { x: 2 }, {}, { cacheDir: dir });
+    const res = runCli(['clear', 'research/domain'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /cleared layer "research\/domain"/);
+    assert.ok(!existsSync(join(dir, 'research', 'domain')));
+    assert.ok(existsSync(join(dir, 'codebase-intelligence')));
+  });
+});
+
+test('cache clear with no args wipes everything', async () => {
+  await withCache((dir) => {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir: dir });
+    const res = runCli(['clear'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /cleared entire cache/);
+    assert.ok(!existsSync(join(dir, 'research')));
+  });
+});
+
+test('get prints compact JSON on a fresh hit (exit 0), nothing on miss (exit 1)', async () => {
+  await withCache((dir) => {
+    write('codebase-intelligence', 'sha9', { files: 142 }, {}, { cacheDir: dir });
+    const hit = runCli(['get', 'codebase-intelligence', 'sha9'], dir);
+    assert.equal(hit.status, 0, hit.stderr);
+    assert.equal(hit.stdout.trim(), '{"files":142}');
+
+    const miss = runCli(['get', 'codebase-intelligence', 'absent'], dir);
+    assert.equal(miss.status, 1);
+    assert.equal(miss.stdout, '');
+  });
+});
+
+test('get treats a past-TTL entry as a miss (exit 1)', async () => {
+  await withCache((dir) => {
+    const { path } = write('security', 'head1', { verdict: 'PASS' }, {}, { cacheDir: dir });
+    const stored = JSON.parse(readFileSync(path, 'utf8'));
+    stored.writtenAt = Date.now() - 2 * 60 * 60 * 1000; // 2 h old
+    writeFileSync(path, JSON.stringify(stored), 'utf8');
+    const res = runCli(['get', 'security', 'head1', '--ttl-ms', String(60 * 60 * 1000)], dir);
+    assert.equal(res.status, 1, 'past-TTL must be a miss');
+  });
+});
+
+test('get feeds maude cache stats (hit + miss counters)', async () => {
+  await withCache((dir) => {
+    write('research/domain', 'k', { v: 1 }, {}, { cacheDir: dir });
+    runCli(['get', 'research/domain', 'k'], dir); // hit
+    runCli(['get', 'research/domain', 'absent'], dir); // miss
+    const res = runCli(['stats'], dir);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /research\/domain/);
+    assert.match(res.stdout, /50%/);
+  });
+});
+
+test('put writes a value (from file) that get then reads back', async () => {
+  await withCache((dir) => {
+    const f = join(dir, 'payload.json');
+    writeFileSync(f, JSON.stringify({ mood: ['calm'], queries: 7 }), 'utf8');
+    const put = runCli(['put', 'research/domain', 'finance--discovery', f], dir);
+    assert.equal(put.status, 0, put.stderr);
+    const get = runCli(['get', 'research/domain', 'finance--discovery'], dir);
+    assert.equal(get.status, 0);
+    assert.deepEqual(JSON.parse(get.stdout), { mood: ['calm'], queries: 7 });
+  });
+});
+
+test('unknown subcommand exits non-zero', async () => {
+  await withCache((dir) => {
+    const res = runCli(['frobnicate'], dir);
+    assert.equal(res.status, 2);
+    assert.match(res.stderr, /unknown subcommand/);
+  });
+});

package/cli/commands/design-link.test.mjs

@@ -6,7 +6,7 @@
 
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -202,6 +202,88 @@ test('status --json emits structured payload', async () => {
   assert.equal(payload.url, URL);
   assert.equal(payload.tokenStored, true);
   assert.equal(payload.hub.reachable, true);
-  assert.equal(payload.sync.agent, 'not-implemented');
+  // No `maude design serve` running in this test → no _sync.json → idle.
+  assert.equal(payload.sync.agent, 'idle');
+  cleanup();
+});
+
+test('status reports zero-syncable when _sync.json is notSyncable (DDR-060 / 9.1-D)', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  // Simulate the dev-server having written a zero-syncable _sync.json.
+  writeFileSync(
+    join(workspace, '.design/_sync.json'),
+    JSON.stringify({
+      linked: true,
+      notSyncable: true,
+      url: URL,
+      reason: '4 TSX canvas(es) found but none are syncable — see DDR-060.',
+      tsxCount: 4,
+      canvases: 0,
+      updatedAt: Date.now(),
+    }),
+    'utf8'
+  );
+
+  const human = await runCli(['design', 'status']);
+  assert.equal(human.status, 0, human.stderr);
+  assert.match(human.stdout, /0 syncable canvases/);
+  assert.match(human.stdout, /DDR-060/);
+
+  const json = await runCli(['design', 'status', '--json']);
+  const payload = JSON.parse(json.stdout);
+  assert.equal(payload.sync.notSyncable, true);
+  assert.equal(payload.sync.tsxCount, 4);
+  cleanup();
+});
+
+// --------------------------------------------------- DDR-054 F2/F4 trust gate
+
+const REMOTE_URL = 'http://hub.invalid:9999'; // .invalid never resolves (RFC 6761)
+
+test('linking a non-loopback hub without --yes (non-TTY) refuses', async () => {
+  // The spawned child has no TTY on stdin, so the gate must refuse rather
+  // than silently link a remote hub in a script.
+  const res = await runCli(['design', 'link', REMOTE_URL, '--token', 'mau_x', '--force']);
+  assert.equal(res.status, 1);
+  assert.match(res.stderr, /requires confirmation/);
+  // No link written.
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub, undefined);
+  cleanup();
+});
+
+test('linking a non-loopback hub with --yes records trust + links', async () => {
+  const res = await runCli(['design', 'link', REMOTE_URL, '--token', 'mau_x', '--yes', '--force']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stderr, /confirmed via --yes/);
+  assert.match(res.stderr, /UNTRUSTED/); // F3 linked-mode banner
+
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub.url, REMOTE_URL);
+
+  // Trust is recorded PER-MACHINE (hubs.json), never in a committable repo file.
+  const hubs = JSON.parse(readFileSync(hubsConfigPath, 'utf8'));
+  assert.ok(hubs.trusted.includes(REMOTE_URL), 'hub should be trusted on this machine');
+  assert.equal(
+    existsSync(join(workspace, '.maude/trusted-hubs')),
+    false,
+    'no committable trust file'
+  );
+
+  // Re-linking the now-trusted hub no longer needs --yes.
+  const second = await runCli(['design', 'link', REMOTE_URL, '--token', 'mau_y', '--force']);
+  assert.equal(second.status, 0, second.stderr);
+  cleanup();
+});
+
+test('--adopt against a non-loopback hub lists the upload manifest in the gate', async () => {
+  writeFileSync(join(workspace, '.design/screen.html'), '<button>hi</button>', 'utf8');
+  const res = await runCli(['design', 'adopt', REMOTE_URL, '--token', 'mau_x', '--yes', '--force']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stderr, /will UPLOAD 1 local file/);
+  assert.match(res.stderr, /\.design\/screen\.html/);
+
+  const hubs = JSON.parse(readFileSync(hubsConfigPath, 'utf8'));
+  assert.equal(typeof hubs.hubs[REMOTE_URL].adoptedAt, 'number'); // F4 attestation
   cleanup();
 });

package/cli/commands/design.mjs

@@ -1,9 +1,11 @@
-import { execSync, spawn } from 'node:child_process';
+import { execSync, spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 import { runAdopt, runLink, runStatus, runUnlink } from '../lib/design-link.mjs';
+import { writeGitignoreBlock } from '../lib/gitignore-block.mjs';
 
 const SUBCOMMANDS = new Set([
   'serve',
@@ -16,6 +18,27 @@ const SUBCOMMANDS = new Set([
   'help',
 ]);
 
+// Dev-tooling verbs that dispatch to the dev-server's bundled bash helpers
+// (Phase C / DDR-062). Plugin markdown invokes these via `maude design <verb>`
+// rather than `bash "$CLAUDE_PLUGIN_ROOT/dev-server/bin/<verb>.sh"` — the
+// marketplace never copies the dev-server beside a plugin, and CLAUDE_PLUGIN_ROOT
+// is unreliable in a real run. `maude` resolves the helper from its OWN package
+// root and sets CLAUDE_PLUGIN_ROOT authoritatively for the child. The whitelist
+// (not arbitrary `<verb>.sh` exec) keeps this off the path-traversal surface.
+const BIN_VERBS = new Set([
+  'screenshot',
+  'server-up',
+  'prep',
+  'slug',
+  'bootstrap-check',
+  'runtime-health',
+  'smoke',
+  'canvas-edit',
+  'handoff',
+  'asset-sweep',
+  'visual-sanity',
+]);
+
 export async function run({ args, pkgRoot }) {
   const { positional } = parseArgs(args);
   const sub = positional[0];
@@ -25,6 +48,10 @@ export async function run({ args, pkgRoot }) {
     return;
   }
 
+  // Dev-tooling verbs dispatch to the bundled bash helpers (DDR-062). Checked
+  // before SUBCOMMANDS so the whitelist owns the bin surface.
+  if (BIN_VERBS.has(sub)) return runBinDispatch(sub, { args, pkgRoot });
+
   if (!SUBCOMMANDS.has(sub)) {
     process.stderr.write(`maude design: unknown subcommand "${sub}"\n${usage()}`);
     process.exit(2);
@@ -39,8 +66,56 @@ export async function run({ args, pkgRoot }) {
   if (sub === 'adopt') return runAdopt({ args });
 }
 
+// Run a whitelisted dev-server bash helper, resolving it from maude's OWN
+// package root (NOT $CLAUDE_PLUGIN_ROOT) and setting CLAUDE_PLUGIN_ROOT
+// authoritatively for the child so the script's sibling-resolution still works
+// (DDR-045 / DDR-062). `stdio: 'inherit'` so the helper's stdout/stderr/exit-code
+// pass straight through — preserves `$(maude design slug …)` capture,
+// `eval "$(maude design prep --shell-export …)"`, and non-zero gating idioms.
+// maude writes nothing of its own on this path (no banner on stdout).
+function runBinDispatch(verb, { args, pkgRoot }) {
+  if (!BIN_VERBS.has(verb)) {
+    process.stderr.write(`maude design: "${verb}" is not a dev-tooling verb.\n${usage()}`);
+    process.exit(2);
+  }
+  const pluginRoot = join(pkgRoot, 'plugins', 'design');
+  const script = join(pluginRoot, 'dev-server', 'bin', `${verb}.sh`);
+  if (!existsSync(script)) {
+    process.stderr.write(
+      `maude design ${verb}: helper not found at ${script}. Reinstall maude (the dev-server bin ships in the npm package).\n`
+    );
+    process.exit(1);
+  }
+  const rest = args.slice(args.indexOf(verb) + 1); // everything after the verb token
+  const child = spawnSync('bash', [script, ...rest], {
+    stdio: 'inherit',
+    env: { ...process.env, CLAUDE_PLUGIN_ROOT: pluginRoot },
+  });
+  if (child.error) {
+    process.stderr.write(`maude design ${verb}: ${child.error.message}\n`);
+    process.exit(1);
+  }
+  process.exit(child.status ?? 1); // pass-through exit code
+}
+
 function usage() {
-  return `maude design <serve|init|export|link|unlink|status|adopt> [options]
+  return `maude design <verb> [options]
+
+Lifecycle:
+  serve · init · export · link · adopt · unlink · status
+
+Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
+  screenshot · server-up · prep · slug · bootstrap-check · runtime-health
+  smoke · canvas-edit · handoff · asset-sweep · visual-sanity
+        Invoke the bundled helper of the same name. maude resolves it from its
+        own package root and sets CLAUDE_PLUGIN_ROOT for the child; stdout,
+        stderr, and exit code pass straight through (so command-substitution
+        capture and non-zero gating work unchanged). Args after the verb are
+        forwarded verbatim, e.g.:
+          maude design slug "Some Canvas Name"
+          PORT=$(maude design server-up --root "$REPO")
+          eval "$(maude design prep --shell-export --shape edit --root "$REPO")"
+          maude design smoke --changed-only
 
   serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
@@ -455,8 +530,14 @@ async function runInit({ args, pkgRoot }) {
 
   // Build explicit copy plan: [srcPath, destPath, transform?]
   const plan = buildCorePlan({ inspirationRoot, designDir, dsName });
-  const previewFiles = await readdir(join(inspirationRoot, 'core', 'preview'));
-  for (const f of previewFiles) {
+  // withFileTypes + file filter: core/preview/ contains a `.archive` dir that
+  // readFile would choke on with EISDIR.
+  const previewEntries = await readdir(join(inspirationRoot, 'core', 'preview'), {
+    withFileTypes: true,
+  });
+  for (const entry of previewEntries) {
+    if (!entry.isFile()) continue;
+    const f = entry.name;
     plan.push({
       src: resolve(inspirationRoot, 'core', 'preview', f),
       dest: resolve(designDir, 'system', dsName, 'preview', f),
@@ -487,6 +568,16 @@ async function runInit({ args, pkgRoot }) {
     else stats.created.push(rel(designDir, destPath));
   }
 
+  // Phase 9 Task 9 (DDR-056) — write the design-runtime .gitignore block so a
+  // fresh project ignores per-machine runtime state (and stays correct if it
+  // later links to a hub). Idempotent + skipped under --dry-run.
+  if (!flags['dry-run']) {
+    const { action } = writeGitignoreBlock(cwd, { designRel: '.design' });
+    if (action !== 'unchanged') {
+      process.stdout.write(`  .gitignore: ${action} maude design-runtime block\n`);
+    }
+  }
+
   printSummary(stats);
   printNextSteps({ dsName, payloadProvided: !!flags['discovery-payload'] });
 }