activate-agentmd 2.4.0

package/src/lib/fetcher.js

@@ -0,0 +1,174 @@
+/**
+ * fetcher.js
+ *
+ * Fetches preset markdown from the registry over HTTPS.
+ * Uses Node's built-in https module — zero extra dependencies.
+ *
+ * This is a supply-chain-sensitive path: the bytes it returns end up in a
+ * file that a developer's coding agent will read as instructions. It is
+ * deliberately strict about what it will talk to and how much it will accept.
+ */
+
+"use strict";
+
+const https = require("https");
+
+const TIMEOUT_MS = Number(process.env.AGENTMD_TIMEOUT_MS) || 30000;
+const MAX_REDIRECTS = 5;
+const MAX_BYTES = 2 * 1024 * 1024; // presets are markdown; the largest today is ~40 KB
+const RETRIES = 2;
+/**
+ * A ceiling on the whole request, headers and body together.
+ * `req.setTimeout` only fires on socket inactivity, so a server that dribbles
+ * one byte at a time keeps resetting it and the CLI hangs indefinitely.
+ */
+const DEADLINE_MS = TIMEOUT_MS * 2;
+
+/**
+ * Shared keep-alive agent.
+ *
+ * `agentmd init` opens ~30 connections in a row. Without pooling, each one
+ * pays a fresh DNS + TLS handshake, and a burst of simultaneous cold
+ * handshakes was reliably timing out the first batch of `outdated`. Reusing a
+ * small pool of sockets fixes that and is kinder to the registry host.
+ */
+const agent = new https.Agent({ keepAlive: true, maxSockets: 6 });
+
+/**
+ * Fetch text over HTTPS.
+ *
+ * Refuses plaintext HTTP outright (including via redirect), so a hijacked
+ * redirect cannot downgrade the transport and inject preset content.
+ * Bounded by a timeout, a redirect limit and a response size cap so a hung or
+ * hostile server cannot wedge the CLI or exhaust memory.
+ */
+function fetchOnce(url, redirectsLeft = MAX_REDIRECTS) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return reject(new Error(`Invalid registry URL: ${url}`));
+    }
+    if (parsed.protocol !== "https:") {
+      return reject(
+        new Error(`Refusing to fetch preset content over ${parsed.protocol}// — HTTPS is required (${url})`)
+      );
+    }
+
+    const req = https.get(parsed, { agent, headers: { "user-agent": "activate-agentmd" } }, (res) => {
+      const { statusCode, headers } = res;
+
+      if (statusCode >= 300 && statusCode < 400 && headers.location) {
+        res.resume(); // drain so the socket can be reused
+        if (redirectsLeft <= 0) {
+          return reject(new Error(`Too many redirects fetching ${url}`));
+        }
+        const next = new URL(headers.location, parsed).toString();
+        return fetchOnce(next, redirectsLeft - 1).then(resolve, reject);
+      }
+
+      if (statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${statusCode} fetching ${url}`));
+      }
+
+      const chunks = [];
+      let bytes = 0;
+      res.setTimeout(TIMEOUT_MS, () => {
+        req.destroy(new Error(`Stalled after ${TIMEOUT_MS}ms while reading ${url}`));
+      });
+      res.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_BYTES) {
+          req.destroy();
+          return reject(new Error(`Preset at ${url} exceeds the ${MAX_BYTES / 1024 / 1024} MB limit`));
+        }
+        chunks.push(chunk);
+      });
+      res.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+      res.on("error", reject);
+    });
+
+    req.setTimeout(TIMEOUT_MS, () => {
+      req.destroy(new Error(`Timed out after ${TIMEOUT_MS}ms fetching ${url}`));
+    });
+    const deadline = setTimeout(() => {
+      req.destroy(new Error(`Timed out after ${DEADLINE_MS}ms fetching ${url} (response never completed)`));
+    }, DEADLINE_MS);
+    if (typeof deadline.unref === "function") deadline.unref();
+    const done = () => clearTimeout(deadline);
+    req.on("close", done);
+    req.on("error", (err) => { done(); reject(err); });
+  });
+}
+
+/**
+ * Fetch with retries.
+ *
+ * Retries only transient failures — a timeout or a dropped connection. An
+ * HTTP 404 means the package genuinely isn't there, and retrying it three
+ * times just makes the user wait longer for the same error.
+ */
+async function fetchText(url) {
+  try {
+    return await fetchWithRetries(url);
+  } catch (err) {
+    // registry.js is required lazily: it imports the package index, which the
+    // fetcher's unit tests never need.
+    const { RAW_BASE, RAW_FALLBACK } = require("./registry");
+    if (RAW_FALLBACK && /HTTP 404/.test(err.message) && url.startsWith(RAW_BASE)) {
+      if (!warnedFallback) {
+        warnedFallback = true;
+        process.stderr.write(`  ! ${RAW_BASE} is missing a file; falling back to main. Update the CLI when the next release lands.\n`);
+      }
+      return fetchWithRetries(RAW_FALLBACK + url.slice(RAW_BASE.length));
+    }
+    throw err;
+  }
+}
+
+let warnedFallback = false;
+
+async function fetchWithRetries(url) {
+  let lastError;
+  for (let attempt = 0; attempt <= RETRIES; attempt++) {
+    try {
+      return await fetchOnce(url);
+    } catch (err) {
+      lastError = err;
+      const transient = /timed out|stalled|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up|ENOTFOUND|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH/i.test(err.message);
+      if (!transient || attempt === RETRIES) throw explain(err, url);
+      await new Promise((r) => setTimeout(r, 400 * (attempt + 1)));
+    }
+  }
+  throw explain(lastError, url);
+}
+
+/**
+ * Turn a Node network error into something a developer can act on. Raw
+ * `getaddrinfo EAI_AGAIN` tells a user nothing about which knob to turn, and
+ * the two knobs that exist (a proxy, and AGENTMD_TIMEOUT_MS) are not
+ * discoverable from the stack trace.
+ */
+function explain(err, url) {
+  const host = (() => { try { return new URL(url).host; } catch { return "the registry"; } })();
+  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+  const hint = (text) => Object.assign(new Error(text), { cause: err, url });
+
+  if (/ENOTFOUND|EAI_AGAIN/i.test(err.message)) {
+    return hint(`Cannot resolve ${host}. Check your network or DNS${proxy ? "" : "; behind a proxy, set HTTPS_PROXY"}.`);
+  }
+  if (/ECONNREFUSED|EHOSTUNREACH|ENETUNREACH/i.test(err.message)) {
+    return hint(`Cannot reach ${host}. Check your network${proxy ? ` and HTTPS_PROXY (${proxy})` : " or firewall"}.`);
+  }
+  if (/timed out|stalled/i.test(err.message)) {
+    return hint(`${err.message.replace(/ fetching .*/, "")} fetching from ${host}. Raise AGENTMD_TIMEOUT_MS (currently ${TIMEOUT_MS}) on a slow link.`);
+  }
+  if (/certificate|self.signed|SELF_SIGNED|UNABLE_TO_VERIFY/i.test(err.message)) {
+    return hint(`TLS verification failed for ${host}: ${err.message}. A corporate proxy needs NODE_EXTRA_CA_CERTS pointed at its root certificate.`);
+  }
+  return err;
+}
+
+module.exports = { fetchText, fetchOnce, explain, TIMEOUT_MS, DEADLINE_MS, MAX_BYTES, MAX_REDIRECTS, RETRIES };

package/src/lib/invocation.js

@@ -0,0 +1,47 @@
+/**
+ * invocation.js
+ *
+ * Works out how the user invoked this CLI, so the commands it suggests are
+ * ones they can actually paste back.
+ *
+ * This matters more than it sounds. `npx activate-agentmd` does not put `agentmd`
+ * on PATH — npm caches the package under ~/.npm/_npx/<hash>/ and runs it from
+ * there. So a first-time user who ran `npx activate-agentmd init`, then followed
+ * the printed "Next: agentmd link", got `command not found` immediately after
+ * their first success.
+ *
+ * Every hint in every command goes through here.
+ */
+
+"use strict";
+
+/**
+ * npm caches npx packages under a `_npx` directory; nothing else uses it.
+ *
+ * Both separators are normalized regardless of the host platform. Keying off
+ * path.sep would mean a Windows-style path is only recognised when running on
+ * Windows, which makes the behaviour untestable anywhere else and silently
+ * wrong for any mixed-separator path.
+ */
+function isNpx(scriptPath = process.argv[1] || "") {
+  const normalized = String(scriptPath).replace(/\\/g, "/");
+  return /\/_npx\//.test(normalized) || process.env.npm_command === "exec";
+}
+
+/**
+ * The prefix to put in front of a subcommand.
+ * "npx activate-agentmd" when run through npx, otherwise the plain binary name
+ * (a global install, a devDependency run via npm scripts, or ./node_modules/.bin).
+ */
+function invocation() {
+  if (process.env.AGENTMD_INVOCATION) return process.env.AGENTMD_INVOCATION;
+  return isNpx() ? "npx activate-agentmd" : "agentmd";
+}
+
+/** Format a runnable command string, e.g. cmd("link") -> "npx activate-agentmd link". */
+function cmd(subcommand = "") {
+  const prefix = invocation();
+  return subcommand ? `${prefix} ${subcommand}` : prefix;
+}
+
+module.exports = { invocation, cmd, isNpx };

package/src/lib/license.js

@@ -0,0 +1,234 @@
+/**
+ * license.js
+ *
+ * Offline verification of Agent.md Pro license keys.
+ *
+ * A key is a signed claim, not a lookup token:
+ *
+ *     agmd_<base64url(payload JSON)>.<base64url(Ed25519 signature)>
+ *
+ * The CLI ships a **keyset** of trusted public keys and verifies the signature
+ * locally, so `agentmd extract` works on a plane, in a CI runner with no
+ * egress, and behind a proxy that blocks everything but npm. No call home on
+ * the hot path, nothing to rate-limit, and no way to forge a key without a
+ * private half.
+ *
+ * Why a keyset rather than one key: a single embedded key cannot be rotated
+ * without breaking every license already issued, and cannot be revoked at all
+ * — a compromise would mean shipping a new CLI and asking every customer to
+ * upgrade before anything improved. With key ids:
+ *
+ *   - each license names the key that signed it (`kid`)
+ *   - adding a key invalidates nothing
+ *   - retiring a key stops it signing while it keeps verifying (rotation grace)
+ *   - revoking a key kills every license under it at the next CLI update
+ *
+ * Licenses issued before `kid` existed carry none, and verify against the
+ * keyset's `legacyKid`. They keep working.
+ *
+ * The trade offline verification makes is revocation latency: a revoked key
+ * stops being trusted when the user updates the CLI, not the instant we say
+ * so. Keys are therefore dated a year at most. An online revocation check is
+ * the obvious next step and is deliberately not here yet, rather than being
+ * half-built and unreliable.
+ *
+ * Ed25519 is in Node's crypto core, so this costs no dependency.
+ */
+
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+
+/**
+ * The trusted keyset, generated from config/license-public-keys.json by
+ * scripts/build-keyset.js. Public halves only.
+ */
+const BUNDLED = require("../config/license-public-keys.json");
+
+const PREFIX = "agmd_";
+const b64url = {
+  encode: (buf) => Buffer.from(buf).toString("base64url"),
+  decode: (str) => Buffer.from(str, "base64url"),
+};
+
+/** Plans that unlock the gated commands, cheapest first. */
+const PAID_PLANS = ["pro", "team", "enterprise"];
+
+/** Statuses that can still verify. `revoked` is the whole point of the field. */
+const VERIFIES = new Set(["active", "retired"]);
+
+/**
+ * The keyset in force.
+ *
+ * Two overrides, both for self-hosting rather than convenience — an enterprise
+ * running its own registry signs its own licenses:
+ *
+ *   AGENTMD_LICENSE_KEYSET      path to a keyset JSON file, or inline JSON
+ *   AGENTMD_LICENSE_PUBLIC_KEY  one bare public key (kept from before keysets)
+ *
+ * A broken override falls back to the bundled keyset rather than failing open
+ * or closed silently: a typo in an env var must not hand someone Pro, and must
+ * not lock a paying customer out either.
+ */
+function keyset() {
+  const inline = process.env.AGENTMD_LICENSE_KEYSET;
+  if (inline) {
+    try {
+      const parsed = inline.trim().startsWith("{") ? JSON.parse(inline) : JSON.parse(fs.readFileSync(inline, "utf-8"));
+      if (parsed && Array.isArray(parsed.keys) && parsed.keys.length) return parsed;
+    } catch {
+      // unreadable or malformed — fall through to the bundled keyset
+    }
+  }
+
+  const single = process.env.AGENTMD_LICENSE_PUBLIC_KEY;
+  if (single) {
+    const kid = process.env.AGENTMD_LICENSE_KID || "env";
+    return { schema: 1, defaultKid: kid, legacyKid: kid, keys: [{ kid, alg: "ed25519", status: "active", publicKey: single }] };
+  }
+
+  return BUNDLED;
+}
+
+/** The key record for a kid, or null. */
+function findKey(kid, set = keyset()) {
+  return set.keys.find((k) => k.kid === kid) || null;
+}
+
+/**
+ * May this kid be used to *sign* a new license?
+ *
+ * Verifying and signing are deliberately different questions. A `retired` key
+ * still verifies — licenses issued under it are in customers' hands — but
+ * signing anything new with it would extend the life of a key we have already
+ * decided to stop using, and the customer would have no way to tell. Only an
+ * `active` key signs.
+ *
+ * Returns `{ ok: true }` or `{ ok: false, reason }`, phrased for an operator
+ * at a terminal rather than for a user.
+ */
+function canSign(kid, set = keyset()) {
+  const record = findKey(kid, set);
+  if (!record) {
+    return { ok: false, reason: `\`${kid}\` is not in config/license-public-keys.json. Add it, run node scripts/build-keyset.js, and ship that CLI before issuing under it.` };
+  }
+  if (record.status === "revoked") {
+    return { ok: false, reason: `\`${kid}\` is revoked. Anything signed with it is void on sight — issuing under it would produce a dead license.` };
+  }
+  if (record.status !== "active") {
+    return { ok: false, reason: `\`${kid}\` is \`${record.status}\`, not \`active\`. A retired key still verifies the licenses already issued under it, but must not sign new ones.` };
+  }
+  return { ok: true, record };
+}
+
+function publicKeyOf(record) {
+  return crypto.createPublicKey({ key: Buffer.from(record.publicKey, "base64"), format: "der", type: "spki" });
+}
+
+/**
+ * Verify a key and return its claims.
+ *
+ * Returns `{ valid: true, claims, kid }` or `{ valid: false, reason }`. Never
+ * throws on malformed input — a user pasting half a key should get a sentence,
+ * not a stack trace. Reasons read as a predicate, because they are printed
+ * after "That key …" and "The key from <source> …".
+ */
+function verify(key, set = keyset()) {
+  if (typeof key !== "string" || !key.startsWith(PREFIX)) {
+    return { valid: false, reason: "is not an Agent.md license key — one starts with `agmd_`" };
+  }
+
+  const [payloadPart, signaturePart, ...rest] = key.slice(PREFIX.length).split(".");
+  if (!payloadPart || !signaturePart || rest.length) {
+    return { valid: false, reason: "is malformed — expected `agmd_<payload>.<signature>`" };
+  }
+
+  let signature;
+  let claims;
+  try {
+    signature = b64url.decode(signaturePart);
+    claims = JSON.parse(b64url.decode(payloadPart).toString("utf-8"));
+  } catch {
+    return { valid: false, reason: "is malformed — the payload or signature is not valid base64url" };
+  }
+  if (!claims || typeof claims !== "object") {
+    return { valid: false, reason: "is malformed — the payload is not an object" };
+  }
+
+  // Which key signed this. A license from before kid support carries none and
+  // verifies against whichever key the keyset nominates as the legacy one.
+  const kid = typeof claims.kid === "string" && claims.kid ? claims.kid : set.legacyKid;
+  const record = findKey(kid, set);
+
+  if (!record) {
+    return {
+      valid: false,
+      kid,
+      reason: `names signing key \`${kid}\`, which this version of the CLI does not trust — update the CLI, or check the key was not mistyped`,
+    };
+  }
+  if (record.status === "revoked") {
+    return {
+      valid: false,
+      kid,
+      reason: `was signed with \`${kid}\`, a key that has been revoked — every license under it is void. Contact support for a replacement`,
+    };
+  }
+  if (!VERIFIES.has(record.status)) {
+    return { valid: false, kid, reason: `was signed with \`${kid}\`, which is in an unknown state (\`${record.status}\`)` };
+  }
+
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(payloadPart, "utf-8"), publicKeyOf(record), signature);
+  } catch {
+    ok = false;
+  }
+  if (!ok) return { valid: false, kid, reason: "was not issued by Agent.md — the signature does not match" };
+
+  if (!PAID_PLANS.includes(claims.plan)) {
+    return { valid: false, kid, claims, reason: `is for the \`${claims.plan || "none"}\` plan, which does not include Pro features` };
+  }
+  if (typeof claims.exp === "number" && claims.exp * 1000 < Date.now()) {
+    return { valid: false, kid, claims, reason: `expired on ${new Date(claims.exp * 1000).toISOString().slice(0, 10)}` };
+  }
+
+  return { valid: true, claims, kid };
+}
+
+/**
+ * Sign a payload. Only ever runs where a private key lives — the issuing
+ * script and its tests, never in a user's CLI.
+ *
+ * `kid` is stamped into the claims so verification knows which key to use.
+ * Omitting it produces a pre-kid license, which is only useful for proving
+ * that licenses issued before keysets still verify.
+ */
+function sign(claims, privateKeyB64, kid) {
+  const key = crypto.createPrivateKey({
+    key: Buffer.from(privateKeyB64, "base64"),
+    format: "der",
+    type: "pkcs8",
+  });
+  const body = kid ? { ...claims, kid } : { ...claims };
+  const payload = b64url.encode(JSON.stringify(body));
+  const signature = b64url.encode(crypto.sign(null, Buffer.from(payload, "utf-8"), key));
+  return `${PREFIX}${payload}.${signature}`;
+}
+
+/** Last 6 characters, for printing a key without printing the key. */
+function fingerprint(key) {
+  return typeof key === "string" && key.length > 6 ? `…${key.slice(-6)}` : "…";
+}
+
+/** Days until expiry, or null when the key never expires. */
+function daysLeft(claims) {
+  if (!claims || typeof claims.exp !== "number") return null;
+  return Math.ceil((claims.exp * 1000 - Date.now()) / 86400000);
+}
+
+module.exports = {
+  verify, sign, fingerprint, daysLeft, keyset, findKey, canSign,
+  PAID_PLANS, PREFIX, VERIFIES,
+};

