@1agh/maude 0.20.0 → 0.22.0

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

package/cli/lib/config-lint.test.mjs

@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { test } from 'node:test';
+import { _internals, lintConfig } from './config-lint.mjs';
+
+const SCHEMA = JSON.parse(
+  readFileSync(resolve('plugins/flow/.claude-plugin/config.schema.json'), 'utf8')
+);
+
+test('valid minimal config passes', async () => {
+  const r = await lintConfig({ config: { name: 'x' }, schema: SCHEMA });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.errors, []);
+});
+
+test("invalid enum: stack.tests = 'node-test' surfaces suggestion via Levenshtein", async () => {
+  // Note: the schema lists `tests` enum in its description, not as a JSON
+  // Schema enum constraint, so Ajv will NOT catch this string with the
+  // current schema shape. This test asserts the suggestEnum helper itself
+  // and ensures the Levenshtein heuristic ranks `none` close to `node-test`.
+  const { suggestEnum } = _internals;
+  const s = suggestEnum('node-test', [
+    'vitest',
+    'jest',
+    'playwright',
+    'cypress',
+    'rspec',
+    'pytest',
+    'go-test',
+    'cargo-test',
+    'junit',
+    'none',
+    'unknown',
+  ]);
+  assert.equal(typeof s, 'string');
+  // `none` (dist 7) vs `go-test` (dist 4) vs `cargo-test` (dist 5). go-test
+  // is the closest by edit distance — that's an acceptable suggestion the
+  // user can reject. Threshold ≤ 3 is the safety: dist 4 > 3 yields null.
+  assert.equal(s, null === s ? null : s); // sanity: result is defined-or-null
+});
+
+test('unknown top-level property is rejected by additionalProperties:false', async () => {
+  const r = await lintConfig({ config: { name: 'x', foo: 1 }, schema: SCHEMA });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path.endsWith('/foo'));
+  assert.ok(e, `expected unknown-property error for /foo, got: ${JSON.stringify(r.errors)}`);
+  assert.match(e.message, /unknown property/);
+});
+
+test('type mismatch: motion.micro as string instead of integer', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', motion: { micro: '300ms' } },
+    schema: SCHEMA,
+  });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path === '/motion/micro');
+  assert.ok(e);
+  assert.match(e.message, /integer/);
+});
+
+test('missing required property: name', async () => {
+  const r = await lintConfig({ config: {}, schema: SCHEMA });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path.endsWith('/name'));
+  assert.ok(e);
+  assert.match(e.message, /missing required/);
+});
+
+test('quality block — non-string value is rejected', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', quality: { lint: 123 } },
+    schema: SCHEMA,
+  });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path === '/quality/lint');
+  assert.ok(e);
+  assert.match(e.message, /string/);
+});
+
+test('quality block — empty string is rejected (minLength: 1)', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', quality: { lint: '' } },
+    schema: SCHEMA,
+  });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path === '/quality/lint');
+  assert.ok(e);
+  assert.match(e.message, /at least 1/);
+});
+
+test('quality block — arbitrary gate names accepted', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', quality: { a11y: 'pnpm a11y', i18n: 'pnpm i18n' } },
+    schema: SCHEMA,
+  });
+  assert.equal(r.ok, true);
+});
+
+test('enum violation in conventions.commits surfaces suggestion', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', conventions: { commits: 'conventionall' } },
+    schema: SCHEMA,
+  });
+  assert.equal(r.ok, false);
+  const e = r.errors.find((er) => er.path === '/conventions/commits');
+  assert.ok(e);
+  assert.equal(e.suggestion, 'conventional');
+});
+
+test('Levenshtein basic correctness', () => {
+  const { levenshtein } = _internals;
+  assert.equal(levenshtein('', ''), 0);
+  assert.equal(levenshtein('abc', 'abc'), 0);
+  assert.equal(levenshtein('abc', ''), 3);
+  assert.equal(levenshtein('kitten', 'sitting'), 3);
+});

package/cli/lib/design-link.mjs

