@1agh/maude 0.20.0 → 0.22.0

package/README.md

@@ -72,6 +72,13 @@ Then inside Claude Code (with `flow@maude` installed):
 - **Claude Code** — desktop app, CLI, or IDE extension.
 - Optional: **`agent-browser`** for design screenshot evidence.
 
+## Collaboration model
+
+Two clean paths, no middle ground ([DDR-047](.ai/decisions/DDR-047-collab-scope-cut-no-lan-mode-hub-admin-ui.md)):
+
+- **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.
+
 ## What's where
 
 User-facing docs live in two places — the README points you the right way:

package/cli/bin/maude.mjs

@@ -14,7 +14,9 @@ const COMMANDS = {
   init: () => import('../commands/init.mjs'),
   config: () => import('../commands/config.mjs'),
   design: () => import('../commands/design.mjs'),
+  doctor: () => import('../commands/doctor.mjs'),
   help: () => import('../commands/help.mjs'),
+  hub: () => import('../commands/hub.mjs'),
   version: () => import('../commands/version.mjs'),
 };
 
@@ -47,7 +49,9 @@ async function main(argv) {
 
   const loader = COMMANDS[cmd];
   if (!loader) {
-    process.stderr.write(`maude: unknown command "${cmd}"\nRun \`maude help\` for usage.\n`);
+    process.stderr.write(
+      `maude: unknown command "${cmd}"\nKnown: ${Object.keys(COMMANDS).join(', ')}.\nRun \`maude help\` for usage.\n`
+    );
     process.exit(2);
   }
   const { run } = await loader();

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

@@ -0,0 +1,207 @@
+// End-to-end CLI tests for `maude design link|unlink|status|adopt` via async spawn.
+//
+// /health is faked with a plain node:http server — we don't need a real
+// Hocuspocus instance. spawnSync would block the parent's event loop and
+// prevent the mock from responding; async spawn keeps the loop ticking.
+
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { 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';
+import { after, before, beforeEach, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+
+const PORT = Number.parseInt(process.env.HUB_TEST_PORT_DESIGN ?? '14396', 10);
+const URL = `http://127.0.0.1:${PORT}`;
+
+let mockServer;
+let workspace;
+let hubsConfigPath;
+
+before(async () => {
+  mockServer = createServer((req, res) => {
+    if (req.method === 'GET' && (req.url === '/health' || req.url.startsWith('/health?'))) {
+      const body = JSON.stringify({
+        ok: true,
+        version: '0.0.0-mock',
+        uptimeMs: 1234,
+        port: PORT,
+        dataDir: '/tmp/mock',
+        tokenCount: 0,
+        authMode: 'dev',
+      });
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      });
+      res.end(body);
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  await new Promise((resolveLi) => mockServer.listen(PORT, '127.0.0.1', resolveLi));
+});
+
+after(async () => {
+  if (mockServer) await new Promise((r) => mockServer.close(r));
+});
+
+beforeEach(() => {
+  workspace = mkdtempSync(join(tmpdir(), 'maude-design-link-ws-'));
+  mkdirSync(join(workspace, '.design'), { recursive: true });
+  writeFileSync(
+    join(workspace, '.design/config.json'),
+    JSON.stringify({ name: 'test', ds: 'default' }, null, 2),
+    'utf8'
+  );
+  hubsConfigPath = join(workspace, 'hubs.json');
+});
+
+function runCli(args) {
+  return new Promise((resolveResult) => {
+    const child = spawn(process.execPath, [BIN, ...args], {
+      cwd: workspace,
+      env: { ...process.env, HUBS_CONFIG_PATH: hubsConfigPath },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+    }, 8000);
+    child.on('exit', (status, signal) => {
+      clearTimeout(timer);
+      resolveResult({ status, signal, stdout, stderr });
+    });
+  });
+}
+
+function cleanup() {
+  if (workspace) rmSync(workspace, { recursive: true, force: true });
+}
+
+test('link without --token exits 2', async () => {
+  const res = await runCli(['design', 'link', URL]);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /--token <value> is required/);
+  cleanup();
+});
+
+test('link without positional url exits 2', async () => {
+  const res = await runCli(['design', 'link', '--token', 'mau_x']);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /<url> positional argument is required/);
+  cleanup();
+});
+
+test('link writes linkedHub + hubs.json + prints reachability', async () => {
+  const res = await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /linked .* to http:\/\/127\.0\.0\.1:/);
+  assert.match(res.stdout, /hub:\s+v[0-9.]/);
+
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub.url, URL);
+  assert.equal(typeof cfg.linkedHub.linkedAt, 'number');
+  assert.equal(cfg.linkedHub.adopt, undefined);
+
+  const hubs = JSON.parse(readFileSync(hubsConfigPath, 'utf8'));
+  assert.equal(hubs.hubs[URL].token, 'mau_test');
+  cleanup();
+});
+
+test('link --adopt records adopt:true in linkedHub', async () => {
+  const res = await runCli(['design', 'link', URL, '--token', 'mau_test', '--adopt']);
+  assert.equal(res.status, 0, res.stderr);
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub.adopt, true);
+  cleanup();
+});
+
+test('adopt subcommand is an alias of link --adopt', async () => {
+  const res = await runCli(['design', 'adopt', URL, '--token', 'mau_test']);
+  assert.equal(res.status, 0, res.stderr);
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub.adopt, true);
+  cleanup();
+});
+
+test('link against unreachable URL exits 1 unless --force', async () => {
+  const dead = 'http://127.0.0.1:1';
+  const fail = await runCli(['design', 'link', dead, '--token', 'mau_test']);
+  assert.equal(fail.status, 1);
+  assert.match(fail.stderr, /cannot reach/);
+
+  const forced = await runCli(['design', 'link', dead, '--token', 'mau_test', '--force']);
+  assert.equal(forced.status, 0, forced.stderr);
+  assert.match(forced.stdout, /NOT REACHED/);
+  cleanup();
+});
+
+test('unlink drops linkedHub + token; idempotent on solo repo', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+
+  const res = await runCli(['design', 'unlink']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /dropped link/);
+
+  const cfg = JSON.parse(readFileSync(join(workspace, '.design/config.json'), 'utf8'));
+  assert.equal(cfg.linkedHub, undefined);
+
+  const hubs = JSON.parse(readFileSync(hubsConfigPath, 'utf8'));
+  assert.equal(URL in hubs.hubs, false);
+
+  const second = await runCli(['design', 'unlink']);
+  assert.equal(second.status, 0);
+  assert.match(second.stdout, /already in solo mode/);
+  cleanup();
+});
+
+test('unlink --keep-token leaves hubs.json entry intact', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  await runCli(['design', 'unlink', '--keep-token']);
+
+  const hubs = JSON.parse(readFileSync(hubsConfigPath, 'utf8'));
+  assert.equal(hubs.hubs[URL].token, 'mau_test');
+  cleanup();
+});
+
+test('status on solo repo reports solo mode', async () => {
+  const res = await runCli(['design', 'status']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /solo mode/);
+  cleanup();
+});
+
+test('status on linked repo reports hub URL + reachability + token presence', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  const res = await runCli(['design', 'status']);
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /linked mode/);
+  assert.match(res.stdout, /token stored:\s+yes/);
+  assert.match(res.stdout, /hub status:\s+up/);
+  cleanup();
+});
+
+test('status --json emits structured payload', async () => {
+  await runCli(['design', 'link', URL, '--token', 'mau_test']);
+  const res = await runCli(['design', 'status', '--json']);
+  assert.equal(res.status, 0, res.stderr);
+  const payload = JSON.parse(res.stdout);
+  assert.equal(payload.mode, 'linked');
+  assert.equal(payload.url, URL);
+  assert.equal(payload.tokenStored, true);
+  assert.equal(payload.hub.reachable, true);
+  assert.equal(payload.sync.agent, 'not-implemented');
+  cleanup();
+});

