activate-agentmd 2.4.0

package/src/lib/agents.js

@@ -0,0 +1,301 @@
+/**
+ * agents.js
+ *
+ * The adapter layer: one installed package, many agent-specific config files.
+ *
+ * Every target below is a documented convention that the named tool actually
+ * reads. Nothing here is aspirational — if a tool's convention isn't
+ * implemented, it isn't listed, and `agentmd agents` will not claim it.
+ */
+
+"use strict";
+
+const path = require("path");
+
+const START = "<!-- agentmd:start -->";
+const END = "<!-- agentmd:end -->";
+
+const TARGETS = {
+  claude: {
+    label: "Claude Code",
+    file: "CLAUDE.md",
+    format: "markdown",
+  },
+  agents: {
+    label: "AGENTS.md (Codex, Amp, Jules, and others)",
+    file: "AGENTS.md",
+    format: "markdown",
+  },
+  cursor: {
+    label: "Cursor",
+    file: path.join(".cursor", "rules", "agentmd.mdc"),
+    format: "mdc",
+  },
+  gemini: {
+    label: "Gemini CLI",
+    file: "GEMINI.md",
+    format: "markdown",
+  },
+  copilot: {
+    label: "GitHub Copilot",
+    file: path.join(".github", "copilot-instructions.md"),
+    format: "markdown",
+  },
+};
+
+/** Rough tokens: four characters each, the cut every tokenizer lands near. */
+const tokens = (text) => Math.ceil(String(text || "").length / 4);
+
+/**
+ * The always-on budget. Adherence collapses as instructions stack (about 96%
+ * with one instruction, as low as 20% with twenty-four, in the 2026
+ * benchmarks), so the block every prompt carries is capped. Everything past
+ * the cap is still installed and linked, but loads on demand.
+ */
+const ALWAYS_ON_BUDGET = 1500;
+
+/** Packages that earn a place in the core first when the budget is tight. */
+const CORE_PRIORITY = ["Security/owasp", "Review/code-review", "AI/agent-rules"];
+const CATEGORY_RANK = ["Security", "AI", "Review", "Backend", "Frontend", "Database", "API", "Testing", "Performance", "DevOps"];
+
+const idOf = (p) => `${p.category}/${p.preset}`;
+const posix = (file) => String(file).split(path.sep).join("/");
+
+function corePriority(p) {
+  const i = CORE_PRIORITY.indexOf(idOf(p));
+  if (i !== -1) return i;
+  const c = CATEGORY_RANK.indexOf(p.category);
+  return 100 + (c === -1 ? CATEGORY_RANK.length : c) * 10;
+}
+
+/**
+ * A package's core: its hard rules and its checklist — the lines an agent
+ * must hold on every prompt. Derived from the standard itself rather than
+ * hand-written, so every package has one today; a canonical file can tighten
+ * it by improving its own **Never** rules and checklist.
+ */
+function coreOf(content, limit = 6) {
+  const body = String(content).replace(/^---[\s\S]*?---\s*/, "");
+  const lines = [];
+  for (const para of body.split(/\n\s*\n/)) {
+    const t = para.trim();
+    if (/^\*\*Never\*\*|^- \*\*Never/.test(t)) {
+      lines.push("- " + t.replace(/^[-*\s]*/, "").replace(/\*\*/g, "").replace(/\s*\n\s*/g, " "));
+    }
+  }
+  for (const m of body.match(/^- \[ \] .+$/gm) || []) {
+    if (lines.length >= limit) break;
+    lines.push("- " + m.replace(/^- \[ \] (Verify: )?/, ""));
+  }
+  if (lines.length) return lines.slice(0, limit);
+  // Older packages carry neither **Never** rules nor a checklist: fall back to
+  // their first substantive bullets so they still earn a place in the core.
+  return (body.match(/^- .{40,}$/gm) || []).slice(0, Math.min(4, limit)).map((l) => l.replace(/\*\*/g, ""));
+}
+
+/**
+ * Decide what fits in the always-on block. Pins go first (they are the
+ * highest-value lines in the file), then package cores in priority order
+ * until the budget is spent. Without a `readPreset` there is nothing to
+ * extract, and every package is listed as a link — the pre-budget shape.
+ */
+function planAlwaysOn(presets, pins = [], readPreset = null, budget = ALWAYS_ON_BUDGET) {
+  const { renderPins } = require("./versions");
+  const core = [];
+  const demoted = [];
+  let used = tokens(renderPins(pins)) + 150; // header, section titles and footer
+  if (!readPreset) return { core, demoted: presets.slice(), used, budget };
+
+  for (const p of presets.slice().sort((a, b) => corePriority(a) - corePriority(b))) {
+    const content = readPreset(p);
+    const lines = content ? coreOf(content) : [];
+    if (!lines.length) { demoted.push(p); continue; }
+    const cost = tokens(lines.join("\n")) + tokens(idOf(p)) + 8;
+    if (used + cost > budget) { demoted.push(p); continue; }
+    used += cost;
+    core.push({ id: idOf(p), file: posix(p.file), lines });
+  }
+  return { core, demoted, used, budget };
+}
+
+/**
+ * The managed block, rendered for an agent to read.
+ *
+ * opts.readPreset  (preset) => text | null — enables the core/reference split
+ * opts.scope       workspace path — marks a nested file that overrides the root
+ */
+function renderBody(presets, pins = [], opts = {}) {
+  if (presets.length === 0 && pins.length === 0) {
+    return "No agentmd packages are installed. Run `agentmd init` to add some.";
+  }
+  const { renderPins } = require("./versions");
+  const plan = planAlwaysOn(presets, pins, opts.readPreset);
+
+  const lines = [
+    "## Engineering standards (managed by agentmd)",
+    "",
+    "Read and follow the standards in these files. They are installed from the",
+    "agentmd registry — edit them through `agentmd`, not by hand, or the next",
+    "`agentmd update` will overwrite your changes.",
+    "",
+  ];
+  if (opts.scope) {
+    lines.push(`_Workspace \`${opts.scope}\`: the nearest file wins. These rules override the root file for everything under this directory._`, "");
+  }
+
+  const pinBlock = renderPins(pins);
+  if (pinBlock) lines.push(pinBlock);
+
+  if (plan.core.length) {
+    lines.push("### Core rules (always on)", "");
+    for (const c of plan.core) {
+      lines.push(`**${c.id}** — [full standard](${c.file})`, ...c.lines, "");
+    }
+  }
+
+  const rest = presets.filter((p) => !plan.core.some((c) => c.id === idOf(p)));
+  if (rest.length) {
+    if (plan.core.length) lines.push("### On demand", "", "Read the standard before working in its area; the always-on budget is spent.", "");
+    const byCategory = new Map();
+    for (const p of rest) {
+      if (!byCategory.has(p.category)) byCategory.set(p.category, []);
+      byCategory.get(p.category).push(p);
+    }
+    for (const [category, items] of [...byCategory].sort((a, b) => a[0].localeCompare(b[0]))) {
+      lines.push(`### ${category}`);
+      for (const item of items.sort((a, b) => a.preset.localeCompare(b.preset))) {
+        lines.push(`- [\`${item.preset}\`](${posix(item.file)})`);
+      }
+      lines.push("");
+    }
+  }
+
+  const budgetNote = plan.core.length ? ` · ${plan.core.length} in core (~${plan.used} of ${plan.budget} tokens always on)` : "";
+  lines.push(`_${presets.length} package${presets.length === 1 ? "" : "s"}${budgetNote}${pins.length ? ` · ${pins.length} version pin${pins.length === 1 ? "" : "s"}` : ""} · regenerate with \`agentmd link\`_`);
+  return lines.join("\n");
+}
+
+/**
+ * Produce the new contents of an agent config file.
+ *
+ * Markdown targets get a delimited block spliced in so hand-written content
+ * around it survives. The Cursor .mdc file is generated wholesale — agentmd
+ * owns that path, and MDC needs frontmatter at the very top.
+ */
+function applyToFile(target, existing, presets, pins = [], opts = {}) {
+  const body = renderBody(presets, pins, opts);
+
+  if (target.format === "mdc") {
+    return [
+      "---",
+      "description: Engineering standards installed by agentmd",
+      "alwaysApply: true",
+      "---",
+      "",
+      body,
+      "",
+    ].join("\n");
+  }
+
+  const block = `${START}\n${body}\n${END}`;
+
+  if (!existing) return block + "\n";
+
+  const startAt = existing.indexOf(START);
+  const endAt = existing.indexOf(END);
+
+  if (startAt !== -1 && endAt > startAt) {
+    return existing.slice(0, startAt) + block + existing.slice(endAt + END.length);
+  }
+  // No managed block yet — append, keeping everything the user wrote.
+  return existing.replace(/\s*$/, "") + "\n\n" + block + "\n";
+}
+
+/**
+ * File globs per category, for Cursor's scoped ("Auto Attached") rules.
+ *
+ * With the index .mdc alone, Cursor only ever saw a list of links. A scoped
+ * rule carries the standard's text and is attached only while a matching
+ * file is open — so the Database standard costs nothing while you edit CSS.
+ * Categories with no natural file shape get no globs; Cursor then treats the
+ * rule as "Agent Requested" and loads it when the description fits the task.
+ */
+const CATEGORY_GLOBS = {
+  Database: "**/*.sql,**/*.prisma,**/prisma/**,**/migrations/**,**/db/**,**/models/**,**/*repository*",
+  Frontend: "**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte,**/*.css,**/app/**,**/components/**,**/pages/**",
+  Design: "**/*.tsx,**/*.jsx,**/*.vue,**/*.svelte,**/*.css,**/styles/**",
+  Backend: "**/api/**,**/server/**,**/routes/**,**/controllers/**,**/services/**,**/handlers/**,**/middleware/**,**/*.py,**/*.go",
+  API: "**/api/**,**/routes/**,**/openapi*,**/*.graphql,**/schema.*,**/handlers/**",
+  Security: "**/auth/**,**/*auth*,**/middleware/**,**/security/**,**/api/**,**/.env*",
+  Testing: "**/*.test.*,**/*.spec.*,**/__tests__/**,**/tests/**,**/test/**,**/conftest.py,**/*_test.go",
+  DevOps: "**/Dockerfile*,**/docker-compose*,**/.github/workflows/**,**/k8s/**,**/*.tf,**/*.yml,**/*.yaml",
+  Performance: "**/*.ts,**/*.tsx,**/*.py,**/*.go,**/*.sql",
+  Documentation: "**/*.md,**/docs/**",
+};
+
+/** First `description:` line of a preset's frontmatter, or a plain fallback. */
+function presetDescription(content, preset) {
+  const m = /^---[\s\S]*?\ndescription:\s*(.+?)\s*\n[\s\S]*?---/m.exec(content);
+  return (m ? m[1] : `${preset.category}/${preset.preset} engineering standard`).replace(/\s+/g, " ");
+}
+
+/**
+ * Where each target keeps its on-demand reference files, and the pattern
+ * `link` may clean up there. Only conventions the tool actually reads:
+ *   cursor  — Auto Attached .mdc rules by glob
+ *   claude  — .claude/rules/*.md with `paths:` frontmatter (loads when a
+ *             matching file is read, not at launch)
+ *   copilot — .github/instructions/*.instructions.md with `applyTo`
+ * AGENTS.md and GEMINI.md have no on-demand mechanism; their block links to
+ * the installed presets instead.
+ */
+const REFERENCE_DIRS = {
+  cursor: { dir: path.join(".cursor", "rules"), pattern: /^agentmd-.+\.mdc$/ },
+  claude: { dir: path.join(".claude", "rules"), pattern: /^agentmd-.+\.md$/ },
+  copilot: { dir: path.join(".github", "instructions"), pattern: /^agentmd-.+\.instructions\.md$/ },
+};
+
+const slugOf = (p) => `${p.category}-${p.preset}`.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+
+/**
+ * One on-demand reference file per installed preset, in the target's own
+ * convention. Categories without a file shape (System Design, AI, …) get no
+ * reference for Claude or Copilot — an unscoped rule there would load every
+ * session and defeat the budget — and stay reachable through the block's links.
+ */
+function referenceRules(presets, readPreset, target = "cursor") {
+  const rules = [];
+  for (const p of presets) {
+    const content = readPreset(p);
+    if (!content) continue;
+    const globs = CATEGORY_GLOBS[p.category];
+    const body = content.replace(/^---[\s\S]*?---\s*/, "");
+    const description = presetDescription(content, p);
+    const slug = slugOf(p);
+
+    if (target === "cursor") {
+      rules.push({
+        file: path.join(REFERENCE_DIRS.cursor.dir, `agentmd-${slug}.mdc`),
+        content: ["---", `description: ${description}`, ...(globs ? [`globs: ${globs}`] : []), "alwaysApply: false", "---", "", body, ""].join("\n"),
+      });
+    } else if (target === "claude" && globs) {
+      rules.push({
+        file: path.join(REFERENCE_DIRS.claude.dir, `agentmd-${slug}.md`),
+        content: ["---", "paths:", ...globs.split(",").map((g) => `  - "${g}"`), "---", "", `# ${idOf(p)}`, "", description, "", body, ""].join("\n"),
+      });
+    } else if (target === "copilot" && globs) {
+      rules.push({
+        file: path.join(REFERENCE_DIRS.copilot.dir, `agentmd-${slug}.instructions.md`),
+        content: ["---", `applyTo: "${globs}"`, "---", "", `# ${idOf(p)}`, "", body, ""].join("\n"),
+      });
+    }
+  }
+  return rules;
+}
+
+/** Kept for callers that predate referenceRules(); the Cursor shape. */
+function scopedRules(presets, readPreset) {
+  return referenceRules(presets, readPreset, "cursor");
+}
+
+module.exports = { TARGETS, CATEGORY_GLOBS, REFERENCE_DIRS, ALWAYS_ON_BUDGET, applyToFile, renderBody, planAlwaysOn, coreOf, referenceRules, scopedRules, tokens, START, END };

