agent-harness-kit 0.3.0

package/src/core/detect-stack.mjs

@@ -0,0 +1,181 @@
+// detect-stack.mjs — auto-detect the user's stack from on-disk signals.
+// Priority order matters: monorepo signals > framework signals > language signals.
+
+import { readFile, access, readdir } from "node:fs/promises";
+import { resolve, basename } from "node:path";
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonSafe(p) {
+  try {
+    const raw = await readFile(p, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function readTextSafe(p) {
+  try {
+    return await readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function detectStack(cwd) {
+  const result = {
+    language: "generic",
+    framework: null,
+    packageManager: "npm",
+    monorepo: false,
+    polyglotSignals: [], // list of detected language signals on a polyglot monorepo
+    appCandidates: [],   // discovered subdirectories that look like individual apps
+    suggestedName: basename(cwd),
+    suggestedPreset: "generic",
+    availablePresets: ["generic"],
+  };
+
+  // Monorepo signals.
+  if (await exists(resolve(cwd, "pnpm-workspace.yaml"))) {
+    result.packageManager = "pnpm";
+    result.monorepo = true;
+  }
+  if (await exists(resolve(cwd, "turbo.json"))) {
+    result.monorepo = true;
+  }
+  if (await exists(resolve(cwd, "lerna.json"))) {
+    result.monorepo = true;
+  }
+  if (await exists(resolve(cwd, "yarn.lock"))) {
+    result.packageManager = "yarn";
+  } else if (await exists(resolve(cwd, "pnpm-lock.yaml"))) {
+    result.packageManager = "pnpm";
+  } else if (await exists(resolve(cwd, "bun.lockb"))) {
+    result.packageManager = "bun";
+  } else if (await exists(resolve(cwd, "package-lock.json"))) {
+    result.packageManager = "npm";
+  }
+
+  // Polyglot probe — only relevant when no root package.json picks a clear
+  // primary language. Walks 1 level deep into common monorepo dirs.
+  await probePolyglot(cwd, result);
+
+  // JavaScript/TypeScript.
+  const pkg = await readJsonSafe(resolve(cwd, "package.json"));
+  if (pkg) {
+    result.language = "typescript";
+    if (pkg.name) result.suggestedName = pkg.name.replace(/^@[^/]+\//, "");
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    if (deps.next) {
+      result.framework = "nextjs";
+      result.suggestedPreset = "nextjs";
+      result.availablePresets = ["nextjs", "generic"];
+    } else if (deps["@nestjs/core"]) {
+      result.framework = "nestjs";
+      result.suggestedPreset = "node-api";
+      result.availablePresets = ["node-api", "generic"];
+    } else if (deps.fastify) {
+      result.framework = "fastify";
+      result.suggestedPreset = "node-api";
+      result.availablePresets = ["node-api", "generic"];
+    } else if (deps.express) {
+      result.framework = "express";
+      result.suggestedPreset = "node-api";
+      result.availablePresets = ["node-api", "generic"];
+    } else {
+      result.framework = "node";
+      result.suggestedPreset = "generic";
+      result.availablePresets = ["generic"];
+    }
+    return result;
+  }
+
+  // Python.
+  const pyproject = await readTextSafe(resolve(cwd, "pyproject.toml"));
+  if (pyproject) {
+    result.language = "python";
+    result.packageManager = "pip";
+    const nameMatch = pyproject.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+    if (nameMatch) result.suggestedName = nameMatch[1];
+    if (/fastapi/i.test(pyproject)) {
+      result.framework = "fastapi";
+      result.suggestedPreset = "fastapi";
+      result.availablePresets = ["fastapi", "generic"];
+    } else if (/django/i.test(pyproject)) {
+      result.framework = "django";
+      result.suggestedPreset = "django";
+      result.availablePresets = ["django", "generic"];
+    } else if (/flask/i.test(pyproject)) {
+      result.framework = "flask";
+      result.suggestedPreset = "flask";
+      result.availablePresets = ["flask", "generic"];
+    } else {
+      result.framework = "python";
+      result.suggestedPreset = "generic";
+    }
+    return result;
+  }
+  if (await exists(resolve(cwd, "requirements.txt"))) {
+    result.language = "python";
+    result.packageManager = "pip";
+    return result;
+  }
+
+  // Go / Rust — core only, no preset.
+  if (await exists(resolve(cwd, "go.mod"))) {
+    result.language = "go";
+    result.packageManager = "go";
+    return result;
+  }
+  if (await exists(resolve(cwd, "Cargo.toml"))) {
+    result.language = "rust";
+    result.packageManager = "cargo";
+    return result;
+  }
+
+  return result;
+}
+
+// Walk apps/ packages/ services/ and one extra level looking for nested
+// language signals. Used to flag polyglot monorepos and recommend per-app
+// init instead of root init.
+async function probePolyglot(cwd, result) {
+  const candidates = ["apps", "packages", "services", "ios", "android", "web", "api"];
+  const signals = new Set();
+  for (const sub of candidates) {
+    const subAbs = resolve(cwd, sub);
+    if (!(await exists(subAbs))) continue;
+    let entries;
+    try {
+      entries = await readdir(subAbs, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const appAbs = resolve(subAbs, e.name);
+      const sigs = [];
+      if (await exists(resolve(appAbs, "package.json"))) sigs.push("typescript");
+      if (await exists(resolve(appAbs, "pyproject.toml"))) sigs.push("python");
+      if (await exists(resolve(appAbs, "go.mod"))) sigs.push("go");
+      if (await exists(resolve(appAbs, "Cargo.toml"))) sigs.push("rust");
+      if (await exists(resolve(appAbs, "Package.swift"))) sigs.push("swift");
+      if (await exists(resolve(appAbs, "build.gradle.kts"))) sigs.push("kotlin");
+      if (sigs.length === 0) continue;
+      result.appCandidates.push({ path: `${sub}/${e.name}`, languages: sigs });
+      for (const s of sigs) signals.add(s);
+    }
+  }
+  result.polyglotSignals = [...signals];
+  if (signals.size >= 2) {
+    result.monorepo = true;
+  }
+}

package/src/core/doctor.mjs

@@ -0,0 +1,106 @@
+// doctor.mjs — diagnose installed kit + Claude Code environment.
+// Prints a checklist; non-zero exit means at least one CRITICAL check failed.
+
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { execSync } from "node:child_process";
+import pc from "picocolors";
+
+function check(name, ok, info = "") {
+  const mark = ok ? pc.green("✓") : pc.red("✗");
+  console.log(`  ${mark} ${name}${info ? pc.dim(" — " + info) : ""}`);
+  return ok;
+}
+
+function which(cmd) {
+  try {
+    const r = execSync(`command -v ${cmd}`, { stdio: ["ignore", "pipe", "ignore"] })
+      .toString()
+      .trim();
+    return r || null;
+  } catch {
+    return null;
+  }
+}
+
+export async function doctor({ cwd, kitVersion }) {
+  console.log(pc.bold(`\nagent-harness-kit doctor (v${kitVersion})\n`));
+  let allOk = true;
+
+  // 1. Lockfile
+  const lockPath = resolve(cwd, ".harness/installed.json");
+  const hasLock = existsSync(lockPath);
+  allOk = check("kit installed (.harness/installed.json present)", hasLock) && allOk;
+  if (hasLock) {
+    const lock = JSON.parse(await readFile(lockPath, "utf8"));
+    check(`installed version`, true, `v${lock.version}`);
+    if (lock.version !== kitVersion) {
+      console.log(
+        pc.yellow(`    ↳ kit CLI is v${kitVersion}; run \`agent-harness-kit upgrade\` to sync.`),
+      );
+    }
+    // Cross-check: harness.config.json carries its own version field that
+    // upgrade is supposed to keep in step. Catch the drift so users notice
+    // before it bites them in CI.
+    const cfgPath = resolve(cwd, "harness.config.json");
+    if (existsSync(cfgPath)) {
+      try {
+        const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+        if (cfg.version && cfg.version !== lock.version) {
+          allOk = false;
+          console.log(
+            pc.red(
+              `  ✗ harness.config.json version drift — config says v${cfg.version}, lockfile says v${lock.version} (run \`agent-harness-kit upgrade\` to sync).`,
+            ),
+          );
+        }
+      } catch {
+        // ignored — invalid JSON is caught by the must-files check below
+      }
+    }
+  }
+
+  // 2. Core files (required for any install).
+  const must = [
+    "CLAUDE.md",
+    "harness.config.json",
+    ".claude/skills/inspect-module/SKILL.md",
+    ".claude/agents/architecture-reviewer.md",
+    "scripts/structural-test-on-edit.sh",
+    "scripts/precompletion-checklist.sh",
+  ];
+  for (const f of must) {
+    allOk = check(f, existsSync(resolve(cwd, f))) && allOk;
+  }
+  // Optional: hooks.json — present if `init` was run without --no-hooks.
+  const hasHooks = existsSync(resolve(cwd, ".claude/hooks/hooks.json"));
+  console.log(
+    `  ${hasHooks ? pc.green("✓") : pc.yellow("•")} .claude/hooks/hooks.json` +
+      (hasHooks ? "" : pc.dim(" — not installed (PostToolUse + Stop hooks disabled)")),
+  );
+
+  // 3. Tooling.
+  console.log(pc.bold("\nTooling:"));
+  const node = which("node");
+  check("node", !!node, node ?? "not installed");
+  check("git", !!which("git"), which("git") ?? "not installed");
+  check("jq (optional, used by hooks)", !!which("jq"), which("jq") ?? "not installed — hooks will exit 0 without blocking");
+  check("claude (Claude Code CLI)", !!which("claude"), which("claude") ?? "install via `npm i -g @anthropic-ai/claude-code`");
+
+  // 4. Adapter health.
+  if (existsSync(resolve(cwd, "harness.config.json"))) {
+    const cfg = JSON.parse(await readFile(resolve(cwd, "harness.config.json"), "utf8"));
+    if (cfg.language === "typescript") {
+      check("ts-morph available", existsSync(resolve(cwd, "node_modules/ts-morph")), "run `npm install`");
+    } else if (cfg.language === "python") {
+      // libcst is harder to detect generically — just print a hint.
+      check("libcst (python adapter)", true, "verify with `python -c 'import libcst'`");
+    }
+  }
+
+  console.log("");
+  if (!allOk) {
+    process.exit(1);
+  }
+}

package/src/core/patch-package-json.mjs

@@ -0,0 +1,53 @@
+// patch-package-json.mjs — non-destructively add npm scripts + devDependencies
+// to an existing package.json. Called from the TypeScript adapter path of
+// renderAll(). If package.json doesn't exist, this is a no-op.
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const NEEDED_SCRIPTS = {
+  "harness:check": "node harness/structural-test.mjs",
+  "harness:gc": "echo 'run /garbage-collection in Claude Code'",
+  "harness:eval": "node harness/eval-runner.mjs",
+  "harness:report": "node scripts/harness-report.mjs",
+};
+
+const NEEDED_DEV_DEPS = {
+  "ts-morph": "^25.0.0",
+  "eslint-plugin-boundaries": "^5.0.0",
+  "dependency-cruiser": "^16.0.0",
+};
+
+export async function patchPackageJson(cwd) {
+  const path = resolve(cwd, "package.json");
+  if (!existsSync(path)) return { patched: false };
+  const raw = await readFile(path, "utf8");
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (err) {
+    return { patched: false, error: "package.json is not valid JSON" };
+  }
+  pkg.scripts = pkg.scripts ?? {};
+  pkg.devDependencies = pkg.devDependencies ?? {};
+  let changed = false;
+  for (const [k, v] of Object.entries(NEEDED_SCRIPTS)) {
+    if (pkg.scripts[k] === undefined) {
+      pkg.scripts[k] = v;
+      changed = true;
+    }
+  }
+  for (const [k, v] of Object.entries(NEEDED_DEV_DEPS)) {
+    if (pkg.devDependencies[k] === undefined && (pkg.dependencies?.[k] === undefined)) {
+      pkg.devDependencies[k] = v;
+      changed = true;
+    }
+  }
+  if (changed) {
+    // Preserve trailing newline.
+    const trailing = raw.endsWith("\n") ? "\n" : "";
+    await writeFile(path, JSON.stringify(pkg, null, 2) + trailing);
+  }
+  return { patched: changed };
+}

package/src/core/render-templates.mjs

@@ -0,0 +1,277 @@
+// render-templates.mjs — copy + Handlebars-render the template tree into the user's repo.
+//
+// Strategy:
+//   - Walk src/templates recursively.
+//   - For files ending in `.hbs`, render via Handlebars (strip the .hbs suffix).
+//   - For everything else, copy verbatim.
+//   - Files that already exist in the target are skipped (we never clobber user
+//     content). Use `agent-harness-kit upgrade` for the version-aware merge flow.
+//   - After the walk, write `.harness/installed.json` (kit lockfile) with sha256
+//     of every kit-written file.
+
+import { readFile, writeFile, mkdir, readdir, stat, chmod } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join, relative, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import Handlebars from "handlebars";
+import { patchPackageJson } from "./patch-package-json.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_ROOT = resolve(__dirname, "..", "templates");
+
+// Files that the user is expected to edit — they win every time, even on
+// fresh init we won't overwrite if they exist. This list is hard-coded
+// because it's tiny and security-sensitive.
+const USER_OWNED_FILES = new Set([
+  "CLAUDE.md",
+  "AGENTS.md",
+  "docs/architecture.md",
+  "docs/core-beliefs.md",
+  "docs/golden-principles.md",
+  "docs/tech-debt-tracker.md",
+  "feature_list.json",
+  "harness.config.json",
+]);
+
+// Paths that should be made executable after rendering.
+const EXEC_BITS = new Set([
+  "scripts/dev-up.sh",
+  "scripts/pre-push.sh",
+  "scripts/install-git-hooks.sh",
+  "scripts/structural-test-on-edit.sh",
+  "scripts/precompletion-checklist.sh",
+  "scripts/telemetry-on-skill.sh",
+  "scripts/harness-report.mjs",
+]);
+
+export function registerHelpers() {
+  Handlebars.registerHelper("kebabCase", (s) =>
+    String(s ?? "")
+      .replace(/[_\s]+/g, "-")
+      .replace(/([a-z])([A-Z])/g, "$1-$2")
+      .toLowerCase(),
+  );
+  Handlebars.registerHelper("pascalCase", (s) =>
+    String(s ?? "")
+      .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+      .replace(/^./, (c) => c.toUpperCase()),
+  );
+  Handlebars.registerHelper("now", (fmt) => {
+    const d = new Date();
+    if (fmt === "yyyy-MM-dd") {
+      return d.toISOString().slice(0, 10);
+    }
+    return d.toISOString();
+  });
+  Handlebars.registerHelper("eq", (a, b) => a === b);
+  Handlebars.registerHelper("includes", (arr, v) =>
+    Array.isArray(arr) && arr.includes(v),
+  );
+  Handlebars.registerHelper("layerJoin", (layers) =>
+    Array.isArray(layers) ? layers.join(" → ") : "",
+  );
+  Handlebars.registerHelper("upper", (s) => String(s ?? "").toUpperCase());
+}
+
+async function* walk(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walk(full);
+    } else {
+      yield full;
+    }
+  }
+}
+
+function buildContext({ projectName, preset, layers, stack, kitVersion }) {
+  const installCmd =
+    stack.language === "python"
+      ? "pip install -e '.[dev]'"
+      : stack.packageManager === "pnpm"
+        ? "pnpm install"
+        : stack.packageManager === "yarn"
+          ? "yarn"
+          : stack.packageManager === "bun"
+            ? "bun install"
+            : "npm install";
+  const devCmd = (() => {
+    switch (stack.framework) {
+      case "nextjs":  return "npm run dev";
+      case "express": return "node ./src/server.js";
+      case "fastify": return "node ./src/server.js";
+      case "nestjs":  return "npm run start:dev";
+      case "fastapi": return "uvicorn app.main:app --reload";
+      case "django":  return "python manage.py runserver";
+      case "flask":   return "flask --app app run --debug";
+      default:
+        return stack.language === "python" ? "python -m app" : "npm run dev";
+    }
+  })();
+  const testCmd = (() => {
+    switch (stack.framework) {
+      case "django": return "python manage.py test";
+      default:
+        return stack.language === "python" ? "pytest -x" : "npm test";
+    }
+  })();
+  const lintCmd =
+    stack.language === "python" ? "ruff check ." : "npm run lint";
+
+  return {
+    projectName,
+    description: `${projectName} — solo-dev project on the agent-harness-kit harness.`,
+    language: stack.language,
+    framework: stack.framework ?? stack.language,
+    packageManager: stack.packageManager,
+    preset,
+    layers,
+    layersJoined: layers.join(" → "),
+    providers: ["auth", "telemetry", "feature-flags"],
+    installCmd,
+    devCmd,
+    testCmd,
+    lintCmd,
+    kitVersion,
+    isTypescript: stack.language === "typescript",
+    isPython: stack.language === "python",
+    isNextjs: stack.framework === "nextjs",
+    isFastapi: stack.framework === "fastapi",
+    isExpress: stack.framework === "express",
+    isFastify: stack.framework === "fastify",
+    isNestjs: stack.framework === "nestjs",
+    isDjango: stack.framework === "django",
+    isFlask: stack.framework === "flask",
+  };
+}
+
+// Decide whether a template path should be rendered for this stack/preset.
+// Adapter-specific files live under templates/_adapter-<id>/ and are merged
+// into the root.
+function pathForStack(rel, stack) {
+  if (rel.startsWith("_adapter-typescript/")) {
+    return stack.language === "typescript" ? rel.slice("_adapter-typescript/".length) : null;
+  }
+  if (rel.startsWith("_adapter-python/")) {
+    return stack.language === "python" ? rel.slice("_adapter-python/".length) : null;
+  }
+  if (rel.startsWith("_preset-nextjs/")) {
+    return stack.framework === "nextjs" ? rel.slice("_preset-nextjs/".length) : null;
+  }
+  if (rel.startsWith("_preset-fastapi/")) {
+    return stack.framework === "fastapi" ? rel.slice("_preset-fastapi/".length) : null;
+  }
+  if (rel.startsWith("_ci/")) {
+    return rel.slice("_ci/".length); // handled separately by installCi flag
+  }
+  return rel;
+}
+
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+export async function renderAll({
+  cwd,
+  projectName,
+  preset,
+  layers,
+  stack,
+  installHooks,
+  installCi,
+  kitVersion,
+}) {
+  registerHelpers();
+  const ctx = buildContext({ projectName, preset, layers, stack, kitVersion });
+
+  const written = [];
+  const skipped = [];
+  const lockfile = { version: kitVersion, files: {} };
+
+  for await (const abs of walk(TEMPLATES_ROOT)) {
+    const relFromTemplates = relative(TEMPLATES_ROOT, abs).split("\\").join("/");
+    const stackRel = pathForStack(relFromTemplates, stack);
+    if (stackRel === null) continue;
+    if (relFromTemplates.startsWith("_ci/") && !installCi) continue;
+    if (relFromTemplates.includes("hooks.json") && !installHooks) continue;
+
+    const targetRel = stackRel.endsWith(".hbs")
+      ? stackRel.slice(0, -".hbs".length)
+      : stackRel;
+    const targetAbs = resolve(cwd, targetRel);
+
+    if (USER_OWNED_FILES.has(targetRel) && existsSync(targetAbs)) {
+      skipped.push(targetRel);
+      continue;
+    }
+
+    let content;
+    if (abs.endsWith(".hbs")) {
+      const raw = await readFile(abs, "utf8");
+      const tpl = Handlebars.compile(raw, { noEscape: true });
+      content = tpl(ctx);
+    } else {
+      content = await readFile(abs);
+    }
+
+    await mkdir(dirname(targetAbs), { recursive: true });
+    await writeFile(targetAbs, content);
+    if (EXEC_BITS.has(targetRel)) {
+      try {
+        await chmod(targetAbs, 0o755);
+      } catch {
+        // ignore on platforms where chmod is a no-op
+      }
+    }
+    lockfile.files[targetRel] = sha256(
+      typeof content === "string" ? Buffer.from(content) : content,
+    );
+    written.push(targetRel);
+  }
+
+  // Write the lockfile last (after we know the full set of files).
+  const lockTarget = resolve(cwd, ".harness/installed.json");
+  await mkdir(dirname(lockTarget), { recursive: true });
+  await writeFile(lockTarget, JSON.stringify(lockfile, null, 2) + "\n");
+  written.push(".harness/installed.json");
+
+  // Try to symlink AGENTS.md → CLAUDE.md if not already present.
+  // On platforms without symlink support this silently falls back to a copy.
+  const agentsMd = resolve(cwd, "AGENTS.md");
+  if (!existsSync(agentsMd) && existsSync(resolve(cwd, "CLAUDE.md"))) {
+    const claudeBody = await readFile(resolve(cwd, "CLAUDE.md"), "utf8");
+    await writeFile(agentsMd, claudeBody);
+    written.push("AGENTS.md");
+  }
+
+  // Empty PROGRESS.md placeholder — the user / agent appends to this every session.
+  const progress = resolve(cwd, ".harness/PROGRESS.md");
+  if (!existsSync(progress)) {
+    await writeFile(
+      progress,
+      "# Session progress\n\n" +
+        "_Append a one-line entry per completed feature. Format: `YYYY-MM-DD HH:MM | <feature_id> | done`._\n",
+    );
+    written.push(".harness/PROGRESS.md");
+  }
+
+  // Empty structural baseline — populated on first `harness:check` run.
+  // Note: we only write the file if it doesn't exist; first run of
+  // `harness:check` writes the actual baseline of existing violations.
+  const baseline = resolve(cwd, ".harness/structural-baseline.json");
+  if (!existsSync(baseline)) {
+    await writeFile(baseline, "[]\n");
+    written.push(".harness/structural-baseline.json");
+  }
+
+  // For TypeScript stacks, non-destructively patch package.json with the
+  // harness:* npm scripts and the peer-dep dev dependencies.
+  if (stack.language === "typescript") {
+    const patch = await patchPackageJson(cwd);
+    if (patch.patched) written.push("package.json (scripts + devDependencies)");
+  }
+
+  return { written, skipped };
+}