@1agh/maude 0.22.2 → 0.24.0

package/cli/lib/cache.test.mjs

@@ -0,0 +1,303 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import {
+  check,
+  clear,
+  getOrCompute,
+  list,
+  resolveCacheRoot,
+  sha8,
+  stats,
+  write,
+} from './cache.mjs';
+
+function tmpCache() {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-cache-'));
+  return { cacheDir: dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+test('write then check returns the same payload', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'finance.abc12345', { mood: ['calm'], n: 3 }, {}, { cacheDir });
+    const hit = check('research/domain', 'finance.abc12345', { cacheDir });
+    assert.ok(hit);
+    assert.deepEqual(hit.value, { mood: ['calm'], n: 3 });
+    assert.equal(typeof hit.ageMs, 'number');
+    assert.ok(hit.ageMs >= 0);
+  } finally {
+    cleanup();
+  }
+});
+
+test('first write drops a README documenting the invalidation policy', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'k', { x: 1 }, {}, { cacheDir });
+    const readme = readFileSync(join(cacheDir, 'README.md'), 'utf8');
+    assert.match(readme, /Invalidation policy/);
+    assert.match(readme, /research\/domain/);
+  } finally {
+    cleanup();
+  }
+});
+
+test('check returns null on miss', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    assert.equal(check('research/domain', 'nope', { cacheDir }), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('check returns null on corrupt entry', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('codebase-intelligence', 'deadbeef', { x: 1 }, {}, { cacheDir });
+    writeFileSync(path, '{ this is not json', 'utf8');
+    assert.equal(check('codebase-intelligence', 'deadbeef', { cacheDir }), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute serves fresh cache without calling compute', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('design-context', 'ds/tok1', { tokens: 12 }, {}, { cacheDir });
+    let called = false;
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'design-context',
+      key: 'ds/tok1',
+      ttlMs: 60_000,
+      compute: () => {
+        called = true;
+        return { tokens: 999 };
+      },
+    });
+    assert.deepEqual(v, { tokens: 12 });
+    assert.equal(called, false, 'compute must not run on a fresh hit');
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute runs compute on miss and caches the result', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    let calls = 0;
+    const opts = {
+      cacheDir,
+      layer: 'codebase-intelligence',
+      key: 'sha-aaa',
+      ttlMs: 60_000,
+      compute: () => {
+        calls += 1;
+        return { files: calls };
+      },
+    };
+    const first = await getOrCompute(opts);
+    const second = await getOrCompute(opts);
+    assert.deepEqual(first, { files: 1 });
+    assert.deepEqual(second, { files: 1 }, 'second call must read cache, not recompute');
+    assert.equal(calls, 1);
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute recomputes past the ttl window', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('security', 'head1', { audit: 'old' }, {}, { cacheDir });
+    // Backdate the stored writtenAt to 2 h ago (past a 1 h ttl).
+    const stored = JSON.parse(readFileSync(path, 'utf8'));
+    stored.writtenAt = Date.now() - 2 * 60 * 60 * 1000;
+    writeFileSync(path, JSON.stringify(stored), 'utf8');
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'security',
+      key: 'head1',
+      ttlMs: 60 * 60 * 1000,
+      compute: () => ({ audit: 'fresh' }),
+    });
+    assert.deepEqual(v, { audit: 'fresh' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute force bypasses a fresh hit', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'x', { v: 'cached' }, {}, { cacheDir });
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'research/domain',
+      key: 'x',
+      ttlMs: 60_000,
+      force: true,
+      compute: () => ({ v: 'recomputed' }),
+    });
+    assert.deepEqual(v, { v: 'recomputed' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute serves a stale entry when compute throws (within maxAge)', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('research/domain', 'stale', { v: 'old-but-usable' }, {}, { cacheDir });
+    const stored = JSON.parse(readFileSync(path, 'utf8'));
+    stored.writtenAt = Date.now() - 10 * 24 * 60 * 60 * 1000; // 10 days old
+    writeFileSync(path, JSON.stringify(stored), 'utf8');
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'research/domain',
+      key: 'stale',
+      ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 day fresh window → stale
+      maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 day ceiling → still usable
+      compute: () => {
+        throw new Error('websearch down');
+      },
+    });
+    assert.deepEqual(v, { v: 'old-but-usable' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute propagates the error when no usable stale entry exists', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    await assert.rejects(
+      getOrCompute({
+        cacheDir,
+        layer: 'research/domain',
+        key: 'missing',
+        compute: () => {
+          throw new Error('boom');
+        },
+      }),
+      /boom/
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test('concurrent writes to the same key never corrupt the file', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    await Promise.all(
+      Array.from({ length: 25 }, (_, i) =>
+        Promise.resolve().then(() =>
+          write('codebase-intelligence', 'race', { i }, {}, { cacheDir })
+        )
+      )
+    );
+    const hit = check('codebase-intelligence', 'race', { cacheDir });
+    assert.ok(hit, 'entry must be readable after concurrent writes');
+    assert.equal(typeof hit.value.i, 'number');
+    assert.ok(hit.value.i >= 0 && hit.value.i < 25);
+  } finally {
+    cleanup();
+  }
+});
+
+test('path traversal in layer or key is rejected', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    assert.throws(() => write('../escape', 'k', {}, {}, { cacheDir }), /escapes cache root/);
+    assert.throws(() => check('research', '../../etc/passwd', { cacheDir }), /escapes cache root/);
+  } finally {
+    cleanup();
+  }
+});
+
+test('clear(layer) removes only that layer; clear() wipes all but README', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir });
+    write('research/domain', 'b', { x: 2 }, {}, { cacheDir });
+    write('codebase-intelligence', 'c', { x: 3 }, {}, { cacheDir });
+    writeFileSync(join(cacheDir, 'README.md'), '# cache', 'utf8');
+
+    clear('research/domain', undefined, { cacheDir });
+    assert.equal(check('research/domain', 'a', { cacheDir }), null);
+    assert.ok(check('codebase-intelligence', 'c', { cacheDir }), 'other layer survives');
+
+    clear(undefined, undefined, { cacheDir });
+    assert.equal(check('codebase-intelligence', 'c', { cacheDir }), null);
+    assert.equal(readFileSync(join(cacheDir, 'README.md'), 'utf8'), '# cache', 'README preserved');
+  } finally {
+    cleanup();
+  }
+});
+
+test('list reports layers with entry counts and bytes', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir });
+    write('research/domain', 'b', { x: 2 }, {}, { cacheDir });
+    write('design-context', 'ds/t', { x: 3 }, {}, { cacheDir });
+    const layers = list({ cacheDir });
+    const byName = Object.fromEntries(layers.map((l) => [l.layer, l]));
+    assert.equal(byName.research.entries, 2);
+    assert.equal(byName['design-context'].entries, 1);
+    assert.ok(byName.research.bytes > 0);
+  } finally {
+    cleanup();
+  }
+});
+
+test('stats accumulate hits and misses per layer', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const base = {
+      cacheDir,
+      layer: 'research/domain',
+      key: 'k',
+      ttlMs: 60_000,
+      compute: () => ({ v: 1 }),
+    };
+    await getOrCompute(base); // miss
+    await getOrCompute(base); // hit
+    await getOrCompute(base); // hit
+    const s = stats({ cacheDir });
+    assert.equal(s.misses['research/domain'], 1);
+    assert.equal(s.hits['research/domain'], 2);
+  } finally {
+    cleanup();
+  }
+});
+
+test('resolveCacheRoot honors MAUDE_CACHE_DIR then CLAUDE_PROJECT_DIR', () => {
+  const prev = { m: process.env.MAUDE_CACHE_DIR, c: process.env.CLAUDE_PROJECT_DIR };
+  try {
+    process.env.MAUDE_CACHE_DIR = '/tmp/explicit-cache';
+    assert.equal(resolveCacheRoot(), '/tmp/explicit-cache');
+    Reflect.deleteProperty(process.env, 'MAUDE_CACHE_DIR');
+    process.env.CLAUDE_PROJECT_DIR = '/tmp/proj';
+    assert.equal(resolveCacheRoot(), join('/tmp/proj', '.ai/cache'));
+  } finally {
+    if (prev.m === undefined) Reflect.deleteProperty(process.env, 'MAUDE_CACHE_DIR');
+    else process.env.MAUDE_CACHE_DIR = prev.m;
+    if (prev.c === undefined) Reflect.deleteProperty(process.env, 'CLAUDE_PROJECT_DIR');
+    else process.env.CLAUDE_PROJECT_DIR = prev.c;
+  }
+});
+
+test('sha8 is stable and 8 hex chars', () => {
+  const a = sha8('finance dashboard');
+  const b = sha8('finance dashboard');
+  assert.equal(a, b);
+  assert.match(a, /^[0-9a-f]{8}$/);
+  assert.notEqual(sha8('finance dashboard'), sha8('ecommerce checkout'));
+});

