skillcellar 0.3.0 → 0.6.1

package/src/backup.mjs

@@ -0,0 +1,609 @@
+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 { projectIdentity, projectSlug } from "./plan.mjs";
+import { skillFolders } from "./scan.mjs";
+import { findSecret } from "./secrets.mjs";
+
+// A backup holds text files of these kinds, each under this size; folders of installed packages,
+// caches and build output are left out, and the CLI lists what it left out.
+export const FILE_BYTES_MAX = 1024 * 1024;
+// A backup holds at most this many files and bytes, read into memory before the push.
+export const FILES_MAX = 20_000;
+export const BYTES_MAX = 256 * 1024 * 1024;
+export const SKIPPED_FOLDERS = new Set([
+  "node_modules", ".venv", "venv", "env", "__pycache__", ".git", ".cache", "dist", "build", "ms-playwright",
+  ".next", ".turbo", ".nuxt", ".svelte-kit", "target", "vendor", "coverage", ".tox", ".mypy_cache", ".pytest_cache", ".ruff_cache", ".gradle",
+]);
+const TEXT_EXTENSIONS = new Set(
+  "md mdx txt rst json jsonc json5 yaml yml toml ini cfg conf properties xml html htm css scss sass less svg js mjs cjs jsx ts mts cts tsx py pyi rb php go rs java kt kts scala swift c h cc cpp hpp cs sh bash zsh fish ps1 psm1 bat cmd sql graphql gql proto csv tsv lock".split(
+    " ",
+  ),
+);
+const TEXT_NAMES = new Set(["Makefile", "Dockerfile", "LICENSE", "LICENCE", "README", "CHANGELOG", "NOTICE", "AUTHORS", "CODEOWNERS", "Procfile", ".gitignore", ".gitattributes", ".editorconfig"]);
+const DEPTH_MAX = 32;
+// A name the sync sends, and so a folder a backup names: the same shape, so a restore can match them.
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/;
+const GITHUB_NAME_RE = /^[A-Za-z0-9_.-]{1,100}$/;
+
+/** Where GitHub is reached: its API to ask whether a repository is public, and its git host to clone from. Stand-ins are read only under NODE_ENV=test. */
+const testing = () => process.env.NODE_ENV === "test";
+const githubApi = () => (testing() && process.env.SKILLCELLAR_GITHUB_API?.replace(/\/$/, "")) || "https://api.github.com";
+const githubGit = () => (testing() && process.env.SKILLCELLAR_GITHUB_GIT?.replace(/\/$/, "")) || "https://github.com";
+
+/** The clone of a backup repository, beside the config: readable by its owner only. */
+export const clonePath = (owner, repo) => join(dirname(configPath()), "backups", owner, repo);
+
+/**
+ * A repository as `--repo` names it: owner/repo, its https address, or its git@github.com address,
+ * which chooses SSH. Null for anything else. The name is kept lowercase, as the site keeps it.
+ */
+export function parseBackupRepo(value, ssh = false) {
+  const text = String(value ?? "").trim();
+  const match = /^(?:https:\/\/(?:www\.)?github\.com\/|(git@github\.com:))?([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(text);
+  if (!match) return null;
+  const [, scp, owner, repo] = match;
+  if (![owner, repo].every((name) => GITHUB_NAME_RE.test(name) && name !== "." && name !== "..")) return null;
+  const name = `${owner.toLowerCase()}/${repo.toLowerCase()}`;
+  const useSsh = ssh || scp !== undefined;
+  return { owner: owner.toLowerCase(), repo: repo.toLowerCase(), name, ssh: useSsh, url: useSsh ? `git@github.com:${owner}/${repo}.git` : `${githubGit()}/${owner}/${repo}.git` };
+}
+
+/**
+ * Refuses a repository that answers an anonymous request, since that makes it public, and one
+ * GitHub would not say is private. The request carries no token, so it sees what anyone sees.
+ */
+export async function refusePublic(repo, version) {
+  let response;
+  try {
+    response = await fetch(`${githubApi()}/repos/${repo.owner}/${repo.repo}`, {
+      headers: { accept: "application/vnd.github+json", "user-agent": `skillcellar/${version}` },
+      redirect: "manual",
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (error) {
+    throw new Error(`Could not ask GitHub whether ${repo.name} is private: ${error?.cause?.code ?? error?.name ?? "network error"}. Nothing was pushed.`);
+  }
+  if (response.status === 404) {
+    // GitHub answers a private repository with its own "Not Found" body; a proxy or a captive portal answering 404 does not pass.
+    const body = await response.json().catch(() => null);
+    if (body && typeof body.message === "string" && /not found/i.test(body.message)) return;
+    throw new Error(`GitHub did not answer as GitHub does about ${repo.name}. Check the network, then try again. Nothing was pushed.`);
+  }
+  if (response.status === 200) {
+    throw new Error(`${repo.name} is public on GitHub, and a backup holds your memory files and configuration: back up to a private repository you own. Nothing was pushed.`);
+  }
+  throw new Error(`GitHub did not say whether ${repo.name} is private (it answered ${response.status}). Try again later. Nothing was pushed.`);
+}
+
+/** Runs git, answering its output; on failure, an error with git's own first line of complaint. */
+export function git(args, { cwd, timeout = 120_000 } = {}) {
+  return new Promise((done, fail) => {
+    execFile("git", args, { cwd, timeout, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" } }, (error, stdout, stderr) => {
+      if (!error) return done(stdout);
+      const line = String(stderr || error.message)
+        .split("\n")
+        .map((text) => text.trim())
+        .filter((text) => text && !text.startsWith("hint:"))
+        .at(-1);
+      fail(new Error(`git ${args[0]} failed: ${line ?? "unknown error"}`));
+    });
+  });
+}
+
+/** Runs git and answers its output as bytes, for a blob. */
+export function gitBuffer(args, { cwd, timeout = 120_000 } = {}) {
+  return new Promise((done, fail) => {
+    execFile("git", args, { cwd, timeout, maxBuffer: 64 * 1024 * 1024, encoding: "buffer", env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" } }, (error, stdout, stderr) => {
+      if (!error) return done(stdout);
+      fail(new Error(`git ${args[0]} failed: ${String(stderr).trim().split("\n").at(-1) || "unknown error"}`));
+    });
+  });
+}
+
+const isTextName = (name) => TEXT_NAMES.has(name) || TEXT_EXTENSIONS.has(extname(name).slice(1).toLowerCase());
+const isBinary = (content) => content.subarray(0, 8192).includes(0);
+const size = (bytes) => (bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.ceil(bytes / 1024)} KB`);
+
+/**
+ * The files of a folder a backup takes, each with its path under `into` and its bytes, and what it
+ * left out: skipped folders at any depth, links, files over the size cap, files of other kinds and
+ * binary files. Only regular files are read.
+ */
+/** Counts what a backup has read so far, and stops it past the caps. */
+export const newBudget = () => ({ files: 0, bytes: 0 });
+function spend(budget, bytes) {
+  budget.files += 1;
+  budget.bytes += bytes;
+  if (budget.files > FILES_MAX || budget.bytes > BYTES_MAX) {
+    throw new Error(`This computer's Claude Code folders hold more than ${FILES_MAX.toLocaleString("en")} files or ${BYTES_MAX / 1024 / 1024} MB of text to back up. Move what is not Claude Code's out of its skills folders, then try again. Nothing was pushed.`);
+  }
+}
+
+export async function collectFolder(dir, into, { tracked = null, root = null, budget = newBudget() } = {}, depth = 0, files = [], skipped = []) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    skipped.push({ path: dir, reason: `could not be read (${error?.code ?? "error"})` });
+    return { files, skipped };
+  }
+  for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+    const path = join(dir, entry.name);
+    const target = `${into}/${entry.name}`;
+    if (entry.isSymbolicLink()) {
+      skipped.push({ path, reason: "a link" });
+    } else if (entry.isDirectory()) {
+      if (SKIPPED_FOLDERS.has(entry.name)) skipped.push({ path, reason: "a folder backups leave out" });
+      else if (depth >= DEPTH_MAX) skipped.push({ path, reason: "too deep" });
+      else await collectFolder(path, target, { tracked, root, budget }, depth + 1, files, skipped);
+    } else if (entry.isFile()) {
+      if (tracked && root && tracked.has(relative(root, path).split("\\").join("/"))) continue;
+      const info = await stat(path).catch(() => null);
+      if (!info) continue;
+      if (info.size > FILE_BYTES_MAX) skipped.push({ path, reason: `over 1 MB (${size(info.size)})` });
+      else if (!isTextName(entry.name)) skipped.push({ path, reason: "not a kind backups take" });
+      else {
+        const content = await readFile(path).catch(() => null);
+        if (!content) skipped.push({ path, reason: "could not be read" });
+        else if (isBinary(content)) skipped.push({ path, reason: "not text" });
+        else {
+          spend(budget, content.length);
+          files.push({ path: target, source: path, content, executable: (info.mode & 0o111) !== 0 });
+        }
+      }
+    }
+  }
+  return { files, skipped };
+}
+
+// ── MCP config without its secrets ──────────────────────────────────────────────────────────
+
+const WORD_RE = /^(?:[a-z]{1,8}|v\d{1,3})$/;
+const SECRET_NAME_RE = /key|token|secret|pass|auth|credential|cookie|session|private/i;
+// A value with letters and digits and no spaces, long enough to be a key, as tokens are.
+const SECRET_VALUE_RE = /^(?=.{16,})(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9_\-+/=.:]+$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PACKAGE_RE = /^@?[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)?(?:@[A-Za-z0-9._+-]+|==?[A-Za-z0-9._+-]+)?$/;
+const PATH_RE = /^(?:\.{0,2}\/|~|[A-Za-z]:[\\/])/;
+const SCHEME_RE = /^[a-z][a-z0-9+.-]{0,30}:\/\//i;
+// Flags whose next argument is a header or an environment assignment, as mcp-remote and runners take them.
+const HEADER_FLAGS = new Set(["-H", "--header"]);
+const ENV_FLAGS = new Set(["-e", "--env"]);
+
+export const placeholder = (name) => `\${${String(name).toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "VALUE"}}`;
+
+/** An address with its credentials, its query's values and the parts of its path that are not short words replaced by placeholders, whatever its scheme. */
+export function sanitizeUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return sanitizeText(value);
+  }
+  const path = url.pathname
+    .split("/")
+    .map((segment, index) => (segment === "" || WORD_RE.test(segment) ? segment : placeholder(`path_${index}`)))
+    .join("/");
+  const query = [...url.searchParams.keys()].map((key) => `${encodeURIComponent(key)}=${placeholder(key)}`).join("&");
+  const auth = url.username || url.password ? "${USERNAME}:${PASSWORD}@" : "";
+  return `${url.protocol}//${auth}${url.host}${path}${query ? `?${query}` : ""}`;
+}
+
+// A package is written lowercase, as npm and PyPI name them, with a separator in any long name; a
+// mixed-case value, a long run with no separator or a hexadecimal one of that shape is a key.
+const packageLike = (value) => PACKAGE_RE.test(value) && value === value.toLowerCase() && !/^[0-9a-f]{20,}$/.test(value) && (value.length < 20 || /[-./@]/.test(value));
+const looksSecret = (value) => typeof value === "string" && (UUID_RE.test(value) || (SECRET_VALUE_RE.test(value) && !packageLike(value) && !PATH_RE.test(value) && !SCHEME_RE.test(value)));
+
+/** A header's value as the backup keeps it: `Name: ${NAME}`, keeping a Bearer or Basic scheme. */
+function sanitizeHeader(text) {
+  const match = /^([A-Za-z][A-Za-z0-9-]{0,80}):\s*(.*)$/s.exec(text);
+  if (!match) return placeholder("header");
+  const [, name, value] = match;
+  const scheme = /^(Bearer|Basic)\s/i.exec(value)?.[1];
+  return `${name}: ${scheme ? `${scheme} ` : ""}${placeholder(name)}`;
+}
+
+/** An environment assignment as the backup keeps it: `KEY=${KEY}`. */
+const sanitizeAssignment = (text) => text.replace(/^([A-Za-z_][A-Za-z0-9_]{0,80})=.*$/s, (_, key) => `${key}=${placeholder(key)}`);
+
+/**
+ * Free text, such as a script an argument holds: credentials in any address, bearer or basic
+ * credentials, and KEY=value assignments replaced in place.
+ */
+export function sanitizeText(text) {
+  return text
+    .replace(/([a-z][a-z0-9+.-]{0,30}:\/\/)([^\s/@:'"]{1,100}):(?!\$\{)[^\s/@'"]{1,200}@/gi, "$1${USERNAME}:${PASSWORD}@")
+    .replace(/\b(Bearer|Basic)\s+(?!\$\{)[A-Za-z0-9_\-./+=]{8,2000}/g, "$1 ${TOKEN}")
+    .replace(/(^|[\s'"])([A-Z][A-Z0-9_]{1,80})=(?!\$\{)[^\s'"]{1,500}/g, (_, before, key) => `${before}${key}=${placeholder(key)}`);
+}
+
+/**
+ * A server's arguments with what looks like a key replaced: a header's or an environment
+ * assignment's value, a value after or inside a flag named for a key, an address's credentials, a
+ * token-shaped value, and a script's credentials.
+ */
+function sanitizeArgs(args) {
+  const out = [];
+  let after = null;
+  for (const arg of args) {
+    if (typeof arg !== "string") {
+      out.push(arg);
+      continue;
+    }
+    if (after) {
+      out.push(HEADER_FLAGS.has(after) ? sanitizeHeader(arg) : ENV_FLAGS.has(after) ? sanitizeAssignment(arg) : placeholder(after));
+      after = null;
+      continue;
+    }
+    const flag = /^(-{1,2}[A-Za-z][\w-]*)(?:=(.*))?$/s.exec(arg);
+    if (flag) {
+      const [, name, value] = flag;
+      if (value === undefined) {
+        if (SECRET_NAME_RE.test(name) || HEADER_FLAGS.has(name) || ENV_FLAGS.has(name)) after = name;
+        out.push(arg);
+      } else if (HEADER_FLAGS.has(name)) out.push(`${name}=${sanitizeHeader(value)}`);
+      else if (ENV_FLAGS.has(name)) out.push(`${name}=${sanitizeAssignment(value)}`);
+      else if (SECRET_NAME_RE.test(name) || looksSecret(value)) out.push(`${name}=${placeholder(name)}`);
+      else if (SCHEME_RE.test(value)) out.push(`${name}=${sanitizeUrl(value)}`);
+      else out.push(`${name}=${sanitizeText(value)}`);
+      continue;
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]{0,80}=/.test(arg) && !/\s/.test(arg)) out.push(sanitizeAssignment(arg));
+    else if (SCHEME_RE.test(arg)) out.push(sanitizeUrl(arg));
+    else if (looksSecret(arg)) out.push(placeholder(`arg_${out.length}`));
+    else out.push(sanitizeText(arg));
+  }
+  return out;
+}
+
+/**
+ * An MCP server's config as the backup keeps it: every `env` and header value a placeholder named
+ * after its key, its address without credentials or a query's values, its arguments and command
+ * without what looks like a key, and no `headersHelper`, which is a command that fetches a
+ * credential. Other fields stay as they are.
+ */
+export function sanitizeServer(server) {
+  if (typeof server !== "object" || server === null) return server;
+  const out = { ...server };
+  if (out.env && typeof out.env === "object") out.env = Object.fromEntries(Object.keys(out.env).map((key) => [key, placeholder(key)]));
+  if (out.headers && typeof out.headers === "object") {
+    out.headers = Object.fromEntries(
+      Object.entries(out.headers).map(([key, value]) => [key, typeof value === "string" && /^Bearer\s/i.test(value) ? `Bearer ${placeholder(key)}` : placeholder(key)]),
+    );
+  }
+  if (typeof out.url === "string") out.url = sanitizeUrl(out.url);
+  if (typeof out.command === "string") out.command = sanitizeText(out.command);
+  if (Array.isArray(out.args)) out.args = sanitizeArgs(out.args);
+  if ("headersHelper" in out) out.headersHelper = placeholder("headers_helper");
+  return out;
+}
+
+const sanitizeServers = (servers) => Object.fromEntries(Object.entries(servers ?? {}).map(([name, server]) => [name, sanitizeServer(server)]));
+
+// ── 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) {
+  const files = [];
+  let found;
+  try {
+    found = await markdownFiles(dir, true);
+  } catch (error) {
+    skipped.push({ path: dir, reason: `could not be read (${error.message})` });
+    return files;
+  }
+  for (const file of found) {
+    if (own && own.tracked.has(relative(own.root, file.path).split("\\").join("/"))) continue;
+    const info = await stat(file.path).catch(() => null);
+    if (!info) continue;
+    if (info.size > FILE_BYTES_MAX) {
+      skipped.push({ path: file.path, reason: `over 1 MB (${size(info.size)})` });
+      continue;
+    }
+    files.push({ path: `${into}/${file.name}`, source: file.path, content: await readFile(file.path), executable: false });
+  }
+  return files;
+}
+
+async function oneFile(path, into, own, skipped) {
+  if (own && own.tracked.has(relative(own.root, path).split("\\").join("/"))) return [];
+  const info = await stat(path).catch(() => null);
+  if (!info?.isFile()) return [];
+  if (info.size > FILE_BYTES_MAX) {
+    skipped.push({ path, reason: `over 1 MB (${size(info.size)})` });
+    return [];
+  }
+  return [{ path: into, source: path, content: await readFile(path), executable: false }];
+}
+
+/** The skill folders of a skills directory, each collected under `<into>/<name>`; a name the sync cannot send is left out. */
+async function skillsInto(dir, into, own, skipped, budget) {
+  const files = [];
+  let folders;
+  try {
+    folders = await skillFolders(dir);
+  } catch (error) {
+    skipped.push({ path: dir, reason: `could not be read (${error.message})` });
+    return files;
+  }
+  for (const folder of folders) {
+    if (!NAME_RE.test(folder.name)) {
+      skipped.push({ path: folder.path, reason: "named in a way the sync cannot send" });
+      continue;
+    }
+    if (own && own.tracked.has(relative(own.root, join(folder.path, "SKILL.md")).split("\\").join("/"))) continue;
+    await collectFolder(folder.path, `${into}/${folder.name}`, { ...own, budget }, 0, files, skipped);
+  }
+  return files;
+}
+
+/**
+ * Everything the device backs up: under `devices/<device>/global`, its skills' files, CLAUDE.md,
+ * rules, agents and MCP servers; under `devices/<device>/projects/<project>`, the same for each
+ * project, with AGENTS.md and the session memory Claude Code keeps for it, leaving out what the
+ * project's own git tracks. The manifest names the device and each project, so a restore finds them.
+ */
+export async function collectBackup({ device, claudeDir, claudeJson, projects, trackedOf, version }) {
+  const files = [];
+  const skipped = [];
+  const budget = newBudget();
+  const base = `devices/${device.slug}`;
+  files.push(...(await skillsInto(join(claudeDir, "skills"), `${base}/global/skills`, null, skipped, budget)));
+  files.push(...(await oneFile(join(claudeDir, "CLAUDE.md"), `${base}/global/CLAUDE.md`, null, skipped)));
+  files.push(...(await markdownInto(join(claudeDir, "rules"), `${base}/global/rules`, null, skipped)));
+  files.push(...(await markdownInto(join(claudeDir, "agents"), `${base}/global/agents`, null, skipped)));
+  const globalServers = claudeJson?.mcpServers && typeof claudeJson.mcpServers === "object" ? sanitizeServers(claudeJson.mcpServers) : {};
+  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 }];
+  // 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;
+    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 before = files.length;
+    // 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);
+        }
+      }
+      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);
+      }
+      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);
+    }
+    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(manifestFile(base, manifest));
+  return { files, skipped, manifest };
+}
+
+// How many findings a stopped backup lists.
+const FINDINGS_MAX = 20;
+
+/**
+ * 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 = [], remembered = []) {
+  const findings = [];
+  const passed = [];
+  for (const file of files) {
+    const found = findSecret(file.content.toString("utf8"));
+    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, 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. */
+export async function writeBackup(clone, files, deviceId, deviceSlug) {
+  const devices = join(clone, "devices");
+  // A link in the clone would carry a delete or a write outside it: the repository is refused as it is.
+  const linked = (info) => info?.isSymbolicLink();
+  if (linked(await lstat(devices).catch(() => null))) throw new Error("The backup repository holds a link at devices; remove it there first. Nothing was pushed.");
+  for (const name of await readdir(devices).catch(() => [])) {
+    if (linked(await lstat(join(devices, name)).catch(() => null))) throw new Error(`The backup repository holds a link at devices/${name}; remove it there first. Nothing was pushed.`);
+    const manifest = await readFile(join(devices, name, "manifest.json"), "utf8").catch(() => null);
+    let id = null;
+    try {
+      id = manifest === null ? null : JSON.parse(manifest)?.device?.id;
+    } catch {
+      // A folder whose manifest cannot be read is another device's, or nobody's: left alone.
+    }
+    if (name === deviceSlug || (id && id === deviceId)) await rm(join(devices, name), { recursive: true, force: true });
+  }
+  for (const file of files) {
+    const path = join(clone, ...file.path.split("/"));
+    // The paths were built here from checked names; this is the last guard before a write.
+    if (relative(clone, path).startsWith("..")) throw new Error(`The backup names a file outside its folder: ${file.path}.`);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, file.content, { mode: file.executable ? 0o755 : 0o644 });
+  }
+}
+
+/** The clone's current branch, or null in an empty repository with no commit yet. */
+export async function currentBranch(clone) {
+  const ref = await git(["symbolic-ref", "--short", "-q", "HEAD"], { cwd: clone }).catch(() => "");
+  const head = await git(["rev-parse", "--verify", "-q", "HEAD"], { cwd: clone }).catch(() => "");
+  return head.trim() ? ref.trim() || null : null;
+}
+
+/**
+ * The clone of the backup repository, made if missing, else brought to the remote's state: the
+ * clone is the tool's own scratch area, so what a failed run left in its tree is dropped, a commit a
+ * failed push left behind is rebased, and an empty remote is not pulled from.
+ */
+export async function ensureClone(repo) {
+  const clone = clonePath(repo.owner, repo.repo);
+  const there = await stat(join(clone, ".git")).catch(() => null);
+  if (!there?.isDirectory()) {
+    await mkdir(dirname(clone), { recursive: true, mode: 0o700 });
+    await git(["clone", "--quiet", repo.url, clone], { timeout: 600_000 });
+    return clone;
+  }
+  await git(["remote", "set-url", "origin", repo.url], { cwd: clone });
+  await git(["fetch", "--quiet", "origin"], { cwd: clone, timeout: 600_000 });
+  const branch = await currentBranch(clone);
+  if (branch) {
+    await git(["reset", "--hard", "--quiet"], { cwd: clone });
+    await git(["clean", "-fdq", "--", "devices"], { cwd: clone });
+    const heads = (await git(["ls-remote", "--heads", "origin"], { cwd: clone, timeout: 120_000 })).trim();
+    if (heads) await git(["pull", "--rebase", "--quiet", "origin", branch], { cwd: clone, timeout: 600_000 });
+  }
+  return clone;
+}
+
+/**
+ * A bare mirror of the backup repository for `restore`, beside the clone and never checked out, so
+ * a link in the repository is never followed; fetched to the remote's state on every call.
+ */
+export async function ensureMirror(repo) {
+  const mirror = `${clonePath(repo.owner, repo.repo)}.git`;
+  const there = await stat(join(mirror, "HEAD")).catch(() => null);
+  if (!there?.isFile()) {
+    await mkdir(dirname(mirror), { recursive: true, mode: 0o700 });
+    await git(["clone", "--quiet", "--bare", repo.url, mirror], { timeout: 600_000 });
+    return mirror;
+  }
+  await git(["--git-dir", mirror, "remote", "set-url", "origin", repo.url]);
+  await git(["--git-dir", mirror, "fetch", "--quiet", "origin", "+refs/heads/*:refs/heads/*"], { timeout: 600_000 });
+  return mirror;
+}
+
+/** What was left out, as lines a person reads: folders and files by reason, each named. */
+export function describeSkipped(skipped) {
+  if (!skipped.length) return [];
+  const lines = ["Left out:"];
+  for (const { path, reason } of skipped) lines.push(`  ${path}: ${reason}`);
+  return lines;
+}
+
+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 = [], 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(
+      `Backup stopped: ${plural(findings.length, "file")} ${findings.length === 1 ? "holds" : "hold"} what looks like a secret${findings.length >= FINDINGS_MAX ? " (the first 20)" : ""}:\n${lines.join("\n")}\nNothing was pushed. Take each out of its file on this computer, or keep the file out of Claude Code's folders, then run skillcellar backup again; for a file you have read and know holds no secret, run it with --allow <path> for that file.`,
+    );
+  }
+  const bytes = files.reduce((total, file) => total + file.content.length, 0);
+  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), ...describePassed(passed)]) print(line);
+    return null;
+  }
+  await refusePublic(repo, version);
+  const clone = await ensureClone(repo);
+  await writeBackup(clone, files, device.id, device.slug);
+  await git(["add", "-A", "-f", "--", "devices"], { cwd: clone });
+  const changed = (await git(["status", "--porcelain", "--", "devices"], { cwd: clone })).trim();
+  let commit = null;
+  if (changed) {
+    await git(["commit", "--quiet", "-m", `Back up ${device.name} (${plural(files.length, "file")})`], { cwd: clone });
+  }
+  // Pushed on every run: a commit a failed push left behind goes now, and the commit reported is one the remote has.
+  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, 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), ...describePassed(passed)]) print(line);
+  return commit;
+}