activate-agentmd 2.4.0

package/src/commands/extract.js

@@ -0,0 +1,254 @@
+/**
+ * extract.js
+ *
+ * `agentmd extract` — reverse-engineer the conventions this repository
+ * already follows (but nobody wrote down) into a local standard that `link`
+ * ships to the agent like any registry package.
+ *
+ *   agentmd extract                 write .agentmd/presets/local-Team-conventions.md
+ *   agentmd extract --dry           print the standard, write nothing
+ *   agentmd extract --force         overwrite an existing extracted standard
+ *   agentmd extract --name style    call the package Team/style instead
+ *
+ * Needs ANTHROPIC_API_KEY (or an `ant auth login` profile). Only the evidence
+ * sample described below leaves the machine.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const pc = require("picocolors");
+const {
+  readManifest,
+  writeManifest,
+  upsertPreset,
+  findPreset,
+  ensurePresetsDir,
+  resolvePresetPath,
+  presetFilename,
+  checksum,
+  PRESETS_DIR,
+} = require("../lib/manifest");
+const { cmd } = require("../lib/invocation");
+
+const A = cmd();
+const MODEL = process.env.AGENTMD_REVIEW_MODEL || "claude-opus-5";
+
+// Evidence budget. ~120k chars ≈ 30k tokens: enough to see real patterns,
+// small enough that one call stays cheap and never hits max_tokens.
+const BUDGET = 120_000;
+const FILE_CAP = 6_000;
+const CONFIG_CAP = 4_000;
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".venv", "venv", "target", "coverage", "__pycache__", ".turbo", ".cache", "out", "vendor"]);
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift|vue|svelte|sql|prisma)$/;
+const TEST_HINT = /(\.test\.|\.spec\.|_test\.|\/tests?\/|\/__tests__\/|conftest\.py)/;
+const CONFIG_GLOBS = [
+  "package.json", "tsconfig.json", "biome.json", "pyproject.toml", "ruff.toml", "go.mod",
+  ".editorconfig", "Makefile", "Dockerfile", ".prettierrc", ".prettierrc.json", ".prettierrc.js",
+  ".eslintrc", ".eslintrc.json", ".eslintrc.js", ".eslintrc.cjs", "eslint.config.js", "eslint.config.mjs", "eslint.config.ts",
+];
+
+function flagValue(args, name) {
+  const withEq = args.find((a) => a.startsWith(`--${name}=`));
+  if (withEq) return withEq.slice(name.length + 3);
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+}
+
+function git(cwd, ...argv) {
+  try {
+    return execFileSync("git", argv, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 16 * 1024 * 1024 });
+  } catch {
+    return null; // not a git repo, or git missing — evidence is just thinner
+  }
+}
+
+/** Directory tree, dirs only, two levels deep. */
+function tree(cwd) {
+  const lines = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries.filter((e) => e.isDirectory() && !SKIP_DIRS.has(e.name) && !e.name.startsWith(".")).sort((a, b) => a.name.localeCompare(b.name))) {
+      lines.push("  ".repeat(depth) + e.name + "/");
+      if (depth < 1) walk(path.join(dir, e.name), depth + 1);
+    }
+  };
+  walk(cwd, 0);
+  return lines.join("\n");
+}
+
+/** Every source file under cwd (bounded walk), with size. */
+function sourceFiles(cwd) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6 || out.length > 5000) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) walk(path.join(dir, e.name), depth + 1); continue; }
+      if (!SOURCE_EXT.test(e.name)) continue;
+      const full = path.join(dir, e.name);
+      let size = 0;
+      try { size = fs.statSync(full).size; } catch { continue; }
+      out.push({ rel: path.relative(cwd, full).split(path.sep).join("/"), size });
+    }
+  };
+  walk(cwd, 0);
+  return out;
+}
+
+function readCapped(cwd, rel, cap) {
+  try { return fs.readFileSync(path.join(cwd, rel), "utf-8").slice(0, cap); } catch { return null; }
+}
+
+/** Collect the evidence sample. Returns { text, omitted } . */
+function gather(cwd) {
+  const parts = [];
+  const omitted = [];
+  let used = 0;
+  const add = (label, body) => {
+    if (!body) return false;
+    const chunk = `<${label}>\n${body}\n</${label}>\n`;
+    if (used + chunk.length > BUDGET) { omitted.push(label); return false; }
+    parts.push(chunk); used += chunk.length; return true;
+  };
+
+  add("tree", tree(cwd));
+
+  for (const name of CONFIG_GLOBS) {
+    const body = readCapped(cwd, name, CONFIG_CAP);
+    if (!body) continue;
+    if (name === "package.json") {
+      // Scripts and dependency names carry the conventions; the rest is noise.
+      try { const p = JSON.parse(fs.readFileSync(path.join(cwd, name), "utf-8")); add(`config file="${name}"`, JSON.stringify({ scripts: p.scripts, dependencies: Object.keys(p.dependencies || {}), devDependencies: Object.keys(p.devDependencies || {}) }, null, 1)); continue; } catch {}
+    }
+    add(`config file="${name}"`, body);
+  }
+  try {
+    const wf = fs.readdirSync(path.join(cwd, ".github", "workflows")).filter((f) => /\.ya?ml$/.test(f));
+    if (wf.length) add("workflows", wf.join("\n"));
+  } catch {}
+
+  const subjects = git(cwd, "log", "--format=%s", "-n", "50");
+  if (subjects) add("recent-commits", subjects.trim());
+
+  const all = sourceFiles(cwd);
+  const tests = all.filter((f) => TEST_HINT.test("/" + f.rel));
+  const src = all.filter((f) => !TEST_HINT.test("/" + f.rel));
+  const largest = src.slice().sort((a, b) => b.size - a.size).slice(0, 6).map((f) => f.rel);
+  const recentRaw = git(cwd, "log", "--name-only", "--format=", "-n", "30") || "";
+  const srcSet = new Set(src.map((f) => f.rel));
+  const recent = [...new Set(recentRaw.split("\n").map((s) => s.trim()).filter((s) => srcSet.has(s)))].slice(0, 6);
+  const picked = [...new Set([...largest, ...recent])].slice(0, 12);
+  for (const rel of picked) add(`file path="${rel}"`, readCapped(cwd, rel, FILE_CAP));
+  for (const f of tests.slice().sort((a, b) => b.size - a.size).slice(0, 4)) add(`test path="${f.rel}"`, readCapped(cwd, f.rel, FILE_CAP));
+
+  return { text: parts.join("\n"), omitted, files: picked.length + Math.min(4, tests.length), chars: used };
+}
+
+function repoName(cwd) {
+  const remote = git(cwd, "remote", "get-url", "origin");
+  const m = remote && /([^/:]+?)(?:\.git)?\s*$/.exec(remote);
+  return (m && m[1]) || path.basename(cwd);
+}
+
+async function extract(args) {
+  args = args || [];
+  const cwd = process.cwd();
+  const dry = args.includes("--dry");
+  const force = args.includes("--force");
+  const name = (flagValue(args, "name") || "conventions").toLowerCase().replace(/[^a-z0-9.-]+/g, "-").replace(/^-+|-+$/g, "") || "conventions";
+  const id = `local/Team/${name}`;
+  const filename = presetFilename("local", "Team", name);
+
+  const manifest = readManifest(cwd);
+  if (!dry && !force && findPreset(manifest, id)) {
+    console.error(pc.yellow(`\n${id} already exists (${PRESETS_DIR}/${filename}).`));
+    console.error(pc.dim(`  Re-extract over it with '${A} extract --force', or preview with '${A} extract --dry'.\n`));
+    process.exit(1);
+  }
+
+  const evidence = gather(cwd);
+  if (evidence.files === 0) {
+    console.error(pc.red("\nNo source files found here — nothing to extract conventions from.\n"));
+    process.exit(1);
+  }
+  console.log(pc.bold(`\nGathered evidence from ${pc.cyan(evidence.files)} file${evidence.files === 1 ? "" : "s"}`) + pc.dim(` (${Math.round(evidence.chars / 1000)}k chars, ${MODEL})`));
+  if (evidence.omitted.length) console.log(pc.yellow(`  Left out to fit the budget: ${evidence.omitted.length} item${evidence.omitted.length === 1 ? "" : "s"}`));
+
+  let Anthropic;
+  try { Anthropic = require("@anthropic-ai/sdk"); } catch {
+    console.error(pc.red("@anthropic-ai/sdk is not installed — reinstall activate-agentmd."));
+    process.exit(2);
+  }
+  const client = new Anthropic();
+  const today = new Date().toISOString().slice(0, 10);
+
+  const system = [
+    "You derive the unwritten, project-specific conventions a codebase actually follows, from a sample of its files, configs and commit history.",
+    "Cover, where the evidence supports it: export style, naming, folder structure, error handling, validation at boundaries, data access patterns, testing conventions, commit conventions, tooling.",
+    "Only state conventions with evidence in the sample. Each rule carries a one-line `evidence:` citation naming the file or config it comes from. Do not restate generic best practice. Do not invent.",
+    "Output one complete standard in this exact format and nothing else — no preamble, no fences around the whole document:",
+    `---\nname: ${name}\ncategory: Team\ndescription: <one sentence>\nlicense: MIT\nauthor: ${repoName(cwd)} (extracted by agentmd)\nlast-verified: ${today}\nreviewed-by: unreviewed\nversion: 1.0.0\n---`,
+    "Then `# Purpose` (what this codebase is and what these rules protect), then one `# <Topic>` section per convention group with short right/wrong code blocks written in the project's own style, then `# Anti-patterns` (a table: pattern | why it is wrong here | do this instead), then `# Checklist` (one `- [ ]` line per rule).",
+  ].join("\n");
+
+  let response;
+  try {
+    response = await client.beta.messages.create({
+      model: MODEL,
+      max_tokens: 16000,
+      betas: ["server-side-fallback-2026-07-01"],
+      fallbacks: "default",
+      system: [{ type: "text", text: system, cache_control: { type: "ephemeral" } }],
+      messages: [{ role: "user", content: evidence.text }],
+    });
+  } catch (e) {
+    if (e instanceof Anthropic.AuthenticationError || /authentication method|api ?key/i.test(e.message)) {
+      console.error(pc.red("No API credentials. Set ANTHROPIC_API_KEY (or run `ant auth login`) and try again."));
+    } else if (e instanceof Anthropic.RateLimitError) console.error(pc.red("Rate limited — retry in a moment."));
+    else console.error(pc.red(`Extract failed: ${e.message}`));
+    process.exit(2);
+  }
+
+  if (response.stop_reason === "refusal") {
+    console.error(pc.red("The model declined to process this repository" + (response.stop_details?.explanation ? `: ${response.stop_details.explanation}` : ".")));
+    process.exit(2);
+  }
+
+  let content = response.content.filter((b) => b.type === "text").map((b) => b.text).join("\n").trim();
+  // Tolerate a fenced reply; refuse anything that is not a standard.
+  content = content.replace(/^```(?:markdown|md)?\s*\n/, "").replace(/\n```\s*$/, "").trim() + "\n";
+  if (!content.startsWith("---") || !/^# Purpose/m.test(content)) {
+    console.error(pc.red("\nThe reply was not a standard in the expected format; nothing written. Raw output:\n"));
+    console.log(content);
+    process.exit(2);
+  }
+
+  const sections = (content.match(/^# (?!Purpose|Anti-patterns|Checklist)/gm) || []).length;
+
+  if (dry) {
+    console.log("");
+    console.log(content);
+    console.log(pc.dim(`--dry: ${sections} convention group${sections === 1 ? "" : "s"} found; nothing written. Run '${A} extract' to install it.\n`));
+    return;
+  }
+
+  ensurePresetsDir(cwd);
+  fs.writeFileSync(resolvePresetPath(cwd, filename), content, "utf-8");
+  upsertPreset(manifest, {
+    id, model: "local", category: "Team", preset: name, version: "1.0.0",
+    checksum: checksum(content), url: "local", file: `${PRESETS_DIR}/${filename}`,
+  });
+  writeManifest(cwd, manifest);
+
+  console.log("");
+  console.log(pc.green(`✓ ${sections} convention group${sections === 1 ? "" : "s"} extracted`) + pc.dim(`  → ${PRESETS_DIR}/${filename}`));
+  console.log(pc.dim(`  Recorded as ${id}. Review it like any other standard — it is your team's, edit freely.`));
+  console.log(pc.dim(`  Run '${A} link' to ship it to your agent.\n`));
+}
+
+module.exports = { extract };

package/src/commands/info.js

@@ -0,0 +1,105 @@
+/**
+ * info.js
+ *
+ * Handles: agentmd info <model/category/preset>
+ *
+ * The package detail view: what it is, how big it is, whether this project
+ * has it, and the command to install it.
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { getPreset, listModels } = require("../lib/registry");
+const { parseCoordinates, suggest } = require("../lib/coordinates");
+const { readManifest, findPreset } = require("../lib/manifest");
+const { TARGETS } = require("../lib/agents");
+const { cmd } = require("../lib/invocation");
+
+/** How the user invoked us — "npx activate-agentmd" or "agentmd". */
+const A = cmd();
+
+function humanBytes(n) {
+  return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
+}
+
+function row(label, value) {
+  console.log(`  ${pc.dim(label.padEnd(14))} ${value}`);
+}
+
+function info(args) {
+  const positional = (args || []).filter((a) => !a.startsWith("--"));
+  if (positional.length === 0) {
+    console.error(pc.red(`Usage: ${A} info <model/category/preset>`));
+    console.error(pc.dim(`  Example: ${A} info claude/Security/owasp`));
+    process.exit(1);
+  }
+
+  const coords = parseCoordinates(positional[0]);
+  if (!coords.model || !listModels().includes(coords.model)) {
+    console.error(pc.red(`Unknown model: "${coords.raw.split("/")[0] || coords.raw}"`));
+    console.error(pc.dim(`  Available: ${listModels().join(", ")}`));
+    process.exit(1);
+  }
+  if (!coords.category || !coords.preset) {
+    console.error(pc.red("info needs a full package path: <model>/<category>/<preset>"));
+    console.error(pc.dim(`  Example: ${A} info ${coords.model}/Security/owasp`));
+    process.exit(1);
+  }
+
+  const entry = getPreset(coords.model, coords.category, coords.preset);
+  if (!entry) {
+    console.error(pc.red(`Package not found: ${coords.model}/${coords.category}/${coords.preset}`));
+    const near = suggest(coords.model, coords.preset);
+    if (near.length) {
+      console.error(pc.dim("\n  Did you mean:"));
+      for (const n of near) console.error(pc.dim(`    ${A} info ${n.id}`));
+    }
+    console.error(pc.dim(`\n  Search:  ${A} search ${coords.preset}`));
+    process.exit(1);
+  }
+
+  const installed = findPreset(readManifest(process.cwd()), entry.id);
+
+  console.log("");
+  console.log(pc.bold(pc.cyan(entry.id)) + pc.dim(`  v${entry.version}`));
+  console.log("");
+  if (entry.description) {
+    console.log(`  ${entry.description}`);
+    console.log("");
+  }
+
+  row("Model", entry.model);
+  row("Category", entry.category);
+  row("Size", humanBytes(entry.bytes));
+  row("File", entry.file);
+  row("License", entry.license || "MIT");
+
+  // Provenance is printed even when empty. "not reviewed" is information; an
+  // omitted row would read as though the question had never been asked.
+  row("Author", entry.author || pc.yellow("unattributed"));
+  row(
+    "Reviewed",
+    entry.reviewedBy
+      ? pc.green(entry.reviewedBy) + (entry.lastVerified ? pc.dim(`  (${entry.lastVerified})`) : "")
+      : pc.yellow("not reviewed") + pc.dim("  — read it before trusting it")
+  );
+  row("Source", pc.dim(entry.url));
+  row("Agents", Object.values(TARGETS).map((t) => t.label.split(" (")[0]).join(", "));
+
+  console.log("");
+  if (installed) {
+    row("Installed", pc.green("yes") + pc.dim(`  ${installed.file}`));
+    row("", pc.dim(`v${installed.version || "?"} on ${new Date(installed.installedAt).toISOString().slice(0, 10)}`));
+    console.log("");
+    console.log(pc.dim(`  Check for changes:  ${A} outdated`));
+    console.log(pc.dim(`  Remove:             ${A} remove ` + entry.id));
+  } else {
+    row("Installed", pc.dim("no"));
+    console.log("");
+    console.log(pc.bold(`  ${A} install ` + entry.id));
+  }
+  console.log("");
+}
+
+module.exports = { info };

package/src/commands/init.js

@@ -0,0 +1,166 @@
+/**
+ * init.js
+ *
+ * Handles: agentmd init [--model=claude] [--yes] [--dry]
+ *
+ * Scans the project, reports what it found, and offers to install the
+ * packages that match. This is the intended first command — it exists so a
+ * developer never has to read the registry to get a useful first install.
+ */
+
+"use strict";
+
+const path = require("path");
+const readline = require("readline");
+const pc = require("picocolors");
+const { detect, RECOMMENDATIONS } = require("../lib/detect");
+const { detectVersions } = require("../lib/versions");
+const { getPreset, listModels } = require("../lib/registry");
+const { installEntries } = require("./install");
+const { readManifest, isInstalled } = require("../lib/manifest");
+const { cmd } = require("../lib/invocation");
+
+/** How the user invoked us — "npx activate-agentmd" or "agentmd". */
+const A = cmd();
+
+const DEFAULT_MODEL = "claude";
+
+/** Yes/no prompt. Non-interactive stdin (CI, pipes) answers "no". */
+function confirm(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(false);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(!/^n/i.test(answer.trim()));
+    });
+  });
+}
+
+function flagValue(args, name) {
+  const hit = (args || []).find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : null;
+}
+
+async function init(args) {
+  args = args || [];
+  const model = flagValue(args, "model") || DEFAULT_MODEL;
+  const assumeYes = args.includes("--yes") || args.includes("-y");
+  const dry = args.includes("--dry");
+
+  if (!listModels().includes(model)) {
+    console.error(pc.red(`Unknown model: "${model}"`));
+    console.error(pc.dim(`  Available: ${listModels().join(", ")}`));
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  console.log(pc.bold("\nagentmd") + pc.dim("  scanning project…\n"));
+
+  const { signals, packages, workspaces } = detect(cwd);
+
+  if (signals.length === 0) {
+    console.log(pc.yellow("  No known stack detected in this directory."));
+    console.log(pc.dim(`\n  ${A} looks for package.json, Dockerfile, tsconfig.json, prisma/,`));
+    console.log(pc.dim("  .github/workflows/ and similar markers."));
+    console.log(pc.dim(`\n  Browse the registry instead:  ${A} list ${model}`));
+    console.log("");
+    return;
+  }
+
+  // A monorepo gets a per-workspace breakdown. Merging four stacks into one
+  // flat list would read as though the repo were one application, which is
+  // exactly the thing that makes the recommendations untrustworthy.
+  const nested = workspaces.filter((w) => w.path !== ".");
+  if (nested.length > 0) {
+    console.log(
+      pc.dim(`  ${workspaces.length} workspace${workspaces.length === 1 ? "" : "s"} detected\n`)
+    );
+    for (const workspace of workspaces) {
+      const name = workspace.path === "." ? "." + path.sep + " (root)" : workspace.path + path.sep;
+      console.log(`  ${pc.cyan(name)}`);
+      for (const s of workspace.signals) {
+        const suffix = (RECOMMENDATIONS[s.signal] || []).length === 0
+          ? pc.dim("  (no packages for this yet)")
+          : "";
+        console.log(`    ${pc.green("✓")} ${pc.white(s.label.padEnd(22))} ${pc.dim(s.via)}${suffix}`);
+      }
+      console.log("");
+    }
+    console.log(pc.dim("  Recommendations below are the union across all workspaces.\n"));
+  } else {
+    for (const s of signals) {
+      const suffix = s.packages.length === 0 ? pc.dim("  (no packages for this yet)") : "";
+      console.log(`  ${pc.green("✓")} ${pc.white(s.label.padEnd(24))} ${pc.dim(s.via)}${suffix}`);
+    }
+  }
+
+  // Version pins: the majors this project runs, which `link` turns into
+  // explicit "v2 not v1" rules — the antidote to a model's training cutoff.
+  const pins = detectVersions(cwd);
+  if (pins.length) {
+    console.log("");
+    for (const p of pins) console.log(`  ${pc.cyan("⇅")} ${pc.white(`${p.label} ${p.version}`.padEnd(24))} ${pc.dim(p.via)}${pc.dim("  (version pin)")}`);
+  }
+
+  // Only recommend what actually resolves. A mapping typo becomes a missing
+  // recommendation here and a test failure in CI — never a broken install.
+  const manifest = readManifest(cwd);
+  const resolved = [];
+  const alreadyInstalled = [];
+
+  for (const id of packages) {
+    const [category, preset] = id.split("/");
+    const entry = getPreset(model, category, preset);
+    if (!entry) continue;
+    if (isInstalled(manifest, entry.model, entry.category, entry.preset)) alreadyInstalled.push(entry);
+    else resolved.push(entry);
+  }
+
+  if (resolved.length === 0) {
+    console.log("");
+    console.log(
+      alreadyInstalled.length > 0
+        ? pc.green(`✓ All ${alreadyInstalled.length} recommended packages are already installed.`)
+        : pc.yellow("No registry packages match this stack yet.")
+    );
+    console.log("");
+    return;
+  }
+
+  const byCategory = new Map();
+  for (const entry of resolved) {
+    if (!byCategory.has(entry.category)) byCategory.set(entry.category, []);
+    byCategory.get(entry.category).push(entry.preset);
+  }
+
+  console.log("");
+  console.log(pc.bold(`Recommended packages for ${pc.cyan(model)}:`));
+  console.log("");
+  for (const [category, presets] of [...byCategory].sort()) {
+    console.log(`  ${pc.white(category.padEnd(14))} ${pc.dim(presets.join(", "))}`);
+  }
+  console.log("");
+  console.log(pc.dim(`  ${resolved.length} to install`) + (alreadyInstalled.length ? pc.dim(`, ${alreadyInstalled.length} already present`) : ""));
+  console.log("");
+
+  if (dry) {
+    console.log(pc.dim("  --dry: nothing installed. Commands that would run:\n"));
+    for (const entry of resolved) console.log(pc.dim(`    ${A} install ${entry.id}`));
+    console.log("");
+    return;
+  }
+
+  const go = assumeYes || (await confirm(pc.bold("Install these? ") + pc.dim("[Y/n] ")));
+  if (!go) {
+    console.log(pc.dim("\n  Nothing installed. Install individually with:"));
+    console.log(pc.dim(`    ${A} install ${resolved[0].id}`));
+    console.log("");
+    return;
+  }
+
+  console.log("");
+  await installEntries(resolved, {});
+}
+
+module.exports = { init };