skillcellar 0.6.0 → 0.6.1

package/README.md

@@ -29,14 +29,14 @@ Both read this computer as `sync` does and send that list as `sync` sends it (na
 
 ## Backups
 
-`skillcellar backup --repo <owner>/<repo>` pushes this computer's Claude Code setup to a private GitHub repository you own, with your own git and its credentials, under `devices/<device>/`: `global/` holds your skills' source files, `CLAUDE.md`, `rules/`, `agents/` and `mcp.json`; `projects/<project>/` holds the same for each project, with its `AGENTS.md`, the session memory Claude Code keeps for it under `memory/`, and its MCP servers in `mcp.json` (the project's `.mcp.json`) and `mcp.local.json` (those Claude Code keeps for its folders). A `manifest.json` names the device and its projects. The repository is remembered, so `skillcellar backup` alone works from then on; `--ssh` clones and pushes over SSH, and `--dry-run` lists what would go without cloning, committing or pushing.
+`skillcellar backup --repo <owner>/<repo>` pushes this computer's Claude Code setup to a private GitHub repository you own, with your own git and its credentials, under `devices/<device>/`: `global/` holds your skills' source files, `CLAUDE.md`, `rules/`, `agents/` and `mcp.json`; `projects/<project>/` holds the same for each project, with its `AGENTS.md`, the session memory Claude Code keeps for it under `memory/`, and its MCP servers in `mcp.json` (the project's `.mcp.json`) and `mcp.local.json` (those Claude Code keeps for its folders). A project checked out more than once on the computer is one project, as on the site: every checkout goes in its one folder, and where two hold a file or a skill of the same name, the one the sync sends first goes and the other is listed as left out. MCP servers of the same name are kept once the same way, but separately in `mcp.json` and in `mcp.local.json`, and the one left out is not listed. A `manifest.json` names the device and its projects. The repository is remembered, so `skillcellar backup` alone works from then on; `--ssh` clones and pushes over SSH, and `--dry-run` lists what would go without cloning, committing or pushing.
 
 - In the MCP config every `env` and header value, an address's credentials and its query's values, the parts of its path that are not short words, and an argument that looks like a key are replaced by a placeholder, named after its key where one exists (`${CONTEXT7_KEY}`), else `${ARG_n}` or `${PATH_n}`. A key of a shape the check does not know, in another field, or given as a bare argument shorter than 16 characters, stays: read the backup once before you rely on it.
 - Source files are text of a known kind (Markdown, code, JSON, YAML and the like) under 1 MB. Folders of installed packages, caches and build output (`node_modules`, `vendor`, `.venv`, `venv`, `env`, `__pycache__`, `.git`, `.cache`, `.next`, `.turbo`, `.nuxt`, `.svelte-kit`, `dist`, `build`, `target`, `coverage`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `.gradle` and `ms-playwright`) are left out at any depth, as are links inside a skill folder, and the command lists the folders and files it left out for those reasons, a file over 1 MB and a folder it could not read among them. Files a project's own git tracks are left out without a line: a clone brings them.
-- Before anything is pushed, every file is read for what looks like a key, a token, a password or a private key: known shapes (GitHub, OpenAI, AWS, Stripe, Slack, Google, npm, Neon, Resend, Hugging Face, Groq, JSON Web Tokens, private key blocks), a password in an address, a bearer or basic credential, and a name such as `API_KEY`, `password` or `token` assigned a value with digits in it. Anything found stops the backup with each file and line (the first 20), and nothing is pushed. A file you have read and know holds no secret goes through with `--allow <path>` for that file. Then the repository is checked without a token: one that answers anyone is public, and is refused. The clone lives beside the config, in `skillcellar/backups/<owner>/<repo>`, readable by you only; each backup brings the clone to the remote's state, commits and pushes, and a commit a failed push left behind goes with the next run.
+- Before anything is pushed, every file is read for what looks like a key, a token, a password or a private key: known shapes (GitHub, OpenAI, AWS, Stripe, Slack, Google, npm, Neon, Resend, Hugging Face, Groq, JSON Web Tokens, private key blocks), a password in an address, a bearer or basic credential, and a name such as `API_KEY`, `password` or `token` assigned a value with digits in it; neither of the last two counts when the value is elided (`abc123...`) or holds an example word (`dummy`, `fake`, `sample`, `example`, `placeholder`, `redacted` or `changeme`) in any case with no letter next to it; an assignment whose value starts with `example`, `placeholder`, `redacted` or `changeme` is passed whatever follows. An assignment does not count either when its value is unquoted and is a dotted name directly followed by `(`, such as `base64.b64encode(`. Anything found stops the backup with each file and line (the first 20), and nothing is pushed. A file you have read and know holds no secret goes through with `--allow <path>` for that file, and each run lists the files it lets through this way. A backup that pushes remembers each with the hash of its contents, so later runs pass it without `--allow` until it changes, and names it in `manifest.json`, so a restore copies it as it was allowed. Then the repository is checked without a token: one that answers anyone is public, and is refused. The clone lives beside the config, in `skillcellar/backups/<owner>/<repo>`, readable by you only; each backup brings the clone to the remote's state, commits and pushes, and a commit a failed push left behind goes with the next run.
 - The site learns only the repository's name, the commit and the time, which the device's page shows. It holds no token for the repository and never reads the backup.
 
-`skillcellar restore` carries out the copy tasks waiting for this computer ("Copy to…" on the compare page, or "Copy everything to…" on a device's page). The site names the other computer's backup repository and commit, and a name is not proof: the restore takes a repository this computer does not itself back up to only with `--repo <owner>/<repo>`, or a yes at the terminal, and refuses a public one. It fetches the backup into a bare mirror beside the config (`skillcellar/backups/<owner>/<repo>.git`, never checked out, so a link in the repository is never followed), reads the commit the site recorded, and writes its skills, memory files and agents into place: a memory file or agent only when its hash is the one the other computer reported, where it reported one, nothing that holds what looks like a secret, nothing over the skillcellar skill, nothing over a file that is a link, and nothing into a project's `.claude`, `.claude/skills`, `.claude/agents` or `.claude/rules` when that folder is a link; what is there already stays unless you pass `--force`, which replaces every item the tasks name. It prints the commands left: a plugin's install, `npx skills add` for a skill from a repository, and `claude mcp add-json` for each MCP server with the backup's config, where each `${NAME}` is yours to fill in, and a `review` note marks a `${VAR:-default}` or `$VAR` reference or a `headersHelper` to read before adding. It also names the `package.json`, `requirements.txt`, `pyproject.toml` or Playwright config a restored skill carries, so you can rebuild its environment. `--from <device>` takes one computer's tasks; `--ssh` fetches over SSH; `--dry-run` fetches the backup but writes nothing into place. The printed commands are quoted for a POSIX shell; on Windows, paste them into Git Bash or WSL. Then `skillcellar sync` closes each task this computer now satisfies.
+`skillcellar restore` carries out the copy tasks waiting for this computer ("Copy to…" on the compare page, or "Copy everything to…" on a device's page). The site names the other computer's backup repository and commit, and a name is not proof: the restore takes a repository this computer does not itself back up to only with `--repo <owner>/<repo>`, or a yes at the terminal, and refuses a public one. It fetches the backup into a bare mirror beside the config (`skillcellar/backups/<owner>/<repo>.git`, never checked out, so a link in the repository is never followed), reads the commit the site recorded, and writes its skills, memory files and agents into place: a memory file or agent only when its hash is the one the other computer reported, where it reported one, nothing that holds what looks like a secret unless the backup's `manifest.json` names the file as allowed with those very contents, nothing over the skillcellar skill, nothing over a file that is a link, and nothing into a project's `.claude`, `.claude/skills`, `.claude/agents` or `.claude/rules` when that folder is a link; what is there already stays unless you pass `--force`, which replaces every item the tasks name. It prints the commands left: a plugin's install, `npx skills add` for a skill from a repository, and `claude mcp add-json` for each MCP server with the backup's config, where each `${NAME}` is yours to fill in, and a `review` note marks a `${VAR:-default}` or `$VAR` reference or a `headersHelper` to read before adding. It also names the `package.json`, `requirements.txt`, `pyproject.toml` or Playwright config a restored skill carries, so you can rebuild its environment. `--from <device>` takes one computer's tasks; `--ssh` fetches over SSH; `--dry-run` fetches the backup but writes nothing into place. The printed commands are quoted for a POSIX shell; on Windows, paste them into Git Bash or WSL. Then `skillcellar sync` closes each task this computer now satisfies.
 
 ## What it reads
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillcellar",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Sync what Claude Code has on this computer (skills, plugins, MCP servers, memory and agents) to your SkillCellar library, by name and hash, list the tasks you queue there for Claude Code to carry out, check which skills and plugins are outdated, and apply playbooks.",
   "keywords": [
     "claude-code",

package/src/backup.mjs

@@ -1,10 +1,11 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { lstat, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, join, relative } from "node:path";
 import { configPath } from "./config.mjs";
 import { markdownFiles } from "./files.mjs";
 import { sessionFolderName } from "./places.mjs";
-import { projectSlug } from "./plan.mjs";
+import { projectIdentity, projectSlug } from "./plan.mjs";
 import { skillFolders } from "./scan.mjs";
 import { findSecret } from "./secrets.mjs";
 
@@ -287,6 +288,7 @@ const sanitizeServers = (servers) => Object.fromEntries(Object.entries(servers ?
 // ── What a device backs up ──────────────────────────────────────────────────────────────────
 
 const text = (path, source, content) => ({ path, source, content: Buffer.from(content), executable: false });
+const manifestFile = (base, manifest) => text(`${base}/manifest.json`, "manifest", `${JSON.stringify(manifest, null, 2)}\n`);
 
 /** The `.md` files of a folder, for the backup, as `<into>/<path>`; a folder's absence is nothing to back up, one that cannot be read is named. */
 async function markdownInto(dir, into, own, skipped) {
@@ -362,52 +364,80 @@ export async function collectBackup({ device, claudeDir, claudeJson, projects, t
   if (Object.keys(globalServers).length) files.push(text(`${base}/global/mcp.json`, "~/.claude.json (mcpServers)", `${JSON.stringify({ mcpServers: globalServers }, null, 2)}\n`));
 
   const places = [{ folder: "global", files: files.length }];
-  const projectFolders = new Set();
+  // Every checkout of one project, such as two clones of a repository, goes in the project's one
+  // folder, as the site merges them into one project. Another project whose name makes the same
+  // folder name is left out.
+  const groups = new Map();
   for (const project of projects) {
     const slug = projectSlug(project, device.slug);
     if (!slug) continue;
-    if (projectFolders.has(slug)) {
-      skipped.push({ path: project.root, reason: `a folder of the same name, ${slug}, is backed up already` });
-      continue;
-    }
-    projectFolders.add(slug);
+    const group = groups.get(slug);
+    if (!group) groups.set(slug, [project]);
+    else if (projectIdentity(group[0]) === projectIdentity(project)) group.push(project);
+    else skipped.push({ path: project.root, reason: `a folder of the same name, ${slug}, is backed up already` });
+  }
+  for (const [slug, group] of groups) {
+    // In the order the sync sends them, which the site merges them in: by name, then as found.
+    const checkouts = [...group].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     const into = `${base}/projects/${slug}`;
-    const own = { root: project.root, tracked: await trackedOf(project.root) };
     const before = files.length;
-    files.push(...(await skillsInto(join(project.root, ".claude", "skills"), `${into}/skills`, own, skipped, budget)));
-    files.push(...(await oneFile(join(project.root, "CLAUDE.md"), `${into}/CLAUDE.md`, own, skipped)));
-    files.push(...(await oneFile(join(project.root, "AGENTS.md"), `${into}/AGENTS.md`, own, skipped)));
-    files.push(...(await markdownInto(join(project.root, ".claude", "rules"), `${into}/rules`, own, skipped)));
-    files.push(...(await markdownInto(join(project.root, ".claude", "agents"), `${into}/agents`, own, skipped)));
-    const seen = new Set();
-    for (const folder of new Set([project.root, ...(project.folders ?? [])])) {
-      for (const file of await markdownInto(join(claudeDir, "projects", sessionFolderName(folder), "memory"), `${into}/memory`, null, skipped)) {
-        if (seen.has(file.path)) continue;
-        seen.add(file.path);
-        files.push(file);
+    // The first checkout's item of a name wins, as on the site: a file by its path, a skill by its whole folder.
+    const item = (path) => (path.startsWith(`${into}/skills/`) ? path.split("/", into.split("/").length + 2).join("/") : path);
+    const taken = new Set();
+    const shared = new Map();
+    const local = new Map();
+    const sharedSources = [];
+    for (const project of checkouts) {
+      const own = { root: project.root, tracked: await trackedOf(project.root) };
+      const found = [
+        ...(await skillsInto(join(project.root, ".claude", "skills"), `${into}/skills`, own, skipped, budget)),
+        ...(await oneFile(join(project.root, "CLAUDE.md"), `${into}/CLAUDE.md`, own, skipped)),
+        ...(await oneFile(join(project.root, "AGENTS.md"), `${into}/AGENTS.md`, own, skipped)),
+        ...(await markdownInto(join(project.root, ".claude", "rules"), `${into}/rules`, own, skipped)),
+        ...(await markdownInto(join(project.root, ".claude", "agents"), `${into}/agents`, own, skipped)),
+      ];
+      const seen = new Set();
+      for (const folder of new Set([project.root, ...(project.folders ?? [])])) {
+        for (const file of await markdownInto(join(claudeDir, "projects", sessionFolderName(folder), "memory"), `${into}/memory`, null, skipped)) {
+          if (seen.has(file.path)) continue;
+          seen.add(file.path);
+          found.push(file);
+        }
       }
-    }
-    if (!own.tracked.has(".mcp.json")) {
-      const mcpJson = await readFile(join(project.root, ".mcp.json"), "utf8").catch(() => null);
-      let servers = null;
-      try {
-        servers = mcpJson === null ? null : JSON.parse(mcpJson)?.mcpServers;
-      } catch {
-        skipped.push({ path: join(project.root, ".mcp.json"), reason: "not valid JSON" });
+      const lost = new Map();
+      for (const file of found) {
+        const key = item(file.path);
+        if (!taken.has(key)) files.push(file);
+        else if (!lost.has(key)) lost.set(key, key.startsWith(`${into}/skills/`) ? join(project.root, ".claude", "skills", key.slice(`${into}/skills/`.length)) : file.source);
       }
-      if (servers && typeof servers === "object" && Object.keys(servers).length) {
-        files.push(text(`${into}/mcp.json`, join(project.root, ".mcp.json"), `${JSON.stringify({ mcpServers: sanitizeServers(servers) }, null, 2)}\n`));
+      for (const path of lost.values()) skipped.push({ path, reason: `another checkout of ${project.name} has one of the same name, backed up instead, as the site keeps one` });
+      for (const file of found) taken.add(item(file.path));
+      if (!own.tracked.has(".mcp.json")) {
+        const mcpJson = await readFile(join(project.root, ".mcp.json"), "utf8").catch(() => null);
+        let servers = null;
+        try {
+          servers = mcpJson === null ? null : JSON.parse(mcpJson)?.mcpServers;
+        } catch {
+          skipped.push({ path: join(project.root, ".mcp.json"), reason: "not valid JSON" });
+        }
+        if (servers && typeof servers === "object" && Object.keys(servers).length) {
+          sharedSources.push(join(project.root, ".mcp.json"));
+          for (const [name, server] of Object.entries(sanitizeServers(servers))) if (!shared.has(name)) shared.set(name, server);
+        }
       }
+      const ownLocal = {};
+      for (const folder of [project.root, ...(project.folders ?? [])]) Object.assign(ownLocal, sanitizeServers(claudeJson?.projects?.[folder]?.mcpServers));
+      for (const [name, server] of Object.entries(ownLocal)) if (!local.has(name)) local.set(name, server);
     }
-    const local = {};
-    for (const folder of [project.root, ...(project.folders ?? [])]) Object.assign(local, sanitizeServers(claudeJson?.projects?.[folder]?.mcpServers));
-    if (Object.keys(local).length) files.push(text(`${into}/mcp.local.json`, `~/.claude.json (projects, mcpServers)`, `${JSON.stringify({ mcpServers: local }, null, 2)}\n`));
+    if (shared.size) files.push({ ...text(`${into}/mcp.json`, sharedSources.join(", "), `${JSON.stringify({ mcpServers: Object.fromEntries(shared) }, null, 2)}\n`), sources: sharedSources });
+    if (local.size) files.push(text(`${into}/mcp.local.json`, `~/.claude.json (projects, mcpServers)`, `${JSON.stringify({ mcpServers: Object.fromEntries(local) }, null, 2)}\n`));
+    const [project] = checkouts;
     places.push({ folder: `projects/${slug}`, name: project.name, repo: project.repo ?? null, remote: Boolean(project.remote), files: files.length - before });
   }
 
   // No time in the manifest: the commit carries it, and an unchanged computer then commits nothing.
   const manifest = { skillcellar: version, device: { id: device.id, slug: device.slug, name: device.name }, places };
-  files.push(text(`${base}/manifest.json`, "manifest", `${JSON.stringify(manifest, null, 2)}\n`));
+  files.push(manifestFile(base, manifest));
   return { files, skipped, manifest };
 }
 
@@ -415,18 +445,27 @@ export async function collectBackup({ device, claudeDir, claudeJson, projects, t
 const FINDINGS_MAX = 20;
 
 /**
- * The files of a backup that hold what looks like a secret, each with the line, up to FINDINGS_MAX;
- * a file the user allowed by its path, or the end of it, is not read.
+ * The files of a backup that hold what looks like a secret, each with the line, up to FINDINGS_MAX,
+ * and those that pass despite one, each with the hash of what passed: a file the user allows by its
+ * path, whole or from a folder's start, and one an earlier backup let through holding these bytes.
  */
-export function findSecretsIn(files, allowed = []) {
+export function findSecretsIn(files, allowed = [], remembered = []) {
   const findings = [];
+  const passed = [];
   for (const file of files) {
-    if (allowed.some((path) => file.source === path || file.source.endsWith(`/${path}`))) continue;
     const found = findSecret(file.content.toString("utf8"));
-    if (found) findings.push({ ...found, file: file.source });
+    if (!found) continue;
+    const sha256 = createHash("sha256").update(file.content).digest("hex");
+    // A merged file, such as the mcp.json of several checkouts, is allowed by any file it came from.
+    const names = file.sources ?? [file.source];
+    if (allowed.some((path) => names.some((name) => name === path || name.endsWith(`/${path}`))) || remembered.some((entry) => entry?.file === file.source && entry.sha256 === sha256)) {
+      passed.push({ file: file.source, path: file.path, sha256, line: found.line, kind: found.kind });
+      continue;
+    }
+    findings.push({ ...found, file: file.source });
     if (findings.length >= FINDINGS_MAX) break;
   }
-  return findings;
+  return { findings, passed };
 }
 
 /** Writes the backup's files into the clone, replacing the device's folder and any older folder of the same device under another slug. */
@@ -514,14 +553,27 @@ export function describeSkipped(skipped) {
 
 const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 
+/** The files let through despite a finding, as lines a person reads, so an allowance is never silent. */
+function describePassed(passed) {
+  if (!passed.length) return [];
+  return ["Let through as you allowed them:", ...passed.map(({ file, line, kind }) => `  ${file}:${line} looks like ${kind}`)];
+}
+
 /**
  * Backs up the device: collects its files, stops on anything that looks like a secret, refuses a
  * public repository, then commits and pushes with the user's own git. Answers what to print and the
  * commit to report, or null when nothing changed.
  */
-export async function runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf, version, dryRun, allowed = [], print, onPushed = async () => {} }) {
-  const { files, skipped, manifest } = await collectBackup({ device, claudeDir, claudeJson, projects, trackedOf, version });
-  const findings = findSecretsIn(files, allowed);
+export async function runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf, version, dryRun, allowed = [], remembered = [], print, onPushed = async () => {} }) {
+  const collected = await collectBackup({ device, claudeDir, claudeJson, projects, trackedOf, version });
+  const { skipped } = collected;
+  const { findings, passed } = findSecretsIn(collected.files, allowed, remembered);
+  // What passed despite a finding is named in the manifest with the hash of what passed, so a
+  // restore copies that and reads any other copy of the file again.
+  const base = `devices/${device.slug}`;
+  const allowedFiles = passed.map(({ path, sha256 }) => ({ path: path.slice(base.length + 1), sha256 })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const manifest = allowedFiles.length ? { ...collected.manifest, allowed: allowedFiles } : collected.manifest;
+  const files = allowedFiles.length ? collected.files.map((file) => (file.path === `${base}/manifest.json` ? manifestFile(base, manifest) : file)) : collected.files;
   if (findings.length) {
     const lines = findings.map((found) => `  ${found.file}:${found.line} looks like ${found.kind}`);
     throw new Error(
@@ -532,7 +584,7 @@ export async function runBackup({ repo, device, claudeDir, claudeJson, projects,
   const summary = `${plural(files.length, "file")} (${size(bytes)}): ${manifest.places.map((place) => `${place.folder} ${place.files}`).join(", ")}`;
   if (dryRun) {
     print(`Would back up ${device.name} to ${repo.name}, ${summary}.`);
-    for (const line of describeSkipped(skipped)) print(line);
+    for (const line of [...describeSkipped(skipped), ...describePassed(passed)]) print(line);
     return null;
   }
   await refusePublic(repo, version);
@@ -548,10 +600,10 @@ export async function runBackup({ repo, device, claudeDir, claudeJson, projects,
   if (await currentBranch(clone)) {
     await git(["push", "--quiet", "-u", "origin", "HEAD"], { cwd: clone, timeout: 600_000 });
     commit = (await git(["rev-parse", "HEAD"], { cwd: clone })).trim();
-    await onPushed(commit);
+    await onPushed(commit, passed);
   }
   if (changed) print(`Backed up ${device.name} to ${repo.name} at ${commit.slice(0, 7)}, ${summary}.`);
   else print(`Nothing changed since the last backup of ${device.name} in ${repo.name}${commit ? ` (${commit.slice(0, 7)})` : ""}.`);
-  for (const line of describeSkipped(skipped)) print(line);
+  for (const line of [...describeSkipped(skipped), ...describePassed(passed)]) print(line);
   return commit;
 }

package/src/cli.mjs

@@ -7,7 +7,7 @@ import { parseBackupRepo, runBackup } from "./backup.mjs";
 import { describeCheck } from "./check.mjs";
 import { configPath, readConfig, writeConfig } from "./config.mjs";
 import { findProjects } from "./places.mjs";
-import { describePlan, localPlan } from "./plan.mjs";
+import { describePlan, localPlan, projectIdentity } from "./plan.mjs";
 import { applyPlaybook, cautionLine, describeStatus, readPlaybook } from "./playbook.mjs";
 import { findProject, trackedFiles } from "./project.mjs";
 import { ask, askSecret, firstLine, interactive } from "./prompt.mjs";
@@ -68,8 +68,8 @@ Usage:
       address credential and key-like argument replaced by a \${NAME} placeholder) and skills'
       source files to a private GitHub repository you own, with your own git. It stops on anything
       that looks like a secret and refuses a public repository. --repo is remembered; --ssh clones
-      and pushes over SSH; --allow <file> pushes a file you have read despite a finding in it;
-      --dry-run lists what would go.
+      and pushes over SSH; --allow <file> pushes a file you have read despite a finding in it,
+      and once pushed is remembered while the file stays the same; --dry-run lists what would go.
   skillcellar restore [--from <device>] [--repo <owner>/<repo>] [--ssh] [--force] [--dry-run]
       Carry out the copy tasks waiting for this computer: fetch the other computer's backup, write
       its skills, memory files and agents into place, and list the commands left to run. A backup
@@ -202,9 +202,6 @@ function summary(payload, result, deviceName, whole) {
  */
 const claudeJsonPath = (home) => (process.env.CLAUDE_CONFIG_DIR?.trim() ? join(process.env.CLAUDE_CONFIG_DIR.trim(), ".claude.json") : join(home, ".claude.json"));
 
-/** What makes checkouts one project on the site: their GitHub repository, else their name. */
-const identity = (project) => project.repo ?? project.name.toLowerCase();
-
 /** The tasks a sync closed, in one line. */
 function closedLine(closed) {
   const verb = (task) => (task.action === "remove" ? "removed" : task.action === "copy" ? "copied" : "installed");
@@ -232,7 +229,7 @@ async function sync(flags, print, warn) {
     if (!here) throw new UsageError("Run sync --project inside the project's folder, not in your home folder.");
     if (!/[A-Za-z0-9]/.test(flags.project)) throw new UsageError("--project needs a letter a–z or a digit 0–9.");
     // Every checkout of the same repository is one project on the site, so all of them go together.
-    const same = projects.filter((known) => known.root === here.root || (here.remote && known.remote && identity(known) === identity(here)));
+    const same = projects.filter((known) => known.root === here.root || (here.remote && known.remote && projectIdentity(known) === projectIdentity(here)));
     projects = (same.length ? same : [{ ...here, folders: new Set([cwd]) }]).map((known) => ({ ...known, name: flags.project }));
   }
 
@@ -252,7 +249,7 @@ async function sync(flags, print, warn) {
     } catch (error) {
       // One project's broken file stops only that project in a sync of the whole computer.
       if (!whole) throw error;
-      unread.add(identity(project));
+      unread.add(projectIdentity(project));
       warn(`Not reported: ${project.name}, because ${error.message} The site keeps what it had there until a sync can read it.`);
       continue;
     }
@@ -266,7 +263,7 @@ async function sync(flags, print, warn) {
   // one as it was and closes no task there; an empty place is then sent, to empty it. Another
   // checkout of the unread project is left out too, or it would replace the project on its own.
   const complete = whole && !unread.size;
-  if (!complete) places = [...places, ...empty].filter((place) => !unread.has(identity(place.project)));
+  if (!complete) places = [...places, ...empty].filter((place) => !unread.has(projectIdentity(place.project)));
   if (places.length > PROJECTS_PER_SYNC) {
     throw new Error(`This computer has ${places.length} projects to send, and one sync takes ${PROJECTS_PER_SYNC}. Sync each one you need from its folder with --project <name>.`);
   }
@@ -415,9 +412,15 @@ async function backup(flags, print, warn) {
   const claudeJson = (await readJson(claudeJsonPath(home))) ?? {};
   const projects = await knownProjects(home, claudeDir);
   const allowed = (Array.isArray(flags.allow) ? flags.allow : []).map((path) => path.trim()).filter(Boolean);
-  // The repository is remembered as soon as a push has gone through, whatever the site answers after.
-  const remember = () => (config ? writeConfig({ ...config, device: { id: device.id, slug: device.slug, name: device.name }, backup: { repo: repo.name, ssh: repo.ssh } }) : Promise.resolve());
-  const commit = await runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf: trackedFiles, version: VERSION, dryRun, allowed, print, onPushed: remember });
+  // The repository is remembered as soon as a push has gone through, whatever the site answers after,
+  // with the files the user allowed despite a finding, each by the hash of what was allowed.
+  const remember = (commit, passed = []) => {
+    if (!config) return Promise.resolve();
+    const kept = passed.length ? { allowed: passed.map(({ file, sha256 }) => ({ file, sha256 })) } : {};
+    return writeConfig({ ...config, device: { id: device.id, slug: device.slug, name: device.name }, backup: { repo: repo.name, ssh: repo.ssh, ...kept } });
+  };
+  const remembered = Array.isArray(config?.backup?.allowed) ? config.backup.allowed : [];
+  const commit = await runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf: trackedFiles, version: VERSION, dryRun, allowed, remembered, print, onPushed: remember });
   if (dryRun || !commit) return;
   const recorded = await call(site, config.key, "POST", "/api/v1/backup", { device: device.id, repo: repo.name, commit }, VERSION);
   const slug = recorded.device?.slug ?? device.slug;

package/src/plan.mjs

@@ -15,6 +15,9 @@ export const toSlug = (name) =>
 /** A project's slug as the site makes it: its name's, and for a folder with no git remote that followed by the device's. */
 export const projectSlug = (project, deviceSlug) => (project.remote ? toSlug(project.name) : `${toSlug(project.name)}-${deviceSlug}`);
 
+/** What makes checkouts one project on the site: their GitHub repository, else their name. */
+export const projectIdentity = (project) => project.repo ?? project.name.toLowerCase();
+
 /**
  * The folder on this computer of a task's project, from the projects the sync finds: one with a
  * GitHub repository by that repository, any other by its slug, which for a folder with no git remote

package/src/restore.mjs

@@ -122,7 +122,12 @@ async function checkProjectFolder(root, sub) {
  * 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 }) {
+async function restoreItem(item, { mirror, tree, budget, place, scope, root, claudeDir, force, dryRun, allowed }) {
+  // A file that looks like it holds a secret is copied only as the source's user allowed it, byte for byte.
+  const secretIn = (path, content) => {
+    const found = findSecret(content.toString("utf8"));
+    return found && allowed.get(path) !== sha256(content) ? found : null;
+  };
   const { kind, name } = item;
   if (item.tracked) return { outcome: "repository" };
   if (kind === "plugin" || (kind === "skill" && item.install)) {
@@ -153,7 +158,7 @@ async function restoreItem(item, { mirror, tree, budget, place, scope, root, cla
       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"));
+      const found = secretIn(path, content);
       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" });
     }
@@ -192,7 +197,7 @@ async function restoreItem(item, { mirror, tree, budget, place, scope, root, cla
   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"));
+  const found = secretIn(path, content);
   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 };
@@ -295,6 +300,8 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
       warn(`${repo.name} at ${commit.slice(0, 7)} holds no backup of ${source.device.name}. Run skillcellar backup there, then restore here again.`);
       continue;
     }
+    const listed = Array.isArray(found.manifest?.allowed) ? found.manifest.allowed : [];
+    const allowed = new Map(listed.filter((entry) => typeof entry?.path === "string" && typeof entry.sha256 === "string").map((entry) => [`${found.folder}/${entry.path}`, entry.sha256]));
     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";
@@ -320,7 +327,7 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
           continue;
         }
         done.add(key);
-        const result = await restoreItem(item, { mirror, tree, budget, place, scope: task.scope, root: task.folder, claudeDir, force, dryRun });
+        const result = await restoreItem(item, { mirror, tree, budget, place, scope: task.scope, root: task.folder, claudeDir, force, dryRun, allowed });
         if (result.outcome === "command") {
           commands.push({ task: where, label, ...result });
           continue;

package/src/secrets.mjs

@@ -9,6 +9,16 @@ 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\.)`;
+// The characters an assigned or bearer value is read with.
+const VALUE = String.raw`[A-Za-z0-9_\-./+=]`;
+// A word in either case, for a pattern that minds case.
+const anyCase = (word) => word.replace(/[a-z]/g, (letter) => `[${letter}${letter.toUpperCase()}]`);
+const EXAMPLE_WORDS = ["dummy", "fake", "sample", "example", "placeholder", "redacted", "change[_-]?me"].map(anyCase).join("|");
+// A value as documentation writes one, not a key: elided (abc123... or abc123…), or holding a word,
+// not part of a longer one, that calls it an example. Real keys are neither.
+const NOT_EXAMPLE = String.raw`(?!${VALUE}{0,255}?(?:\.\.\.|(?<![A-Za-z])(?:${EXAMPLE_WORDS})(?![A-Za-z])))(?!${VALUE}{1,255}…)`;
+// Code such as base64.b64encode( is no value; a quoted value is one, whatever it holds.
+const NOT_CALL = String.raw`(?:(?<=["'\x60])|(?![A-Za-z_]\w{0,60}(?:\.[A-Za-z_]\w{0,60}){1,5}\())`;
 
 const PATTERNS = [
   ["a private key", /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/],
@@ -25,12 +35,12 @@ const PATTERNS = [
   ["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 bearer or basic credential", new RegExp(String.raw`\b(?:Bearer|Basic)\s{1,5}(?!\$\{|\$[A-Za-z_]|<)${NOT_EXAMPLE}[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}`,
+      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}${NOT_EXAMPLE}${NOT_CALL}(?=[A-Za-z0-9_\-./+=]{0,254}[0-9])[A-Za-z0-9_\-./+=]{8,255}`,
       "i",
     ),
   ],