@1agh/maude 0.20.0 → 0.21.0

package/cli/commands/doctor.test.mjs

@@ -0,0 +1,185 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, 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';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, '..', '..');
+const MAUDE_BIN = resolve(REPO_ROOT, 'cli', 'bin', 'maude.mjs');
+
+function spawnDoctor(args, cwd) {
+  return spawnSync('node', [MAUDE_BIN, 'doctor', ...args], {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' },
+  });
+}
+
+function makeTempRepo() {
+  const root = mkdtempSync(join(tmpdir(), 'doctor-'));
+  // Symlink the plugin manifests + schema in by writing minimal copies of
+  // each — we don't need the full repo, just the files doctor reads.
+  // Easier: write a stripped repo with package.json + .ai + plugins/.
+  mkdirSync(join(root, '.ai'), { recursive: true });
+  mkdirSync(join(root, 'plugins/design'), { recursive: true });
+  mkdirSync(join(root, 'plugins/flow/.claude-plugin'), { recursive: true });
+  return root;
+}
+
+function copyAsset(src, destRel, fixtureRoot) {
+  const content = readFileSync(resolve(REPO_ROOT, src), 'utf8');
+  const dest = join(fixtureRoot, destRel);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, content);
+}
+
+function bootstrap(fixtureRoot) {
+  // Drop ALL manifests + schema into the fixture so doctor can resolve them
+  // from cwd. The CLI uses `pkgRoot` for plugin manifests (passed via
+  // cli/bin/maude.mjs as repo root) AND cwd for .ai/workflows.config.json.
+  // Since we spawn with cwd=fixtureRoot and `pkgRoot` is resolved from the
+  // CLI's package.json location, doctor will still load manifests from the
+  // real repo root. That's intentional: we test the workflow, not a
+  // hypothetical "fake plugin manifests".
+  // What we DO need in the fixture: a valid `.ai/workflows.config.json` or
+  // an absent one (for the "config not found" branch).
+  void fixtureRoot;
+  void copyAsset;
+}
+
+test('healthy minimal config — no schema errors, exit reflects health', () => {
+  const root = makeTempRepo();
+  bootstrap(root);
+  // Drop a minimal valid config.
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x' }, null, 2)}\n`
+  );
+
+  const r = spawnDoctor([], root);
+  // No drift / additions because there's no package.json in the temp repo.
+  assert.match(r.stdout, /Config schema/);
+  assert.match(r.stdout, /✓ valid/);
+  // exit 0 unless hard dep missing on the dev machine (these tests assume
+  // the machine running them has node + git — both checked at the test
+  // suite level by tests A7 etc.).
+});
+
+test('schema error: unknown top-level property forces exit 1', () => {
+  const root = makeTempRepo();
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x', futureKnob: true }, null, 2)}\n`
+  );
+
+  const r = spawnDoctor([], root);
+  assert.equal(r.status, 1);
+  assert.match(r.stdout, /unknown property "futureKnob"/);
+});
+
+test('schema error: enum violation surfaces suggestion in output', () => {
+  const root = makeTempRepo();
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x', conventions: { commits: 'conventionall' } }, null, 2)}\n`
+  );
+
+  const r = spawnDoctor([], root);
+  assert.equal(r.status, 1);
+  assert.match(r.stdout, /conventions\/commits/);
+  assert.match(r.stdout, /suggestion: "conventional"/);
+});
+
+test('--json emits structured envelope', () => {
+  const root = makeTempRepo();
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x' }, null, 2)}\n`
+  );
+
+  const r = spawnDoctor(['--json'], root);
+  // Parse — must be valid JSON.
+  const env = JSON.parse(r.stdout);
+  assert.ok(env.deps);
+  assert.ok(env.config);
+  assert.ok(env.summary);
+  assert.equal(typeof env.summary.healthy, 'boolean');
+  assert.equal(typeof env.summary.schemaErrors, 'number');
+});
+
+test('--plugin design scopes deps to one plugin (config still global)', () => {
+  const root = makeTempRepo();
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x' }, null, 2)}\n`
+  );
+
+  const r = spawnDoctor(['--plugin', 'design', '--json'], root);
+  const env = JSON.parse(r.stdout);
+  assert.ok(env.deps.design);
+  assert.equal(env.deps.flow, undefined);
+  // Config section is still present.
+  assert.equal(env.config.exists, true);
+});
+
+test('config missing — section reports not-found, no schema check', () => {
+  const root = makeTempRepo();
+  // No .ai/workflows.config.json — leave .ai dir but no file.
+
+  const r = spawnDoctor(['--json'], root);
+  const env = JSON.parse(r.stdout);
+  assert.equal(env.config.exists, false);
+  assert.equal(env.summary.schemaErrors, 0);
+});
+
+test('--fix on config with unknown property drops it; existing values preserved', () => {
+  const root = makeTempRepo();
+  const initial = {
+    name: 'x',
+    futureKnob: true,
+    conventions: { prohibited: ['lodash'] },
+  };
+  writeFileSync(join(root, '.ai/workflows.config.json'), `${JSON.stringify(initial, null, 2)}\n`);
+
+  // --fix doesn't prompt for installs because there are no missing deps on
+  // the dev machine. Provide empty stdin just in case.
+  spawnSync('node', [MAUDE_BIN, 'doctor', '--fix'], {
+    cwd: root,
+    encoding: 'utf8',
+    input: '',
+    env: { ...process.env, NO_COLOR: '1' },
+  });
+
+  const after = JSON.parse(readFileSync(join(root, '.ai/workflows.config.json'), 'utf8'));
+  assert.equal(after.futureKnob, undefined, 'unknown property should be dropped');
+  // User-tuned value preserved.
+  assert.deepEqual(after.conventions.prohibited, ['lodash']);
+});
+
+test('summary line reflects counts (drift/additions tracked via package.json)', () => {
+  const root = makeTempRepo();
+  writeFileSync(
+    join(root, '.ai/workflows.config.json'),
+    `${JSON.stringify({ name: 'x', stack: { language: 'javascript' } }, null, 2)}\n`
+  );
+  // Drop a tsconfig so the language detector picks up TS.
+  writeFileSync(join(root, 'tsconfig.json'), '{}');
+  writeFileSync(
+    join(root, 'package.json'),
+    JSON.stringify({ name: 'x', scripts: { lint: 'echo' } })
+  );
+
+  const r = spawnDoctor(['--json'], root);
+  const env = JSON.parse(r.stdout);
+  // Drift: language js → typescript.
+  const langDrift = env.config.drift.find((d) => d.key === 'language');
+  assert.ok(langDrift, `expected language drift, got ${JSON.stringify(env.config.drift)}`);
+  assert.equal(langDrift.detected, 'typescript');
+  // Quality addition: lint.
+  const lintAdd = env.config.qualityAdditions.find((a) => a.gate === 'lint');
+  assert.ok(lintAdd);
+});

