@1agh/maude 0.20.0 → 0.21.0

package/cli/lib/preflight.mjs

@@ -0,0 +1,232 @@
+// Preflight checker — loads a plugin's dependencies.json and runs each
+// dependency's `check.command` (or `check.mcp` probe) to report
+// presence / version / missing-ness.
+//
+// Used by:
+//   - cli/commands/doctor.mjs (the unified diagnostic CLI)
+//   - plugins/flow/commands/init.md (the wired pre-flight Step 1)
+//   - plugins/design/dev-server/bin/preflight.sh (which re-shells to node
+//     for the actual checks — keeps detection logic in one place).
+//
+// Pure-ish: no process.exit; returns an envelope. printReport() is here
+// because every consumer wants the same table format.
+
+import { spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const SEM_RE = /(\d+)\.(\d+)\.(\d+)/;
+
+function parseVersion(text) {
+  const m = text.match(SEM_RE);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+function checkVersion(stdout, minVersion) {
+  if (!minVersion) return { ok: true };
+  const have = parseVersion(stdout);
+  const want = parseVersion(minVersion);
+  if (!have) return { ok: false, reason: `could not parse version from "${stdout.trim()}"` };
+  if (!want) return { ok: true };
+  if (compareVersions(have, want) < 0) {
+    return {
+      ok: false,
+      reason: `have ${have.join('.')} need ≥ ${want.join('.')}`,
+      have: have.join('.'),
+    };
+  }
+  return { ok: true, have: have.join('.') };
+}
+
+async function runCommand(command) {
+  const r = spawnSync('bash', ['-c', command], { encoding: 'utf8', timeout: 5000 });
+  return {
+    status: r.status === null ? -1 : r.status,
+    stdout: (r.stdout || '').toString(),
+    stderr: (r.stderr || '').toString(),
+  };
+}
+
+export async function checkDependency(dep) {
+  // MCP probes — we can't actually call MCP tools from a plain Node script;
+  // they're surfaced through Claude Code's tool layer. Mark as `unknown`
+  // and let the agent layer fill it in (the agent has visibility into
+  // available MCP tools).
+  if (dep.type === 'mcp') {
+    return {
+      id: dep.id,
+      status: 'unknown',
+      hardness: dep.hardness,
+      detail: `MCP probe — not checkable from a non-agent process. Tool: ${dep.check.mcp}${dep.check.tool ? `/${dep.check.tool}` : ''}`,
+    };
+  }
+
+  const command = dep.check.command || `${dep.id} --version`;
+  const expectExit = dep.check.expectExit ?? 0;
+  const result = await runCommand(command);
+
+  if (result.status !== expectExit) {
+    return {
+      id: dep.id,
+      status: 'missing',
+      hardness: dep.hardness,
+      detail:
+        result.status === -1 ? 'command timed out or failed to spawn' : `exit ${result.status}`,
+      install: dep.install,
+    };
+  }
+
+  const versionCheck = checkVersion(result.stdout, dep.check.minVersion);
+  if (!versionCheck.ok) {
+    return {
+      id: dep.id,
+      status: 'outdated',
+      hardness: dep.hardness,
+      detail: versionCheck.reason,
+      install: dep.install,
+    };
+  }
+
+  return {
+    id: dep.id,
+    status: 'ok',
+    hardness: dep.hardness,
+    version: versionCheck.have || result.stdout.trim().split('\n')[0],
+  };
+}
+
+export async function loadManifest(manifestPath) {
+  const raw = await readFile(resolve(manifestPath), 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function checkAll(manifestPath) {
+  const manifest = await loadManifest(manifestPath);
+  const results = [];
+  for (const dep of manifest.dependencies) {
+    // eslint-disable-next-line no-await-in-loop
+    results.push(await checkDependency(dep));
+  }
+  const hardFailing = results.filter((r) => r.hardness === 'hard' && r.status !== 'ok');
+  const softFailing = results.filter((r) => r.hardness === 'soft' && r.status === 'missing');
+  return {
+    plugin: manifest.plugin,
+    results,
+    summary: {
+      total: results.length,
+      ok: results.filter((r) => r.status === 'ok').length,
+      missing: results.filter((r) => r.status === 'missing').length,
+      outdated: results.filter((r) => r.status === 'outdated').length,
+      unknown: results.filter((r) => r.status === 'unknown').length,
+      hardFailing: hardFailing.length,
+      softFailing: softFailing.length,
+      allHardPass: hardFailing.length === 0,
+    },
+  };
+}
+
+const STATUS_GLYPH = {
+  ok: '✓',
+  missing: '✗',
+  outdated: '⚠',
+  unknown: '?',
+};
+
+export function formatTable(envelope, { color = false } = {}) {
+  const lines = [];
+  const tag = (s) => (color ? colorFor(s) : s);
+  for (const r of envelope.results) {
+    const glyph = STATUS_GLYPH[r.status] || '?';
+    const label = r.id.padEnd(20);
+    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 if (r.status === 'unknown') {
+      rhs = r.detail || '';
+    }
+    lines.push(`  ${tag(glyph)} ${label} ${rhs}`);
+  }
+  return lines.join('\n');
+}
+
+function colorFor(g) {
+  if (g === '✓') return `${g}`;
+  if (g === '✗') return `${g}`;
+  if (g === '⚠') return `${g}`;
+  return g;
+}
+
+// ─── CLI entry — `node cli/lib/preflight.mjs --plugin design --json` ──────
+
+function parseFlags(args) {
+  const out = { plugin: null, mode: 'text' };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--plugin') out.plugin = args[++i];
+    else if (a === '--json') out.mode = 'json';
+    else if (a === '--shell-export') out.mode = 'shell-export';
+    else if (a === '--quiet') out.mode = 'quiet';
+    else if (a === '--warn-only') out.mode = 'warn-only';
+  }
+  return out;
+}
+
+function manifestPathForPlugin(pluginName) {
+  return resolve(`plugins/${pluginName}/dependencies.json`);
+}
+
+async function main(argv) {
+  const flags = parseFlags(argv.slice(2));
+  if (!flags.plugin) {
+    process.stderr.write('preflight.mjs: pass --plugin <design|flow>\n');
+    process.exit(2);
+  }
+  const env = await checkAll(manifestPathForPlugin(flags.plugin));
+  if (flags.mode === 'json') {
+    process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
+  } else if (flags.mode === 'shell-export') {
+    const missing = env.results
+      .filter((r) => r.status === 'missing')
+      .map((r) => r.id)
+      .join(',');
+    process.stdout.write(`export DEPS_OK=${env.summary.allHardPass ? 1 : 0}\n`);
+    process.stdout.write(`export DEPS_MISSING="${missing}"\n`);
+    process.stdout.write(`export DEPS_PLUGIN="${env.plugin}"\n`);
+  } else if (flags.mode === 'quiet' || flags.mode === 'warn-only') {
+    const missingHard = env.results.filter(
+      (r) => r.hardness === 'hard' && r.status !== 'ok' && r.status !== 'unknown'
+    );
+    if (missingHard.length > 0) {
+      const ids = missingHard.map((r) => r.id).join(', ');
+      process.stdout.write(`MISSING HARD DEPS: ${ids}. Run \`maude doctor --fix\` to install.\n`);
+    }
+  } else {
+    process.stdout.write(`Dependencies (plugin: ${env.plugin}):\n`);
+    process.stdout.write(`${formatTable(env, { color: process.stdout.isTTY })}\n`);
+    process.stdout.write(
+      `\nSummary: ${env.summary.ok}/${env.summary.total} ok, ${env.summary.hardFailing} hard failing, ${env.summary.softFailing} soft missing.\n`
+    );
+  }
+  process.exit(env.summary.allHardPass ? 0 : 1);
+}
+
+// Entry guard — only run main() when invoked directly.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv).catch((err) => {
+    process.stderr.write(`preflight: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/cli/lib/stack-detect.mjs

@@ -0,0 +1,344 @@
+// Pure detection of project stack + quality-gate hints.
+//
+// Read-only. Never throws. Returns "unknown" / null when nothing matches.
+//
+// Port of /flow:init Step 2 bash (plugins/flow/commands/init.md lines 71–181)
+// with one extension: when the root lacks a marker (tsconfig.json, next.config.*,
+// …) AND pnpm-workspace.yaml exists, glance one level into workspace packages.
+// Without that, a monorepo where every workspace is TypeScript still reports
+// `language: javascript` because the root only has a JS package.json.
+//
+// Consumers: cli/commands/doctor.mjs and the drift-aware /flow:init re-run.
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function anyExists(repoRoot, names) {
+  for (const n of names) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await fileExists(join(repoRoot, n))) return n;
+  }
+  return null;
+}
+
+async function listWorkspaceDirs(repoRoot) {
+  // Cheap depth-1 scan triggered only when pnpm-workspace.yaml exists.
+  // We do not parse the YAML — common monorepo layouts (`packages/*`,
+  // `apps/*`, `plugins/*`, `site/`) cover ~all cases. Returns absolute paths.
+  if (!(await fileExists(join(repoRoot, 'pnpm-workspace.yaml')))) return [];
+  const out = [];
+  // Candidate directories that, depending on layout, are either
+  //   (a) the workspace member itself (e.g. ./site)
+  //   (b) a container of members (e.g. ./packages/foo, ./plugins/design)
+  // We include BOTH the candidate path and its first-level subdirs in the
+  // scan target list, so layouts like this repo's `site/tsconfig.json` are
+  // reached even though `site/` is itself the member.
+  const candidates = ['packages', 'apps', 'plugins', 'site', 'scripts', 'examples'];
+  for (const c of candidates) {
+    const dir = join(repoRoot, c);
+    // eslint-disable-next-line no-await-in-loop
+    if (!(await fileExists(dir))) continue;
+    out.push(dir);
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const ents = await readdir(dir, { withFileTypes: true });
+      for (const e of ents) {
+        if (e.isDirectory()) out.push(join(dir, e.name));
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return out;
+}
+
+async function anyExistsDeep(repoRoot, names, workspaceDirs) {
+  // First check root, then one level into each workspace dir.
+  const root = await anyExists(repoRoot, names);
+  if (root) return root;
+  for (const wd of workspaceDirs) {
+    for (const n of names) {
+      // eslint-disable-next-line no-await-in-loop
+      if (await fileExists(join(wd, n))) return `${wd.slice(repoRoot.length + 1)}/${n}`;
+    }
+  }
+  return null;
+}
+
+async function readPkgJson(repoRoot) {
+  try {
+    const raw = await readFile(join(repoRoot, 'package.json'), 'utf8');
+    return { raw, parsed: JSON.parse(raw) };
+  } catch {
+    return { raw: '', parsed: null };
+  }
+}
+
+export async function detectStack(repoRoot) {
+  const ws = await listWorkspaceDirs(repoRoot);
+  const { raw: pkgRaw, parsed: pkg } = await readPkgJson(repoRoot);
+
+  // Package manager — lock files at root.
+  let packageManager = 'unknown';
+  if (await fileExists(join(repoRoot, 'pnpm-lock.yaml'))) packageManager = 'pnpm';
+  else if (await fileExists(join(repoRoot, 'yarn.lock'))) packageManager = 'yarn';
+  else if (await fileExists(join(repoRoot, 'package-lock.json'))) packageManager = 'npm';
+  else if (await fileExists(join(repoRoot, 'bun.lockb'))) packageManager = 'bun';
+  else if (await fileExists(join(repoRoot, 'Cargo.toml'))) packageManager = 'cargo';
+  else if (await fileExists(join(repoRoot, 'go.mod'))) packageManager = 'go';
+  else if (
+    (await fileExists(join(repoRoot, 'pyproject.toml'))) ||
+    (await fileExists(join(repoRoot, 'requirements.txt')))
+  )
+    packageManager = 'pip';
+  else if (await fileExists(join(repoRoot, 'pom.xml'))) packageManager = 'maven';
+  else if (
+    (await fileExists(join(repoRoot, 'build.gradle'))) ||
+    (await fileExists(join(repoRoot, 'build.gradle.kts')))
+  )
+    packageManager = 'gradle';
+
+  // Language — deep-scan tsconfig before falling back to package.json → js.
+  let language = 'unknown';
+  if (await anyExistsDeep(repoRoot, ['tsconfig.json'], ws)) language = 'typescript';
+  else if (await fileExists(join(repoRoot, 'Cargo.toml'))) language = 'rust';
+  else if (await fileExists(join(repoRoot, 'go.mod'))) language = 'go';
+  else if (
+    (await fileExists(join(repoRoot, 'pyproject.toml'))) ||
+    (await fileExists(join(repoRoot, 'requirements.txt')))
+  )
+    language = 'python';
+  else if (
+    (await fileExists(join(repoRoot, 'pom.xml'))) ||
+    (await fileExists(join(repoRoot, 'build.gradle'))) ||
+    (await fileExists(join(repoRoot, 'build.gradle.kts')))
+  )
+    language = 'java';
+  else if (await fileExists(join(repoRoot, 'package.json'))) language = 'javascript';
+
+  // Framework — root first, then workspace.
+  let framework = 'unknown';
+  if (await anyExistsDeep(repoRoot, ['next.config.js', 'next.config.ts', 'next.config.mjs'], ws))
+    framework = 'next.js';
+  else if (await anyExistsDeep(repoRoot, ['vite.config.js', 'vite.config.ts'], ws))
+    framework = 'vite';
+  else if (await anyExistsDeep(repoRoot, ['app.json', 'app.config.js', 'app.config.ts'], ws))
+    framework = 'expo';
+  else if (await anyExistsDeep(repoRoot, ['svelte.config.js'], ws)) framework = 'sveltekit';
+  else if (await anyExistsDeep(repoRoot, ['remix.config.js'], ws)) framework = 'remix';
+  else if (await anyExistsDeep(repoRoot, ['astro.config.mjs'], ws)) framework = 'astro';
+  else if (await anyExistsDeep(repoRoot, ['nuxt.config.ts', 'nuxt.config.js'], ws))
+    framework = 'nuxt';
+
+  // Monorepo + build tool.
+  let monorepo = false;
+  let buildTool = 'none';
+  if (await fileExists(join(repoRoot, 'turbo.json'))) {
+    monorepo = true;
+    buildTool = 'turbo';
+  } else if (await fileExists(join(repoRoot, 'nx.json'))) {
+    monorepo = true;
+    buildTool = 'nx';
+  } else if (await fileExists(join(repoRoot, 'lerna.json'))) {
+    monorepo = true;
+    buildTool = 'lerna';
+  } else if (await fileExists(join(repoRoot, 'rush.json'))) {
+    monorepo = true;
+    buildTool = 'rush';
+  } else if (await fileExists(join(repoRoot, 'pnpm-workspace.yaml'))) {
+    monorepo = true;
+  } else if (await fileExists(join(repoRoot, 'Makefile'))) {
+    buildTool = 'make';
+  } else if (
+    (await fileExists(join(repoRoot, 'BUILD.bazel'))) ||
+    (await fileExists(join(repoRoot, 'WORKSPACE')))
+  ) {
+    buildTool = 'bazel';
+  }
+
+  // CI.
+  let ci = 'unknown';
+  if (await fileExists(join(repoRoot, '.github/workflows'))) ci = 'github-actions';
+  else if (await fileExists(join(repoRoot, '.gitlab-ci.yml'))) ci = 'gitlab-ci';
+  else if (await fileExists(join(repoRoot, 'Jenkinsfile'))) ci = 'jenkins';
+  else if (await fileExists(join(repoRoot, 'azure-pipelines.yml'))) ci = 'azure-devops';
+  else if (await fileExists(join(repoRoot, '.circleci/config.yml'))) ci = 'circleci';
+  else if (await fileExists(join(repoRoot, 'bitbucket-pipelines.yml'))) ci = 'bitbucket';
+
+  // Tests — substring match on raw package.json so it picks up references in
+  // scripts (`"vitest run"`) as well as devDependencies (matches the bash port).
+  let tests = 'unknown';
+  if (pkgRaw) {
+    if (pkgRaw.includes('"vitest"')) tests = 'vitest';
+    else if (pkgRaw.includes('"jest"')) tests = 'jest';
+    else if (pkgRaw.includes('"@playwright/test"')) tests = 'playwright';
+    else if (pkgRaw.includes('"cypress"')) tests = 'cypress';
+  }
+  if (await fileExists(join(repoRoot, 'go.mod'))) tests = 'go-test';
+  if (await fileExists(join(repoRoot, 'Cargo.toml'))) tests = 'cargo-test';
+  if (await fileExists(join(repoRoot, 'pytest.ini'))) tests = 'pytest';
+  else if (await fileExists(join(repoRoot, 'pyproject.toml'))) {
+    try {
+      const py = await readFile(join(repoRoot, 'pyproject.toml'), 'utf8');
+      if (py.includes('pytest')) tests = 'pytest';
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // CSS approach.
+  let css = 'unknown';
+  if (pkgRaw) {
+    if (pkgRaw.includes('"tailwindcss"')) css = 'tailwind';
+    else if (pkgRaw.includes('"styled-components"')) css = 'styled-components';
+    else if (pkgRaw.includes('"@emotion/')) css = 'emotion';
+    else if (pkgRaw.includes('"@vanilla-extract/')) css = 'vanilla-extract';
+    else if (
+      (await fileExists(join(repoRoot, 'postcss.config.js'))) ||
+      (await fileExists(join(repoRoot, 'postcss.config.cjs')))
+    )
+      css = 'css-modules';
+  }
+
+  // Router — framework-dependent.
+  let router = 'unknown';
+  switch (framework) {
+    case 'next.js': {
+      const appAtRoot =
+        (await fileExists(join(repoRoot, 'app'))) || (await fileExists(join(repoRoot, 'src/app')));
+      if (appAtRoot) {
+        router = 'next-app';
+      } else {
+        // Workspace pass — first member with an `app/` or `src/app/` wins.
+        for (const wd of ws) {
+          if (
+            // eslint-disable-next-line no-await-in-loop
+            (await fileExists(join(wd, 'app'))) ||
+            // eslint-disable-next-line no-await-in-loop
+            (await fileExists(join(wd, 'src/app')))
+          ) {
+            router = 'next-app';
+            break;
+          }
+        }
+        if (router === 'unknown') router = 'next-pages';
+      }
+      break;
+    }
+    case 'remix':
+      router = 'react-router';
+      break;
+    case 'sveltekit':
+      router = 'sveltekit-router';
+      break;
+    case 'expo':
+      router = 'expo-router';
+      break;
+    default:
+      if (pkgRaw?.includes('"@tanstack/router')) router = 'tanstack-router';
+      else if (pkgRaw?.includes('"react-router')) router = 'react-router';
+  }
+
+  // _ avoids unused-warning for `pkg` (kept around in case future detectors
+  // need parsed access).
+  void pkg;
+
+  return {
+    language,
+    framework,
+    packageManager,
+    buildTool,
+    monorepo,
+    ci,
+    tests,
+    css,
+    router,
+  };
+}
+
+// ─── Quality-gate detection ────────────────────────────────────────────────
+//
+// detectQualityGates(repoRoot) → { lint, format, typecheck, tests, build } | null
+//
+// Strategy: prefer the user's declared `scripts.<name>` (they know how their
+// project is wired) over inferring from tool presence. Only fall back to tool
+// presence when no script is declared. Always emits the package-manager
+// prefix so the command can be eval'd directly.
+
+function pmPrefix(packageManager) {
+  if (packageManager === 'pnpm') return 'pnpm';
+  if (packageManager === 'yarn') return 'yarn';
+  if (packageManager === 'bun') return 'bun';
+  return 'npm run'; // default — works for npm and unknown package managers
+}
+
+export async function detectQualityGates(repoRoot) {
+  const { parsed: pkg } = await readPkgJson(repoRoot);
+  if (!pkg) return null;
+  const scripts = pkg.scripts || {};
+
+  // Pick the package manager from lockfile (same logic as detectStack but
+  // standalone — this function is composable and may be called separately).
+  let pm = 'npm';
+  if (await fileExists(join(repoRoot, 'pnpm-lock.yaml'))) pm = 'pnpm';
+  else if (await fileExists(join(repoRoot, 'yarn.lock'))) pm = 'yarn';
+  else if (await fileExists(join(repoRoot, 'bun.lockb'))) pm = 'bun';
+  const prefix = pmPrefix(pm);
+
+  const out = {};
+
+  // lint.
+  if (scripts.lint) out.lint = `${prefix} lint`;
+  else if (
+    (await fileExists(join(repoRoot, 'biome.json'))) ||
+    (await fileExists(join(repoRoot, 'biome.jsonc')))
+  )
+    out.lint = `${prefix === 'npm run' ? 'npx' : prefix} biome check .`;
+  else if (
+    (await fileExists(join(repoRoot, 'eslint.config.js'))) ||
+    (await fileExists(join(repoRoot, 'eslint.config.mjs'))) ||
+    (await fileExists(join(repoRoot, '.eslintrc.cjs'))) ||
+    (await fileExists(join(repoRoot, '.eslintrc.js'))) ||
+    (await fileExists(join(repoRoot, '.eslintrc.json')))
+  )
+    out.lint = `${prefix === 'npm run' ? 'npx' : prefix} eslint .`;
+
+  // format.
+  if (scripts.format) out.format = `${prefix} format`;
+  else if (
+    (await fileExists(join(repoRoot, 'biome.json'))) ||
+    (await fileExists(join(repoRoot, 'biome.jsonc')))
+  )
+    out.format = `${prefix === 'npm run' ? 'npx' : prefix} biome format --write .`;
+  else if (
+    (await fileExists(join(repoRoot, '.prettierrc'))) ||
+    (await fileExists(join(repoRoot, '.prettierrc.json'))) ||
+    (await fileExists(join(repoRoot, '.prettierrc.js'))) ||
+    (await fileExists(join(repoRoot, 'prettier.config.js'))) ||
+    (await fileExists(join(repoRoot, 'prettier.config.mjs')))
+  )
+    out.format = `${prefix === 'npm run' ? 'npx' : prefix} prettier --write .`;
+
+  // typecheck.
+  if (scripts.typecheck) out.typecheck = `${prefix} typecheck`;
+  else if (await fileExists(join(repoRoot, 'tsconfig.json')))
+    out.typecheck = `${prefix === 'npm run' ? 'npx' : prefix === 'pnpm' ? 'pnpm exec' : prefix} tsc --noEmit`;
+
+  // tests.
+  if (scripts.test) out.tests = `${prefix} test`;
+
+  // build.
+  if (scripts.build) out.build = `${prefix} build`;
+
+  if (Object.keys(out).length === 0) return null;
+  return out;
+}

package/cli/lib/stack-detect.test.mjs

@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { detectQualityGates, detectStack } from './stack-detect.mjs';
+
+function fresh() {
+  return mkdtempSync(join(tmpdir(), 'stackdetect-'));
+}
+function file(root, rel, content = '') {
+  const path = join(root, rel);
+  const parts = rel.split('/');
+  if (parts.length > 1) mkdirSync(join(root, parts.slice(0, -1).join('/')), { recursive: true });
+  writeFileSync(path, content);
+}
+
+test('empty repo — all unknown, quality null', async () => {
+  const root = fresh();
+  const stack = await detectStack(root);
+  assert.equal(stack.language, 'unknown');
+  assert.equal(stack.framework, 'unknown');
+  assert.equal(stack.packageManager, 'unknown');
+  assert.equal(stack.monorepo, false);
+  assert.equal(await detectQualityGates(root), null);
+});
+
+test('Next.js + biome + tsconfig — language=ts, framework=next.js, router=next-app, quality has lint/format/typecheck', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'x', scripts: { build: 'next build' } }));
+  file(root, 'pnpm-lock.yaml');
+  file(root, 'tsconfig.json', '{}');
+  file(root, 'next.config.mjs');
+  file(root, 'biome.json', '{}');
+  file(root, 'app/page.tsx');
+
+  const stack = await detectStack(root);
+  assert.equal(stack.language, 'typescript');
+  assert.equal(stack.framework, 'next.js');
+  assert.equal(stack.router, 'next-app');
+  assert.equal(stack.packageManager, 'pnpm');
+
+  const q = await detectQualityGates(root);
+  assert.equal(q.lint, 'pnpm biome check .');
+  assert.equal(q.format, 'pnpm biome format --write .');
+  assert.equal(q.typecheck, 'pnpm exec tsc --noEmit');
+  assert.equal(q.build, 'pnpm build');
+  assert.equal(q.tests, undefined);
+});
+
+test('Expo + prettier — framework=expo, router=expo-router, format=prettier', async () => {
+  const root = fresh();
+  file(
+    root,
+    'package.json',
+    JSON.stringify({ name: 'x', scripts: { test: 'jest' }, devDependencies: { jest: '*' } })
+  );
+  file(root, 'yarn.lock');
+  file(root, 'app.json', '{}');
+  file(root, '.prettierrc', '{}');
+
+  const stack = await detectStack(root);
+  assert.equal(stack.framework, 'expo');
+  assert.equal(stack.router, 'expo-router');
+  assert.equal(stack.packageManager, 'yarn');
+  assert.equal(stack.tests, 'jest');
+
+  const q = await detectQualityGates(root);
+  assert.equal(q.format, 'yarn prettier --write .');
+  assert.equal(q.tests, 'yarn test');
+});
+
+test('pnpm monorepo with workspace-only tsconfig — TS detected via deep scan', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'monorepo' }));
+  file(root, 'pnpm-workspace.yaml', '');
+  file(root, 'pnpm-lock.yaml');
+  file(root, 'packages/web/package.json', '{}');
+  file(root, 'packages/web/tsconfig.json', '{}');
+
+  const stack = await detectStack(root);
+  assert.equal(stack.language, 'typescript');
+  assert.equal(stack.monorepo, true);
+});
+
+test('package.json with only scripts.format — single quality gate emitted', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'x', scripts: { format: 'biome format .' } }));
+
+  const q = await detectQualityGates(root);
+  assert.deepEqual(q, { format: 'npm run format' });
+});
+
+test('npm (no lockfile signals) — pmPrefix falls back to `npm run` for scripts, `npx` for tool fallbacks', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'x' }));
+  file(root, 'tsconfig.json', '{}');
+
+  const q = await detectQualityGates(root);
+  // No scripts → tsconfig fallback should use npx tsc.
+  assert.equal(q.typecheck, 'npx tsc --noEmit');
+});
+
+test('vitest in devDependencies — tests=vitest via substring match', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'x', devDependencies: { vitest: '^2' } }));
+  file(root, 'package-lock.json');
+
+  const stack = await detectStack(root);
+  assert.equal(stack.tests, 'vitest');
+  assert.equal(stack.packageManager, 'npm');
+});
+
+test('CI detection — .github/workflows wins', async () => {
+  const root = fresh();
+  file(root, 'package.json', JSON.stringify({ name: 'x' }));
+  mkdirSync(join(root, '.github/workflows'), { recursive: true });
+
+  const stack = await detectStack(root);
+  assert.equal(stack.ci, 'github-actions');
+});