activate-agentmd 2.4.0

package/src/commands/review.js

@@ -0,0 +1,293 @@
+/**
+ * review.js
+ *
+ * `agentmd review` — check a diff against the standards installed in this
+ * project. Turns the installed markdown from passive text into an active
+ * gate: locally before a commit, or in CI on every pull request.
+ *
+ *   agentmd review                      working tree vs HEAD
+ *   agentmd review --base origin/main   the branch's changes (CI)
+ *   agentmd review --fail-on=high       exit 1 if a high-severity finding exists
+ *   agentmd review --github             also post the report as a PR comment
+ *   agentmd review --fast               deterministic patterns only: free, offline, milliseconds
+ *   agentmd review --local              judge with a local Ollama model instead of the cloud
+ *
+ * Every run starts with the pattern fast-path (no network). The cloud path
+ * needs ANTHROPIC_API_KEY (or an `ant auth login` profile) and sends only the
+ * diff and the installed standards; --local sends them to Ollama on this
+ * machine instead, so nothing leaves it.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const pc = require("picocolors");
+const { readManifest, resolvePresetPath } = require("../lib/manifest");
+const { cmd } = require("../lib/invocation");
+const analytics = require("../lib/analytics");
+const { track, EVENTS } = require("../lib/telemetry");
+const { runPatterns } = require("../lib/patterns");
+
+const A = cmd();
+const MODEL = process.env.AGENTMD_REVIEW_MODEL || "claude-opus-5";
+const LOCAL_MODEL = process.env.AGENTMD_LOCAL_MODEL || "qwen2.5-coder:7b";
+const OLLAMA = (process.env.OLLAMA_HOST || "http://localhost:11434").replace(/\/$/, "");
+const MAX_STANDARDS_CHARS = 160_000;
+const SEVERITIES = ["low", "medium", "high"];
+
+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) {
+  return execFileSync("git", argv, { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** Installed standards, largest-first trimmed to a budget so the request stays bounded. */
+function loadStandards(cwd, manifest, changedFiles) {
+  const all = manifest.presets.map((p) => {
+    let text = "";
+    try { text = fs.readFileSync(resolvePresetPath(cwd, p.file), "utf-8"); } catch {}
+    return { id: `${p.category}/${p.preset}`, category: p.category, text };
+  }).filter((s) => s.text);
+
+  // Standards whose category plausibly matches the touched files go first, so
+  // if we must drop some, we drop the least relevant.
+  const touched = changedFiles.join("\n").toLowerCase();
+  const relevance = (s) => (touched.includes(s.category.toLowerCase().split(" ")[0]) ? 0 : 1);
+  all.sort((a, b) => relevance(a) - relevance(b) || a.id.localeCompare(b.id));
+
+  const kept = [], dropped = [];
+  let used = 0;
+  for (const s of all) {
+    if (used + s.text.length > MAX_STANDARDS_CHARS) { dropped.push(s.id); continue; }
+    kept.push(s); used += s.text.length;
+  }
+  return { kept, dropped };
+}
+
+function parseFindings(text) {
+  const m = /\{[\s\S]*\}/.exec(text);
+  if (!m) return null;
+  try {
+    const obj = JSON.parse(m[0]);
+    return Array.isArray(obj.findings) ? obj : null;
+  } catch { return null; }
+}
+
+async function postGithubComment(body) {
+  const token = process.env.GITHUB_TOKEN;
+  const repo = process.env.GITHUB_REPOSITORY;
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (!token || !repo || !eventPath) throw new Error("--github needs GITHUB_TOKEN, GITHUB_REPOSITORY and GITHUB_EVENT_PATH (set automatically in GitHub Actions)");
+  const event = JSON.parse(fs.readFileSync(eventPath, "utf-8"));
+  const number = event.pull_request?.number ?? event.issue?.number;
+  if (!number) throw new Error("--github: no pull request number in the event payload");
+  const res = await fetch(`https://api.github.com/repos/${repo}/issues/${number}/comments`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/vnd.github+json", "Content-Type": "application/json" },
+    body: JSON.stringify({ body }),
+  });
+  if (!res.ok) throw new Error(`GitHub API ${res.status}: ${await res.text()}`);
+}
+
+async function review(args) {
+  args = args || [];
+  const cwd = process.cwd();
+  const base = flagValue(args, "base");
+  const failOn = flagValue(args, "fail-on");
+  const toGithub = args.includes("--github");
+  const fast = args.includes("--fast");
+  const local = args.includes("--local");
+  const modelName = flagValue(args, "model") || (local ? LOCAL_MODEL : MODEL);
+  if (failOn && !SEVERITIES.includes(failOn)) {
+    console.error(pc.red(`--fail-on must be one of ${SEVERITIES.join(", ")}`));
+    process.exit(2);
+  }
+
+  const manifest = readManifest(cwd);
+  if (manifest.presets.length === 0) {
+    console.log(pc.yellow("\nNo packages installed — nothing to review against."));
+    console.log(pc.dim(`  Run '${A} init' first.\n`));
+    return;
+  }
+
+  let diff, changedFiles;
+  try {
+    if (base) {
+      diff = git(cwd, "diff", `${base}...HEAD`);
+      changedFiles = git(cwd, "diff", "--name-only", `${base}...HEAD`).split("\n").filter(Boolean);
+    } else {
+      // Working tree vs HEAD, plus untracked files — a brand-new file is
+      // exactly what most needs reviewing, and plain `git diff` skips it.
+      diff = git(cwd, "diff", "HEAD");
+      changedFiles = git(cwd, "diff", "--name-only", "HEAD").split("\n").filter(Boolean);
+      const untracked = git(cwd, "ls-files", "--others", "--exclude-standard").split("\n").filter(Boolean);
+      for (const f of untracked) {
+        try { git(cwd, "diff", "--no-index", "--", "/dev/null", f); }
+        catch (e) { if (e.stdout) diff += e.stdout; } // --no-index exits 1 when the files differ
+        changedFiles.push(f);
+      }
+    }
+  } catch (e) {
+    console.error(pc.red(`git diff failed: ${e.message.split("\n")[0]}`));
+    process.exit(2);
+  }
+  if (!diff.trim()) {
+    console.log(pc.dim(`\nNo changes ${base ? `since ${base}` : "in the working tree"} — nothing to review.\n`));
+    return;
+  }
+
+  const { kept, dropped } = loadStandards(cwd, manifest, changedFiles);
+  const installedIds = new Set(manifest.presets.map((p) => `${p.category}/${p.preset}`));
+
+  // Fast-path: deterministic patterns, always, before any model.
+  const patternFindings = runPatterns(diff, installedIds);
+
+  console.log(pc.bold(`\nReviewing ${pc.cyan(changedFiles.length)} changed file${changedFiles.length === 1 ? "" : "s"} against ${pc.cyan(kept.length)} standard${kept.length === 1 ? "" : "s"}`) + pc.dim(fast ? " (patterns only)" : ` (${modelName}${local ? ", local" : ""})`));
+  if (dropped.length) console.log(pc.yellow(`  ${dropped.length} standard${dropped.length === 1 ? "" : "s"} left out to fit the request: ${dropped.join(", ")}`));
+  if (patternFindings.length) console.log(pc.dim(`  ${patternFindings.length} finding${patternFindings.length === 1 ? "" : "s"} from the pattern fast-path`));
+
+  if (fast) {
+    return report({ findings: patternFindings, summary: patternFindings.length ? "Pattern checks only — run without --fast for a full review." : "No pattern violations. Run without --fast for a full review." }, kept, "patterns", toGithub, failOn);
+  }
+
+  let Anthropic = null, client = null;
+  if (!local) {
+    try { Anthropic = require("@anthropic-ai/sdk"); } catch {
+      console.error(pc.red("@anthropic-ai/sdk is not installed — reinstall activate-agentmd."));
+      process.exit(2);
+    }
+    client = new Anthropic();
+  }
+
+  const system = [
+    "You are a strict code reviewer. You are given engineering standards the project has adopted, then a diff.",
+    "Report only violations of those standards that are present in the diff. Do not invent rules; do not comment on style the standards do not cover; do not praise.",
+    "For every finding cite the standard id and the exact heading of the rule it breaks.",
+    'Reply with JSON only, no prose: {"findings":[{"file":"path","line":123,"severity":"low|medium|high","standard":"Category/preset","rule":"heading text","issue":"what is wrong","fix":"smallest change that complies"}],"summary":"one sentence"}',
+    "If nothing violates a standard, reply {\"findings\":[],\"summary\":\"No violations of the installed standards.\"}.",
+  ].join("\n");
+
+  const standardsText = kept.map((s) => `<standard id="${s.id}">\n${s.text}\n</standard>`).join("\n\n");
+
+  const userMessage = `Changed files:\n${changedFiles.join("\n")}\n\n<diff>\n${diff}\n</diff>`;
+
+  // Local path: Ollama's chat endpoint on this machine. No key, no egress.
+  if (local) {
+    let text;
+    try {
+      const res = await fetch(`${OLLAMA}/api/chat`, {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: modelName, stream: false, format: "json", options: { num_ctx: 32768 },
+          messages: [{ role: "system", content: `${system}\n\n${standardsText}` }, { role: "user", content: userMessage }] }),
+      });
+      if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
+      text = (await res.json()).message?.content ?? "";
+    } catch (e) {
+      console.error(pc.red(`Ollama at ${OLLAMA} failed: ${e.message.split("\n")[0]}`));
+      console.error(pc.dim(`  Is it running, and is "${modelName}" pulled? (ollama pull ${modelName})`));
+      process.exit(2);
+    }
+    const parsed = parseFindings(text);
+    if (!parsed) { console.log(pc.yellow("\nCould not parse the local model's reply as JSON; raw output follows.\n")); console.log(text); process.exit(2); }
+    return report(merge(patternFindings, parsed), kept, modelName, toGithub, failOn);
+  }
+
+  let response;
+  try {
+    response = await client.beta.messages.create({
+      model: modelName,
+      max_tokens: 16000,
+      betas: ["server-side-fallback-2026-07-01"],
+      fallbacks: "default",
+      system: [
+        { type: "text", text: system },
+        // The standards are the stable prefix; cache them so CI runs on the
+        // same repo pay for them once.
+        { type: "text", text: standardsText, cache_control: { type: "ephemeral" } },
+      ],
+      messages: [{ role: "user", content: userMessage }],
+    });
+  } 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(`Review failed: ${e.message}`));
+    process.exit(2);
+  }
+
+  if (response.stop_reason === "refusal") {
+    console.error(pc.red("The model declined to review this diff" + (response.stop_details?.explanation ? `: ${response.stop_details.explanation}` : ".")));
+    process.exit(2);
+  }
+
+  const text = response.content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+  const parsed = parseFindings(text);
+  if (!parsed) {
+    console.log(pc.yellow("\nCould not parse the review as JSON; raw output follows.\n"));
+    console.log(text);
+    process.exit(2);
+  }
+  return report(merge(patternFindings, parsed), kept, modelName, toGithub, failOn);
+}
+
+/** Pattern findings first; model findings that duplicate one (same file, line, standard) are dropped. */
+function merge(patternFindings, parsed) {
+  const seen = new Set(patternFindings.map((f) => `${f.file}:${f.line}:${f.standard}`));
+  const rest = (parsed.findings || []).filter((f) => !seen.has(`${f.file}:${f.line}:${f.standard}`));
+  return { findings: [...patternFindings, ...rest], summary: parsed.summary };
+}
+
+async function report(parsed, kept, modelName, toGithub, failOn) {
+  const order = { high: 0, medium: 1, low: 2 };
+  const findings = parsed.findings.slice().sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3));
+
+  // Every run is recorded locally, free, so `analytics` can answer "did these
+  // rules earn their tokens?" later. Nothing here leaves the machine.
+  analytics.record(process.cwd(), { findings, standards: kept, mode: modelName });
+  if (findings.length) track(EVENTS.HALLUCINATIONS_BLOCKED, { findings: findings.length, command: "review" });
+  const paint = { high: pc.red, medium: pc.yellow, low: pc.dim };
+
+  console.log("");
+  if (findings.length === 0) {
+    console.log(`  ${pc.green("✓")}  ${parsed.summary || "No violations of the installed standards."}`);
+  } else {
+    for (const f of findings) {
+      const sev = (paint[f.severity] || pc.white)(String(f.severity || "?").toUpperCase().padEnd(6));
+      console.log(`  ${sev} ${pc.white(f.file)}${f.line ? pc.dim(":" + f.line) : ""}  ${pc.dim(f.standard + " › " + f.rule)}${f.pattern ? pc.dim("  [pattern]") : ""}`);
+      console.log(`         ${f.issue}`);
+      if (f.fix) console.log(`         ${pc.dim("fix:")} ${f.fix}`);
+    }
+    console.log("");
+    console.log(`  ${findings.length} finding${findings.length === 1 ? "" : "s"}${parsed.summary ? " — " + parsed.summary : ""}`);
+  }
+  console.log("");
+
+  if (toGithub) {
+    const lines = findings.length === 0
+      ? [`✅ **${A} review** — ${parsed.summary || "no violations of the installed standards."}`]
+      : [`### ${A} review — ${findings.length} finding${findings.length === 1 ? "" : "s"}`, "", "| Severity | File | Standard › rule | Issue | Fix |", "|---|---|---|---|---|",
+         ...findings.map((f) => `| ${f.severity} | \`${f.file}${f.line ? ":" + f.line : ""}\` | ${f.standard} › ${f.rule} | ${String(f.issue).replace(/\|/g, "\\|")} | ${String(f.fix || "").replace(/\|/g, "\\|")} |`),
+         "", `_${kept.length} standards checked · ${modelName}_`];
+    try { await postGithubComment(lines.join("\n")); console.log(pc.dim("  Posted to the pull request.\n")); }
+    catch (e) { console.error(pc.red(`  Could not post to GitHub: ${e.message}`)); }
+  }
+
+  if (failOn) {
+    const threshold = SEVERITIES.indexOf(failOn);
+    const failing = findings.filter((f) => SEVERITIES.indexOf(f.severity) >= threshold);
+    if (failing.length) {
+      console.error(pc.red(`  ${failing.length} finding${failing.length === 1 ? "" : "s"} at or above "${failOn}" — failing.\n`));
+      process.exit(1);
+    }
+  }
+}
+
+module.exports = { review };