package/cli/commands/help.mjs

@@ -31,6 +31,25 @@ COMMANDS
         full discovery. --no-discovery uses Recommended defaults; --discovery-
         payload reads pre-computed answers from JSON.
 
+  hub serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
+        Start the self-hostable Yjs sync hub (Phase 9). Defaults to port 1234,
+        data dir ./data. --dev mints a mau_dev_<hex> token + prints the
+        connect command before booting. Local-dev-tree only in v1.1 Task 2.
+
+  hub token generate --label NAME [--data PATH] [--dev]
+        Mint a new mau_<32hex> token in <data>/tokens.json. Prints the raw
+        token ONCE plus the ready-to-paste 'maude design link' command.
+
+  hub status [URL] [--json]
+        Probe a hub's /health endpoint. URL defaults to http://localhost:1234.
+
+  doctor [--plugin <name>] [--fix] [--json]
+        Unified workspace health check. Reports missing dependencies, config
+        schema errors, stack drift, and missing quality-gate declarations in
+        one shot. --fix applies safe auto-fixes (prompts per dep install;
+        never overwrites existing config values). --json for programmatic
+        consumers.
+
   help              Print this help.
   version           Print the installed version.
 
@@ -40,6 +59,11 @@ EXAMPLES
   maude config get motion.complex
   maude design serve --port 4399
   maude design init --no-discovery --name acme-app
