skillcellar 0.3.0 → 0.6.1

package/src/playbook.mjs

@@ -0,0 +1,164 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { field } from "./check.mjs";
+import { installPulled, PULL_REF_RE, readPulled } from "./pull.mjs";
+
+// The playbook skill's folder, as the site names it: playbook-<slug>, up to a skill name's 64 characters.
+const SKILL_NAME_RE = /^playbook-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SKILL_BYTES_MAX = 1024 * 1024;
+const STATUSES = new Set(["installed", "outdated", "missing"]);
+const KINDS = { catalog: "catalog", skill: "this site", github: "GitHub", web: "web page" };
+
+const plural = (n, word) => `${n} ${n === 1 ? word : `${word}s`}`;
+const label = (skill) => `${field(skill.name, 80)} (${KINDS[skill.kind] ?? "skill"})`;
+const placeOf = (skill) => (skill.where === "project" ? "in the project" : "globally");
+
+/** The site's answer, checked before anything is written or printed: the playbook skill's name and text, and its skills. */
+export function readPlaybook(answer) {
+  const skill = answer?.skill;
+  const skills = Array.isArray(answer?.skills) ? answer.skills : null;
+  const valid =
+    typeof skill?.name === "string" &&
+    skill.name.length <= 64 &&
+    SKILL_NAME_RE.test(skill.name) &&
+    typeof skill.content === "string" &&
+    Buffer.byteLength(skill.content) <= SKILL_BYTES_MAX &&
+    (answer.installPrompt === null || typeof answer.installPrompt === "string") &&
+    skills?.every((entry) => entry && STATUSES.has(entry.status) && (entry.pull === null || (typeof entry.pull === "string" && PULL_REF_RE.test(entry.pull))));
+  if (!valid) throw new Error("The site's answer is not a playbook this command can apply.");
+  return answer;
+}
+
+/** For someone else's playbook, the line that says nobody has reviewed it; null for one's own. */
+export function cautionLine(answer) {
+  if (answer.playbook?.own) return null;
+  return `${field(answer.playbook?.name, 80)} is published by ${field(answer.playbook?.author, 40)}, not curated: nobody at the site has reviewed it. Read each step before you let Claude Code run it.`;
+}
+
+/**
+ * Applies a playbook into the skills folder `skills`: writes the playbook skill, and pulls the
+ * skills of the site it uses that the computer lacks, each checked as `pull` checks it and written
+ * into a hidden folder first, then moved into place. A folder already there is kept unless `force`.
+ * Nothing it writes leaves `skills`. With `dryRun`, it lists the files it would write and writes
+ * none; otherwise `confirm`, when given, sees each file first and can refuse them all. Answers the
+ * lines to print and the pulls and writes that failed.
+ */
+export async function applyPlaybook({ answer, skills, force, dryRun, fetchPull, confirm = null }) {
+  const lines = [];
+  const writes = [];
+  const kept = [];
+  const failed = [];
+
+  const folder = join(skills, answer.skill.name);
+  const there = await lstat(folder).catch(() => null);
+  // Up to date is the folder apply writes, as status hashes it: that SKILL.md alone, read only as a
+  // file of a skill's size, since a checkout can put a link to a device or a pipe there.
+  const only = there?.isDirectory() ? (await readdir(folder).catch(() => [])).join("/") === "SKILL.md" : false;
+  const file = only ? await lstat(join(folder, "SKILL.md")).catch(() => null) : null;
+  const current = file?.isFile() && file.size <= SKILL_BYTES_MAX ? await readFile(join(folder, "SKILL.md"), "utf8").catch(() => null) : null;
+  if (current === answer.skill.content) lines.push(`The playbook skill in ${folder} is up to date.`);
+  else if (there && !force) kept.push(`${folder}, which differs from the playbook on the site; run playbook apply again with --force to replace it`);
+  else {
+    const files = [{ segments: ["SKILL.md"], content: Buffer.from(answer.skill.content), executable: false }];
+    writes.push({ ref: null, pulled: { slug: answer.skill.name, version: null, files }, replace: !!there });
+  }
+
+  // Each folder is written once: a pulled skill never takes the playbook skill's place, or another's.
+  const folders = new Set([answer.skill.name]);
+  for (const skill of answer.skills) {
+    if (skill.status !== "missing" || !skill.pull || skill.forSale) continue;
+    let pulled;
+    try {
+      pulled = readPulled(await fetchPull(skill.pull));
+    } catch (error) {
+      failed.push(`${skill.pull}: ${field(error.message, 300)}`);
+      continue;
+    }
+    if (folders.has(pulled.slug)) {
+      failed.push(`${skill.pull}: its folder, ${pulled.slug}, is another of this playbook's.`);
+      continue;
+    }
+    folders.add(pulled.slug);
+    const target = join(skills, pulled.slug);
+    const exists = await lstat(target).catch(() => null);
+    if (exists && !force) kept.push(`${target}, which is there already; run playbook apply again with --force to replace it`);
+    else writes.push({ ref: skill.pull, pulled, replace: !!exists });
+  }
+
+  const files = writes.flatMap(({ pulled }) => pulled.files.map((entry) => ({ path: join(skills, pulled.slug, ...entry.segments), executable: entry.executable })));
+  if (dryRun) {
+    for (const { pulled, replace } of writes) if (replace) lines.push(`Would replace ${join(skills, pulled.slug)} and everything in it.`);
+    lines.push(files.length ? `Would write ${plural(files.length, "file")}:` : "Would write nothing.", ...files.map(({ path }) => `  ${path}`));
+  } else if (files.length && confirm && !(await confirm(files))) {
+    return { lines: ["Nothing written."], failed };
+  } else {
+    for (const { ref, pulled, replace } of writes) {
+      try {
+        const target = await installPulled(skills, pulled, replace);
+        lines.push(ref ? `Pulled ${ref}, version ${field(pulled.version, 20)}, into ${target}.` : `Wrote the playbook skill into ${target}.`);
+      } catch (error) {
+        failed.push(`${ref ?? "the playbook skill"}: ${field(error.message, 300)}`);
+      }
+    }
+  }
+  for (const note of kept) lines.push(`Kept ${note}.`);
+
+  const here = answer.skills.filter((skill) => skill.status !== "missing");
+  if (here.length) lines.push(`Already on this computer: ${here.map((skill) => `${field(skill.name, 80)}${skill.where === "global" ? " (globally)" : ""}`).join(", ")}.`);
+  for (const skill of answer.skills.filter((entry) => entry.status === "missing" && entry.kind === "skill" && !entry.pull)) {
+    lines.push(
+      skill.forSale
+        ? `Requires purchase: ${field(skill.name, 80)}. Buy it at ${field(skill.page, 200) || "its page"}, then run playbook apply again.`
+        : `Not pulled: ${field(skill.name, 80)}, which the site names no way to pull. ${field(skill.install, 300)}.`,
+    );
+  }
+  const elsewhere = answer.skills.filter((skill) => skill.status === "missing" && skill.kind !== "skill").length;
+  if (answer.installPrompt && elsewhere) {
+    lines.push(
+      "",
+      `${elsewhere === 1 ? "1 of its skills comes" : `${elsewhere} of its skills come`} from elsewhere, and this command never runs their installers. Paste this prompt into Claude Code to install ${elsewhere === 1 ? "it" : "them"}:`,
+      "",
+      answer.installPrompt,
+    );
+  }
+  return { lines, failed };
+}
+
+/** The site's check of a playbook against this computer, as lines a person reads. `project` names the project the command ran in. */
+export function describeStatus(answer, project) {
+  const skills = answer.skills;
+  const ref = field(answer.playbook?.ref, 120);
+  const outdated = skills.filter((skill) => skill.status === "outdated");
+  const missing = skills.filter((skill) => skill.status === "missing");
+  const current = skills.filter((skill) => skill.status === "installed");
+  const where = project ? `in ${field(project, 80)} and globally` : "globally";
+  const lines = [
+    `${field(answer.playbook?.name, 80)} (${ref}) on this computer, ${where}: ${skills.length - missing.length} of ${plural(skills.length, "skill")} installed${outdated.length ? `, ${outdated.length} of them outdated` : ""}.`,
+  ];
+  const state = answer.skill?.state;
+  lines.push(
+    state === "current"
+      ? "The playbook skill is installed."
+      : state === "other"
+        ? `The playbook skill here is another copy, older or edited: skillcellar playbook apply ${ref} --force replaces it.`
+        : `The playbook skill is not installed: skillcellar playbook apply ${ref} writes it.`,
+  );
+  if (current.length) lines.push("", "Installed:", ...current.map((skill) => `- ${label(skill)}, ${placeOf(skill)}`));
+  if (outdated.length) {
+    lines.push("", "Outdated:", ...outdated.map((skill) => `- ${label(skill)}, ${placeOf(skill)}${skill.update ? `: ${field(skill.update, 300)}` : ""}`));
+  }
+  if (missing.length) {
+    lines.push(
+      "",
+      "Missing:",
+      ...missing.map((skill) =>
+        skill.forSale
+          ? `- ${label(skill)}: requires purchase at ${field(skill.page, 200) || "its page"}`
+          : skill.pull
+            ? `- ${label(skill)}: skillcellar playbook apply ${ref} pulls it`
+            : `- ${label(skill)}: ${field(skill.install, 300)}`,
+      ),
+    );
+  }
+  return lines;
+}

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,352 @@
+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, 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)) {
+    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 = 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" });
+    }
+    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 = 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 };
+}
+
+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;
+    }
+    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";
+      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, allowed });
+        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 };
 }