skillcellar 0.0.0-stage → 0.6.0

package/src/hash.mjs

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+// ponytail: a folder past this size is reported without a hash, so a stray virtualenv cannot stall
+// a sync; read the files as a stream if large skills turn out to need one.
+const HASH_BYTES_MAX = 20 * 1024 * 1024;
+
+/**
+ * The hash `npx skills` writes to skills-lock.json as `computedHash`, and the site stores as a
+ * skill's content hash: SHA-256 over each file's path relative to the folder, then its bytes, the
+ * paths sorted by localeCompare, skipping `.git` and `node_modules` folders and anything that is not
+ * a regular file. Read from the skills CLI 1.7.2 source. Null for a folder past HASH_BYTES_MAX.
+ */
+export async function folderHash(dir) {
+  const files = [];
+  const budget = { left: HASH_BYTES_MAX };
+  if (!(await collect(dir, dir, files, budget))) return null;
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  const hash = createHash("sha256");
+  for (const file of files) hash.update(file.path).update(file.content);
+  return hash.digest("hex");
+}
+
+async function collect(base, current, files, budget) {
+  for (const entry of await readdir(current, { withFileTypes: true })) {
+    const path = join(current, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      if (!(await collect(base, path, files, budget))) return false;
+    } else if (entry.isFile()) {
+      budget.left -= (await stat(path)).size;
+      if (budget.left < 0) return false;
+      files.push({ path: relative(base, path).split("\\").join("/"), content: await readFile(path) });
+    }
+  }
+  return true;
+}

package/src/mcp.mjs

