skillcellar 0.0.0-stage → 0.3.0

package/src/files.mjs

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { join } 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) {
+  const hash = await fileHash(path);
+  return { kind, name, source: null, skillPath: null, hash, hashKind: hash ? "sha256" : null, version: null };
+}
+
+/**
+ * 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) {
+  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));
+      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) {
+  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));
+    else skipped.push(file.name);
+  }
+  return items;
+}

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 };
+}
+
+/** 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,138 @@
+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. */
+const toSlug = (name) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, 64)
+    .replace(/-+$/, "");
+
+/**
+ * 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));
+  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 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) {
+  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");
+
+/** 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 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.`);
+    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.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}`));
+  });
+  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/project.mjs

@@ -0,0 +1,62 @@
+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),
+    );
+  });
+}
+
+/**
+ * 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 };
+}

package/src/prompt.mjs

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

package/src/pull.mjs

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