package/src/lib/analytics.js

@@ -0,0 +1,137 @@
+/**
+ * analytics.js
+ *
+ * A local ledger of what the installed standards actually caught.
+ *
+ * Every `review` appends one run: when it happened, which standards were
+ * loaded, and one row per finding. Nothing leaves the machine — this file is
+ * written next to the manifest, inside the project, and is as private as the
+ * diff it describes. (Telemetry is a separate, opt-in thing; see lib/telemetry.js.)
+ *
+ * It exists because "did these rules earn their tokens?" is the question every
+ * team asks in week three, and until now the only answer was a shrug. A
+ * finding is a moment the agent was about to ship something a standard forbids
+ * — an interpolated query, a deprecated call from a training set two years
+ * stale — and that is the number worth counting.
+ *
+ * Recording is free for everyone. `agentmd analytics` reads it back.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const FILE = path.join(".agentmd", "analytics.json");
+/** Runs kept on disk. A year of daily CI on one repo is well under this. */
+const MAX_RUNS = 500;
+
+const filePath = (cwd) => path.join(cwd, FILE);
+
+/** The ledger, or an empty one. A corrupt file is replaced, never thrown over. */
+function read(cwd = process.cwd()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath(cwd), "utf-8"));
+    if (parsed && Array.isArray(parsed.runs)) return parsed;
+  } catch {
+    // unreadable or malformed — start fresh rather than break `review`
+  }
+  return { version: 1, runs: [] };
+}
+
+/**
+ * Append one review. Called from `review` after it reports; a failure here
+ * must never turn a successful review into a crash, so everything is guarded.
+ */
+function record(cwd, { findings = [], standards = [], mode = "patterns", base = null } = {}) {
+  try {
+    const ledger = read(cwd);
+    ledger.runs.push({
+      at: new Date().toISOString(),
+      mode,
+      base,
+      standards: standards.length,
+      findings: findings.map((f) => ({
+        severity: String(f.severity || "low"),
+        standard: String(f.standard || "unknown"),
+        rule: String(f.rule || ""),
+        file: String(f.file || ""),
+        pattern: !!f.pattern,
+      })),
+    });
+    if (ledger.runs.length > MAX_RUNS) ledger.runs = ledger.runs.slice(-MAX_RUNS);
+
+    fs.mkdirSync(path.dirname(filePath(cwd)), { recursive: true });
+    fs.writeFileSync(filePath(cwd), JSON.stringify(ledger, null, 2) + "\n", "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Roll the ledger up for reporting.
+ *
+ * `since` is a Date; runs before it are ignored so `--since 30d` is a filter
+ * on the same data rather than a second storage format.
+ */
+function summarise(cwd = process.cwd(), since = null) {
+  const ledger = read(cwd);
+  const runs = ledger.runs.filter((r) => !since || new Date(r.at) >= since);
+
+  const byStandard = new Map();
+  const bySeverity = { high: 0, medium: 0, low: 0 };
+  const byRule = new Map();
+  const byWeek = new Map();
+  let total = 0;
+  let patterns = 0;
+
+  for (const run of runs) {
+    const week = weekOf(new Date(run.at));
+    byWeek.set(week, (byWeek.get(week) || 0) + run.findings.length);
+    for (const f of run.findings) {
+      total++;
+      if (f.pattern) patterns++;
+      bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+      byStandard.set(f.standard, (byStandard.get(f.standard) || 0) + 1);
+      const rule = `${f.standard} › ${f.rule || "—"}`;
+      byRule.set(rule, (byRule.get(rule) || 0) + 1);
+    }
+  }
+
+  const sorted = (map) => [...map.entries()].sort((a, b) => b[1] - a[1]);
+
+  return {
+    runs: runs.length,
+    firstRun: runs[0]?.at ?? null,
+    lastRun: runs[runs.length - 1]?.at ?? null,
+    total,
+    patterns,
+    bySeverity,
+    byStandard: sorted(byStandard),
+    byRule: sorted(byRule),
+    byWeek: [...byWeek.entries()].sort(),
+    /** Standards that have never caught anything: candidates for removal. */
+    idle: (() => {
+      const seen = new Set(byStandard.keys());
+      return { seen };
+    })(),
+  };
+}
+
+/** ISO-ish week key, `2026-W38`, for the trend column. */
+function weekOf(date) {
+  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7));
+  const start = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((d - start) / 86400000 + 1) / 7);
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+/** Findings recorded in the last `days` days — the free one-line footer. */
+function recentCount(cwd = process.cwd(), days = 7) {
+  const since = new Date(Date.now() - days * 86400000);
+  return summarise(cwd, since).total;
+}
+
+module.exports = { read, record, summarise, recentCount, weekOf, filePath, FILE, MAX_RUNS };

package/src/lib/coordinates.js

@@ -0,0 +1,103 @@
+/**
+ * coordinates.js
+ *
+ * Parsing and did-you-mean help for package coordinates
+ * (`<model>/<category>/<preset>`).
+ */
+
+"use strict";
+
+const { getAllPresets, listModels } = require("./registry");
+
+/** Used when a coordinate names no model. Matches the website's default. */
+const DEFAULT_MODEL = "claude";
+
+/** Case- and separator-insensitive membership test against the model list. */
+function knownModel(part) {
+  const normalized = String(part || "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  return listModels().some((m) => m.toLowerCase().replace(/[^a-z0-9]/g, "") === normalized);
+}
+
+/**
+ * Split a coordinate string into its parts.
+ *
+ * Tolerates leading/trailing slashes and stray whitespace, so
+ * `claude/Security/`, `/claude/Security`, and `claude / Security` all parse
+ * the same way.
+ *
+ * Two grammars are accepted:
+ *
+ *   claude/Security/owasp   model-first, the original form
+ *   Security/owasp          model-less, resolved against the default model
+ *
+ * The model-less form is what the website now shows and what detect.js has
+ * always emitted for recommendations. It is distinguished by testing whether
+ * the first segment actually names a model family, not by counting segments —
+ * `claude/Security` and `Security/owasp` are both two parts and mean different
+ * things.
+ *
+ * `explicitModel` records which grammar was used, so callers can tell "the
+ * user asked for claude" from "nobody said, so we assumed claude".
+ */
+function parseCoordinates(raw) {
+  const parts = String(raw || "")
+    .split("/")
+    .map((p) => p.trim())
+    .filter(Boolean);
+
+  const modelFirst = parts.length === 0 || knownModel(parts[0]);
+  const [model, category, preset] = modelFirst
+    ? parts
+    : [DEFAULT_MODEL, ...parts];
+
+  return {
+    raw: String(raw || ""),
+    model: model || null,
+    category: category || null,
+    preset: preset || null,
+    // Depth stays the caller-visible shape: how many coordinate levels were
+    // resolved, so progressive browsing (`list claude/Security`) is unchanged.
+    depth: modelFirst ? parts.length : parts.length + 1,
+    explicitModel: modelFirst && parts.length > 0,
+  };
+}
+
+/** Levenshtein distance, capped — used only for short package names. */
+function distance(a, b) {
+  if (a === b) return 0;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const carry = prev[j];
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diagonal + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      diagonal = carry;
+    }
+  }
+  return prev[b.length];
+}
+
+/**
+ * Closest package names to a typo'd one, for "did you mean" output.
+ * Only suggests names within a distance that scales with length, so a short
+ * query doesn't match half the registry.
+ */
+function suggest(model, name, limit = 3) {
+  const query = String(name || "").toLowerCase();
+  if (!query) return [];
+  const threshold = Math.max(2, Math.floor(query.length / 3));
+
+  return getAllPresets(model)
+    .map((entry) => ({ entry, d: distance(query, entry.preset.toLowerCase()) }))
+    .filter(({ entry, d }) => d <= threshold || entry.preset.toLowerCase().includes(query))
+    .sort((a, b) => a.d - b.d)
+    .slice(0, limit)
+    .map(({ entry }) => entry);
+}
+
+module.exports = { parseCoordinates, suggest, distance, listModels, knownModel, DEFAULT_MODEL };