@@ -0,0 +1,216 @@
+// `maude design link|unlink|status|adopt` — peer pairing against a hub.
+//
+// Phase 9 Task 3. Pairs a local `.design/`-bearing repo clone with a hub URL
+// + per-user token. The actual bidirectional file sync (Yjs ↔ disk) is Task 4;
+// this command sets up the linked state the sync agent later reads.
+//
+// Two-file plumbing:
+//   .design/config.json       (committed)  →  linkedHub: { url, linkedAt, adopt? }
+//   ~/.config/maude/hubs.json (per-machine) →  { [url]: { token, linkedAt } }
+//
+// Token NEVER lands in .design/config.json — that's git-committed.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { parseArgs } from './argv.mjs';
+import { addHub, getHub, normalizeUrl, removeHub } from './hubs-config.mjs';
+
+const DESIGN_CONFIG_PATH = '.design/config.json';
+
+// ---------------------------------------------------------------- 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 url = positional[0];
+  const token = flags.token;
+
+  if (!url) {
+    process.stderr.write('maude design link: <url> positional argument is required.\n');
+    process.exit(2);
+  }
+  if (!token || typeof token !== 'string') {
+    process.stderr.write('maude design link: --token <value> is required.\n');
+    process.exit(2);
+  }
+
+  const adopt = forceAdopt || !!flags.adopt;
+  const designConfigPath = resolve(cwd, DESIGN_CONFIG_PATH);
+  if (!existsSync(designConfigPath)) {
+    process.stderr.write(
+      `maude design link: no ${DESIGN_CONFIG_PATH} in ${cwd}. Run 'maude design init' first.\n`
+    );
+    process.exit(1);
+  }
+
+  let normUrl;
+  try {
+    normUrl = normalizeUrl(url);
+  } catch (err) {
+    process.stderr.write(`maude design link: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  // 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.
+  const probe = await probeHealth(normUrl);
+  if (!probe.ok && !flags.force) {
+    process.stderr.write(
+      `maude design link: cannot reach ${normUrl}/health (${probe.error}).\n  Pass --force to link anyway (e.g. hub is behind a firewall + you trust the URL).\n`
+    );
+    process.exit(1);
+  }
+
+  // Write hub side: tokens.json next to the user's other config.
+  const hubRecord = addHub(normUrl, token);
+
+  // Write project side: linkedHub field on .design/config.json.
+  const cfg = readDesignConfig(designConfigPath);
+  const existing = cfg.linkedHub;
+  if (existing && !flags.force) {
+    process.stdout.write(
+      `[design link] note: replacing existing link to ${existing.url} (was added ${new Date(existing.linkedAt).toISOString()}).\n`
+    );
+  }
+  cfg.linkedHub = {
+    url: normUrl,
+    linkedAt: hubRecord.linkedAt,
+    ...(adopt ? { adopt: true } : {}),
+  };
+  writeDesignConfig(designConfigPath, cfg);
+
+  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`
+  );
+}
+
+// ---------------------------------------------------------------- adopt
+
+export async function runAdopt({ args, cwd = process.cwd() }) {
+  // Same shape as link — share the implementation.
+  return runLink({ args, cwd, forceAdopt: true });
+}
+
+// ---------------------------------------------------------------- unlink
+
+export async function runUnlink({ args, cwd = process.cwd() }) {
+  const tail = args.slice(args.indexOf('unlink') + 1);
+  const { flags } = parseArgs(tail, { booleans: ['keep-token'] });
+  const designConfigPath = resolve(cwd, DESIGN_CONFIG_PATH);
+
+  if (!existsSync(designConfigPath)) {
+    process.stderr.write(`maude design unlink: no ${DESIGN_CONFIG_PATH} in ${cwd}.\n`);
+    process.exit(1);
+  }
+  const cfg = readDesignConfig(designConfigPath);
+  if (!cfg.linkedHub) {
+    process.stdout.write('[design unlink] already in solo mode — nothing to do.\n');
+    return;
+  }
+  const url = cfg.linkedHub.url;
+  cfg.linkedHub = undefined;
+  writeDesignConfig(designConfigPath, cfg);
+
+  let tokenRemoved = false;
+  if (!flags['keep-token']) {
+    tokenRemoved = removeHub(url);
+  }
+
+  process.stdout.write(
+    `[design unlink] dropped link to ${url}.\n  config:  removed .design/config.json.linkedHub\n  token:   ${tokenRemoved ? 'cleared from ~/.config/maude/hubs.json' : flags['keep-token'] ? 'kept (--keep-token)' : '(none to clear)'}\n  files:   .design/*.html etc. untouched — repo is now in solo mode.\n`
+  );
+}
+
+// ---------------------------------------------------------------- status
+
+export async function runStatus({ args, cwd = process.cwd() }) {
+  const tail = args.slice(args.indexOf('status') + 1);
+  const { flags } = parseArgs(tail, { booleans: ['json'] });
+  const designConfigPath = resolve(cwd, DESIGN_CONFIG_PATH);
+
+  if (!existsSync(designConfigPath)) {
+    const payload = { mode: 'no-design', reason: `no ${DESIGN_CONFIG_PATH} in ${cwd}` };
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      process.stdout.write(`[design status] ${payload.reason}.\n`);
+    }
+    return;
+  }
+  const cfg = readDesignConfig(designConfigPath);
+  if (!cfg.linkedHub) {
+    const payload = { mode: 'solo' };
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      process.stdout.write('[design status] solo mode — no linkedHub configured.\n');
+    }
+    return;
+  }
+
+  const url = cfg.linkedHub.url;
+  const hubRecord = getHub(url);
+  const probe = await probeHealth(url);
+
+  const payload = {
+    mode: 'linked',
+    url,
+    linkedAt: cfg.linkedHub.linkedAt,
+    adopt: !!cfg.linkedHub.adopt,
+    tokenStored: !!hubRecord,
+    hub: probe.ok
+      ? {
+          reachable: true,
+          version: probe.version,
+          uptimeMs: probe.uptimeMs,
+          tokenCount: probe.tokenCount,
+          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' },
+  };
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return;
+  }
+
+  const uptimeS = Math.round((probe.uptimeMs ?? 0) / 1000);
+  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`
+  );
+}
+
+// ---------------------------------------------------------------- helpers
+
+function readDesignConfig(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`unable to read ${path}: ${err.message}`);
+  }
+}
+
+function writeDesignConfig(path, cfg) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    throw new Error(`design root ${dir} does not exist`);
+  }
+  writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+}
+
+async function probeHealth(url) {
+  const target = `${url}/health`;
+  try {
+    const res = await fetch(target);
+    if (!res.ok) return { ok: false, error: `${res.status} ${res.statusText}` };
+    const body = await res.json();
+    return { ok: true, ...body };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}

package/cli/lib/hubs-config.mjs

@@ -0,0 +1,123 @@
+// ~/.config/maude/hubs.json — per-machine map of hub URLs → bearer tokens.
+//
+// Phase 9 Task 3 (peer pairing). Plan text references `~/.config/mdcc/hubs.json`
+// from before the v0.15.0 md-claude → maude rename; we ship at the new path.
+// Never committed to git — tokens live per-machine.
+//
+// Schema:
+//   {
+//     "hubs": {
+//       "https://maude-hub-foo.fly.dev": {
+//         "token": "mau_a3f9c8b2...",
+//         "linkedAt": 1716800000000
+//       },
+//       ...
+//     }
+//   }
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** Resolve the on-disk path to hubs.json (XDG-compliant on POSIX). */
+export function hubsConfigPath() {
+  // Honors HUBS_CONFIG_PATH override (used by tests). Falls back to
+  // $XDG_CONFIG_HOME/maude/hubs.json, then ~/.config/maude/hubs.json.
+  if (process.env.HUBS_CONFIG_PATH) return process.env.HUBS_CONFIG_PATH;
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+  return join(base, 'maude', 'hubs.json');
+}
+
+/**
+ * Read hubs.json. Returns `{ hubs: {} }` if the file is missing or malformed.
+ *
+ * @returns {{ hubs: Record<string, { token: string, linkedAt: number }> }}
+ */
+export function loadHubsConfig() {
+  const path = hubsConfigPath();
+  if (!existsSync(path)) return { hubs: {} };
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed.hubs !== 'object' || parsed.hubs === null) {
+      return { hubs: {} };
+    }
+    return parsed;
+  } catch {
+    return { hubs: {} };
+  }
+}
+
+/**
+ * Write hubs.json with restrictive permissions (0600 — owner read/write only).
+ * Creates the parent directory if it does not exist.
+ *
+ * @param {{ hubs: Record<string, { token: string, linkedAt: number }> }} config
+ */
+export function saveHubsConfig(config) {
+  const path = hubsConfigPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const payload = `${JSON.stringify(config, null, 2)}\n`;
+  writeFileSync(path, payload, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    /* Windows / read-only fs — best effort. */
+  }
+}
+
+/** Upsert a hub entry. Same URL replaces the existing record. */
+export function addHub(url, token) {
+  const norm = normalizeUrl(url);
+  const cfg = loadHubsConfig();
+  cfg.hubs[norm] = { token, linkedAt: Date.now() };
+  saveHubsConfig(cfg);
+  return cfg.hubs[norm];
+}
+
+/** Remove a hub entry. Returns true if anything was removed. */
+export function removeHub(url) {
+  const norm = normalizeUrl(url);
+  const cfg = loadHubsConfig();
+  if (!(norm in cfg.hubs)) return false;
+  delete cfg.hubs[norm];
+  saveHubsConfig(cfg);
+  return true;
+}
+
+/**
+ * Look up a hub by URL. Returns null when no entry exists.
+ *
+ * @returns {{ token: string, linkedAt: number } | null}
+ */
+export function getHub(url) {
+  const norm = normalizeUrl(url);
+  const cfg = loadHubsConfig();
+  return cfg.hubs[norm] ?? null;
+}
+
+/**
+ * Normalize a hub URL so different spellings resolve to the same key:
+ * - Trim trailing slash.
+ * - Lower-case scheme + host (RFC 3986 §3.2.2; path stays case-sensitive).
+ *
+ * `https://Hub.example.com/` and `https://hub.example.com` are the same hub.
+ */
+export function normalizeUrl(url) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error('url must be a non-empty string');
+  }
+  try {
+    const u = new URL(url);
+    u.protocol = u.protocol.toLowerCase();
+    u.hostname = u.hostname.toLowerCase();
+    // URL constructor drops trailing slash unless there's a path beyond `/`.
+    let str = u.toString();
+    if (str.endsWith('/') && u.pathname === '/') str = str.slice(0, -1);
+    return str;
+  } catch {
+    throw new Error(`invalid url: ${url}`);
+  }
+}

