skillcellar 0.0.0-stage → 0.6.0

package/src/cli.mjs

@@ -0,0 +1,525 @@
+import { readFile, stat } from "node:fs/promises";
+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 { 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";
+
+const DEFAULT_SITE = "https://skillcellar.com";
+const VERSION = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+// One sync takes the global place and up to this many projects, and this many items in all: the
+// site's SYNC_PLACES_MAX less one, and its SYNC_ITEMS_TOTAL_MAX.
+const PROJECTS_PER_SYNC = 299;
+const ITEMS_PER_SYNC = 5000;
+
+const help = () => `skillcellar ${VERSION}: keeps your SkillCellar library's list of what this computer has installed,
+and hands Claude Code the tasks you queue for it on the site.
+
+Usage:
+  skillcellar login [--device <name>] [--site <url>]
+      Sign in with an API key from <site>/dashboard/keys, and choose which of your devices this
+      computer is, or name a new one. Then offers to install Claude Code's skillcellar skill.
+  skillcellar sync [--project <name>] [--dry-run]
+      Report what this computer has, globally and in every project Claude Code knows: skills,
+      plugins, MCP servers, memory files and agents, by name and hash, in one request. The site
+      closes the tasks it then finds done.
+      --project <name>  report only the project you are in, under this name
+      --dry-run         print what would be sent, and send nothing
+  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.`;
+
+/** A mistake in how the command was called: printed with the usage, exit code 2. */
+class UsageError extends Error {}
+
+/** The site's origin: an https address, or http on this computer for development. */
+function siteOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  const local = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  return (url.protocol === "https:" || local) && !url.username && !url.password ? url.origin : null;
+}
+
+/** The device a name gives: a new one, or the account's device of that name. */
+async function namedDevice(site, key, name) {
+  try {
+    return (await call(site, key, "POST", "/api/v1/devices", { name }, VERSION)).device;
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 409 && error.body?.device) return error.body.device;
+    throw error;
+  }
+}
+
+/** Asks which of the account's devices this computer is, or for a new one's name, offering the computer's own. */
+async function chooseDevice(site, key, devices, print) {
+  if (!interactive()) throw new UsageError("Choose this computer's device with --device <name>.");
+  let choice = devices.length + 1;
+  if (devices.length) {
+    print("Which of your devices is this computer?");
+    devices.forEach((device, index) => print(`  ${index + 1}) ${device.name}`));
+    print(`  ${devices.length + 1}) A new device`);
+    choice = Number(await ask(`Choose 1-${devices.length + 1}: `));
+    if (!Number.isInteger(choice) || choice < 1 || choice > devices.length + 1) throw new UsageError("Choose one of the numbers listed.");
+  }
+  if (choice <= devices.length) return devices[choice - 1];
+  // The computer's name is sent only when the user takes it.
+  const suggested = plain(hostname());
+  const name = (await ask(`Name this computer (Enter for "${suggested}"): `)) || suggested;
+  return (await call(site, key, "POST", "/api/v1/devices", { name }, VERSION)).device;
+}
+
+/** 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();
+  if (!config) throw new Error("Run skillcellar login first.");
+  const site = siteOrigin(config.site);
+  if (!site) throw new Error(`The saved site, ${config.site}, is not an https address. Run skillcellar login again.`);
+  return { config, site };
+}
+
+/** Offers to install or update the skillcellar skill, which only a yes at the terminal writes. */
+async function offerSkill(print) {
+  const claudeDir = claudeFolder(homedir());
+  const state = await skillState(claudeDir);
+  if (state === "current") return;
+  const verb = state === "missing" ? "Install" : "Update";
+  const yes = interactive() && /^y(es)?$/i.test(await ask(`${verb} the skillcellar skill, so Claude Code can carry out the tasks you queue on the site? It goes in ${skillFolder(claudeDir)}. [y/N] `));
+  if (yes) print(`${verb === "Install" ? "Installed" : "Updated"} the skillcellar skill in ${await installSkill(claudeDir)}.`);
+  else print(`The skillcellar skill is not ${state === "missing" ? "installed" : "up to date"}; run skillcellar skill to ${verb.toLowerCase()} it.`);
+}
+
+async function login(flags, print) {
+  const site = siteOrigin(flags.site ?? process.env.SKILLCELLAR_URL ?? DEFAULT_SITE);
+  if (!site) throw new UsageError("--site must be an https address, such as https://skillcellar.com, or http on this computer for development.");
+  const key = process.env.SKILLCELLAR_API_KEY?.trim() || (interactive() ? await askSecret(`API key (create one at ${site}/dashboard/keys): `) : await firstLine());
+  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);
+  // 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);
+}
+
+const plural = (n, word, words = `${word}s`) => `${n} ${n === 1 ? word : words}`;
+
+const KINDS = [
+  ["skill", "skill"],
+  ["plugin", "plugin"],
+  ["mcp", "MCP server"],
+  ["memory", "memory file"],
+  ["agent", "agent"],
+];
+
+/** One line on what a sync reported and changed. */
+function summary(payload, result, deviceName, whole) {
+  const items = payload.places.flatMap((place) => place.items);
+  const counts = KINDS.flatMap(([kind, word]) => {
+    const n = items.filter((item) => item.kind === kind).length;
+    return n ? [plural(n, word)] : [];
+  });
+  const projects = whole ? plural(result.projects.length, "project") : (result.projects[0] ?? "no project");
+  const changes = [result.added && `${result.added} new`, result.removed && `${result.removed} no longer there`].filter(Boolean);
+  const manual =
+    result.skipped === 1
+      ? " 1 was marked by hand already; that mark stays as it is."
+      : result.skipped
+        ? ` ${result.skipped} were marked by hand already; those marks stay as they are.`
+        : "";
+  return `Synced ${deviceName}, globally and in ${projects}: ${counts.join(", ") || "nothing installed"}.${changes.length ? ` Since the last sync: ${changes.join(", ")}.` : ""}${manual}`;
+}
+
+/**
+ * Where Claude Code keeps its user settings, MCP servers and the projects it knows: ~/.claude.json,
+ * or .claude.json in CLAUDE_CONFIG_DIR when that is set.
+ */
+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 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("; ")}.`;
+}
+
+async function sync(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.`);
+  // Read from the wrong folder, a sync would report nothing and remove what the last one reported.
+  await checkClaudeFolder(claudeDir);
+
+  const claudeJson = (await readJson(claudeJsonPath(home))) ?? {};
+  const cwd = process.cwd();
+  const whole = flags.project === undefined;
+  let projects = await findProjects({ home, claudeDir, claudeJson, cwd });
+  if (!whole) {
+    const here = await findProject(cwd, home);
+    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)));
+    projects = (same.length ? same : [{ ...here, folders: new Set([cwd]) }]).map((known) => ({ ...known, name: flags.project }));
+  }
+
+  const global = await scanGlobal({ home, claudeDir, claudeJson });
+  const skipped = [...global.skipped];
+  let places = [];
+  const empty = [];
+  const unread = new Set();
+  for (const project of projects) {
+    if (!/[A-Za-z0-9]/.test(project.name)) {
+      warn(`Not reported: ${project.name} has no letter a–z or digit 0–9 to name its project by. Sync it from its folder with --project <name>.`);
+      continue;
+    }
+    let scanned;
+    try {
+      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));
+      warn(`Not reported: ${project.name}, because ${error.message} The site keeps what it had there until a sync can read it.`);
+      continue;
+    }
+    skipped.push(...scanned.skipped);
+    const place = { scope: "project", project: { name: project.name, repo: project.repo, remote: project.remote }, items: scanned.items };
+    // A complete sync replaces every place on the device, so a project with nothing in it needs no place.
+    if (whole && !scanned.items.length) empty.push(place);
+    else places.push(place);
+  }
+  // With a project unread, the sync replaces only the places it sends, so the site keeps the unread
+  // 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 (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>.`);
+  }
+  places.sort((a, b) => (a.project.name < b.project.name ? -1 : a.project.name > b.project.name ? 1 : 0));
+  if (skipped.length) {
+    warn(
+      `Not reported, because its name cannot be sent as it is (up to 128 letters, digits and . _ @ + -, starting with a letter or digit; a plugin's name reads <plugin>@<marketplace>) or its MCP transport is not stdio, http or sse: ${skipped.join(", ")}.`,
+    );
+  }
+
+  const device = config?.device.id ?? null;
+  const payload = { device, complete, places: [{ scope: "global", project: null, items: global.items }, ...places] };
+  const items = payload.places.reduce((total, place) => total + place.items.length, 0);
+  if (items > ITEMS_PER_SYNC) {
+    throw new Error(`This computer has ${items} items, and one sync takes ${ITEMS_PER_SYNC}. Sync the projects you need from their folders with --project <name>.`);
+  }
+  if (dryRun) {
+    if (!device) warn("Not signed in: the device is filled in once you run skillcellar login.");
+    print(JSON.stringify(payload, null, 2));
+    return;
+  }
+  const result = await call(site, config.key, "POST", "/api/v1/sync", payload, VERSION);
+  print(summary(payload, result, config.device.name, whole));
+  for (const note of Array.isArray(result.left) ? result.left : []) warn(`Left out ${note}`);
+  const closed = Array.isArray(result.closed) ? result.closed : [];
+  if (closed.length) print(closedLine(closed));
+  if (result.open > 0) print(`${plural(result.open, "task")} still ${result.open === 1 ? "waits" : "wait"} for ${config.device.name}: run skillcellar plan to see ${result.open === 1 ? "it" : "them"}.`);
+  else if (closed.length) print(`No task waits for ${config.device.name} now.`);
+}
+
+/** Prints this computer's open tasks, with each project task's folder here. */
+async function plan(flags, print) {
+  const { config, site } = await signedIn();
+  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 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.");
+  const scope = flags.scope ?? "global";
+  if (scope !== "global" && scope !== "project") throw new UsageError("--scope is global or project.");
+  const { config, site } = await signedIn();
+  const home = homedir();
+  let skills = join(claudeFolder(home), "skills");
+  if (scope === "project") {
+    const here = await findProject(process.cwd(), home);
+    if (!here) throw new UsageError("Run pull --scope project inside the project's folder, not in your home folder.");
+    await checkProjectSkills(here.root);
+    skills = join(here.root, ".claude", "skills");
+  }
+  const pulled = readPulled(await call(site, config.key, "GET", `/api/v1/pull?ref=${encodeURIComponent(ref)}`, undefined, VERSION));
+  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());
+  const state = await skillState(claudeDir);
+  if (state === "current") print(`The skillcellar skill in ${skillFolder(claudeDir)} is up to date.`);
+  else print(`${state === "missing" ? "Installed" : "Updated"} the skillcellar skill in ${await installSkill(claudeDir)}.`);
+}
+
+/**
+ * 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) && !FORMAT_RE.test(char));
+    })
+    .join("");
+
+/** Runs one command; the exit code: 0 done, 1 failed, 2 called wrongly. */
+export async function main(argv, toOut = console.log, toErr = console.error) {
+  const print = (text) => toOut(plain(text));
+  const warn = (text) => toErr(plain(text));
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        site: { type: "string" },
+        device: { type: "string" },
+        project: { type: "string" },
+        "dry-run": { type: "boolean" },
+        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" },
+      },
+    });
+  } catch (error) {
+    warn(`skillcellar: ${error.message}\n\n${help()}`);
+    return 2;
+  }
+  const { values: flags, positionals } = parsed;
+  if (flags.version) {
+    print(VERSION);
+    return 0;
+  }
+  const [command, ...extra] = positionals;
+  if (flags.help || !command) {
+    print(help());
+    return flags.help ? 0 : 2;
+  }
+  try {
+    // 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) {
+    if (error instanceof UsageError) {
+      warn(`skillcellar: ${error.message}\n\n${help()}`);
+      return 2;
+    }
+    const hint = error instanceof ApiError && error.status === 401 ? " If you revoked it or reset your password, create a key at the site's /dashboard/keys and run skillcellar login again." : "";
+    warn(`skillcellar: ${error.message}${hint}`);
+    return 1;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,35 @@
+import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { readJson } from "./scan.mjs";
+
+/**
+ * Where the key and this computer's device are kept: SKILLCELLAR_CONFIG, else the platform's config
+ * folder. A relative XDG_CONFIG_HOME is ignored, as the XDG spec says.
+ */
+export function configPath(env = process.env) {
+  if (env.SKILLCELLAR_CONFIG) return resolve(env.SKILLCELLAR_CONFIG);
+  const xdg = env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : null;
+  const base = process.platform === "win32" ? env.APPDATA || join(homedir(), "AppData", "Roaming") : xdg || join(homedir(), ".config");
+  return join(base, "skillcellar", "config.json");
+}
+
+/** 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.`);
+  });
+  return typeof config?.site === "string" && typeof config.key === "string" && typeof config.device?.id === "string" ? config : null;
+}
+
+/**
+ * Saves the login readable by its owner only (mode 0600, in a 0700 folder): written to a new file
+ * first, then moved over the old one, so the key never sits in a file anyone else can read.
+ */
+export async function writeConfig(config, path = configPath()) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const next = `${path}.${process.pid}.tmp`;
+  await writeFile(next, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  await chmod(next, 0o600);
+  await rename(next, path);
+}

package/src/files.mjs

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+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.
+const SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._@+-]*$/;
+const NAME_MAX = 128;
+// ponytail: a file past this is reported without a hash; memory and agents are small text.
+const HASH_BYTES_MAX = 1024 * 1024;
+// How deep a rules folder is read, so a link back to a folder above cannot loop.
+const DEPTH_MAX = 8;
+
+const sendable = (name) => name.length <= NAME_MAX && name.split("/").every((segment) => SEGMENT_RE.test(segment));
+
+/** The SHA-256 of a file's bytes, or null for one too large or gone meanwhile. */
+async function fileHash(path) {
+  const info = await stat(path).catch(() => null);
+  if (!info?.isFile() || info.size > HASH_BYTES_MAX) return null;
+  const content = await readFile(path).catch(() => null);
+  return content ? createHash("sha256").update(content).digest("hex") : null;
+}
+
+/** 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, tracked) {
+  const hash = await fileHash(path);
+  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
+ * holds none; one that cannot be read stops the sync, rather than report less than is there.
+ */
+async function markdownFiles(dir, deep, prefix = "", depth = 0, seen = new Set()) {
+  const real = await realpath(dir).catch(() => dir);
+  if (seen.has(real)) return [];
+  seen.add(real);
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return [];
+    throw new Error(`Could not read ${dir}: ${error?.code ?? error}.`);
+  }
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const path = join(dir, entry.name);
+    const info = entry.isSymbolicLink() ? await stat(path).catch(() => null) : entry;
+    if (info?.isDirectory() && deep && depth < DEPTH_MAX) files.push(...(await markdownFiles(path, deep, `${prefix}${entry.name}/`, depth + 1, seen)));
+    else if (info?.isFile() && entry.name.endsWith(".md")) files.push({ name: `${prefix}${entry.name}`, path });
+  }
+  return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * 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, own = null) {
+  const items = [];
+  for (const source of sources) {
+    const files = source.file
+      ? (await stat(source.file).catch(() => null))?.isFile()
+        ? [{ name: source.name, path: source.file }]
+        : []
+      : (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, trackedBy(own, file.path)));
+      else skipped.push(file.name);
+    }
+  }
+  return items;
+}
+
+/** 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, 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, 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 };