package/src/lib/credentials.js

@@ -0,0 +1,115 @@
+/**
+ * credentials.js
+ *
+ * Where the license key lives between runs.
+ *
+ * A mode-0600 JSON file in the user's config directory, which is what npm,
+ * `gh`, Stripe and Vercel all do. `keytar` was the other candidate and was
+ * rejected: it is a native module, so it needs a toolchain or a prebuilt
+ * binary for every platform, and it is the single most common reason a CLI
+ * fails to install in Alpine, in a slim Docker image, or on a CI runner
+ * without libsecret. A package manager for supply-chain-sensitive content
+ * should not add a node-gyp dependency to store one string.
+ *
+ * Resolution order, highest first:
+ *
+ *   1. AGENTMD_PRO_KEY          — CI and one-off runs, nothing touches disk
+ *   2. .agentmd/enterprise.json — a key committed by the company for its repo
+ *   3. ~/.agentmd/credentials.json (0600)
+ */
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const FILE = "credentials.json";
+
+/**
+ * The config directory. Honours AGENTMD_CONFIG_HOME first (tests and
+ * containers), then XDG_CONFIG_HOME, then ~/.agentmd.
+ */
+function configDir() {
+  if (process.env.AGENTMD_CONFIG_HOME) return path.resolve(process.env.AGENTMD_CONFIG_HOME);
+  if (process.env.XDG_CONFIG_HOME) return path.join(path.resolve(process.env.XDG_CONFIG_HOME), "agentmd");
+  return path.join(os.homedir(), ".agentmd");
+}
+
+const credentialsPath = () => path.join(configDir(), FILE);
+
+/** Stored credentials, or null. A corrupt file reads as "not signed in". */
+function read() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(), "utf-8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write credentials with owner-only permissions.
+ *
+ * The mode is set on the descriptor as the file is created, not with a
+ * chmod afterwards: between the two there is a window where the key is
+ * world-readable, and on a shared CI box that window is the whole exposure.
+ */
+function write(data) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = credentialsPath();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ ...data, updatedAt: new Date().toISOString() }, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  fs.renameSync(tmp, file); // atomic: a half-written file never becomes the real one
+  return file;
+}
+
+/** Remove stored credentials. Returns true when there was something to remove. */
+function clear() {
+  try {
+    fs.unlinkSync(credentialsPath());
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/**
+ * The key to use, and where it came from. `source` is worth carrying: when a
+ * key is rejected, the first question is always which key was used.
+ */
+function resolveKey(cwd = process.cwd()) {
+  const fromEnv = process.env.AGENTMD_PRO_KEY;
+  if (fromEnv) return { key: fromEnv.trim(), source: "AGENTMD_PRO_KEY" };
+
+  try {
+    const enterprise = JSON.parse(fs.readFileSync(path.join(cwd, ".agentmd", "enterprise.json"), "utf-8"));
+    if (enterprise && typeof enterprise.licenseKey === "string" && enterprise.licenseKey) {
+      return { key: enterprise.licenseKey.trim(), source: ".agentmd/enterprise.json" };
+    }
+  } catch {
+    // no enterprise config, or it is not readable — fall through
+  }
+
+  const stored = read();
+  if (stored && typeof stored.key === "string" && stored.key) {
+    return { key: stored.key, source: credentialsPath() };
+  }
+
+  return { key: null, source: null };
+}
+
+/** Permissions as a string ("600"), or null when the file is absent. */
+function permissions() {
+  try {
+    return (fs.statSync(credentialsPath()).mode & 0o777).toString(8).padStart(3, "0");
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { read, write, clear, resolveKey, configDir, credentialsPath, permissions };