package/cli/commands/design.mjs

@@ -3,8 +3,18 @@ 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';
-
-const SUBCOMMANDS = new Set(['serve', 'init', 'export', 'help']);
+import { runAdopt, runLink, runStatus, runUnlink } from '../lib/design-link.mjs';
+
+const SUBCOMMANDS = new Set([
+  'serve',
+  'init',
+  'export',
+  'link',
+  'unlink',
+  'status',
+  'adopt',
+  'help',
+]);
 
 export async function run({ args, pkgRoot }) {
   const { positional } = parseArgs(args);
@@ -20,19 +30,17 @@ export async function run({ args, pkgRoot }) {
     process.exit(2);
   }
 
-  if (sub === 'serve') {
-    return runServe({ args, pkgRoot });
-  }
-  if (sub === 'init') {
-    return runInit({ args, pkgRoot });
-  }
-  if (sub === 'export') {
-    return runExport({ args });
-  }
+  if (sub === 'serve') return runServe({ args, pkgRoot });
+  if (sub === 'init') return runInit({ args, pkgRoot });
+  if (sub === 'export') return runExport({ args });
+  if (sub === 'link') return runLink({ args });
+  if (sub === 'unlink') return runUnlink({ args });
+  if (sub === 'status') return runStatus({ args });
+  if (sub === 'adopt') return runAdopt({ args });
 }
 
 function usage() {
-  return `maude design <serve|init|export> [options]
+  return `maude design <serve|init|export|link|unlink|status|adopt> [options]
 
   serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
@@ -56,6 +64,28 @@ function usage() {
         port from .design/_server.json; requires a running dev server. The
         response body is written to --out (default: current dir, server-
         supplied filename). Formats: png pdf svg html pptx canva zip.
+
+  link <url> --token <hex> [--adopt] [--force]
+        Pair this clone with a Maude hub. Writes .design/config.json's
+        linkedHub field (committed) plus the per-machine token to
+        ~/.config/maude/hubs.json (NEVER committed). --adopt signals to the
+        sync agent (Phase 9 Task 4) to push local state up unconditionally on
+        first connect — use it when bootstrapping a hub from a populated repo.
+        --force skips the /health reachability probe (e.g. behind a firewall
+        + trusted URL).
+
+  adopt <url> --token <hex>
+        Alias of 'link --adopt'. Shipped as a discoverable subcommand so
+        first-time bootstrap reads like 'git remote add' + 'git push -f'.
+
+  unlink [--keep-token]
+        Drop linkedHub from .design/config.json + remove the per-machine
+        token (unless --keep-token). Repo returns to solo mode. Local
+        .design/*.html etc. are untouched.
+
+  status [--json]
+        Print whether this repo is linked, the configured hub URL, when
+        it was linked, and a live /health probe of the hub.
 `;
 }
 

package/cli/commands/doctor.mjs

@@ -0,0 +1,361 @@
+// `maude doctor` — unified workspace diagnostic.
+// Combines (1) plugin dependency preflight, (2) workflows.config.json schema
+// validation, (3) stack drift, (4) quality-gate additions into one report.
+//
+// Flags:
+//   --plugin <name>   Scope deps section to one plugin. Config section is
+//                     always global.
+//   --fix             Apply safe auto-fixes: per-dep prompts for autoInstall
+//                     deps, silent drops of unknown schema keys, silent
+//                     drift-resync for keys where detector returned a
+//                     concrete value, silent additive quality merges.
+//                     NEVER touches a key the user already wrote a non-trivial
+//                     value into.
+//   --json            Machine-readable envelope.
+//
+// Exit: 1 if any hard dep missing OR any schema error; 0 otherwise (drift +
+// additions are warnings).
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from '../lib/argv.mjs';
+import { lintConfig } from '../lib/config-lint.mjs';
+import { checkAll } from '../lib/preflight.mjs';
+import { detectQualityGates, detectStack } from '../lib/stack-detect.mjs';
+
+const CONFIG_PATH = '.ai/workflows.config.json';
+
+// Stack keys we treat as "drift-able". detector emits every one of these;
+// keys outside this list (prohibited, boundaries, motion, …) are NEVER
+// touched by --fix.
+const STACK_KEYS = [
+  'language',
+  'framework',
+  'packageManager',
+  'buildTool',
+  'monorepo',
+  'ci',
+  'tests',
+  'css',
+  'router',
+];
+
+export async function run({ args, pkgRoot }) {
+  const { flags, positional } = parseArgs(args, {
+    booleans: ['fix', 'json', 'help'],
+  });
+
+  if (positional[0] === 'help' || flags.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const repoRoot = process.cwd();
+  const scope = flags.plugin || null;
+  const fix = !!flags.fix;
+  const jsonMode = !!flags.json;
+
+  // ── Dependencies ────────────────────────────────────────────────────────
+  const depsByPlugin = {};
+  const pluginList = scope ? [scope] : ['design', 'flow'];
+  for (const p of pluginList) {
+    const manifestPath = resolve(pkgRoot || repoRoot, `plugins/${p}/dependencies.json`);
+    if (!existsSync(manifestPath)) {
+      depsByPlugin[p] = { error: `manifest not found at ${manifestPath}` };
+      continue;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    depsByPlugin[p] = await checkAll(manifestPath);
+  }
+
+  // ── Config: schema, stack drift, quality additions ──────────────────────
+  let configReport = { exists: false };
+  const configFsPath = resolve(repoRoot, CONFIG_PATH);
+  if (existsSync(configFsPath)) {
+    const schemaPath = resolve(
+      pkgRoot || repoRoot,
+      'plugins/flow/.claude-plugin/config.schema.json'
+    );
+    const config = JSON.parse(readFileSync(configFsPath, 'utf8'));
+    const lint = await lintConfig({ config, schemaPath });
+    const detectedStack = await detectStack(repoRoot);
+    const detectedQuality = (await detectQualityGates(repoRoot)) || {};
+
+    const drift = [];
+    for (const k of STACK_KEYS) {
+      const declared = config.stack?.[k];
+      const detected = detectedStack[k];
+      if (detected === 'unknown' || detected === null || detected === undefined) continue;
+      // Booleans (monorepo) compared directly.
+      if (typeof detected === 'boolean') {
+        if (declared !== detected) drift.push({ key: k, declared, detected });
+        continue;
+      }
+      if (declared !== detected) {
+        drift.push({ key: k, declared: declared ?? '(unset)', detected });
+      }
+    }
+
+    const qualityAdditions = [];
+    const declaredQuality = config.quality || {};
+    for (const [gate, cmd] of Object.entries(detectedQuality)) {
+      if (!declaredQuality[gate]) qualityAdditions.push({ gate, command: cmd });
+    }
+
+    configReport = {
+      exists: true,
+      schema: lint,
+      drift,
+      qualityAdditions,
+      detectedStack,
+      detectedQuality,
+    };
+  }
+
+  // ── Summary ─────────────────────────────────────────────────────────────
+  const hardDepsMissing = Object.values(depsByPlugin)
+    .filter((r) => r.summary)
+    .reduce((acc, r) => acc + r.summary.hardFailing, 0);
+  const schemaErrors = configReport.schema ? configReport.schema.errors.length : 0;
+  const driftCount = configReport.drift?.length || 0;
+  const additionsCount = configReport.qualityAdditions?.length || 0;
+  const summary = {
+    hardDepsMissing,
+    schemaErrors,
+    driftCount,
+    qualityAdditions: additionsCount,
+    healthy: hardDepsMissing === 0 && schemaErrors === 0,
+  };
+
+  if (jsonMode) {
+    process.stdout.write(
+      `${JSON.stringify({ deps: depsByPlugin, config: configReport, summary }, null, 2)}\n`
+    );
+    process.exit(summary.healthy ? 0 : 1);
+  }
+
+  printReport({ depsByPlugin, configReport, summary });
+
+  // ── Fix path ────────────────────────────────────────────────────────────
+  if (fix) {
+    await applyFixes({ repoRoot, configFsPath, depsByPlugin, configReport });
+  } else if (!summary.healthy) {
+    process.stdout.write(
+      '\nRun with --fix to: install missing deps (prompt per item), drop unknown keys, apply detected drift, add missing quality gates. Existing user values are NEVER overwritten.\n'
+    );
+  }
+
+  process.exit(summary.healthy ? 0 : 1);
+}
+
+function usage() {
+  return `maude doctor [--plugin <name>] [--fix] [--json]
+
+  Unified workspace diagnostic. Reports missing dependencies, config schema
+  errors, stack drift, and missing quality-gate declarations in one shot.
+
+  Flags:
+    --plugin <name>   Scope dependency section to one plugin (design | flow).
+                      Config section is global.
+    --fix             Apply safe auto-fixes. Prompts per autoInstall dep,
+                      drops unknown schema keys, applies drift where the
+                      detector returned a concrete value, adds missing
+                      quality gates. Never overwrites existing user values.
+    --json            Machine-readable envelope.
+
+  Exit: 1 if any hard dep is missing OR config schema has errors; 0 otherwise.
+`;
+}
+
+function printReport({ depsByPlugin, configReport, summary }) {
+  process.stdout.write('maude doctor\n\n');
+  for (const [name, env] of Object.entries(depsByPlugin)) {
+    process.stdout.write(`  Dependencies (plugins/${name}):\n`);
+    if (env.error) {
+      process.stdout.write(`    ✗ ${env.error}\n\n`);
+      continue;
+    }
+    for (const r of env.results) {
+      const glyph = r.status === 'ok' ? '✓' : r.status === 'unknown' ? '?' : '✗';
+      const label = r.id.padEnd(22);
+      let rhs;
+      if (r.status === 'ok') rhs = r.version || '';
+      else if (r.status === 'missing') {
+        const hint = (r.install && (r.install[process.platform] || r.install.preferred)) || '';
+        rhs = `missing${hint ? ` — ${hint}` : ''}`;
+      } else if (r.status === 'outdated') rhs = `outdated (${r.detail})`;
+      else rhs = r.detail || '';
+      process.stdout.write(`    ${glyph} ${label} ${rhs}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (!configReport.exists) {
+    process.stdout.write(
+      `  Config (${CONFIG_PATH}):\n    not found — run \`maude init\` first.\n\n`
+    );
+  } else {
+    process.stdout.write(`  Config schema (${CONFIG_PATH}):\n`);
+    if (configReport.schema.ok) {
+      process.stdout.write('    ✓ valid\n');
+    } else {
+      for (const e of configReport.schema.errors) {
+        process.stdout.write(`    ✗ ${e.path}\n`);
+        if (e.value !== undefined)
+          process.stdout.write(`      value: ${JSON.stringify(e.value)}\n`);
+        process.stdout.write(`      ${e.message}\n`);
+        if (e.suggestion)
+          process.stdout.write(`      suggestion: "${e.suggestion}" (closest match)\n`);
+      }
+    }
+    process.stdout.write('\n');
+
+    if (configReport.drift.length > 0) {
+      process.stdout.write('  Stack drift:\n');
+      process.stdout.write('    Key                Declared              Detected\n');
+      for (const d of configReport.drift) {
+        process.stdout.write(
+          `    ${d.key.padEnd(18)} ${String(d.declared).padEnd(20)}  ${d.detected}\n`
+        );
+      }
+      process.stdout.write('\n');
+    }
+
+    if (configReport.qualityAdditions.length > 0) {
+      process.stdout.write(
+        '  Quality gates (additions only — existing values never overwritten):\n'
+      );
+      for (const a of configReport.qualityAdditions) {
+        process.stdout.write(`    + quality.${a.gate.padEnd(14)} ${a.command}\n`);
+      }
+      process.stdout.write('\n');
+    }
+  }
+
+  const parts = [];
+  if (summary.hardDepsMissing) parts.push(`${summary.hardDepsMissing} hard dep missing`);
+  if (summary.schemaErrors)
+    parts.push(`${summary.schemaErrors} schema error${summary.schemaErrors === 1 ? '' : 's'}`);
+  if (summary.driftCount)
+    parts.push(`${summary.driftCount} stack drift${summary.driftCount === 1 ? '' : 's'}`);
+  if (summary.qualityAdditions)
+    parts.push(
+      `${summary.qualityAdditions} quality addition${summary.qualityAdditions === 1 ? '' : 's'}`
+    );
+  if (parts.length === 0) parts.push('all clear');
+  process.stdout.write(`  Summary: ${parts.join(', ')}.\n`);
+}
+
+async function applyFixes({ repoRoot, configFsPath, depsByPlugin, configReport }) {
+  let configChanged = false;
+
+  // ── Config edits ───────────────────────────────────────────────────────
+  // Run FIRST — deterministic (filesystem only) and must not be blocked by
+  // an interactive prompt that may never resolve on a non-TTY stdin (CI,
+  // scripted spawns with empty input). Dep prompts come AFTER.
+  if (configReport.exists) {
+    const config = JSON.parse(readFileSync(configFsPath, 'utf8'));
+
+    // Drop unknown additionalProperties errors.
+    for (const e of configReport.schema.errors) {
+      if (e.message.startsWith('unknown property')) {
+        const parts = e.path.split('/').filter(Boolean);
+        let cur = config;
+        for (let i = 0; i < parts.length - 1; i++) cur = cur?.[parts[i]];
+        if (cur && parts.length > 0) {
+          delete cur[parts[parts.length - 1]];
+          configChanged = true;
+        }
+      }
+    }
+
+    // Apply drift — silent (detector returned a concrete value, so we know
+    // declared is wrong or stale).
+    if (configReport.drift.length > 0) {
+      if (!config.stack) config.stack = {};
+      for (const d of configReport.drift) {
+        config.stack[d.key] = d.detected;
+        configChanged = true;
+      }
+    }
+
+    // Add missing quality gates — silent additive merge.
+    if (configReport.qualityAdditions.length > 0) {
+      if (!config.quality) config.quality = {};
+      for (const a of configReport.qualityAdditions) {
+        if (!config.quality[a.gate]) {
+          config.quality[a.gate] = a.command;
+          configChanged = true;
+        }
+      }
+    }
+
+    if (configChanged) {
+      writeFileSync(configFsPath, `${JSON.stringify(config, null, 2)}\n`);
+      process.stdout.write(`\n  ✓ wrote ${CONFIG_PATH}\n`);
+    } else {
+      process.stdout.write('\n  (no config edits applied)\n');
+    }
+
+    // Note: invalid-enum errors (e.g. tests: "node-test") are NEVER auto-
+    // fixed — the user picks the migration target. Surface the leftover.
+    const remaining = configReport.schema.errors.filter(
+      (e) => !e.message.startsWith('unknown property')
+    );
+    if (remaining.length > 0) {
+      process.stdout.write(
+        `\n  ⚠ ${remaining.length} schema error${remaining.length === 1 ? '' : 's'} not auto-fixed — user decision required:\n`
+      );
+      for (const e of remaining) {
+        process.stdout.write(`    ${e.path}: ${e.message}\n`);
+      }
+    }
+  }
+
+  // ── Dependency installs ────────────────────────────────────────────────
+  const installable = [];
+  for (const env of Object.values(depsByPlugin)) {
+    if (!env.results) continue;
+    for (const r of env.results) {
+      if (r.status !== 'missing') continue;
+      installable.push(r);
+    }
+  }
+  // Per-dep prompt — no silent installs. Skip when stdin is not a TTY
+  // (CI runners, scripted spawns) so config edits above are never bypassed
+  // by a never-resolving readline prompt against closed stdin.
+  if (installable.length > 0) {
+    if (!stdin.isTTY) {
+      process.stdout.write(
+        `\n--- Dependency installs skipped (non-interactive stdin; ${installable.length} missing) ---\n`
+      );
+    } else {
+      process.stdout.write('\n--- Dependency installs (per-dep prompt) ---\n');
+      const rl = createInterface({ input: stdin, output: stdout });
+      for (const r of installable) {
+        const cmd = (r.install && (r.install[process.platform] || r.install.preferred)) || null;
+        if (!cmd) {
+          process.stdout.write(`  skip ${r.id} — no install command declared\n`);
+          continue;
+        }
+        // eslint-disable-next-line no-await-in-loop
+        const ans = await rl.question(`  Install ${r.id} via \`${cmd}\`? [y/N] `);
+        const norm = (ans || '').trim().toLowerCase();
+        if (norm === 'y' || norm === 'yes') {
+          process.stdout.write(`  running: ${cmd}\n`);
+          const res = spawnSync('bash', ['-c', cmd], { stdio: 'inherit' });
+          if (res.status !== 0) process.stdout.write(`  ✗ install failed (exit ${res.status})\n`);
+        } else {
+          process.stdout.write(`  skipped ${r.id}\n`);
+        }
+      }
+      rl.close();
+    }
+  }
+
+  // Use the actually-changed state to decide on re-run hint.
+  void repoRoot;
+}