@1agh/maude 0.20.0 → 0.22.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,245 @@
+// 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).
+                         If unset on an empty hub, a one-time bootstrap link is
+                         printed to logs — open it in a browser to claim admin.
+        --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).
+
+        On boot the hub prints its /admin URL. The admin UI generates invite
+        tokens, lists peers, and rotates tokens without shelling into the host.
+
+  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).
+
+        Equivalent to the "Generate invite" button in the /admin UI — use
+        whichever is more convenient for the deploy.
+
+  status [URL] [--json]
+        HTTP GET <url>/health, print uptime/version/token-count/peers. 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
+
+  # Recommended flow on a fresh deploy:
+  #   1. maude hub serve            → copy bootstrap link from logs
+  #   2. open the link in browser   → first-run wizard, mint admin secret
+  #   3. click "Generate invite"    → copy 'maude design link …' command
+  #   4. paste on the peer machine  → linked
+`;
+}
+
+// ---------------------------------------------------------------- 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"/);
+});