@@ -0,0 +1,104 @@
+import { basename } from "node:path";
+
+// What the site accepts, checked here too, so a sync never fails on one odd server: a name an
+// install prompt can print as it is, a command's own name, a package as npm or PyPI write one, and
+// an address whose path holds only short words, such as /v1/mcp.
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/;
+const COMMAND_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+const PACKAGE_RE = /^@?[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)?(?:@[A-Za-z0-9._+-]+|==?[A-Za-z0-9._+-]+)?$/;
+const ENDPOINT_RE = /^https?:\/\/[A-Za-z0-9.-]+(?::\d{1,5})?(?:\/(?:[a-z]{1,8}|v\d{1,3})?)*$/;
+const WORD_RE = /^(?:[a-z]{1,8}|v\d{1,3})$/;
+const TARGET_MAX = 200;
+
+/**
+ * Runners that start a package: the flags of theirs known to take a value before it, and those
+ * known to stand alone. Any other flag could be followed by a key, so it ends the search.
+ */
+const RUNNERS = new Map([
+  ["npx", { valued: ["-p", "--package", "-c", "--call"], alone: ["-y", "--yes", "-q", "--quiet", "-s", "--silent", "--no-install", "--prefer-offline", "--prefer-online"] }],
+  ["bunx", { valued: ["-p", "--package"], alone: ["-b", "--bun", "--silent", "--no-install"] }],
+  ["pnpm dlx", { valued: ["-p", "--package"], alone: ["-s", "--silent", "--shell-mode", "-c"] }],
+  ["pnpx", { valued: ["-p", "--package"], alone: ["-s", "--silent"] }],
+  ["uvx", { valued: ["--from", "--with", "--with-editable", "--with-requirements", "--python", "-p", "--index", "--index-url"], alone: ["-q", "--quiet", "--offline", "--isolated", "--no-cache", "-n", "--refresh"] }],
+]);
+
+/**
+ * The runner and the package it starts: the first argument that is not a known flag or a known
+ * flag's value, as npm or PyPI write a package; null for anything else, such as a path, an address
+ * or a secret, and after any flag it does not know.
+ */
+function runnerPackage(command, args) {
+  const runner = command === "pnpm" && args[0] === "dlx" ? "pnpm dlx" : command;
+  const flags = RUNNERS.get(runner);
+  if (!flags) return null;
+  const rest = runner === "pnpm dlx" ? args.slice(1) : args;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (typeof arg !== "string") return null;
+    if (!arg.startsWith("-")) return PACKAGE_RE.test(arg) ? `${runner} ${arg}` : null;
+    if (flags.valued.includes(arg)) index += 1;
+    else if (!flags.alone.includes(arg) && !arg.includes("=")) return null;
+  }
+  return null;
+}
+
+/**
+ * An address's origin and path, up to the first part of the path that is not a short word such as
+ * mcp, sse or v1, since some addresses carry a key there; never its credentials, query or fragment.
+ * Null for anything but http and https, and for a host the site would not take.
+ */
+function endpoint(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  const kept = [];
+  for (const segment of url.pathname.split("/").slice(1)) {
+    if (!WORD_RE.test(segment)) break;
+    kept.push(segment);
+  }
+  const target = `${url.origin}/${kept.join("/")}`;
+  return target.length <= TARGET_MAX && ENDPOINT_RE.test(target) ? target : null;
+}
+
+/**
+ * An MCP server as the sync sends it: its name, its transport and what it runs or answers on. For
+ * a local server, the command's own name and the package a runner such as npx starts; for a remote
+ * one, the address's origin and path. Never its environment, headers, other arguments or a query.
+ * Null when the name cannot be sent as it is, and for what Claude Code itself skips or this site
+ * does not keep: a server with no command or address, or a WebSocket or SDK one.
+ */
+export function mcpItem(name, server) {
+  if (!NAME_RE.test(name) || typeof server !== "object" || server === null) return null;
+  // Claude Code reads a server without a type as stdio, and streamable-http as http.
+  const transport = server.type === "streamable-http" ? "http" : (server.type ?? "stdio");
+  let target = null;
+  if (transport === "stdio") {
+    if (typeof server.command !== "string") return null;
+    const command = basename(server.command.replaceAll("\\", "/")).replace(/\.(cmd|exe|bat)$/i, "");
+    if (COMMAND_RE.test(command)) {
+      const run = runnerPackage(command, Array.isArray(server.args) ? server.args : []);
+      target = run && run.length <= TARGET_MAX ? run : command;
+    }
+  } else if (transport === "http" || transport === "sse") {
+    if (typeof server.url !== "string") return null;
+    target = endpoint(server.url);
+  } else {
+    return null;
+  }
+  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`. */
+export function mcpItems(servers, skipped) {
+  const items = [];
+  for (const [name, server] of Object.entries(servers ?? {})) {
+    const item = mcpItem(name, server);
+    if (item) items.push(item);
+    else skipped.push(name);
+  }
+  return items;
+}

package/src/places.mjs

@@ -0,0 +1,76 @@
+import { open, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+import { findProject } from "./project.mjs";
+
+// How much of a session's transcript is read for the folder it ran in, which its first lines name.
+const TRANSCRIPT_HEAD_BYTES = 64 * 1024;
+const CWD_RE = /"cwd":("(?:[^"\\]|\\.)*")/;
+
+/** The folder name Claude Code keeps a project's sessions and memory under: its path, with each character but a letter or digit as `-`. */
+export const sessionFolderName = (path) => path.replace(/[^A-Za-z0-9]/g, "-");
+
+/** The folder a session of `~/.claude/projects/<name>` ran in, read from the start of its newest transcript; null without one. */
+async function sessionFolder(dir) {
+  let names;
+  try {
+    names = (await readdir(dir)).filter((name) => name.endsWith(".jsonl"));
+  } catch {
+    return null;
+  }
+  const dated = await Promise.all(names.map(async (name) => ({ name, at: (await stat(join(dir, name)).catch(() => null))?.mtimeMs ?? 0 })));
+  for (const { name } of dated.sort((a, b) => b.at - a.at)) {
+    const file = await open(join(dir, name), "r").catch(() => null);
+    if (!file) continue;
+    try {
+      const buffer = Buffer.alloc(TRANSCRIPT_HEAD_BYTES);
+      const { bytesRead } = await file.read(buffer, 0, TRANSCRIPT_HEAD_BYTES, 0);
+      const match = CWD_RE.exec(buffer.subarray(0, bytesRead).toString("utf8"));
+      if (match) return JSON.parse(match[1]);
+    } catch {
+      // A transcript cut mid-escape names no folder; the next one may.
+    } finally {
+      await file.close();
+    }
+  }
+  return null;
+}
+
+/**
+ * Every folder Claude Code knows on this computer: the projects `~/.claude.json` lists, and the
+ * folder each of `~/.claude/projects/*` ran in. Folders that are gone are skipped.
+ */
+async function knownFolders(claudeDir, claudeJson) {
+  const folders = new Set(Object.keys(claudeJson?.projects ?? {}));
+  const sessions = join(claudeDir, "projects");
+  const names = await readdir(sessions).catch(() => []);
+  const listed = new Set([...folders].map(sessionFolderName));
+  for (const name of names) {
+    if (listed.has(name)) continue;
+    const folder = await sessionFolder(join(sessions, name));
+    if (typeof folder === "string") folders.add(folder);
+  }
+  const present = [];
+  for (const folder of folders) if ((await stat(folder).catch(() => null))?.isDirectory()) present.push(folder);
+  return present;
+}
+
+const real = (path) => realpath(path).catch(() => path);
+
+/**
+ * The projects on this computer, one per checkout or folder, each with the folders Claude Code ran
+ * in inside it: their local MCP servers and session memory belong to it. `cwd` is added when it is
+ * in a project. The home folder, those above it and Claude Code's own folder are never one.
+ */
+export async function findProjects({ home, claudeDir, claudeJson, cwd }) {
+  const projects = new Map();
+  const own = await real(claudeDir);
+  for (const folder of [...(await knownFolders(claudeDir, claudeJson)), cwd]) {
+    const project = await findProject(folder, home);
+    const inside = project && relative(own, project.root);
+    if (!project || inside === "" || (inside && !inside.startsWith("..") && !isAbsolute(inside))) continue;
+    const known = projects.get(project.root) ?? { ...project, folders: new Set() };
+    known.folders.add(folder);
+    projects.set(project.root, known);
+  }
+  return [...projects.values()];
+}

package/src/plan.mjs

@@ -0,0 +1,160 @@
+import { stat } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+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. */
+export const toSlug = (name) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .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 matches = projects.filter((known) => (project.repo ? known.repo === project.repo : projectSlug(known, deviceSlug) === project.slug));
+  return matches.map((known) => known.root).sort()[0] ?? null;
+}
+
+// A name as the sync sends it: segments of letters, digits and ._@+-, each starting with a letter or digit.
+const SENT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@+-]*(?:\/[A-Za-z0-9][A-Za-z0-9._@+-]*)*$/;
+
+const exists = async (path) => (await stat(path).catch(() => null)) !== null;
+
+/** The first of these paths that exists, else the first. */
+async function firstThere(paths) {
+  for (const path of paths) if (await exists(path)) return path;
+  return paths[0] ?? null;
+}
+
+const UNKNOWN_NAME = "Its name is not one a sync sends from this place, so this computer cannot tell what it would remove. Dismiss it on the site.";
+
+/** A path that stays inside its base folder, or null. */
+function inside(base, path) {
+  const from = relative(base, path);
+  return from && !from.startsWith("..") && !isAbsolute(from) ? path : null;
+}
+
+/**
+ * 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.
+ */
+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("/");
+  const [first, ...rest] = name.split("/");
+  if (name === "CLAUDE.md" || (first === "rules" && rest.length > 0)) return true;
+  return project ? name === "AGENTS.md" || (first === "memory" && rest.length === 1) : false;
+}
+
+/**
+ * Where an item a removal names is on this computer, as the sync read it: a skill's folder, an
+ * agent's or a memory file's path, or the `--scope` that `claude plugin` and `claude mcp` take for
+ * a plugin or an MCP server. Null for what this computer does not have where the task says; a
+ * `problem` for a name the sync could not have sent, which could otherwise reach out of its folder.
+ */
+async function removalTarget(task, { claudeDir, project }) {
+  const { kind, name } = task.item;
+  const root = project?.root ?? null;
+  const none = { path: null, claudeScope: null, problem: null };
+  if (!sentName(kind, name, task.scope === "project")) return { ...none, problem: UNKNOWN_NAME };
+  if (task.scope === "project" && !root) return none;
+  const own = (...segments) => join(root ?? claudeDir, ...(root ? [".claude"] : []), ...segments);
+  if (kind === "skill") return { ...none, path: inside(own("skills"), own("skills", name)) };
+  if (kind === "agent") return { ...none, path: inside(own("agents"), own("agents", `${name}.md`)) };
+  if (kind === "memory") {
+    const [first, ...rest] = name.split("/");
+    if (first === "rules") return { ...none, path: inside(own("rules"), own("rules", ...rest)) };
+    if (first === "memory") {
+      const folders = [...new Set([root, ...(project.folders ?? [])])];
+      return { ...none, path: await firstThere(folders.map((folder) => join(claudeDir, "projects", sessionFolderName(folder), "memory", ...rest))) };
+    }
+    return { ...none, path: join(root ?? claudeDir, name) };
+  }
+  if (kind === "mcp") {
+    if (!root) return { ...none, claudeScope: "user" };
+    const shared = (await readJson(join(root, ".mcp.json")).catch(() => null))?.mcpServers ?? {};
+    return { ...none, claudeScope: Object.hasOwn(shared, name) ? "project" : "local" };
+  }
+  if (!root) return { ...none, claudeScope: "user" };
+  // A plugin installed in a project is installed for everyone there ("project") or this computer only ("local").
+  const installed = (await readJson(join(claudeDir, "plugins", "installed_plugins.json")).catch(() => null))?.plugins?.[name];
+  const here = Array.isArray(installed) ? installed.find((entry) => entry?.projectPath && [root, ...(project.folders ?? [])].includes(entry.projectPath)) : null;
+  return { ...none, claudeScope: here?.scope === "project" ? "project" : "local" };
+}
+
+/**
+ * The plan the site gives, with what only this computer knows added to each task: `folder`, the
+ * project's folder here (null for a global task, or a project this computer has no folder of), and
+ * for a removal `path` and `claudeScope`. Nothing here is sent to the site.
+ */
+export async function localPlan(plan, { claudeDir, projects, deviceSlug }) {
+  const tasks = [];
+  for (const task of plan.tasks ?? []) {
+    const root = task.project ? projectFolder(task.project, projects, deviceSlug) : null;
+    const project = root ? projects.find((known) => known.root === root) : null;
+    const local = { folder: root };
+    if (task.action === "remove") {
+      const { path, claudeScope, problem } = await removalTarget(task, { claudeDir, project });
+      Object.assign(local, { path, claudeScope }, problem ? { problem } : {});
+    }
+    tasks.push({ ...task, ...local });
+  }
+  return { device: plan.device, tasks };
+}
+
+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" : 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(
+        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}`);
+    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;
+}

package/src/project.mjs

@@ -0,0 +1,77 @@
+import { execFile } from "node:child_process";
+import { realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+/** The folder holding the nearest .git above `cwd`, or null. */
+async function gitRoot(cwd) {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    if (await stat(join(dir, ".git")).catch(() => null)) return dir;
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/**
+ * The address of a checkout's `origin` remote, read by git itself, so worktrees and includes work;
+ * null without one. On Windows git is looked up on PATH only, never in the checkout.
+ */
+function originUrl(root) {
+  return new Promise((done) => {
+    execFile(
+      "git",
+      ["-C", root, "config", "--get", "remote.origin.url"],
+      { timeout: 5000, env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" } },
+      (error, stdout) => done(error ? null : stdout.trim() || null),
+    );
+  });
+}
+
+/**
+ * The files a checkout's git tracks, by their path from its root with forward slashes; an empty set
+ * when git is missing or the folder is no checkout. A clone brings these, so a backup leaves them out.
+ */
+export function trackedFiles(root) {
+  return new Promise((done) => {
+    execFile(
+      "git",
+      ["-C", root, "ls-files", "-z"],
+      { timeout: 10_000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" } },
+      (error, stdout) => done(new Set(error ? [] : stdout.split("\0").filter(Boolean))),
+    );
+  });
+}
+
+/**
+ * A remote's last two path segments, `owner/repo`, and whether it is a GitHub repository: from an
+ * https, ssh or git address, or an scp-style user@host:path whose host has a dot. Anything else, a
+ * path on disk or a file: address included, names nothing. Credentials are never read.
+ */
+export function remoteName(url) {
+  const text = url ?? "";
+  const scheme = /^(?:https?|ssh|git):\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+)$/i.exec(text);
+  const scp = /^[^@/\s:]+@([^/:\s]+\.[^/:\s]+):(?!\/)(.+)$/.exec(text);
+  const [, host, path] = scheme ?? scp ?? [];
+  if (!host || !path) return null;
+  const segments = path.replace(/\/+$/, "").replace(/\.git$/, "").split("/").filter(Boolean);
+  const last = segments.slice(-2);
+  if (last.length < 2 || last.some((segment) => !/^[A-Za-z0-9_.-]+$/.test(segment) || segment === "." || segment === "..")) return null;
+  const name = last.join("/");
+  const github = /^(www\.)?github\.com$/i.test(host) && segments.length === 2;
+  return { name, repo: github ? name.toLowerCase() : null };
+}
+
+/**
+ * The project a folder is part of: its git checkout, or the folder itself. The home folder and
+ * the folders above it are never a project, since ~/.claude/skills is the global one. The project
+ * is named by its git remote's owner/repo, else by its folder; `named` overrides both. One with no
+ * remote belongs to this computer alone.
+ */
+export async function findProject(cwd, home, named) {
+  const real = (path) => realpath(path).catch(() => resolve(path));
+  const start = await real(cwd);
+  const root = (await gitRoot(start)) ?? start;
+  // On another drive, relative() answers with an absolute path: that folder is outside home too.
+  const fromHome = relative(root, await real(home));
+  if (fromHome === "" || (!fromHome.startsWith("..") && !isAbsolute(fromHome))) return null;
+  const remote = remoteName(await originUrl(root));
+  return { root, name: named ?? remote?.name ?? basename(root), repo: remote?.repo ?? null, remote: remote !== null };
+}