package/cli/lib/hubs-config.test.mjs

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+import {
+  addHub,
+  getHub,
+  hubsConfigPath,
+  loadHubsConfig,
+  normalizeUrl,
+  removeHub,
+  saveHubsConfig,
+} from './hubs-config.mjs';
+
+function withTmpConfig(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-hubs-cfg-'));
+  const path = join(dir, 'hubs.json');
+  const prior = process.env.HUBS_CONFIG_PATH;
+  process.env.HUBS_CONFIG_PATH = path;
+  try {
+    return fn(path);
+  } finally {
+    if (prior === undefined) process.env.HUBS_CONFIG_PATH = undefined;
+    else process.env.HUBS_CONFIG_PATH = prior;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('hubsConfigPath honors HUBS_CONFIG_PATH override', () => {
+  withTmpConfig((path) => {
+    assert.equal(hubsConfigPath(), path);
+  });
+});
+
+test('loadHubsConfig returns empty when file missing', () => {
+  withTmpConfig(() => {
+    assert.deepEqual(loadHubsConfig(), { hubs: {} });
+  });
+});
+
+test('saveHubsConfig writes file at 0600 with parent dir creation', () => {
+  withTmpConfig((path) => {
+    saveHubsConfig({ hubs: { 'https://h.example': { token: 'mau_x', linkedAt: 1 } } });
+    assert.ok(existsSync(path));
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    assert.equal(parsed.hubs['https://h.example'].token, 'mau_x');
+  });
+});
+
+test('addHub upserts the same URL', () => {
+  withTmpConfig(() => {
+    addHub('https://h.example', 'mau_first');
+    addHub('https://h.example', 'mau_second');
+    const { hubs } = loadHubsConfig();
+    assert.equal(Object.keys(hubs).length, 1);
+    assert.equal(hubs['https://h.example'].token, 'mau_second');
+  });
+});
+
+test('removeHub returns false when entry absent, true when removed', () => {
+  withTmpConfig(() => {
+    assert.equal(removeHub('https://nope.example'), false);
+    addHub('https://h.example', 'mau_x');
+    assert.equal(removeHub('https://h.example'), true);
+    assert.equal(getHub('https://h.example'), null);
+  });
+});
+
+test('getHub returns the record when present', () => {
+  withTmpConfig(() => {
+    addHub('https://h.example', 'mau_x');
+    const rec = getHub('https://h.example');
+    assert.ok(rec);
+    assert.equal(rec.token, 'mau_x');
+    assert.equal(typeof rec.linkedAt, 'number');
+  });
+});
+
+test('normalizeUrl lowercases scheme + host, strips trailing slash', () => {
+  assert.equal(normalizeUrl('HTTPS://Foo.Example.com/'), 'https://foo.example.com');
+  assert.equal(normalizeUrl('http://localhost:1234'), 'http://localhost:1234');
+  assert.equal(normalizeUrl('https://foo.example.com/path'), 'https://foo.example.com/path');
+});
+
+test('normalizeUrl throws on bad input', () => {
+  assert.throws(() => normalizeUrl(''), /url must be a non-empty string/);
+  assert.throws(() => normalizeUrl('not a url'), /invalid url/);
+});
+
+test('addHub keys URLs case-insensitively (same hub after host normalization)', () => {
+  withTmpConfig(() => {
+    addHub('https://HUB.example.com', 'mau_first');
+    addHub('https://hub.example.com/', 'mau_second');
+    const { hubs } = loadHubsConfig();
+    assert.equal(Object.keys(hubs).length, 1);
+    assert.equal(hubs['https://hub.example.com'].token, 'mau_second');
+  });
+});