package/src/lib/manifest.js

@@ -0,0 +1,191 @@
+/**
+ * manifest.js
+ *
+ * Reads and writes .agentmd/manifest.json in the user's project root.
+ * Tracks which presets are installed, their versions, checksums and paths.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const MANIFEST_DIR = ".agentmd";
+const MANIFEST_FILE = "manifest.json";
+const PRESETS_DIR = ".agentmd/presets";
+
+function getManifestPath(cwd) {
+  return path.join(cwd, MANIFEST_DIR, MANIFEST_FILE);
+}
+
+function getPresetsDir(cwd) {
+  return path.join(cwd, PRESETS_DIR);
+}
+
+function checksum(content) {
+  return "sha256-" + crypto.createHash("sha256").update(content, "utf-8").digest("hex");
+}
+
+/**
+ * Resolve a preset filename to an absolute path inside .agentmd/presets/,
+ * refusing anything that would escape it.
+ *
+ * Filenames are derived from registry coordinates, so today they are already
+ * constrained — but this is the one place the CLI turns remote-influenced data
+ * into a filesystem write, and a registry index is exactly the kind of thing
+ * an attacker would target to get `../../.bashrc` written. Check it here so
+ * every caller is covered rather than trusting each one to remember.
+ */
+function resolvePresetPath(cwd, filename) {
+  if (typeof filename !== "string" || filename.length === 0) {
+    throw new Error("Invalid preset filename");
+  }
+  const dir = path.resolve(getPresetsDir(cwd));
+  const target = path.resolve(dir, filename);
+  if (target !== path.join(dir, path.basename(target)) || !target.startsWith(dir + path.sep)) {
+    throw new Error(`Refusing to write outside ${PRESETS_DIR}/: ${filename}`);
+  }
+  return target;
+}
+
+/**
+ * Resolve a path the CLI is about to write inside the project, refusing
+ * anything that escapes it.
+ *
+ * `link` writes outside `.agentmd/` by design — CLAUDE.md, .cursor/rules/,
+ * .github/instructions/, and one file per detected workspace. Those paths are
+ * built from category and preset names and from a directory walk, so they are
+ * constrained today; this makes that a property of the code rather than of
+ * every caller remembering. Symlinks are resolved so a linked directory cannot
+ * be used to step outside the project either.
+ */
+function resolveInProject(cwd, relative) {
+  if (typeof relative !== "string" || relative.length === 0) {
+    throw new Error("Invalid path");
+  }
+  if (path.isAbsolute(relative)) {
+    throw new Error(`Refusing to write to an absolute path: ${relative}`);
+  }
+  const root = realpath(path.resolve(cwd));
+  const target = path.resolve(root, relative);
+  // The file itself may not exist yet; its nearest existing ancestor must
+  // still live inside the project once symlinks are followed.
+  let existing = target;
+  while (!fs.existsSync(existing) && path.dirname(existing) !== existing) existing = path.dirname(existing);
+  const real = realpath(existing);
+  if (real !== root && !real.startsWith(root + path.sep)) {
+    throw new Error(`Refusing to write outside the project: ${relative}`);
+  }
+  return target;
+}
+
+function realpath(p) {
+  try { return fs.realpathSync(p); } catch { return p; }
+}
+
+/**
+ * Turn registry coordinates into a flat, filesystem-safe preset filename.
+ *
+ * The model is part of the name. Without it, claude/Security/owasp and
+ * grok/Security/owasp both resolved to Security-owasp.md — two manifest
+ * entries pointing at one file, so whichever installed last silently replaced
+ * the other while the manifest still claimed both were present.
+ *
+ * Runs of dots collapse to one, and leading dots are stripped, so no input can
+ * produce a `..` segment or a hidden file. Package names like `linear.app` and
+ * `x.ai` keep their single dot.
+ */
+function presetFilename(model, category, preset) {
+  const slug = (s) =>
+    String(s)
+      .replace(/[^a-zA-Z0-9._-]+/g, "-")
+      .replace(/\.{2,}/g, ".")
+      .replace(/^[.\-]+|[-]+$/g, "");
+  return `${slug(model)}-${slug(category)}-${slug(preset)}.md`;
+}
+
+/** Read the existing manifest, or return a fresh one. */
+function readManifest(cwd) {
+  const manifestPath = getManifestPath(cwd);
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+      if (!Array.isArray(parsed.presets)) parsed.presets = [];
+      return parsed;
+    } catch {
+      // Corrupt manifest — start fresh rather than crashing the install.
+    }
+  }
+  return { version: "1", installedAt: new Date().toISOString(), presets: [] };
+}
+
+/** Write the manifest, creating .agentmd/ if needed. */
+function writeManifest(cwd, manifest) {
+  fs.mkdirSync(path.join(cwd, MANIFEST_DIR), { recursive: true });
+  manifest.presets.sort((a, b) => a.id.localeCompare(b.id));
+  fs.writeFileSync(getManifestPath(cwd), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+function ensurePresetsDir(cwd) {
+  const dir = getPresetsDir(cwd);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Add or replace a preset entry. */
+function upsertPreset(manifest, entry) {
+  const record = {
+    id: entry.id,
+    model: entry.model,
+    category: entry.category,
+    preset: entry.preset,
+    version: entry.version,
+    checksum: entry.checksum,
+    source: entry.url,
+    installedAt: new Date().toISOString(),
+    file: entry.file,
+  };
+  const index = manifest.presets.findIndex((p) => p.id === record.id);
+  if (index >= 0) {
+    record.installedAt = manifest.presets[index].installedAt;
+    record.updatedAt = new Date().toISOString();
+    manifest.presets[index] = record;
+  } else {
+    manifest.presets.push(record);
+  }
+  return record;
+}
+
+function findPreset(manifest, id) {
+  return manifest.presets.find((p) => p.id.toLowerCase() === String(id).toLowerCase()) || null;
+}
+
+function isInstalled(manifest, model, category, preset) {
+  return findPreset(manifest, `${model}/${category}/${preset}`) !== null;
+}
+
+/** Drop an entry from the manifest. Returns the removed record, or null. */
+function removePreset(manifest, id) {
+  const index = manifest.presets.findIndex((p) => p.id.toLowerCase() === String(id).toLowerCase());
+  if (index < 0) return null;
+  return manifest.presets.splice(index, 1)[0];
+}
+
+module.exports = {
+  readManifest,
+  writeManifest,
+  ensurePresetsDir,
+  upsertPreset,
+  findPreset,
+  removePreset,
+  isInstalled,
+  getManifestPath,
+  getPresetsDir,
+  resolvePresetPath,
+  resolveInProject,
+  presetFilename,
+  checksum,
+  MANIFEST_DIR,
+  PRESETS_DIR,
+};