package/cli/lib/design-link.mjs

@@ -10,19 +10,22 @@
 //
 // Token NEVER lands in .design/config.json — that's git-committed.
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
 
 import { parseArgs } from './argv.mjs';
-import { addHub, getHub, normalizeUrl, removeHub } from './hubs-config.mjs';
+import { BEGIN_MARKER, writeGitignoreBlock } from './gitignore-block.mjs';
+import { addHub, getHub, isHubTrusted, normalizeUrl, removeHub, trustHub } from './hubs-config.mjs';
 
 const DESIGN_CONFIG_PATH = '.design/config.json';
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 
 // ---------------------------------------------------------------- link
 
 export async function runLink({ args, cwd = process.cwd(), forceAdopt = false }) {
   const tail = args.slice(args.indexOf(forceAdopt ? 'adopt' : 'link') + 1);
-  const { flags, positional } = parseArgs(tail, { booleans: ['adopt', 'force'] });
+  const { flags, positional } = parseArgs(tail, { booleans: ['adopt', 'force', 'yes'] });
   const url = positional[0];
   const token = flags.token;
 
@@ -52,6 +55,46 @@ export async function runLink({ args, cwd = process.cwd(), forceAdopt = false })
     process.exit(2);
   }
 
+  const cfg = readDesignConfig(designConfigPath);
+
+  // DDR-054 F2/F4: linking to a non-loopback hub grants a remote actor the same
+  // write access to .design/ as the local user (hub-pushed content lands on
+  // disk verbatim, like `git pull` from a stranger). Require explicit trust for
+  // a new remote hub. Trust is checked PER-MACHINE (`isHubTrusted`), never from
+  // a committable repo file — a committed allowlist (or the committed
+  // `linkedHub.url` itself) would let a malicious PR pre-seed trust and bypass
+  // this gate (trust laundering). Loopback dev hubs are exempt.
+  const loopback = isLoopbackUrl(normUrl);
+  const alreadyTrusted = loopback || isHubTrusted(normUrl);
+  const manifest = adopt ? collectAdoptManifest(cwd) : [];
+
+  if (!alreadyTrusted) {
+    process.stderr.write(trustGateText(normUrl, adopt, manifest));
+    if (flags.yes) {
+      process.stderr.write('  → confirmed via --yes\n');
+    } else if (process.stdin.isTTY) {
+      const question = adopt
+        ? `Link this repo to ${normUrl} AND push local design state up to it? [y/N] `
+        : `Link this repo to ${normUrl}? [y/N] `;
+      const ok = await promptYesNo(question);
+      if (!ok) {
+        process.stderr.write('maude design link: aborted — hub not trusted.\n');
+        process.exit(1);
+      }
+    } else {
+      process.stderr.write(
+        `maude design link: linking to a non-local hub (${normUrl}) requires confirmation.\n  Re-run in an interactive terminal, or pass --yes to confirm non-interactively.\n`
+      );
+      process.exit(1);
+    }
+    // NOTE: trust is recorded AFTER the link succeeds (below), not here — an
+    // aborted link (probe fail without --force, config write throws) must not
+    // leave a persisted trust that silently skips the gate on a later re-link.
+  } else if (adopt && manifest.length > 0) {
+    // Trusted (e.g. localhost) adopt — surface the manifest informationally.
+    process.stdout.write(adoptManifestText(normUrl, manifest));
+  }
+
   // Reachability probe — best-effort. Hub auth happens on WS upgrade (Task 4),
   // so a successful /health response only tells us the hub is up + reachable.
   // Token validity is verified when the sync agent connects for real.