+  maude hub serve --dev
+  maude hub token generate --label alice
+  maude hub status http://localhost:1234
+  maude doctor
+  maude doctor --fix
 
 NOTES
   'maude init' does mechanical scaffolding of .ai/ only.

package/cli/commands/hub.mjs

@@ -0,0 +1,231 @@
+// maude hub — self-hostable Yjs sync hub control plane.
+//
+// Phase 9 Task 2 (minimal subset): serve + token generate + status.
+// Token rotate, deploy fly|docker land in subsequent slices.
+// See .ai/plans/phase-9-self-hosted-hub-file-sync.md.
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { parseArgs } from '../lib/argv.mjs';
+
+const SUBCOMMANDS = new Set(['serve', 'token', 'status', 'help']);
+
+export async function run({ args, pkgRoot }) {
+  const { positional } = parseArgs(args);
+  const sub = positional[0];
+
+  if (!sub || sub === 'help') {
+    process.stdout.write(usage());
+    return;
+  }
+  if (!SUBCOMMANDS.has(sub)) {
+    process.stderr.write(`maude hub: unknown subcommand "${sub}"\n${usage()}`);
+    process.exit(2);
+  }
+
+  if (sub === 'serve') return runServe({ args, pkgRoot });
+  if (sub === 'token') return runToken({ args, pkgRoot });
+  if (sub === 'status') return runStatus({ args });
+}
+
+function usage() {
+  return `maude hub <serve|token|status> [options]
+
+  serve [--port N] [--data PATH] [--secret HEX] [--insecure-http] [--dev]
+        Start the self-hostable Yjs sync hub in the current process tree.
+        --port           listen port (default 1234, env PORT)
+        --data           hub.db + tokens.json dir (default ./data, env DATA_DIR)
+        --secret         HUB_SECRET escape-hatch token (env HUB_SECRET)
+        --insecure-http  cosmetic log-only flag for non-TLS dev
+        --dev            generate a one-shot mau_dev_<hex> token, print the
+                         connect command, then run the hub. Convenience for
+                         contributor onboarding — drops tokens.json on exit
+                         is NOT performed (tokens persist; clean by hand).
+
+  token generate --label NAME [--data PATH] [--dev]
+        Generate a new mau_<32hex> token and append it to
+        <data>/tokens.json with the given label. Prints the raw token ONCE,
+        plus the ready-to-paste 'maude design link' connect command.
+
+        --dev produces a mau_dev_<hex> token (convention only — same auth).
+
+  status [URL] [--json]
+        HTTP GET <url>/health, print uptime/version/token-count. URL defaults
+        to http://localhost:1234. --json emits the raw response.
+
+NOTES
+  Local dev only in v1.1 Task 2 slice — production-install packaging
+  (adding plugins/design/hub to package.json:files + dep hoisting) lands
+  in a follow-up slice. For now, run inside a 'maude' source checkout.
+
+EXAMPLES
+  maude hub serve --port 4400
+  maude hub token generate --label alice
+  maude hub status http://localhost:4400
+`;
+}
+
+// ---------------------------------------------------------------- serve
+
+async function runServe({ args, pkgRoot }) {
+  const { flags } = parseArgs(args.slice(args.indexOf('serve') + 1), {
+    booleans: ['insecure-http', 'dev'],
+  });
+
+  const hubRoot = findHubRoot(pkgRoot);
+  if (!hubRoot) {
+    process.stderr.write(
+      'maude hub serve: hub workspace not found.\n\n' +
+        'This slice ships in local dev tree only. Production-install packaging\n' +
+        'is a follow-up Task 2 sub-slice. Run inside a maude source checkout.\n'
+    );
+    process.exit(1);
+  }
+
+  const env = { ...process.env };
+  if (flags.port) env.PORT = String(flags.port);
+  if (flags.data) env.DATA_DIR = resolve(String(flags.data));
+  if (flags.secret) env.HUB_SECRET = String(flags.secret);
+  if (flags['insecure-http']) env.HUB_INSECURE_HTTP = '1';
+
+  if (flags.dev) {
+    const dataDir = env.DATA_DIR ?? resolve(process.cwd(), 'data');
+    const { addToken } = await import(resolveHubModule(hubRoot, 'src/tokens.mjs'));
+    const port = env.PORT ?? '1234';
+    const record = addToken(dataDir, { label: 'dev', dev: true });
+    process.stdout.write(
+      `[hub] --dev token written to ${dataDir}/tokens.json:\n      label: ${record.label}\n      value: ${record.value}\n\n      Connect from a peer:\n        maude design link http://localhost:${port} --token=${record.value}\n\n`
+    );
+  }
+
+  const entry = resolveHubEntry(hubRoot);
+  const child = spawn(process.execPath, [entry], {
+    stdio: 'inherit',
+    env,
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+  child.on('error', (err) => {
+    process.stderr.write(`maude hub serve: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+// ---------------------------------------------------------------- token generate
+
+async function runToken({ args, pkgRoot }) {
+  const tail = args.slice(args.indexOf('token') + 1);
+  const op = tail[0];
+
+  if (op !== 'generate') {
+    process.stderr.write(
+      `maude hub token: only "generate" is supported in v1.1 Task 2 slice.\n` +
+        `"rotate" lands in a follow-up. Use "generate" with --label to mint a new token.\n`
+    );
+    process.exit(2);
+  }
+
+  const { flags } = parseArgs(tail.slice(1), { booleans: ['dev'] });
+  const label = flags.label;
+  if (!label || typeof label !== 'string') {
+    process.stderr.write('maude hub token generate: --label <name> is required.\n');
+    process.exit(2);
+  }
+  const dataDir = flags.data ? resolve(String(flags.data)) : resolve(process.cwd(), 'data');
+
+  const hubRoot = findHubRoot(pkgRoot);
+  if (!hubRoot) {
+    process.stderr.write('maude hub token generate: hub workspace not found.\n');
+    process.exit(1);
+  }
+  const { addToken } = await import(resolveHubModule(hubRoot, 'src/tokens.mjs'));
+  const record = addToken(dataDir, { label, dev: !!flags.dev });
+
+  process.stdout.write(
+    `[hub] token written to ${dataDir}/tokens.json:\n  label:      ${record.label}\n  value:      ${record.value}\n  created:    ${new Date(record.createdAt).toISOString()}\n\nConnect from a peer (replace HOST):\n  maude design link https://HOST --token=${record.value}\n\nRestart the hub if it is already running for the new token to take effect.\n`
+  );
+}
+
+// ---------------------------------------------------------------- status
+
+async function runStatus({ args }) {
+  const { flags, positional } = parseArgs(args.slice(args.indexOf('status') + 1), {
+    booleans: ['json'],
+  });
+  let url = positional[0] ?? 'http://localhost:1234';
+  if (url.startsWith('ws://')) url = `http://${url.slice('ws://'.length)}`;
+  if (url.startsWith('wss://')) url = `https://${url.slice('wss://'.length)}`;
+  if (url.endsWith('/')) url = url.slice(0, -1);
+
+  const target = `${url}/health`;
+  let payload;
+  try {
+    const res = await fetch(target);
+    if (!res.ok) {
+      process.stderr.write(
+        `maude hub status: ${target} returned ${res.status} ${res.statusText}\n`
+      );
+      process.exit(1);
+    }
+    payload = await res.json();
+  } catch (err) {
+    process.stderr.write(`maude hub status: cannot reach ${target}: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  const uptimeS = Math.round((payload.uptimeMs ?? 0) / 1000);
+  process.stdout.write(
+    `Maude Hub @ ${url}\n` +
+      `  ok:         ${payload.ok}\n` +
+      `  version:    ${payload.version}\n` +
+      `  uptime:     ${formatDuration(uptimeS)}\n` +
+      `  port:       ${payload.port}\n` +
+      `  dataDir:    ${payload.dataDir}\n` +
+      `  tokens:     ${payload.tokenCount} (mode: ${payload.authMode})\n`
+  );
+}
+
+// ---------------------------------------------------------------- helpers
+
+function findHubRoot(pkgRoot) {
+  const dev = resolve(pkgRoot, 'plugins', 'design', 'hub');
+  if (existsSync(resolve(dev, 'package.json'))) {
+    try {
+      const pkg = JSON.parse(readFileSync(resolve(dev, 'package.json'), 'utf8'));
+      if (pkg.name === '@maude/hub') return dev;
+    } catch {
+      /* fall through */
+    }
+  }
+  return null;
+}
+
+function resolveHubEntry(hubRoot) {
+  // Prefer the bundled binary (matches the production-install path); fall back
+  // to source for fresh dev trees where bun build hasn't been run yet.
+  const bundle = resolve(hubRoot, 'dist', 'hub.bundle.mjs');
+  if (existsSync(bundle)) return bundle;
+  return resolve(hubRoot, 'src', 'server.mjs');
+}
+
+function resolveHubModule(hubRoot, relPath) {
+  // Dynamic import expects a URL or absolute path. Bundle does not include
+  // standalone module exports (tokens.mjs lives in src/), so we always load
+  // from src/ for CLI helpers — independent of whether the bundle exists.
+  return `file://${resolve(hubRoot, relPath)}`;
+}
+
+function formatDuration(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  if (m < 60) return `${m}m${s.toString().padStart(2, '0')}s`;
+  const h = Math.floor(m / 60);
+  return `${h}h${(m % 60).toString().padStart(2, '0')}m${s.toString().padStart(2, '0')}s`;
+}

package/cli/commands/hub.test.mjs

@@ -0,0 +1,87 @@
+// `maude hub token generate` CLI end-to-end via spawnSync — verifies stdout
+// shape, file contents, and label-overwrite (rotation) idempotence.
+
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } 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';
+
+const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+
+function runCli(args, { cwd } = {}) {
+  return spawnSync(process.execPath, [BIN, ...args], {
+    cwd: cwd ?? process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function withDataDir(fn) {
+  const dataDir = mkdtempSync(join(tmpdir(), 'maude-cli-hub-'));
+  try {
+    return fn(dataDir);
+  } finally {
+    rmSync(dataDir, { recursive: true, force: true });
+  }
+}
+
+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>/);
+  assert.match(res.stdout, /token generate --label NAME/);
+});
+
+test('hub token generate without --label exits 2', () => {
+  const res = runCli(['hub', 'token', 'generate']);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /--label <name> is required/);
+});
+
+test('hub token generate writes tokens.json + prints the connect command', () => {
+  withDataDir((dataDir) => {
+    const res = runCli(['hub', 'token', 'generate', '--label', 'alice', '--data', dataDir]);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /label:\s+alice/);
+    assert.match(res.stdout, /value:\s+mau_[0-9a-f]{32}/);
+    assert.match(res.stdout, /maude design link/);
+
+    const raw = readFileSync(join(dataDir, 'tokens.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    assert.equal(parsed.tokens.length, 1);
+    assert.equal(parsed.tokens[0].label, 'alice');
+    assert.match(parsed.tokens[0].value, /^mau_[0-9a-f]{32}$/);
+  });
+});
+
+test('hub token generate --label is idempotent (overwrites in place)', () => {
+  withDataDir((dataDir) => {
+    runCli(['hub', 'token', 'generate', '--label', 'alice', '--data', dataDir]);
+    runCli(['hub', 'token', 'generate', '--label', 'alice', '--data', dataDir]);
+
+    const parsed = JSON.parse(readFileSync(join(dataDir, 'tokens.json'), 'utf8'));
+    assert.equal(parsed.tokens.length, 1);
+  });
+});
+
+test('hub token generate --dev uses mau_dev_ prefix', () => {
+  withDataDir((dataDir) => {
+    const res = runCli(['hub', 'token', 'generate', '--label', 'dev', '--data', dataDir, '--dev']);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /value:\s+mau_dev_[0-9a-f]{32}/);
+  });
+});
+
+test('hub status against an unreachable URL exits 1 with diagnostic', () => {
+  const res = runCli(['hub', 'status', 'http://127.0.0.1:1']);
+  assert.equal(res.status, 1);
+  assert.match(res.stderr, /cannot reach/);
+});
+
+test('hub serve|token|status are the only known subcommands', () => {
+  const res = runCli(['hub', 'nope']);
+  assert.equal(res.status, 2);
+  assert.match(res.stderr, /unknown subcommand "nope"/);
+});

package/cli/lib/config-lint.mjs

@@ -0,0 +1,141 @@
+// Schema-validate a workflows.config.json against the flow plugin's
+// JSON Schema (Draft 2020-12), with a Levenshtein-distance post-pass that
+// turns "enum" errors into actionable suggestions.
+//
+// Pure: no I/O for output, no process.exit. The CLI (cli/commands/doctor.mjs)
+// handles all formatting and termination. Two input shapes accepted:
+//
+//   lintConfig({ configPath, schemaPath })  // loads from disk
+//   lintConfig({ config, schema })          // already-parsed objects
+//
+// Returns { ok, errors }, where each error is
+//   { path: '/quality/lint', message: '...', value, allowed?, suggestion? }
+//
+// `additionalProperties: false` errors in the schema surface as "unknown
+// property X" — actionable on its own.
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import addFormats from 'ajv-formats';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const prev = new Array(n + 1);
+  const curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    for (let j = 0; j <= n; j++) prev[j] = curr[j];
+  }
+  return prev[n];
+}
+
+function suggestEnum(value, allowed) {
+  if (typeof value !== 'string') return null;
+  let best = null;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const candidate of allowed) {
+    if (typeof candidate !== 'string') continue;
+    const d = levenshtein(value, candidate);
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  if (bestDist <= 3) return best;
+  return null;
+}
+
+function ajvErrorToReport(e) {
+  // e.instancePath is JSON Pointer ('' = root). For additionalProperties
+  // violations, Ajv puts the offending key in e.params.additionalProperty,
+  // and instancePath points at the parent.
+  const path = e.instancePath || '/';
+  if (e.keyword === 'additionalProperties') {
+    const sep = path === '/' || path === '' ? '' : path;
+    return {
+      path: `${sep}/${e.params.additionalProperty}`,
+      message: `unknown property "${e.params.additionalProperty}" (additionalProperties: false)`,
+      value: undefined,
+    };
+  }
+  if (e.keyword === 'enum') {
+    return {
+      path,
+      message: `must be one of: ${e.params.allowedValues.join(' | ')}`,
+      value: e.data,
+      allowed: e.params.allowedValues,
+    };
+  }
+  if (e.keyword === 'required') {
+    const sep = path === '/' || path === '' ? '' : path;
+    return {
+      path: `${sep}/${e.params.missingProperty}`,
+      message: `missing required property "${e.params.missingProperty}"`,
+      value: undefined,
+    };
+  }
+  if (e.keyword === 'type') {
+    return {
+      path,
+      message: `must be ${Array.isArray(e.params.type) ? e.params.type.join(' | ') : e.params.type}`,
+      value: e.data,
+    };
+  }
+  if (e.keyword === 'minLength') {
+    return {
+      path,
+      message: `must have at least ${e.params.limit} character${e.params.limit === 1 ? '' : 's'}`,
+      value: e.data,
+    };
+  }
+  return {
+    path,
+    message: e.message || e.keyword,
+    value: e.data,
+  };
+}
+
+export async function lintConfig(input) {
+  let config = input.config;
+  let schema = input.schema;
+  if (config === undefined) {
+    if (!input.configPath) throw new Error('lintConfig: need `config` or `configPath`');
+    config = JSON.parse(await readFile(resolve(input.configPath), 'utf8'));
+  }
+  if (schema === undefined) {
+    if (!input.schemaPath) throw new Error('lintConfig: need `schema` or `schemaPath`');
+    schema = JSON.parse(await readFile(resolve(input.schemaPath), 'utf8'));
+  }
+
+  // Ajv2020 is the Draft-2020-12 entry. Default `import Ajv from 'ajv'` is
+  // Draft-07 and silently accepts schemas with $schema: 2020-12 while
+  // skipping new keywords — that would mask bugs.
+  const ajv = new Ajv2020({ allErrors: true, strict: false, verbose: true });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  const ok = validate(config);
+  if (ok) return { ok: true, errors: [] };
+
+  const errors = (validate.errors || []).map((e) => {
+    const report = ajvErrorToReport(e);
+    if (report.allowed && typeof report.value === 'string') {
+      const s = suggestEnum(report.value, report.allowed);
+      if (s !== null) report.suggestion = s;
+    }
+    return report;
+  });
+  return { ok: false, errors };
+}
+
+// Exported for the test file.
+export const _internals = { levenshtein, suggestEnum };