skillcellar 0.3.0 → 0.6.1

package/src/check.mjs

@@ -0,0 +1,59 @@
+/**
+ * A field of the site's answer as one line of the terminal: whatever the site, or a marketplace
+ * through it, put there, it cannot forge a line of this output. Line breaks become spaces.
+ */
+export const field = (value, max = 160) =>
+  String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+
+const placeOf = (item) => (item.project ? `in ${field(item.project.name, 80) || "a project"}` : "globally");
+
+/** A hash cut to what tells it apart in a line; a version as it is. */
+const short = (value) => (typeof value === "string" && /^[0-9a-f]{40,64}$/.test(value) ? value.slice(0, 7) : field(value, 64));
+
+/** What moved, in a few words: a folder's tree, a marketplace's version, or a version on the site. */
+function moved(item) {
+  if (item.kind === "plugin") return `${short(item.installed)} here, ${short(item.latest)} in its marketplace`;
+  if (item.update?.method === "pull") return "an older version of the skill on the site";
+  return `${short(item.installed)} here, ${short(item.latest)} in ${field(item.source) || "its repository"}`;
+}
+
+/** When the site last heard from the computer, as the check reads it, to the minute. */
+const syncedLine = (check) => {
+  const at = typeof check.syncedAt === "string" ? new Date(check.syncedAt) : null;
+  return at && !Number.isNaN(at.getTime()) ? `As of the last sync, ${at.toISOString().slice(0, 16).replace("T", " ")} UTC; run skillcellar sync first for the computer as it is now.` : null;
+};
+
+/** The site's check as lines a person reads: what is outdated, with its command, then what could not be checked. */
+export function describeCheck(check) {
+  const items = Array.isArray(check.items) ? check.items : [];
+  const name = field(check.device?.name, 80) || "this computer";
+  if (!items.length) return [`Nothing on ${name} to check: no skill or plugin whose source the site can read.`];
+  const outdated = items.filter((item) => item?.status === "outdated");
+  const unknown = items.filter((item) => item?.status === "unknown");
+  const current = items.filter((item) => item?.status === "current").length;
+  const lines = [];
+  if (!outdated.length) lines.push(`Nothing outdated on ${name}: ${current} ${current === 1 ? "item is" : "items are"} current.`);
+  else {
+    lines.push(`${outdated.length} of ${items.length} checked ${items.length === 1 ? "item" : "items"} on ${name} ${outdated.length === 1 ? "is" : "are"} outdated:`, "");
+    outdated.forEach((item, index) => {
+      lines.push(`${index + 1}. ${field(item.kind, 20)} ${field(item.name)}, ${placeOf(item)}: ${moved(item)}`);
+      if (item.update?.command) {
+        const where = item.project ? `inside ${field(item.project.name, 80) || "the project"}` : "";
+        const warning = item.update.method === "pull" ? "replaces the folder with the site's latest version" : "";
+        const notes = [where, warning].filter(Boolean).join("; ");
+        lines.push(`   ${field(item.update.command, 300)}${notes ? `   (${notes})` : ""}`);
+      }
+    });
+    lines.push("", `${current} ${current === 1 ? "item is" : "items are"} current.`);
+  }
+  if (unknown.length) {
+    lines.push("", `${unknown.length} could not be checked:`);
+    for (const item of unknown) lines.push(`- ${field(item.kind, 20)} ${field(item.name)}, ${placeOf(item)}: ${field(item.note) || "no way to compare it"}`);
+  }
+  const synced = syncedLine(check);
+  if (synced) lines.push("", synced);
+  return lines;
+}

package/src/cli.mjs

@@ -3,12 +3,16 @@ import { homedir, hostname } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { ApiError, call } from "./api.mjs";
+import { parseBackupRepo, runBackup } from "./backup.mjs";
+import { describeCheck } from "./check.mjs";
 import { configPath, readConfig, writeConfig } from "./config.mjs";
 import { findProjects } from "./places.mjs";
-import { describePlan, localPlan } from "./plan.mjs";
-import { findProject } from "./project.mjs";
+import { describePlan, localPlan, projectIdentity } from "./plan.mjs";
+import { applyPlaybook, cautionLine, describeStatus, readPlaybook } from "./playbook.mjs";
+import { findProject, trackedFiles } from "./project.mjs";
 import { ask, askSecret, firstLine, interactive } from "./prompt.mjs";
 import { checkProjectSkills, installPulled, PULL_REF_RE, readPulled } from "./pull.mjs";