@@ -63,11 +106,10 @@ export async function runLink({ args, cwd = process.cwd(), forceAdopt = false })
     process.exit(1);
   }
 
-  // Write hub side: tokens.json next to the user's other config.
-  const hubRecord = addHub(normUrl, token);
+  // Write hub side: token (+ adopt attestation) in ~/.config/maude/hubs.json.
+  const hubRecord = addHub(normUrl, token, adopt ? { adoptedAt: Date.now() } : {});
 
   // Write project side: linkedHub field on .design/config.json.
-  const cfg = readDesignConfig(designConfigPath);
   const existing = cfg.linkedHub;
   if (existing && !flags.force) {
     process.stdout.write(
@@ -81,9 +123,22 @@ export async function runLink({ args, cwd = process.cwd(), forceAdopt = false })
   };
   writeDesignConfig(designConfigPath, cfg);
 
+  // Record per-machine trust only now that the link fully succeeded, so a
+  // later re-link to this hub won't re-prompt. Skipped for loopback + hubs
+  // already trusted on this machine.
+  if (!alreadyTrusted) trustHub(normUrl);
+
+  // Phase 9 Task 9 (DDR-056) — solo→linked transition. On --adopt, offer to add
+  // the design-runtime .gitignore block if it's missing, so the shared repo
+  // ignores per-machine runtime state. Default yes; --yes / non-TTY auto-adds.
+  if (adopt) {
+    await maybeWriteGitignoreBlock(cwd, !!flags.yes);
+  }
+
   process.stdout.write(
-    `[design link] linked ${cwd} to ${normUrl}.\n  token:   stored in ~/.config/maude/hubs.json (per-machine, never committed)\n  config:  .design/config.json.linkedHub = { url, linkedAt${adopt ? ', adopt: true' : ''} }\n  hub:     ${probe.ok ? `v${probe.version}, uptime ${Math.round((probe.uptimeMs ?? 0) / 1000)}s, ${probe.tokenCount} token(s) (${probe.authMode})` : 'NOT REACHED — linked anyway (--force)'}\n\nNext step: start 'maude design serve' — the linked sync agent ${adopt ? 'will push local state up to the hub on first connect' : 'will mirror hub state to disk on first connect'}.\n  (Sync agent lands in Phase 9 Task 4.)\n`
+    `[design link] linked ${cwd} to ${normUrl}.\n  token:   stored in ~/.config/maude/hubs.json (per-machine, never committed)\n  config:  .design/config.json.linkedHub = { url, linkedAt${adopt ? ', adopt: true' : ''} }\n  hub:     ${probe.ok ? `v${probe.version}, uptime ${Math.round((probe.uptimeMs ?? 0) / 1000)}s, ${probe.tokenCount} token(s) (${probe.authMode})` : 'NOT REACHED — linked anyway (--force)'}\n\nNext step: start 'maude design serve' — the linked sync agent ${adopt ? 'will push local state up to the hub on first connect' : 'will mirror hub state to disk on first connect'}.\n`
   );
+  if (!loopback) process.stderr.write(linkedModeBanner());
 }
 
 // ---------------------------------------------------------------- adopt
