skillcellar 0.0.0-stage → 0.6.0

package/src/prompt.mjs

@@ -0,0 +1,55 @@
+import { createInterface } from "node:readline/promises";
+
+const CTRL_C = String.fromCharCode(3);
+const BACKSPACE = [String.fromCharCode(8), String.fromCharCode(127)];
+const ESCAPE_SEQUENCE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[~A-Za-z]`, "g");
+
+export const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+/** One answer typed at the terminal. */
+export async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+/** A secret typed or pasted at the terminal, never echoed. */
+export function askSecret(question) {
+  const { stdin, stdout } = process;
+  stdout.write(question);
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const finish = (error) => {
+      stdin.off("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write("\n");
+      if (error) reject(error);
+      else resolve(value.replace(ESCAPE_SEQUENCE, "").trim());
+    };
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\r" || char === "\n") return finish();
+        if (char === CTRL_C) return finish(new Error("Cancelled."));
+        value = BACKSPACE.includes(char) ? value.slice(0, -1) : value + char;
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+    stdin.resume();
+  });
+}
+
+/** The first line piped into the command, for a key passed without a terminal. */
+export async function firstLine() {
+  let text = "";
+  for await (const chunk of process.stdin) {
+    text += chunk;
+    if (text.includes("\n")) break;
+  }
+  return text.split("\n")[0].trim();
+}

package/src/pull.mjs

@@ -0,0 +1,95 @@
+import { chmod, lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+// What `skillcellar pull` names: <username>/<name>, or <name> for one of the user's own.
+export const PULL_REF_RE = /^(?:[a-z0-9]+(?:-[a-z0-9]+)*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// ponytail: the site keeps 200 files and 1 MB a version; these only stop an answer that is not one.
+const FILES_MAX = 1000;
+const BYTES_MAX = 16 * 1024 * 1024;
+const PATH_MAX = 255;
+// The site's own rules for a file's path (src/lib/skills/files.ts), checked again here, so that an
+// answer the site would never give cannot write one: characters no file name holds on one of Linux,
+// macOS or Windows or that hide a name, Windows device names and trimmed names, and what npx skills
+// leaves out, such as a .git folder whose config would run a command.
+const UNSAFE_CHARACTER_RE = /[\\:*?"<>|\u2028\u2029\p{Cc}\p{Cf}\p{Default_Ignorable_Code_Point}]/u;
+const WINDOWS_NAME_RE = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$|[. ]$/i;
+const SKIPPED_FOLDERS = new Set([".git", "node_modules", "__pycache__", "__pypackages__"]);
+const SKIPPED_FILES = new Set(["metadata.json", ".DS_Store", "Thumbs.db", "desktop.ini"]);
+// The folder Claude Code's own skillcellar skill lives in: nothing pulled may take its place.
+const RESERVED_SLUG = "skillcellar";
+
+/** A file's path inside the skill's folder, as relative segments the site would store; null otherwise. */
+function safePath(path) {
+  if (typeof path !== "string" || !path || path.length > PATH_MAX || path.startsWith("/")) return null;
+  if (UNSAFE_CHARACTER_RE.test(path) || !path.isWellFormed() || path !== path.normalize("NFC")) return null;
+  const segments = path.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === ".." || WINDOWS_NAME_RE.test(segment))) return null;
+  if (SKIPPED_FILES.has(segments[segments.length - 1]) || segments.slice(0, -1).some((segment) => SKIPPED_FOLDERS.has(segment))) return null;
+  return segments;
+}
+
+/** The skill the site answered with, checked before anything is written: its name and files, decoded. */
+export function readPulled(answer) {
+  const slug = answer?.skill?.slug;
+  if (typeof slug !== "string" || !SLUG_RE.test(slug) || slug === RESERVED_SLUG || !Array.isArray(answer.files) || answer.files.length > FILES_MAX) {
+    throw new Error("The site's answer is not a skill this command can install.");
+  }
+  let bytes = 0;
+  const files = answer.files.map((file) => {
+    const segments = safePath(file?.path);
+    if (!segments || typeof file.content !== "string") throw new Error(`The site's answer holds a file this command will not write: ${String(file?.path).slice(0, 80)}.`);
+    const content = Buffer.from(file.content, "base64");
+    bytes += content.length;
+    return { segments, content, executable: file.executable === true };
+  });
+  if (bytes > BYTES_MAX || !files.some((file) => file.segments.join("/") === "SKILL.md")) throw new Error("The site's answer is not a skill this command can install.");
+  return { slug, version: answer.skill.version, files };
+}
+
+/**
+ * Refuses a project whose `.claude` or `.claude/skills` is a link: a cloned repository can carry one
+ * that points anywhere, and the pull would write there.
+ */
+export async function checkProjectSkills(root) {
+  for (const path of [join(root, ".claude"), join(root, ".claude", "skills")]) {
+    if ((await lstat(path).catch(() => null))?.isSymbolicLink()) throw new Error(`${path} is a link, so the skill could land outside the project. Pull it globally instead.`);
+  }
+}
+
+/**
+ * Writes a pulled skill into `<skills>/<slug>`: into a new hidden folder beside it first, which the
+ * sync skips, then moved into place, so a failure leaves no half-written skill. A folder or link
+ * already there is replaced only with `force`, and put back when the swap fails.
+ */
+export async function installPulled(skills, pulled, force) {
+  const target = join(skills, pulled.slug);
+  const there = await lstat(target).catch(() => null);
+  if (there && !force) throw new Error(`${target} is there already. Run pull again with --force to replace it.`);
+  const fresh = join(skills, `.${pulled.slug}.skillcellar-${process.pid}`);
+  const old = join(skills, `.${pulled.slug}.replaced-${process.pid}`);
+  await rm(fresh, { recursive: true, force: true });
+  await mkdir(fresh, { recursive: true });
+  let moved = false;
+  try {
+    for (const file of pulled.files) {
+      const path = join(fresh, ...file.segments);
+      // The segments were checked; this is the last guard before a write.
+      if (relative(fresh, path).startsWith("..")) throw new Error("The site's answer names a file outside the skill's folder.");
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, file.content, { flag: "wx" });
+      await chmod(path, file.executable ? 0o755 : 0o644);
+    }
+    if (there) {
+      await rename(target, old);
+      moved = true;
+    }
+    await rename(fresh, target);
+  } catch (error) {
+    await rm(fresh, { recursive: true, force: true });
+    if (moved && !(await lstat(target).catch(() => null))) await rename(old, target).catch(() => {});
+    throw error;
+  }
+  if (moved) await rm(old, { recursive: true, force: true });
+  return target;
+}

package/src/restore.mjs

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