+import { runRestore } from "./restore.mjs";
 import { readJson, scanGlobal, scanProject } from "./scan.mjs";
 import { installSkill, skillFolder, skillState } from "./skill.mjs";
 
@@ -35,12 +39,42 @@ Usage:
   skillcellar plan [--json]
       List the tasks waiting for this computer, each with how to carry it out and, for a project,
       its folder here.
+  skillcellar check [--json]
+      List what this computer has that its source has moved past, as the site last synced it: a
+      skill npx skills installed globally whose folder changed in its repository, a plugin whose
+      marketplace declares another version, a skill from the site that is an older version of
+      it; each with the command that updates it, then what the site cannot check.
   skillcellar pull <username>/<name> [--scope global|project] [--force]
       Install a skill from the site: one you wrote (<name> alone will do), one you bought, or a free
       Community skill, into ~/.claude/skills/<name>, or with --scope project into the skills folder
       of the project you are in. --force replaces a folder of that name.
+  skillcellar playbook apply <username>/<name> [--global] [--dry-run] [--force] [--yes]
+      Apply a playbook: one of yours (<name> alone will do) or one published in Community. Writes
+      its skill into the project's .claude/skills/playbook-<name>, or ~/.claude/skills with --global,
+      pulls the skills it uses from the site that this computer lacks, and prints an install prompt
+      for the ones from elsewhere, whose installers it never runs. It writes nothing outside those
+      skills folders, and keeps a folder that is there already unless you add --force. Someone
+      else's playbook writes only after a yes at the terminal, or with --yes.
+      --dry-run         list the files it would write, and write nothing
+      --yes             write someone else's playbook without asking, once you have read what it writes
+  skillcellar playbook status <username>/<name> [--global] [--json]
+      List which of a playbook's skills this computer has, in the project you are in and globally
+      (only globally with --global): installed, outdated with the command that updates it, or
+      missing with how to install it. It reads this computer as sync does, and the site keeps none of it.
   skillcellar skill
       Install or update the skillcellar skill, which tells Claude Code how to carry out your tasks.