@@ -153,6 +208,7 @@ export async function runStatus({ args, cwd = process.cwd() }) {
   const url = cfg.linkedHub.url;
   const hubRecord = getHub(url);
   const probe = await probeHealth(url);
+  const sync = readSyncState(resolve(cwd, '.design', '_sync.json'));
 
   const payload = {
     mode: 'linked',
@@ -169,9 +225,9 @@ export async function runStatus({ args, cwd = process.cwd() }) {
           authMode: probe.authMode,
         }
       : { reachable: false, error: probe.error },
-    // Sync agent surfaces ('lastSync', 'pendingOps', 'conflictState') land
-    // in Phase 9 Task 4. For now report n/a.
-    sync: { agent: 'not-implemented' },
+    // Task 8 — the running sync agent writes `.design/_sync.json` with the live
+    // offline/online state, queued-op count, last sync, and conflict log.
+    sync: sync ?? { agent: 'idle', detail: 'no _sync.json — sync agent not running' },
   };
 
   if (flags.json) {
@@ -180,11 +236,55 @@ export async function runStatus({ args, cwd = process.cwd() }) {
   }
 
   const uptimeS = Math.round((probe.uptimeMs ?? 0) / 1000);
+  const syncLine = sync?.notSyncable
+    ? `linked but 0 syncable canvases — ${sync.reason}`
+    : sync
+      ? `${sync.state}${sync.sharedDoc ? ' [shared-doc]' : ''}${sync.queuedOps ? ` — ${sync.queuedOps} edit(s) queued` : ''}${
+          sync.lastSyncAt ? `, last sync ${new Date(sync.lastSyncAt).toISOString()}` : ''
+        }${sync.conflicts?.length ? `, ${sync.conflicts.length} conflict notice(s)` : ''}`
+      : 'idle (start `maude design serve` in linked mode)';
   process.stdout.write(
-    `Maude design — linked mode\n  hub URL:      ${url}\n  linked at:    ${new Date(cfg.linkedHub.linkedAt).toISOString()}\n  adopt mode:   ${cfg.linkedHub.adopt ? 'yes (push-on-first-sync)' : 'no (hub-wins)'}\n  token stored: ${hubRecord ? 'yes (~/.config/maude/hubs.json)' : "NO — re-run 'maude design link'"}\n  hub status:   ${probe.ok ? `up — v${probe.version}, ${uptimeS}s uptime, ${probe.tokenCount} token(s), ${probe.authMode}` : `UNREACHABLE — ${probe.error}`}\n  sync agent:   not-implemented (Phase 9 Task 4 follow-up)\n`
+    `Maude design — linked mode\n  hub URL:      ${url}\n  linked at:    ${new Date(cfg.linkedHub.linkedAt).toISOString()}\n  adopt mode:   ${cfg.linkedHub.adopt ? 'yes (push-on-first-sync)' : 'no (hub-wins)'}\n  token stored: ${hubRecord ? 'yes (~/.config/maude/hubs.json)' : "NO — re-run 'maude design link'"}\n  hub status:   ${probe.ok ? `up — v${probe.version}, ${uptimeS}s uptime, ${probe.tokenCount} token(s), ${probe.authMode}` : `UNREACHABLE — ${probe.error}`}\n  sync agent:   ${syncLine}\n`
   );
 }
 
+/**
+ * On --adopt, add the design-runtime .gitignore block if missing. Prompts
+ * [Y/n] in a TTY (default yes); auto-adds with --yes or non-interactively.
+ * Idempotent — a repo that already has the block is left untouched.
+ */
+async function maybeWriteGitignoreBlock(cwd, assumeYes) {
+  const gitignorePath = resolve(cwd, '.gitignore');
+  const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+  if (current.includes(BEGIN_MARKER)) return; // already present — nothing to do
+
+  let add = assumeYes || !process.stdin.isTTY;
+  if (!add) {
+    add = await promptYesNo(
+      'Add the Maude design-runtime .gitignore block (ignores per-machine runtime state)? [Y/n] ',
+      true
+    );
+  }
+  if (!add) {
+    process.stdout.write(
+      '[design link] skipped .gitignore block — add it later with another `maude design adopt`.\n'
+    );
+    return;
+  }
+  const { action } = writeGitignoreBlock(cwd, { designRel: '.design' });
+  process.stdout.write(`[design link] .gitignore: ${action} maude design-runtime block.\n`);
+}
+
+/** Read the sync agent's `_sync.json` runtime state, or null when absent. */
+function readSyncState(p) {
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------- helpers
 
 function readDesignConfig(path) {
@@ -214,3 +314,114 @@ async function probeHealth(url) {
     return { ok: false, error: err.message };
   }
 }
+
+// ----------------------------------------------------- trust gate (DDR-054 F2/F4)
+
+/** True when the hub URL points at the local machine (no remote-write risk). */
+function isLoopbackUrl(normUrl) {
+  try {
+    return LOOPBACK_HOSTS.has(new URL(normUrl).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Promise-resolving prompt. Prompt + echo go to stderr (stdout is data).
+ * `defaultYes` controls how an empty answer resolves ([Y/n] vs [y/N]).
+ */
+function promptYesNo(question, defaultYes = false) {
+  return new Promise((res) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      if (trimmed === '') return res(defaultYes);
+      res(/^y(es)?$/i.test(trimmed));
+    });
+  });
+}
+
+/**
+ * Files `--adopt` would push up to the hub: top-level canvases + annotation
+ * SVGs + comment JSON snapshots (the git-tracked sync surface per Task 9).
+ */
+function collectAdoptManifest(cwd) {
+  const base = resolve(cwd, '.design');
+  const files = [];
+  try {
+    for (const f of readdirSync(base)) {
+      if (f.endsWith('.html') || f.endsWith('.annotations.svg')) {
+        try {
+          files.push({ rel: `.design/${f}`, bytes: statSync(resolve(base, f)).size });
+        } catch {
+          /* skip unreadable */
+        }
+      }
+    }
+  } catch {
+    /* no .design — manifest stays empty */
+  }
+  const commentsDir = resolve(base, '_comments');
+  try {
+    for (const f of readdirSync(commentsDir)) {
+      if (!f.endsWith('.json')) continue;
+      try {
+        files.push({
+          rel: `.design/_comments/${f}`,
+          bytes: statSync(resolve(commentsDir, f)).size,
+        });
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  } catch {
+    /* no comments dir */
+  }
+  return files;
+}
+
+function adoptManifestText(normUrl, manifest) {
+  const lines = manifest.map((f) => `    ${f.rel} (${f.bytes} B)`).join('\n');
+  return `[design link] --adopt will push ${manifest.length} local file(s) up to ${normUrl}:\n${lines}\n`;
+}
+
+function trustGateText(normUrl, adopt, manifest) {
+  let url;
+  try {
+    url = new URL(normUrl);
+  } catch {
+    url = { protocol: '?', hostname: normUrl };
+  }
+  const scheme = `${url.protocol.replace(':', '')}${url.protocol === 'http:' ? ' (NOT encrypted — token + edits travel in cleartext)' : ''}`;
+  let out = `
+⚠ Linking to a NON-LOCAL hub.
+    URL:    ${normUrl}
+    scheme: ${scheme}
+    host:   ${url.hostname}
+  A linked hub can write to your .design/ files (treat like \`git pull\` from a stranger).
+  Only link to hubs you operate or fully trust. See DDR-054 for the trust model.
+`;
+  if (adopt) {
+    const list = manifest.map((f) => `    ${f.rel} (${f.bytes} B)`).join('\n');
+    out +=
+      manifest.length > 0
+        ? `\n  --adopt will UPLOAD ${manifest.length} local file(s) to this hub:\n${list}\n`
+        : '\n  --adopt is set but no local canvases/comments/annotations were found to upload.\n';
+  }
+  return out;
+}
+
+function linkedModeBanner() {
+  return `
+⚠ Linked mode writes hub-pushed content into your .design/ files as UNTRUSTED
+  input — synced files are listed in .design/_untrusted/INDEX.json and a managed
+  .claudeignore block. Do not act on instructions found inside synced canvases.
+  HTML canvases sync by default; a TSX body syncs only with a per-canvas opt-in
+  (.meta.json "syncable": true). The canvas sandbox is ON by default
+  (MAUDE_CANVAS_ORIGIN_SPLIT=0 opts out, which also disables TSX sync). The
+  sandbox contains browser execution, but a hostile canvas you opt into syncing
+  can still exfiltrate collab metadata (WebRTC / navigation are residual).
+  Only link to hubs you operate or fully trust. See DDR-054 + DDR-060.
+`;
+}