skillcellar 0.3.0 → 0.6.0

package/src/project.mjs

@@ -25,6 +25,21 @@ function originUrl(root) {
   });
 }
 
+/**
+ * The files a checkout's git tracks, by their path from its root with forward slashes; an empty set
+ * when git is missing or the folder is no checkout. A clone brings these, so a backup leaves them out.
+ */
+export function trackedFiles(root) {
+  return new Promise((done) => {
+    execFile(
+      "git",
+      ["-C", root, "ls-files", "-z"],
+      { timeout: 10_000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" } },
+      (error, stdout) => done(new Set(error ? [] : stdout.split("\0").filter(Boolean))),
+    );
+  });
+}
+
 /**
  * A remote's last two path segments, `owner/repo`, and whether it is a GitHub repository: from an
  * https, ssh or git address, or an scp-style user@host:path whose host has a dot. Anything else, a

package/src/restore.mjs

@@ -0,0 +1,345 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { ensureMirror, git, gitBuffer, parseBackupRepo, refusePublic } from "./backup.mjs";
+import { sessionFolderName } from "./places.mjs";
+import { sentName, toSlug } from "./plan.mjs";
+import { ask, interactive } from "./prompt.mjs";
+import { checkProjectSkills, installPulled } from "./pull.mjs";
+import { findSecret, oddReferencesIn, placeholdersIn } from "./secrets.mjs";
+
+// The folder Claude Code's own skillcellar skill lives in: nothing restored may take its place.
+const RESERVED_SLUG = "skillcellar";
+// What a restore reads from the backup at most, as a backup's caps.
+const FILES_MAX = 20_000;
+const BYTES_MAX = 256 * 1024 * 1024;
+// The install commands a copy may hand over, in the shapes the site's plan gives them.
+const NPX_SKILLS_RE = /^npx skills add https:\/\/github\.com\/[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}(?: --skill [A-Za-z0-9][A-Za-z0-9._@+-]{0,127})?$/;
+const PLUGIN_RE = /^\/plugin (?:marketplace add [A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}, then \/plugin install |marketplace add https:\/\/[A-Za-z0-9._~:/%+-]+, then \/plugin install |install )[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/;
+
+/** A path that stays inside its base folder, or null. */
+function inside(base, ...segments) {
+  const path = join(base, ...segments);
+  const from = relative(base, path);
+  return from && !from.startsWith("..") && !isAbsolute(from) ? path : null;
+}
+
+/**
+ * The backup's files at one commit, by path: the mode and the blob of each entry. Read from the
+ * mirror's objects, never a checkout, so a link in the repository is listed and never followed.
+ */
+async function treeAt(mirror, commit) {
+  const listing = await git(["--git-dir", mirror, "ls-tree", "-r", "-z", commit, "--", "devices"]);
+  const entries = new Map();
+  for (const line of listing.split("\0").filter(Boolean)) {
+    const match = /^(\d{6}) (\w+) ([0-9a-f]{40})\t(.+)$/s.exec(line);
+    if (match) entries.set(match[4], { mode: match[1], type: match[2], sha: match[3] });
+  }
+  return entries;
+}
+
+const regular = (entry) => entry?.type === "blob" && (entry.mode === "100644" || entry.mode === "100755");
+
+/** A blob's bytes, counted against the caps. */
+async function blobOf(mirror, entry, budget) {
+  const content = await gitBuffer(["--git-dir", mirror, "cat-file", "blob", entry.sha]);
+  budget.files += 1;
+  budget.bytes += content.length;
+  if (budget.files > FILES_MAX || budget.bytes > BYTES_MAX) throw new Error(`The backup holds more than ${FILES_MAX.toLocaleString("en")} files or ${BYTES_MAX / 1024 / 1024} MB: nothing more is restored.`);
+  return content;
+}
+
+const readJsonBlob = async (mirror, entry, budget) => {
+  if (!regular(entry)) return null;
+  try {
+    return JSON.parse((await blobOf(mirror, entry, budget)).toString("utf8"));
+  } catch {
+    return null;
+  }
+};
+
+/** The folder of a device in the backup: the one whose manifest names its id, else the one of its slug. */
+async function deviceFolder(mirror, tree, device, budget) {
+  for (const path of tree.keys()) {
+    const match = /^devices\/([^/]+)\/manifest\.json$/.exec(path);
+    if (!match) continue;
+    const manifest = await readJsonBlob(mirror, tree.get(path), budget);
+    if (manifest?.device?.id === device.id) return { folder: `devices/${match[1]}`, manifest };
+  }
+  const manifest = await readJsonBlob(mirror, tree.get(`devices/${device.slug}/manifest.json`), budget);
+  return manifest ? { folder: `devices/${device.slug}`, manifest } : null;
+}
+
+/** The backup folder of a task's place: global, or the project's by its repository, its slug or its name. */
+function placeFolder(found, task) {
+  if (!task.project) return `${found.folder}/global`;
+  const places = Array.isArray(found.manifest?.places) ? found.manifest.places : [];
+  const place =
+    (task.project.repo && places.find((entry) => entry.repo === task.project.repo)) ??
+    places.find((entry) => entry.folder === `projects/${task.project.slug}`) ??
+    places.find((entry) => typeof entry.name === "string" && toSlug(entry.name) === task.project.slug);
+  if (!place || typeof place.folder !== "string" || !/^projects\/[a-z0-9-]+$/.test(place.folder)) return null;
+  return `${found.folder}/${place.folder}`;
+}
+
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+
+/** Writes one file into place; "exists" when one is there already and `force` is not set, "link" when the target is a link. */
+async function placeFile(content, target, force) {
+  const there = await lstat(target).catch(() => null);
+  if (there?.isSymbolicLink()) return "link";
+  if (there && !force) return "exists";
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return "copied";
+}
+
+const ENVIRONMENTS = [
+  ["package.json", "npm install"],
+  ["requirements.txt", "pip install -r requirements.txt"],
+  ["pyproject.toml", "pip install . (or uv sync)"],
+  ["playwright.config.ts", "npx playwright install"],
+  ["playwright.config.js", "npx playwright install"],
+];
+
+/** The environments a restored skill folder names, each with the command that rebuilds it. */
+async function environmentsOf(folder) {
+  const hints = [];
+  for (const [file, command] of ENVIRONMENTS) if ((await stat(join(folder, file)).catch(() => null))?.isFile()) hints.push(`${file} (${command})`);
+  return hints;
+}
+
+/** Refuses a project whose `.claude` or the folder written into is a link: a cloned repository can carry one that points anywhere. */
+async function checkProjectFolder(root, sub) {
+  await checkProjectSkills(root);
+  const path = join(root, ".claude", sub);
+  if ((await lstat(path).catch(() => null))?.isSymbolicLink()) throw new Error(`${path} is a link, so a file could land outside the project.`);
+}
+
+/**
+ * One item of a copy, in one place: files from the backup are written into Claude Code's folders,
+ * once they match what the source reported and hold nothing that looks like a secret, and what a
+ * command installs, a plugin, a skill from a repository or an MCP server, is answered as that
+ * command for Claude Code or the user to run. Nothing is run here.
+ */
+async function restoreItem(item, { mirror, tree, budget, place, scope, root, claudeDir, force, dryRun }) {
+  const { kind, name } = item;
+  if (item.tracked) return { outcome: "repository" };
+  if (kind === "plugin" || (kind === "skill" && item.install)) {
+    const command = item.install?.command;
+    if (typeof command !== "string") return { outcome: "missing" };
+    return (kind === "plugin" ? PLUGIN_RE : NPX_SKILLS_RE).test(command) ? { outcome: "command", command } : { outcome: "odd-command", command };
+  }
+  if (!["skill", "mcp", "memory", "agent"].includes(kind)) return { outcome: "unknown-kind" };
+  if (!sentName(kind, name, scope === "project")) return { outcome: "unsendable" };
+  const own = (...segments) => join(root ?? claudeDir, ...(root ? [".claude"] : []), ...segments);
+  if (kind === "mcp") {
+    const local = await readJsonBlob(mirror, tree.get(`${place}/mcp.local.json`), budget);
+    const shared = await readJsonBlob(mirror, tree.get(`${place}/mcp.json`), budget);
+    const holds = (json) => json?.mcpServers && typeof json.mcpServers === "object" && Object.hasOwn(json.mcpServers, name);
+    const fromLocal = holds(local);
+    const server = fromLocal ? local.mcpServers[name] : holds(shared) ? shared.mcpServers[name] : null;
+    if (!server || typeof server !== "object") return { outcome: "missing" };
+    const json = JSON.stringify(server);
+    const claudeScope = scope === "global" ? "user" : fromLocal ? "local" : "project";
+    const review = [...oddReferencesIn(json), ...("headersHelper" in server ? ["headersHelper, a command that fetches a credential"] : [])];
+    return { outcome: "command", command: `claude mcp add-json ${name} '${json.replaceAll("'", "'\\''")}' --scope ${claudeScope}`, placeholders: placeholdersIn(json), review };
+  }
+  if (kind === "skill") {
+    if (name === RESERVED_SLUG) return { outcome: "reserved" };
+    const prefix = `${place}/skills/${name}/`;
+    const files = [];
+    for (const [path, entry] of tree) {
+      if (!path.startsWith(prefix)) continue;
+      if (!regular(entry)) return { outcome: "link", path };
+      const content = await blobOf(mirror, entry, budget);
+      const found = findSecret(content.toString("utf8"));
+      if (found) return { outcome: "secret", path, line: found.line, kind: found.kind };
+      files.push({ segments: path.slice(prefix.length).split("/"), content, executable: entry.mode === "100755" });
+    }
+    if (!files.length) return { outcome: "missing" };
+    if (root) await checkProjectFolder(root, "skills");
+    const skills = own("skills");
+    const target = join(skills, name);
+    if (dryRun) return { outcome: (await lstat(target).catch(() => null)) && !force ? "exists" : "copied", target };
+    try {
+      await installPulled(skills, { slug: name, files }, force);
+    } catch (error) {
+      if (/is there already/.test(error.message)) return { outcome: "exists", target };
+      throw error;
+    }
+    return { outcome: "copied", target, environments: await environmentsOf(target) };
+  }
+  let path;
+  let target;
+  if (kind === "agent") {
+    path = `${place}/agents/${name}.md`;
+    if (root) await checkProjectFolder(root, "agents");
+    target = inside(own("agents"), `${name}.md`);
+  } else {
+    const [first, ...rest] = name.split("/");
+    path = `${place}/${name}`;
+    if (first === "rules") {
+      if (root) await checkProjectFolder(root, "rules");
+      target = inside(own("rules"), ...rest);
+    } else if (first === "memory" && root) target = inside(join(claudeDir, "projects", sessionFolderName(root), "memory"), ...rest);
+    else target = join(root ?? claudeDir, name);
+  }
+  const entry = tree.get(path);
+  if (!entry) return { outcome: "missing" };
+  if (!regular(entry)) return { outcome: "link", path };
+  if (!target) return { outcome: "unsendable" };
+  const content = await blobOf(mirror, entry, budget);
+  // The site holds the file's hash as the source reported it: a file that differs is not the source's.
+  if (item.hash && sha256(content) !== item.hash) return { outcome: "differs" };
+  const found = findSecret(content.toString("utf8"));
+  if (found) return { outcome: "secret", path, line: found.line, kind: found.kind };
+  if (dryRun) return { outcome: (await lstat(target).catch(() => null)) && !force ? "exists" : "copied", target };
+  return { outcome: await placeFile(content, target, force), target };
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+/**
+ * Whether this computer may take the backup from the repository the site names: it is the one this
+ * computer backs up to, the user named it with --repo, or the user says yes at the terminal. The
+ * site's word alone is not enough: a key that could write it could name another repository.
+ */
+async function trustedRepo(repo, source, config, flags) {
+  if (config?.backup?.repo === repo.name) return true;
+  if (typeof flags.repo === "string") return parseBackupRepo(flags.repo)?.name === repo.name;
+  if (!interactive()) return false;
+  return /^y(es)?$/i.test(await ask(`The site names ${source.device.name}'s backup as ${repo.name}. Clone it and restore from it? [y/N] `));
+}
+
+/** What one restored item came to, as a line. */
+function describe(result, label, source, dryRun) {
+  switch (result.outcome) {
+    case "copied":
+      return `${dryRun ? "would copy" : "copied"} ${label} to ${result.target}`;
+    case "exists":
+      return `kept ${label}: ${result.target} is there already (run again with --force to replace it)`;
+    case "odd-command":
+      return `${label}: its install command is not one this tool hands over (${result.command.slice(0, 80)}); install it from the site's page`;
+    case "repository":
+      return `${label}: tracked by the project's git; pull the repository to bring it`;
+    case "unsendable":
+      return `${label}: not a name a sync sends from this place; dismiss the task on the site`;
+    case "unknown-kind":
+      return `${label}: not a kind this tool restores`;
+    case "reserved":
+      return `${label}: the skillcellar skill itself; run skillcellar skill to update it`;
+    case "link":
+      return result.path ? `${label}: ${result.path} is a link in the backup, which is not restored` : `kept ${label}: ${result.target} is a link`;
+    case "secret":
+      return `${label}: ${result.path}:${result.line} in the backup looks like ${result.kind}; not restored`;
+    case "differs":
+      return `${label}: the backup's copy differs from what ${source.device.name} reported; run skillcellar backup there again`;
+    default:
+      return `${label}: not in the backup`;
+  }
+}
+
+/**
+ * Carries out the copy tasks of the plan whose source has a backup: refuses a public repository and
+ * one this computer was not told to trust, fetches the backup into a bare mirror with the user's own
+ * git, reads the commit the site recorded, writes skills, memory files and agents into place, and
+ * lists the commands left to run.
+ */
+export async function runRestore({ plan, claudeDir, config, flags, version, print, warn }) {
+  const force = flags.force === true;
+  const dryRun = flags["dry-run"] === true;
+  const from = typeof flags.from === "string" ? flags.from.trim().toLowerCase() : null;
+  const wanted = (plan.tasks ?? []).filter(
+    (task) => task.action === "copy" && task.copy && (!from || task.copy.from.device.slug === from || task.copy.from.device.name.toLowerCase() === from),
+  );
+  if (!wanted.length) {
+    print(from ? `No copy task from ${flags.from} waits for ${plan.device.name}.` : `No copy task waits for ${plan.device.name}.`);
+    return;
+  }
+  const bySource = new Map();
+  for (const task of wanted) bySource.set(task.copy.from.device.id, [...(bySource.get(task.copy.from.device.id) ?? []), task]);
+
+  const commands = [];
+  const environments = [];
+  // Two tasks can name one item in one place, such as a copy of it and a copy of everything there: it is brought over once.
+  const done = new Set();
+  let copied = 0;
+  for (const tasks of bySource.values()) {
+    const source = tasks[0].copy.from;
+    if (!source.backup) {
+      warn(`No backup of ${source.device.name} yet: run skillcellar backup there, then skillcellar restore here again. Its ${plural(tasks.length, "copy task")} wait.`);
+      continue;
+    }
+    const repo = parseBackupRepo(source.backup.repo, flags.ssh === true || config?.backup?.ssh === true);
+    if (!repo) {
+      warn(`The site names ${source.device.name}'s backup as ${source.backup.repo}, which is not a GitHub repository. Its tasks wait.`);
+      continue;
+    }
+    if (!(await trustedRepo(repo, source, config, flags))) {
+      warn(`Not restored: the site names ${source.device.name}'s backup as ${repo.name}, which this computer does not back up to. Check it is yours, then run skillcellar restore --repo ${repo.name}.`);
+      continue;
+    }
+    await refusePublic(repo, version);
+    const mirror = await ensureMirror(repo);
+    const commit = source.backup.commit;
+    const known = await git(["--git-dir", mirror, "cat-file", "-e", `${commit}^{commit}`]).then(() => true, () => false);
+    if (!known) {
+      warn(`The backup's commit ${commit.slice(0, 7)} is not in ${repo.name}: run skillcellar backup on ${source.device.name} again, then restore here. Its tasks wait.`);
+      continue;
+    }
+    const budget = { files: 0, bytes: 0 };
+    const tree = await treeAt(mirror, commit);
+    const found = await deviceFolder(mirror, tree, source.device, budget);
+    if (!found) {
+      warn(`${repo.name} at ${commit.slice(0, 7)} holds no backup of ${source.device.name}. Run skillcellar backup there, then restore here again.`);
+      continue;
+    }
+    print(`${dryRun ? "Would restore" : "Restoring"} from ${source.device.name}'s backup, ${repo.name} at ${commit.slice(0, 7)}:`);
+    for (const task of tasks) {
+      const where = task.project ? `in ${task.project.name}` : "globally";
+      if (task.problem) {
+        print(`  ${where}: ${task.problem} Dismiss the task on the site.`);
+        continue;
+      }
+      if (task.project && !task.folder) {
+        print(`  ${where}: this computer has no folder of ${task.project.name}; clone it, then run skillcellar restore from inside it.`);
+        continue;
+      }
+      const place = placeFolder(found, task);
+      if (!place) {
+        print(`  ${where}: the backup holds nothing for this place.`);
+        continue;
+      }
+      if (!task.copy.items.length) print(`  ${where}: nothing left to copy; the next sync closes the task.`);
+      for (const item of task.copy.items) {
+        const label = `${item.kind} ${item.name}`;
+        const key = `${place}/${label}`;
+        if (done.has(key)) {
+          print(`  ${label}: brought over above`);
+          continue;
+        }
+        done.add(key);
+        const result = await restoreItem(item, { mirror, tree, budget, place, scope: task.scope, root: task.folder, claudeDir, force, dryRun });
+        if (result.outcome === "command") {
+          commands.push({ task: where, label, ...result });
+          continue;
+        }
+        if (result.outcome === "copied") {
+          copied += 1;
+          for (const hint of result.environments ?? []) environments.push(`${item.name} has ${hint}`);
+        }
+        print(`  ${describe(result, label, source, dryRun)}`);
+      }
+    }
+  }
+  if (commands.length) {
+    print("To run, each in the folder of its task (a command with a ${NAME} placeholder, or one marked for review, is for the user to run):");
+    for (const entry of commands) {
+      const notes = [...(entry.placeholders?.length ? [`needs ${entry.placeholders.join(", ")}`] : []), ...(entry.review?.length ? [`review: ${entry.review.join(", ")}`] : [])];
+      print(`  ${entry.task}: ${entry.command}${notes.length ? `   (${notes.join("; ")})` : ""}`);
+    }
+  }
+  if (environments.length) print(`Rebuild: ${environments.join("; ")}.`);
+  if (!dryRun) print(`${copied ? `Copied ${plural(copied, "item")}. ` : ""}Run skillcellar sync to close the tasks that are done.`);
+}

package/src/scan.mjs

@@ -1,5 +1,5 @@
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { agentItems, memoryItems } from "./files.mjs";
 import { folderHash } from "./hash.mjs";
 import { mcpItems } from "./mcp.mjs";
@@ -76,12 +76,17 @@ function lockSource(entry) {
   return rest.length || !owner || !repo ? null : githubRepository(owner, repo);
 }
 
-/** The folder a lock entry's SKILL.md sits in, relative to its repository; null at the root or when odd. */
-function lockFolder(entry) {
+/**
+ * Where a lock entry's SKILL.md sits in its repository: `{ folder }`, null for the repository's
+ * root; or null for an entry whose folder the sync cannot send as it is (odd characters, over 200
+ * characters, or no path at all), which must not pass for the root.
+ */
+export function lockFolder(entry) {
   if (typeof entry?.skillPath !== "string") return null;
   const folder = entry.skillPath.replaceAll("\\", "/").replace(/(^|\/)SKILL\.md$/, "");
+  if (!folder) return { folder: null };
   const segments = folder.split("/");
-  return folder && folder.length <= PATH_MAX && segments.every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..") ? folder : null;
+  return folder.length <= PATH_MAX && segments.every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..") ? { folder } : null;
 }
 
 /**
@@ -132,21 +137,27 @@ function lockEntries(lock) {
 
 /**
  * A skill folder as the sync sends it. A folder `npx skills` installed carries what its lock
- * records: the repository, the folder in it and its hash; any other is hashed here.
+ * records: the repository, the folder in it and its hash; any other is hashed here, as is one
+ * whose lock names a folder the sync cannot send, since a tree hash without its folder would be
+ * read as the root's.
  */
-async function skillItem(folder, locked, lockHashKind) {
+async function skillItem(folder, locked, lockHashKind, tracked) {
   const entry = locked.get(folder.name);
   const source = lockSource(entry);
+  const located = lockFolder(entry);
   const lockHash = lockHashKind === "git-tree" ? entry?.skillFolderHash : entry?.computedHash;
-  if (source && typeof lockHash === "string" && /^[0-9a-f]+$/.test(lockHash) && lockHash.length === (lockHashKind === "git-tree" ? 40 : 64)) {
-    return { kind: "skill", name: folder.name, source, skillPath: lockFolder(entry), hash: lockHash, hashKind: lockHashKind, version: null };
+  if (source && located && typeof lockHash === "string" && /^[0-9a-f]+$/.test(lockHash) && lockHash.length === (lockHashKind === "git-tree" ? 40 : 64)) {
+    return { kind: "skill", name: folder.name, source, skillPath: located.folder, hash: lockHash, hashKind: lockHashKind, version: null, tracked };
   }
   // A file that cannot be read, or vanished meanwhile, costs only this folder its hash.
   const hash = await folderHash(folder.path).catch(() => null);
-  return { kind: "skill", name: folder.name, source, skillPath: source ? lockFolder(entry) : null, hash, hashKind: hash ? "sha256" : null, version: null };
+  return { kind: "skill", name: folder.name, source, skillPath: source ? (located?.folder ?? null) : null, hash, hashKind: hash ? "sha256" : null, version: null, tracked };
 }
 
-async function skillItems(dir, lock, lockHashKind, skipped) {
+/** Whether a project's git tracks a file, by its path from the project's root. */
+export const isTracked = (tracked, root, path) => tracked.has(relative(root, path).split("\\").join("/"));
+
+async function skillItems(dir, lock, lockHashKind, skipped, trackedIn = null) {
   const items = [];
   const locked = lockEntries(lock);
   for (const folder of await skillFolders(dir)) {
@@ -154,7 +165,9 @@ async function skillItems(dir, lock, lockHashKind, skipped) {
       skipped.push(folder.name);
       continue;
     }
-    items.push(await skillItem(folder, locked, lockHashKind));
+    // A skill is the project's own when its SKILL.md is.
+    const tracked = trackedIn ? isTracked(trackedIn.tracked, trackedIn.root, join(folder.path, "SKILL.md")) : false;
+    items.push(await skillItem(folder, locked, lockHashKind, tracked));
   }
   return items;
 }
@@ -203,6 +216,7 @@ async function pluginItems(claudeDir, projectFolders, skipped) {
       hash: null,
       hashKind: version ? "version" : null,
       version,
+      tracked: false,
     });
   }
   return items.sort(byName);
@@ -255,14 +269,15 @@ export async function scanGlobal({ home, claudeDir, claudeJson }) {
  * CLAUDE.md, AGENTS.md and rules, the session memory of each folder Claude Code ran in, and its
  * agents.
  */
-export async function scanProject({ root, folders = [root], claudeDir, claudeJson }) {
+export async function scanProject({ root, folders = [root], claudeDir, claudeJson, tracked = new Set() }) {
   const skipped = [];
   const lock = await readJson(join(root, "skills-lock.json"));
   const mcpJson = await readJson(join(root, ".mcp.json"));
+  const own = { tracked, root };
   const items = [
-    ...(await skillItems(join(root, ".claude", "skills"), lock, "sha256", skipped)),
+    ...(await skillItems(join(root, ".claude", "skills"), lock, "sha256", skipped, own)),
     ...(await pluginItems(claudeDir, [root, ...folders], skipped)),
-    ...mcpItems(mcpJson?.mcpServers, skipped),
+    ...mcpItems(mcpJson?.mcpServers, skipped).map((item) => ({ ...item, tracked: tracked.has(".mcp.json") })),
     ...folders.flatMap((folder) => mcpItems(claudeJson?.projects?.[folder]?.mcpServers, skipped)),
     ...(await memoryItems(
       [
@@ -274,8 +289,9 @@ export async function scanProject({ root, folders = [root], claudeDir, claudeJso
         ...[...new Set([root, ...folders])].map((folder) => ({ name: "memory", dir: join(claudeDir, "projects", sessionFolderName(folder), "memory"), deep: false })),
       ],
       skipped,
+      own,
     )),
-    ...(await agentItems(join(root, ".claude", "agents"), skipped)),
+    ...(await agentItems(join(root, ".claude", "agents"), skipped, own)),
   ];
   return { items: distinct(items), skipped };
 }

package/src/secrets.mjs

@@ -0,0 +1,65 @@
+// What stops a backup: a line that looks like a key, a token or a password. Each pattern is bounded,
+// so a line of any length is read in one pass, and a placeholder such as ${NAME}, $NAME, <your key>
+// or your_api_key is not a secret. A finding is a reason to look, not proof: the backup stops either
+// way, and a key of a shape no pattern knows is not found.
+
+// A key stands alone: nothing alphanumeric right before or after it, so STRIPE_API_KEY= and "apiKey"
+// count, which a word boundary would miss between _ and a letter.
+const EDGE = String.raw`(?<![A-Za-z0-9])`;
+const END = String.raw`(?![A-Za-z0-9])`;
+// A value that is not a placeholder, a variable, a template, an example or a reference into config or code.
+const NOT_PLACEHOLDER = String.raw`(?!\$\{|\$[A-Za-z_]|<|\{\{|%|your[_-]|xxx|example|placeholder|change[_-]?me|redacted|none\b|null\b|true\b|false\b|\*{3}|process\.|os\.|env\.|config\.|settings\.|this\.|self\.)`;
+
+const PATTERNS = [
+  ["a private key", /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/],
+  ["an AWS access key", new RegExp(String.raw`${EDGE}AKIA[0-9A-Z]{16}${END}`)],
+  ["a GitHub token", new RegExp(String.raw`${EDGE}(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})${END}`)],
+  ["an OpenAI or Anthropic key", new RegExp(String.raw`${EDGE}sk-(?:proj-|ant-|svcacct-)?[A-Za-z0-9_-]{20,255}(?![A-Za-z0-9_-])`)],
+  ["a Slack token", new RegExp(String.raw`${EDGE}xox[abeprs]-[A-Za-z0-9-]{10,255}(?![A-Za-z0-9-])`)],
+  ["a Stripe key", new RegExp(String.raw`${EDGE}(?:[sr]k_(?:live|test)_[A-Za-z0-9]{16,255}|whsec_[A-Za-z0-9]{16,255})${END}`)],
+  ["a Google API key", new RegExp(String.raw`${EDGE}AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9_-])`)],
+  ["a SkillCellar API key", new RegExp(String.raw`${EDGE}skc_[A-Za-z0-9]{64}${END}`)],
+  ["an npm token", new RegExp(String.raw`${EDGE}npm_[A-Za-z0-9]{36}${END}`)],
+  ["a Neon API key", new RegExp(String.raw`${EDGE}napi_[a-z0-9]{40,255}${END}`)],
+  ["a Resend, Hugging Face or Groq key", new RegExp(String.raw`${EDGE}(?:re_[A-Za-z0-9_]{20,255}|hf_[A-Za-z0-9]{20,255}|gsk_[A-Za-z0-9]{20,255})${END}`)],
+  ["a JSON Web Token", new RegExp(String.raw`${EDGE}eyJ[A-Za-z0-9_-]{10,2000}\.[A-Za-z0-9_-]{10,2000}\.[A-Za-z0-9_-]{10,2000}(?![A-Za-z0-9_-])`)],
+  // user:password@host in an address of any scheme, unless the password is a placeholder.
+  ["a password in an address", /[a-z][a-z0-9+.-]{0,30}:\/\/[^\s/@:'"]{1,100}:(?!\$\{)[^\s/@'"]{1,200}@/i],
+  ["a bearer or basic credential", new RegExp(String.raw`\b(?:Bearer|Basic)\s{1,5}(?!\$\{|\$[A-Za-z_]|<)[A-Za-z0-9_\-./+=]{16,2000}(?![A-Za-z0-9_\-./+=])`)],
+  // A key named as one, assigned a value with a digit in it, as random keys have; the name may be quoted, as in JSON.
+  [
+    "a key or password in an assignment",
+    new RegExp(
+      String.raw`${EDGE}(?:api[_-]?key|apikey|secret[_-]?(?:access[_-]?)?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|password|passwd|secret|token)${END}["'\x60]?\s{0,5}[:=]\s{0,5}["'\x60]?${NOT_PLACEHOLDER}(?=[A-Za-z0-9_\-./+=]{0,254}[0-9])[A-Za-z0-9_\-./+=]{8,255}`,
+      "i",
+    ),
+  ],
+];
+
+/**
+ * The first line of a text that looks like a secret, as `{ line, kind }` (the line counted from
+ * 1), or null. Lines are read one by one, so the file's size sets the cost, never a pattern.
+ */
+export function findSecret(text) {
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    for (const [kind, pattern] of PATTERNS) if (pattern.test(line)) return { line: index + 1, kind };
+  }
+  return null;
+}
+
+/** The placeholders a sanitized MCP config holds, such as ${CONTEXT7_KEY}, in order and once each. */
+export function placeholdersIn(text) {
+  return [...new Set(Array.from(text.matchAll(/\$\{([A-Z0-9_]{1,80})\}/g), (match) => match[0]))];
+}
+
+/**
+ * References in an MCP config that Claude Code would expand from the environment and that are not
+ * plain placeholders: `${VAR:-default}`, `$VAR`, or a placeholder of another shape. Each is a reason
+ * to read the server's config before adding it, since it reaches into the user's environment.
+ */
+export function oddReferencesIn(text) {
+  const all = Array.from(text.matchAll(/\$\{[^}]{0,200}\}|\$[A-Za-z_][A-Za-z0-9_]{0,80}/g), (match) => match[0]);
+  return [...new Set(all.filter((reference) => !/^\$\{[A-Z0-9_]{1,80}\}$/.test(reference)))];
+}