+  skillcellar backup [--repo <owner>/<repo>] [--ssh] [--allow <file>] [--dry-run]
+      Push this computer's memory files, rules, agents, MCP config (every env and header value,
+      address credential and key-like argument replaced by a \${NAME} placeholder) and skills'
+      source files to a private GitHub repository you own, with your own git. It stops on anything
+      that looks like a secret and refuses a public repository. --repo is remembered; --ssh clones
+      and pushes over SSH; --allow <file> pushes a file you have read despite a finding in it,
+      and once pushed is remembered while the file stays the same; --dry-run lists what would go.
+  skillcellar restore [--from <device>] [--repo <owner>/<repo>] [--ssh] [--force] [--dry-run]
+      Carry out the copy tasks waiting for this computer: fetch the other computer's backup, write
+      its skills, memory files and agents into place, and list the commands left to run. A backup
+      in a repository this computer does not back up to is taken only with --repo, or a yes at the
+      terminal. --force replaces a folder or file that is there already.
 
 login reads the key from SKILLCELLAR_API_KEY when it is set, else from the terminal or the first
 line piped in. The key and the device are kept in ${configPath()}, written with mode 0600.`;
@@ -91,6 +125,13 @@ async function chooseDevice(site, key, devices, print) {
 /** Claude Code's own folder: CLAUDE_CONFIG_DIR when it is set, else ~/.claude. */
 const claudeFolder = (home) => process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude");
 
+/** Stops a command that reads this computer when Claude Code's folder is not there: read from the wrong one, it would find nothing. */
+async function checkClaudeFolder(claudeDir) {
+  if (!(await stat(claudeDir).catch(() => null))?.isDirectory()) {
+    throw new Error(`There is no Claude Code folder at ${claudeDir}. Set CLAUDE_CONFIG_DIR to the one Claude Code uses.`);
+  }
+}
+
 /** The saved login and its site, for a command that calls the site. */
 async function signedIn() {
   const config = await readConfig();
@@ -118,7 +159,10 @@ async function login(flags, print) {
   if (!/^[A-Za-z0-9_]{1,200}$/.test(key)) throw new Error(`That is not an API key. Create one at ${site}/dashboard/keys.`);
   const library = await call(site, key, "GET", "/api/v1/library", undefined, VERSION);
   const device = flags.device !== undefined ? await namedDevice(site, key, flags.device) : await chooseDevice(site, key, library.devices ?? [], print);
-  await writeConfig({ site, key, device: { id: device.id, slug: device.slug, name: device.name } });
+  // A backup repository remembered for this site stays remembered across sign-ins.
+  const earlier = await readConfig().catch(() => null);
+  const backup = earlier?.site === site && earlier.backup ? { backup: earlier.backup } : {};
+  await writeConfig({ site, key, device: { id: device.id, slug: device.slug, name: device.name }, ...backup });
   const who = library.account?.email ? ` as ${library.account.email}` : "";
   print(`Signed in to ${new URL(site).host}${who}. This computer syncs as ${device.name}.`);
   await offerSkill(print);
@@ -158,12 +202,10 @@ function summary(payload, result, deviceName, whole) {
  */
 const claudeJsonPath = (home) => (process.env.CLAUDE_CONFIG_DIR?.trim() ? join(process.env.CLAUDE_CONFIG_DIR.trim(), ".claude.json") : join(home, ".claude.json"));
 
-/** What makes checkouts one project on the site: their GitHub repository, else their name. */
-const identity = (project) => project.repo ?? project.name.toLowerCase();
-
 /** The tasks a sync closed, in one line. */
 function closedLine(closed) {
-  const done = closed.map((task) => `${task.action === "remove" ? "removed" : "installed"} ${task.name} ${task.project ? `in ${task.project}` : "globally"}`);
+  const verb = (task) => (task.action === "remove" ? "removed" : task.action === "copy" ? "copied" : "installed");
+  const done = closed.map((task) => `${verb(task)} ${task.name ?? "everything"} ${task.project ? `in ${task.project}` : "globally"}`);
   return `Closed ${plural(closed.length, "task")}: ${done.join("; ")}.`;
 }
 
@@ -176,9 +218,7 @@ async function sync(flags, print, warn) {
   const site = config ? siteOrigin(config.site) : null;
   if (config && !site) throw new Error(`The saved site, ${config.site}, is not an https address. Run skillcellar login again.`);
   // Read from the wrong folder, a sync would report nothing and remove what the last one reported.
-  if (!(await stat(claudeDir).catch(() => null))?.isDirectory()) {
-    throw new Error(`There is no Claude Code folder at ${claudeDir}. Set CLAUDE_CONFIG_DIR to the one Claude Code uses.`);
-  }
+  await checkClaudeFolder(claudeDir);
 
   const claudeJson = (await readJson(claudeJsonPath(home))) ?? {};
   const cwd = process.cwd();
@@ -189,7 +229,7 @@ async function sync(flags, print, warn) {
     if (!here) throw new UsageError("Run sync --project inside the project's folder, not in your home folder.");
     if (!/[A-Za-z0-9]/.test(flags.project)) throw new UsageError("--project needs a letter a–z or a digit 0–9.");
     // Every checkout of the same repository is one project on the site, so all of them go together.
-    const same = projects.filter((known) => known.root === here.root || (here.remote && known.remote && identity(known) === identity(here)));
+    const same = projects.filter((known) => known.root === here.root || (here.remote && known.remote && projectIdentity(known) === projectIdentity(here)));
     projects = (same.length ? same : [{ ...here, folders: new Set([cwd]) }]).map((known) => ({ ...known, name: flags.project }));
   }
 
@@ -205,11 +245,11 @@ async function sync(flags, print, warn) {
     }
     let scanned;
     try {
-      scanned = await scanProject({ root: project.root, folders: [...project.folders], claudeDir, claudeJson });
+      scanned = await scanProject({ root: project.root, folders: [...project.folders], claudeDir, claudeJson, tracked: await trackedFiles(project.root) });
     } catch (error) {
       // One project's broken file stops only that project in a sync of the whole computer.
       if (!whole) throw error;
-      unread.add(identity(project));
+      unread.add(projectIdentity(project));
       warn(`Not reported: ${project.name}, because ${error.message} The site keeps what it had there until a sync can read it.`);
       continue;
     }
@@ -223,7 +263,7 @@ async function sync(flags, print, warn) {
   // one as it was and closes no task there; an empty place is then sent, to empty it. Another
   // checkout of the unread project is left out too, or it would replace the project on its own.
   const complete = whole && !unread.size;
-  if (!complete) places = [...places, ...empty].filter((place) => !unread.has(identity(place.project)));
+  if (!complete) places = [...places, ...empty].filter((place) => !unread.has(projectIdentity(place.project)));
   if (places.length > PROJECTS_PER_SYNC) {
     throw new Error(`This computer has ${places.length} projects to send, and one sync takes ${PROJECTS_PER_SYNC}. Sync each one you need from its folder with --project <name>.`);
   }
@@ -260,15 +300,21 @@ async function plan(flags, print) {
   const answer = await call(site, config.key, "GET", `/api/v1/plan?device=${encodeURIComponent(config.device.id)}`, undefined, VERSION);
   const home = homedir();
   const claudeDir = claudeFolder(home);
-  const projects = (answer.tasks ?? []).some((task) => task.project)
-    ? await findProjects({ home, claudeDir, claudeJson: (await readJson(claudeJsonPath(home))) ?? {}, cwd: process.cwd() })
-    : [];
+  const projects = (answer.tasks ?? []).some((task) => task.project) ? await knownProjects(home, claudeDir) : [];
   // The device's slug as the site has it now: a rename changes the slugs of its folders' projects.
   const local = await localPlan(answer, { claudeDir, projects, deviceSlug: answer.device?.slug ?? config.device.slug });
   if (flags.json) print(JSON.stringify(local, null, 2));
   else for (const line of describePlan(local)) print(line);
 }
 
+/** Prints which of this computer's skills and plugins their sources have moved past, as the site checked them. */
+async function check(flags, print) {
+  const { config, site } = await signedIn();
+  const answer = await call(site, config.key, "GET", `/api/v1/check?device=${encodeURIComponent(config.device.id)}`, undefined, VERSION);
+  if (flags.json) print(JSON.stringify(answer, null, 2));
+  else for (const line of describeCheck(answer)) print(line);
+}
+
 /** Installs a skill from the site into the global skills folder, or the project's. */
 async function pull(flags, ref, print) {
   if (!ref || !PULL_REF_RE.test(ref)) throw new UsageError("Name the skill as <username>/<name>, or <name> for one of your own.");
@@ -287,6 +333,111 @@ async function pull(flags, ref, print) {
   print(`Pulled ${ref}, version ${pulled.version}, into ${await installPulled(skills, pulled, flags.force === true)}.`);
 }
 
+/**
+ * Applies a playbook to the project the command runs in, or globally, or prints where this
+ * computer stands with it. Either way the site checks it against what this computer has now,
+ * scanned as a sync scans it, and keeps none of it.
+ */
+async function playbook(flags, action, ref, print, warn) {
+  if (action !== "apply" && action !== "status") throw new UsageError("Run playbook apply <username>/<name>, or playbook status <username>/<name>.");
+  if (!ref || !PULL_REF_RE.test(ref)) throw new UsageError("Name the playbook as <username>/<name>, or <name> for one of your own.");
+  const { config, site } = await signedIn();
+  const home = homedir();
+  const claudeDir = claudeFolder(home);
+  await checkClaudeFolder(claudeDir);
+  const here = flags.global === true ? null : await findProject(process.cwd(), home);
+  if (action === "apply" && flags.global !== true && !here) throw new UsageError("Run playbook apply inside the project's folder, or add --global to apply it in ~/.claude/skills.");
+  if (action === "apply" && here) await checkProjectSkills(here.root);
+
+  const claudeJson = (await readJson(claudeJsonPath(home))) ?? {};
+  const global = await scanGlobal({ home, claudeDir, claudeJson });
+  // The project as a sync reads it: every folder in it Claude Code ran in, as well as this one.
+  const known = here ? (await findProjects({ home, claudeDir, claudeJson, cwd: process.cwd() })).find((entry) => entry.root === here.root) : null;
+  const folders = here ? [...new Set([here.root, ...(known?.folders ?? []), process.cwd()])] : [];
+  const project = here ? await scanProject({ root: here.root, folders, claudeDir, claudeJson, tracked: await trackedFiles(here.root) }) : null;
+  const body = { ref, global: global.items, project: project?.items ?? null, updates: action === "status" };
+  const answer = readPlaybook(await call(site, config.key, "POST", "/api/v1/playbook", body, VERSION));
+
+  if (action === "status") {
+    if (flags.json) print(JSON.stringify(answer, null, 2));
+    else for (const line of describeStatus(answer, here?.name ?? null)) print(line);
+    return;
+  }
+  const caution = cautionLine(answer);
+  if (caution) warn(caution);
+  const skills = here ? join(here.root, ".claude", "skills") : join(claudeDir, "skills");
+  const fetchPull = (pullRef) => call(site, config.key, "GET", `/api/v1/pull?ref=${encodeURIComponent(pullRef)}`, undefined, VERSION);
+  // Someone else's playbook writes what its author chose, scripts included: only after a yes.
+  const confirm = answer.playbook?.own
+    ? null
+    : async (files) => {
+        if (flags.yes === true) return true;
+        if (!interactive()) throw new UsageError("This playbook is someone else's: read what --dry-run lists, then run apply again with --yes.");
+        print(`It would write ${files.length === 1 ? "1 file" : `${files.length} files`}:`);
+        for (const { path, executable } of files) print(`  ${path}${executable ? " (a program it can run)" : ""}`);
+        return /^y(es)?$/i.test(await ask("Write them? [y/N] "));
+      };
+  const { lines, failed } = await applyPlaybook({ answer, skills, force: flags.force === true, dryRun: flags["dry-run"] === true, fetchPull, confirm });
+  for (const line of lines) print(line);
+  for (const note of failed) warn(`Not written: ${note}`);
+  if (failed.length) throw new Error(`${failed.length === 1 ? "1 skill was" : `${failed.length} skills were`} not written; run playbook apply again once the reason above is fixed.`);
+}
+
+/** This computer's projects, as the sync finds them. */
+async function knownProjects(home, claudeDir) {
+  return findProjects({ home, claudeDir, claudeJson: (await readJson(claudeJsonPath(home))) ?? {}, cwd: process.cwd() });
+}
+
+/**
+ * Backs up this computer to a private GitHub repository the user owns, with their own git, and
+ * reports the commit to the site. The repository is remembered from one run to the next.
+ */
+async function backup(flags, print, warn) {
+  const home = homedir();
+  const claudeDir = claudeFolder(home);
+  const dryRun = flags["dry-run"] === true;
+  const config = await readConfig();
+  if (!config && !dryRun) throw new Error("Run skillcellar login first.");
+  const site = config ? siteOrigin(config.site) : null;
+  if (config && !site) throw new Error(`The saved site, ${config.site}, is not an https address. Run skillcellar login again.`);
+  await checkClaudeFolder(claudeDir);
+  const repoValue = flags.repo ?? config?.backup?.repo;
+  if (repoValue === undefined) throw new UsageError("Name the private repository the backup goes to with --repo <owner>/<repo>, once; it is remembered.");
+  const repo = parseBackupRepo(repoValue, flags.ssh === true || (flags.repo === undefined && config?.backup?.ssh === true));
+  if (!repo) throw new UsageError("--repo takes a GitHub repository as <owner>/<repo>, its https address, or its git@github.com address.");
+  // The device's slug as the site has it now: a rename changes the folder the backup goes under.
+  const device = config
+    ? ((await call(site, config.key, "GET", `/api/v1/plan?device=${encodeURIComponent(config.device.id)}`, undefined, VERSION)).device ?? config.device)
+    : { id: null, slug: "this-computer", name: "this computer" };
+  const claudeJson = (await readJson(claudeJsonPath(home))) ?? {};
+  const projects = await knownProjects(home, claudeDir);
+  const allowed = (Array.isArray(flags.allow) ? flags.allow : []).map((path) => path.trim()).filter(Boolean);
+  // The repository is remembered as soon as a push has gone through, whatever the site answers after,
+  // with the files the user allowed despite a finding, each by the hash of what was allowed.
+  const remember = (commit, passed = []) => {
+    if (!config) return Promise.resolve();
+    const kept = passed.length ? { allowed: passed.map(({ file, sha256 }) => ({ file, sha256 })) } : {};
+    return writeConfig({ ...config, device: { id: device.id, slug: device.slug, name: device.name }, backup: { repo: repo.name, ssh: repo.ssh, ...kept } });
+  };
+  const remembered = Array.isArray(config?.backup?.allowed) ? config.backup.allowed : [];
+  const commit = await runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf: trackedFiles, version: VERSION, dryRun, allowed, remembered, print, onPushed: remember });
+  if (dryRun || !commit) return;
+  const recorded = await call(site, config.key, "POST", "/api/v1/backup", { device: device.id, repo: repo.name, commit }, VERSION);
+  const slug = recorded.device?.slug ?? device.slug;
+  if (slug !== device.slug) warn(`The site now calls this computer ${recorded.device.name}; the next backup goes under devices/${slug}.`);
+}
+
+/** Carries out this computer's copy tasks from the other computers' backups. */
+async function restore(flags, print, warn) {
+  const { config, site } = await signedIn();
+  const home = homedir();
+  const claudeDir = claudeFolder(home);
+  const answer = await call(site, config.key, "GET", `/api/v1/plan?device=${encodeURIComponent(config.device.id)}`, undefined, VERSION);
+  const projects = (answer.tasks ?? []).some((task) => task.project) ? await knownProjects(home, claudeDir) : [];
+  const plan = await localPlan(answer, { claudeDir, projects, deviceSlug: answer.device?.slug ?? config.device.slug });
+  await runRestore({ plan, claudeDir, config, flags, version: VERSION, print, warn });
+}
+
 /** Installs or updates the skillcellar skill without asking: the command itself is the yes. */
 async function skill(print) {
   const claudeDir = claudeFolder(homedir());
@@ -296,14 +447,16 @@ async function skill(print) {
 }
 
 /**
- * Text as the terminal gets it: without control characters, which a site's answer or a folder's
- * name could use to move the cursor or recolour what follows. Line breaks and tabs stay.
+ * Text as the terminal gets it: without control or format characters, which a site's answer, a
+ * folder's name or a backup's file could use to move the cursor, recolour or reorder what follows.
+ * Line breaks and tabs stay.
  */
+const FORMAT_RE = /\p{Cf}|[\u2028\u2029]/u;
 const plain = (text) =>
   Array.from(String(text))
     .filter((char) => {
       const code = char.codePointAt(0);
-      return code === 9 || code === 10 || (code >= 32 && code !== 127 && (code < 128 || code >= 160));
+      return code === 9 || code === 10 || (code >= 32 && code !== 127 && (code < 128 || code >= 160) && !FORMAT_RE.test(char));
     })
     .join("");
 
@@ -324,6 +477,12 @@ export async function main(argv, toOut = console.log, toErr = console.error) {
         json: { type: "boolean" },
         scope: { type: "string" },
         force: { type: "boolean" },
+        global: { type: "boolean" },
+        yes: { type: "boolean" },
+        repo: { type: "string" },
+        ssh: { type: "boolean" },
+        from: { type: "string" },
+        allow: { type: "string", multiple: true },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
       },
@@ -343,14 +502,18 @@ export async function main(argv, toOut = console.log, toErr = console.error) {
     return flags.help ? 0 : 2;
   }
   try {
-    // Only pull takes an argument: the skill it installs.
-    const [ref, ...rest] = command === "pull" ? extra : [undefined, ...extra];
+    // Only pull takes an argument, the skill it installs, and playbook two: what to do, and with which playbook.
+    const [action, ref, ...rest] = command === "playbook" ? extra : command === "pull" ? [undefined, ...extra] : [undefined, undefined, ...extra];
     if (rest.length) throw new UsageError(`Unexpected ${rest.join(" ")}.`);
     if (command === "login") await login(flags, print);
     else if (command === "sync") await sync(flags, print, warn);
     else if (command === "plan") await plan(flags, print);
+    else if (command === "check") await check(flags, print);
     else if (command === "pull") await pull(flags, ref, print);
+    else if (command === "playbook") await playbook(flags, action, ref, print, warn);
     else if (command === "skill") await skill(print);
+    else if (command === "backup") await backup(flags, print, warn);
+    else if (command === "restore") await restore(flags, print, warn);
     else throw new UsageError(`Unknown command ${command}.`);
     return 0;
   } catch (error) {

package/src/config.mjs

@@ -14,7 +14,7 @@ export function configPath(env = process.env) {
   return join(base, "skillcellar", "config.json");
 }
 
-/** The saved login, or null before the first one. */
+/** The saved login, or null before the first one. A saved backup repository rides along when it is there. */
 export async function readConfig(path = configPath()) {
   const config = await readJson(path).catch((error) => {
     throw new Error(`${error.message} Run skillcellar login to save it again.`);

package/src/files.mjs

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 
 // A name the site takes: segments of letters, digits and ._@+-, each starting with a letter or
 // digit, joined by slashes for a file in a folder.
@@ -22,11 +22,14 @@ async function fileHash(path) {
 }
 
 /** A memory file or an agent as the sync sends it: its name and its SHA-256, never its content. */
-async function fileItem(kind, name, path) {
+async function fileItem(kind, name, path, tracked) {
   const hash = await fileHash(path);
-  return { kind, name, source: null, skillPath: null, hash, hashKind: hash ? "sha256" : null, version: null };
+  return { kind, name, source: null, skillPath: null, hash, hashKind: hash ? "sha256" : null, version: null, tracked };
 }
 
+/** Whether a project's git tracks the file: `own` holds the project's root and its tracked paths, or is null outside a project. */
+const trackedBy = (own, path) => (own ? own.tracked.has(relative(own.root, path).split("\\").join("/")) : false);
+
 /**
  * The `.md` files in a folder and, with `deep`, in the folders inside it, by their path from it.
  * Each folder is read once, so a link back to one above cannot loop. A folder that is not there
@@ -58,7 +61,7 @@ async function markdownFiles(dir, deep, prefix = "", depth = 0, seen = new Set()
  * Memory files, each named by the label of the folder it comes from and its path there, such as
  * rules/common/testing.md; a single file is named as it is, such as CLAUDE.md.
  */
-export async function memoryItems(sources, skipped) {
+export async function memoryItems(sources, skipped, own = null) {
   const items = [];
   for (const source of sources) {
     const files = source.file
@@ -67,7 +70,7 @@ export async function memoryItems(sources, skipped) {
         : []
       : (await markdownFiles(source.dir, source.deep)).map((file) => ({ name: `${source.name}/${file.name}`, path: file.path }));
     for (const file of files) {
-      if (sendable(file.name)) items.push(await fileItem("memory", file.name, file.path));
+      if (sendable(file.name)) items.push(await fileItem("memory", file.name, file.path, trackedBy(own, file.path)));
       else skipped.push(file.name);
     }
   }
@@ -75,12 +78,15 @@ export async function memoryItems(sources, skipped) {
 }
 
 /** The agents in a folder and the folders inside it, as Claude Code reads them: each `.md` file, by its path from the folder without `.md`. */
-export async function agentItems(dir, skipped) {
+export async function agentItems(dir, skipped, own = null) {
   const items = [];
   for (const file of await markdownFiles(dir, true)) {
     const name = file.name.slice(0, -".md".length);
-    if (sendable(name)) items.push(await fileItem("agent", name, file.path));
+    if (sendable(name)) items.push(await fileItem("agent", name, file.path, trackedBy(own, file.path)));
     else skipped.push(file.name);
   }
   return items;
 }
+
+/** The `.md` files of a folder, for a backup: the same files a sync names, with their paths. */
+export { markdownFiles };

package/src/mcp.mjs

@@ -89,7 +89,7 @@ export function mcpItem(name, server) {
   } else {
     return null;
   }
-  return { kind: "mcp", name, source: null, skillPath: null, hash: null, hashKind: null, version: null, transport, target };
+  return { kind: "mcp", name, source: null, skillPath: null, hash: null, hashKind: null, version: null, transport, target, tracked: false };
 }
 
 /** The MCP servers of one `mcpServers` object, by name; the names it cannot send go to `skipped`. */

package/src/plan.mjs

@@ -4,7 +4,7 @@ import { sessionFolderName } from "./places.mjs";
 import { readJson } from "./scan.mjs";
 
 /** A name's slug as the site makes it: lowercase letters and digits with single hyphens between. */
-const toSlug = (name) =>
+export const toSlug = (name) =>
   name
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
@@ -12,14 +12,19 @@ const toSlug = (name) =>
     .slice(0, 64)
     .replace(/-+$/, "");
 
+/** A project's slug as the site makes it: its name's, and for a folder with no git remote that followed by the device's. */
+export const projectSlug = (project, deviceSlug) => (project.remote ? toSlug(project.name) : `${toSlug(project.name)}-${deviceSlug}`);
+
+/** What makes checkouts one project on the site: their GitHub repository, else their name. */
+export const projectIdentity = (project) => project.repo ?? project.name.toLowerCase();
+
 /**
  * The folder on this computer of a task's project, from the projects the sync finds: one with a
  * GitHub repository by that repository, any other by its slug, which for a folder with no git remote
  * ends with this device's. With several checkouts, the first; null when this computer has none.
  */
 export function projectFolder(project, projects, deviceSlug) {
-  const slug = (known) => (known.remote ? toSlug(known.name) : `${toSlug(known.name)}-${deviceSlug}`);
-  const matches = projects.filter((known) => (project.repo ? known.repo === project.repo : slug(known) === project.slug));
+  const matches = projects.filter((known) => (project.repo ? known.repo === project.repo : projectSlug(known, deviceSlug) === project.slug));
   return matches.map((known) => known.root).sort()[0] ?? null;
 }
 
@@ -43,11 +48,11 @@ function inside(base, path) {
 }
 
 /**
- * Whether a removal names an item the way the sync sends it from that place (scan.mjs): a skill,
- * plugin or MCP server by one name, an agent by its path in its folder, and a memory file only from
- * the places the sync reads. A plan naming anything else did not come from a sync of this computer.
+ * Whether a removal or a copy names an item the way the sync sends it from that place (scan.mjs): a
+ * skill, plugin or MCP server by one name, an agent by its path in its folder, and a memory file only
+ * from the places the sync reads. A plan naming anything else did not come from a sync of this computer.
  */
-function sentName(kind, name, project) {
+export function sentName(kind, name, project) {
   if (!SENT_NAME_RE.test(name)) return false;
   if (kind === "agent") return true;
   if (kind !== "memory") return !name.includes("/");
@@ -114,24 +119,44 @@ export async function localPlan(plan, { claudeDir, projects, deviceSlug }) {
 
 const placeOf = (task) => (task.project ? `in ${task.project.name}${task.folder ? ` (${task.folder})` : ""}` : "globally");
 
+/** One line per item a copy still needs: from the backup's files, a command, or the repository a clone brings it with. */
+function copyLines(copy) {
+  return copy.items.map((item) => {
+    const how = item.tracked ? "tracked by the project's git: pull the repository" : item.install ? item.install.command : item.kind === "mcp" ? "from the backup's MCP config (claude mcp add-json)" : "from the backup";
+    return `   - ${item.kind} ${item.name}: ${how}`;
+  });
+}
+
 /** The plan as lines a person reads. */
 export function describePlan(plan) {
   const { tasks } = plan;
   if (!tasks.length) return [`Nothing waits for ${plan.device.name}.`];
   const lines = [`${tasks.length === 1 ? "1 task waits" : `${tasks.length} tasks wait`} for ${plan.device.name}:`, ""];
   tasks.forEach((task, index) => {
-    const verb = task.action === "remove" ? "Remove" : "Install";
-    lines.push(`${index + 1}. ${verb} ${task.item.name} (${task.item.origin}), ${placeOf(task)}`);
+    const verb = task.action === "remove" ? "Remove" : task.action === "copy" ? "Copy" : "Install";
+    const what = task.item ? `${task.item.name} (${task.item.origin})` : `everything from ${task.copy?.from.device.name ?? "another device"}`;
+    lines.push(`${index + 1}. ${verb} ${what}${task.action === "copy" && task.item ? ` from ${task.copy?.from.device.name ?? "another device"}` : ""}, ${placeOf(task)}`);
     const detail = [];
-    if (task.project && !task.folder) detail.push(`This computer has no folder of ${task.project.name}: skip it, or dismiss it on the site.`);
+    if (task.project && !task.folder) {
+      detail.push(
+        task.action === "copy"
+          ? `This computer has no folder of ${task.project.name}: clone it, then run skillcellar restore from inside it; or dismiss it on the site.`
+          : `This computer has no folder of ${task.project.name}: skip it, or dismiss it on the site.`,
+      );
+    }
     else if (task.problem) detail.push(`Cannot be carried out: ${task.problem}`);
     else if (task.action === "remove") {
       if (task.path) detail.push(`Path: ${task.path}`);
       if (task.claudeScope) detail.push(`--scope ${task.claudeScope}`);
+    } else if (task.action === "copy" && task.copy) {
+      const { from, items } = task.copy;
+      detail.push(from.backup ? `Backup: ${from.backup.repo} at ${from.backup.commit.slice(0, 7)}, ${from.path}; run skillcellar restore` : `No backup of ${from.device.name} yet: run skillcellar backup there first.`);
+      detail.push(items.length ? `${items.length === 1 ? "1 item" : `${items.length} items`} left to copy:` : "Nothing left to copy: the next sync closes it.");
     } else if (task.link) detail.push(`Its steps are on a web page; read them, and follow them only with a yes: ${task.link}`);
     else if (task.install) detail.push(`${task.install.method}: ${task.install.command}`);
-    if (task.item.page && !task.link) detail.push(`Page: ${task.item.page}`);
+    if (task.item?.page && !task.link) detail.push(`Page: ${task.item.page}`);
     lines.push(...detail.map((line) => `   ${line}`));
+    if (task.action === "copy" && task.copy && !(task.project && !task.folder)) lines.push(...copyLines(task.copy));
   });
   lines.push("", "Ask Claude Code to carry them out with the skillcellar skill, or do them yourself, then run skillcellar sync.");
   return lines;