package/src/commands/search.js

@@ -0,0 +1,110 @@
+/**
+ * search.js
+ *
+ * Handles: agentmd search <query> [--model=<name>] [--category=<name>] [--limit=<n>]
+ *
+ * Searches package names, categories and descriptions. Results are ranked by
+ * how well they match (see registry.searchPresets) rather than by directory
+ * order, so `search jwt` leads with Security/jwt.
+ *
+ * By default it searches one model — the same package exists for every model
+ * family, so showing each copy would multiply the output for no extra
+ * information.
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { searchPresets, listModels } = require("../lib/registry");
+const { cmd } = require("../lib/invocation");
+
+/** How the user invoked us — "npx activate-agentmd" or "agentmd". */
+const A = cmd();
+
+const DEFAULT_MODEL = "claude";
+const DEFAULT_LIMIT = 20;
+
+function flagValue(args, name) {
+  const hit = args.find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : null;
+}
+
+function search(args) {
+  args = args || [];
+  const query = args.filter((a) => !a.startsWith("--")).join(" ");
+
+  if (!query) {
+    console.error(pc.red(`Usage: ${A} search <query>`));
+    console.error(pc.dim(`  ${A} search authentication`));
+    console.error(pc.dim(`  ${A} search caching --category=Performance`));
+    console.error(pc.dim(`  ${A} search docker --model=gemini`));
+    process.exit(1);
+  }
+
+  const allModels = args.includes("--all-models");
+  const model = flagValue(args, "model") || DEFAULT_MODEL;
+  const category = flagValue(args, "category");
+  const limit = Number(flagValue(args, "limit")) || DEFAULT_LIMIT;
+
+  const models = allModels ? listModels() : [model];
+  for (const m of models) {
+    if (!listModels().includes(m)) {
+      console.error(pc.red(`Unknown model: "${m}"`));
+      console.error(pc.dim(`  Available: ${listModels().join(", ")}`));
+      process.exit(1);
+    }
+  }
+
+  // Every family ships the same package set, so searching all of them returned
+  // 11 identical rows per hit and a match count 11× the truth. Collapse on
+  // Category/preset and keep the first — the package is what matched, not the
+  // family it happens to be phrased for.
+  let results = models.flatMap((m) => searchPresets(m, query));
+  if (allModels) {
+    const seen = new Set();
+    results = results.filter((r) => {
+      const key = `${r.category}/${r.preset}`.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+  if (category) {
+    results = results.filter((r) => r.category.toLowerCase() === category.toLowerCase());
+  }
+
+  if (results.length === 0) {
+    console.log(pc.yellow(`\nNothing matched "${query}"` + (category ? ` in ${category}` : "")));
+    console.log("");
+    console.log(pc.dim(`  Browse categories:  ${A} list ` + model));
+    console.log(pc.dim(`  Scan this project:  ${A} init\n`));
+    return;
+  }
+
+  const shown = results.slice(0, limit);
+  console.log(
+    pc.bold(`\n${results.length} match${results.length === 1 ? "" : "es"} for "${pc.cyan(query)}"`) +
+      (results.length > shown.length ? pc.dim(` (showing ${shown.length})`) : "") +
+      "\n"
+  );
+
+  const width = Math.max(...shown.map((r) => (r.category + "/" + r.preset).length));
+  for (const entry of shown) {
+    const coordinate = `${entry.category}/${entry.preset}`;
+    const description = entry.description ? pc.dim(" · " + entry.description.slice(0, 60)) : "";
+    console.log(`  ${pc.white(coordinate.padEnd(width))} ${pc.dim("v" + entry.version)}${description}`);
+  }
+
+  console.log("");
+  console.log(pc.dim(`  Details:  ${A} info ${shown[0].id}`));
+  console.log(pc.dim(`  Install:  ${A} install ${shown[0].id}`));
+  if (results.length > shown.length) {
+    console.log(pc.dim(`  More:     ${A} search ${query} --limit=${results.length}`));
+  }
+  if (!allModels) {
+    console.log(pc.dim(`  Searched ${model}; add --all-models to search all ${listModels().length}.`));
+  }
+  console.log("");
+}
+
+module.exports = { search };

package/src/commands/sync.js

@@ -0,0 +1,245 @@
+/**
+ * sync.js
+ *
+ * Handles: agentmd sync --private [--push|--pull] [--dry]   (Pro)
+ *
+ * Your company's own standards, shared the way the public ones are.
+ *
+ * The public registry covers what everyone needs. What it cannot cover is the
+ * rule your team argues about in every review — the one about which service
+ * owns writes to `orders`, or why every handler takes a request id. Those live
+ * in `.agentmd/presets/local-*.md` and `.agentmd/overrides/`, and until now
+ * they only existed in whichever repo someone first wrote them in.
+ *
+ * A private registry is a place the team can put them. It is deliberately
+ * boring: a directory of markdown, reachable either over HTTPS or as a path
+ * on a shared volume. A git repo on a network share works. An S3 bucket
+ * mounted with s3fs works. No service to run, and if we disappear tomorrow
+ * the files are still just files.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("picocolors");
+const { load, ssoStatus, FILE: ENTERPRISE_FILE } = require("../lib/enterprise");
+const { fetchText } = require("../lib/fetcher");
+const { checksum, resolveInProject } = require("../lib/manifest");
+const { cmd } = require("../lib/invocation");
+
+const A = cmd();
+
+/** Where a project's own standards live, relative to the project root. */
+const LOCAL_DIRS = [path.join(".agentmd", "presets"), path.join(".agentmd", "overrides")];
+/** Only a project's *own* standards sync; registry copies come from the registry. */
+const LOCAL_PREFIX = "local-";
+
+const has = (args, name) => (args || []).includes(`--${name}`);
+
+/** Files this project owns and would push. */
+function localStandards(cwd) {
+  const out = [];
+  for (const dir of LOCAL_DIRS) {
+    const full = path.join(cwd, dir);
+    let entries = [];
+    try { entries = fs.readdirSync(full); } catch { continue; }
+    for (const name of entries) {
+      if (!name.endsWith(".md")) continue;
+      // Presets carry registry copies too; only the local- ones are ours.
+      if (dir.endsWith("presets") && !name.startsWith(LOCAL_PREFIX)) continue;
+      const file = path.join(full, name);
+      const content = fs.readFileSync(file, "utf-8");
+      out.push({ name, rel: path.join(dir, name), content, checksum: checksum(content), bytes: Buffer.byteLength(content) });
+    }
+  }
+  return out.sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+/** An https endpoint, or a directory on disk. Both are first-class. */
+const isHttp = (target) => /^https:\/\//i.test(target);
+
+async function readRemote(target, name) {
+  if (isHttp(target)) {
+    try {
+      return await fetchText(`${target.replace(/\/$/, "")}/${encodeURIComponent(name)}`);
+    } catch (err) {
+      if (/HTTP 404/.test(err.message)) return null;
+      throw err;
+    }
+  }
+  try {
+    return fs.readFileSync(path.join(target, name), "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function listRemote(target) {
+  if (isHttp(target)) {
+    // An index.json is the contract for an HTTPS registry: a plain list of
+    // filenames. It keeps the server a static file host rather than an API.
+    try {
+      const raw = await fetchText(`${target.replace(/\/$/, "")}/index.json`);
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : Array.isArray(parsed.standards) ? parsed.standards : [];
+    } catch {
+      return null; // no index — pull cannot enumerate, push still can
+    }
+  }
+  try {
+    return fs.readdirSync(target).filter((f) => f.endsWith(".md"));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+function writeRemote(target, name, content) {
+  if (isHttp(target)) {
+    // Deliberately not implemented: an unauthenticated PUT to a company's
+    // standards registry is a supply-chain hole, and every host does auth
+    // differently. Push to the filesystem path — a git checkout, a mounted
+    // share — and let the existing review process publish it.
+    throw new Error(
+      `Pushing over HTTPS is not supported. Point \`privateRegistry\` at a directory ` +
+      `(a git checkout or a mounted share) to push, and serve that directory over HTTPS for pulls.`
+    );
+  }
+  fs.mkdirSync(target, { recursive: true });
+  fs.writeFileSync(path.join(target, name), content, "utf-8");
+}
+
+async function sync(args) {
+  args = args || [];
+  const cwd = process.cwd();
+  const dry = has(args, "dry");
+  const push = has(args, "push");
+  const pull = has(args, "pull");
+
+  if (!has(args, "private")) {
+    console.error(pc.red(`\n  ${A} sync needs --private.`));
+    console.error(pc.dim("  It is the only mode: your own standards, to and from your own registry.\n"));
+    process.exitCode = 1;
+    return;
+  }
+  if (push && pull) {
+    console.error(pc.red("\n  --push and --pull are opposites. Pick one, or neither to see the difference.\n"));
+    process.exitCode = 1;
+    return;
+  }
+
+  const { config, problems } = load(cwd);
+  for (const p of problems) console.error(pc.yellow(`  ! ${p}`));
+
+  const target = config.privateRegistry;
+  if (!target) {
+    console.error(pc.red(`\n  No private registry configured.`));
+    console.error(pc.dim(`  Add one to ${ENTERPRISE_FILE}:\n`));
+    console.error(pc.dim(`      { "privateRegistry": "/mnt/team/agentmd-standards" }\n`));
+    console.error(pc.dim(`  or set AGENTMD_PRIVATE_REGISTRY. An https URL for pulls, a directory for both.\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const sso = ssoStatus(config);
+  if (!sso.satisfied) {
+    console.error(pc.red(`\n  ${sso.hint}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const local = localStandards(cwd);
+  const remoteNames = await listRemote(target);
+
+  console.log(pc.bold(`\nPrivate registry ${pc.dim(isHttp(target) ? target : path.resolve(target))}`));
+  if (sso.required) console.log(pc.dim(`  SSO satisfied via ${sso.via}`));
+  console.log("");
+
+  // ── status: what differs, without changing anything ────────────────────
+  if (!push && !pull) {
+    if (!local.length && !(remoteNames || []).length) {
+      console.log(pc.dim("  Nothing local, nothing remote.\n"));
+      console.log(pc.dim(`  Write a standard at .agentmd/presets/local-Team-conventions.md, or run '${A} extract'.\n`));
+      return;
+    }
+    const remote = new Set(remoteNames || []);
+    for (const f of local) {
+      const there = remote.has(f.name) ? await readRemote(target, f.name) : null;
+      const state =
+        there === null ? pc.green("new") :
+        checksum(there) === f.checksum ? pc.dim("in sync") : pc.yellow("differs");
+      console.log(`  ${state.padEnd(18)} ${pc.white(f.rel)} ${pc.dim(`${(f.bytes / 1024).toFixed(1)} KB`)}`);
+    }
+    for (const name of remoteNames || []) {
+      if (!local.some((f) => f.name === name)) console.log(`  ${pc.cyan("remote only").padEnd(18)} ${pc.white(name)}`);
+    }
+    console.log(pc.dim(`\n  '${A} sync --private --push' to publish yours · '--pull' to take theirs\n`));
+    return;
+  }
+
+  // ── push ───────────────────────────────────────────────────────────────
+  if (push) {
+    if (!local.length) {
+      console.log(pc.dim("  No local standards to push. Files matching .agentmd/presets/local-*.md and .agentmd/overrides/*.md are pushed.\n"));
+      return;
+    }
+    let changed = 0;
+    for (const f of local) {
+      const there = await readRemote(target, f.name);
+      if (there !== null && checksum(there) === f.checksum) {
+        console.log(`  ${pc.dim("=")}  ${pc.white(f.name.padEnd(42))} ${pc.dim("already current")}`);
+        continue;
+      }
+      if (dry) {
+        console.log(`  ${pc.yellow("~")}  ${pc.white(f.name.padEnd(42))} ${pc.dim(there === null ? "would create" : "would update")}`);
+        changed++;
+        continue;
+      }
+      writeRemote(target, f.name, f.content);
+      console.log(`  ${pc.green("✓")}  ${pc.white(f.name.padEnd(42))} ${pc.dim(there === null ? "created" : "updated")}`);
+      changed++;
+    }
+    console.log(dry ? pc.dim(`\n  --dry: nothing written. ${changed} file(s) would change.\n`) : `\n  ${changed} file(s) published.\n`);
+    return;
+  }
+
+  // ── pull ───────────────────────────────────────────────────────────────
+  if (remoteNames === null) {
+    console.error(pc.red(`  Cannot list ${target} — an https registry needs an index.json listing its files.\n`));
+    process.exitCode = 1;
+    return;
+  }
+  if (!remoteNames.length) {
+    console.log(pc.dim("  The registry is empty — nothing to pull.\n"));
+    return;
+  }
+
+  const presets = path.join(".agentmd", "presets");
+  let changed = 0;
+  for (const name of remoteNames) {
+    const content = await readRemote(target, name);
+    if (content === null) continue;
+    // Remote filenames decide where bytes land, so they go through the same
+    // guard as every other write rather than being trusted.
+    const dest = resolveInProject(cwd, path.join(name.startsWith(LOCAL_PREFIX) ? presets : path.join(".agentmd", "overrides"), path.basename(name)));
+    const before = fs.existsSync(dest) ? fs.readFileSync(dest, "utf-8") : null;
+    if (before === content) {
+      console.log(`  ${pc.dim("=")}  ${pc.white(name.padEnd(42))} ${pc.dim("already current")}`);
+      continue;
+    }
+    if (dry) {
+      console.log(`  ${pc.yellow("~")}  ${pc.white(name.padEnd(42))} ${pc.dim(before === null ? "would create" : "would update")}`);
+      changed++;
+      continue;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, content, "utf-8");
+    console.log(`  ${pc.green("✓")}  ${pc.white(name.padEnd(42))} ${pc.dim(before === null ? "created" : "updated")}`);
+    changed++;
+  }
+  console.log(dry ? pc.dim(`\n  --dry: nothing written. ${changed} file(s) would change.\n`) : `\n  ${changed} file(s) pulled. Run '${A} link' to wire them in.\n`);
+}
+
+module.exports = { sync, localStandards, isHttp };