skillcellar 0.3.0 → 0.6.0

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 { 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;
+      --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);
@@ -163,7 +207,8 @@ 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 +221,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();
@@ -205,7 +248,7 @@ 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;
@@ -260,15 +303,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 +336,105 @@ 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.
+  const remember = () => (config ? writeConfig({ ...config, device: { id: device.id, slug: device.slug, name: device.name }, backup: { repo: repo.name, ssh: repo.ssh } }) : Promise.resolve());
+  const commit = await runBackup({ repo, device, claudeDir, claudeJson, projects, trackedOf: trackedFiles, version: VERSION, dryRun, allowed, print, onPushed: remember });
+  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 +444,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 +474,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 +499,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,16 @@ 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}`);
+
 /**
  * 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 +45,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 +116,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;

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;
+}