skillcellar 0.0.0-stage → 0.3.0

package/src/scan.mjs

@@ -0,0 +1,281 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { agentItems, memoryItems } from "./files.mjs";
+import { folderHash } from "./hash.mjs";
+import { mcpItems } from "./mcp.mjs";
+import { sessionFolderName } from "./places.mjs";
+
+// What the site accepts, checked here too, so a sync never fails on one odd folder: a name an
+// install prompt can print as it is, a path inside a repository, and an https address.
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/;
+const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+const GITHUB_NAME_RE = /^[A-Za-z0-9_.-]{1,100}$/;
+// An address an install prompt can print as it is.
+const SAFE_URL_RE = /^https:\/\/[A-Za-z0-9._~:/%+-]+$/;
+const SOURCE_MAX = 200;
+const PATH_MAX = 200;
+
+/** Folders under a skills directory that Claude Code does not load as skills. */
+const SKIPPED_FOLDERS = new Set(["learned", "synced"]);
+
+/**
+ * Parsed JSON, or null when the file does not exist. A file that exists but cannot be read stops
+ * the sync: reported as empty, it would remove what the last sync reported.
+ */
+export async function readJson(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`Could not read ${path}: ${error?.code ?? error}.`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON.`);
+  }
+}
+
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+
+/**
+ * The skills in a skills directory as Claude Code loads them: each folder directly inside it, or a
+ * link to one, with a SKILL.md of its own. Hidden folders, `learned`, `synced` and `*-workspace`
+ * are skipped, and so is a folder whose skills sit deeper inside it.
+ */
+export async function skillFolders(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw new Error(`Could not read ${dir}: ${error?.code ?? error}.`);
+  }
+  const folders = [];
+  for (const entry of entries) {
+    const { name } = entry;
+    if (name.startsWith(".") || SKIPPED_FOLDERS.has(name) || name.endsWith("-workspace")) continue;
+    const path = join(dir, name);
+    const [folder, skillMd] = await Promise.all([stat(path).catch(() => null), stat(join(path, "SKILL.md")).catch(() => null)]);
+    if (folder?.isDirectory() && skillMd?.isFile()) folders.push({ name, path });
+  }
+  return folders.sort(byName);
+}
+
+const githubRepository = (owner, repo) =>
+  GITHUB_NAME_RE.test(owner) && GITHUB_NAME_RE.test(repo) && ![owner, repo].includes(".") && ![owner, repo].includes("..")
+    ? `https://github.com/${owner.toLowerCase()}/${repo.toLowerCase()}`
+    : null;
+
+/** The GitHub repository of a skills-lock.json entry, as https://github.com/<owner>/<repo>. */
+function lockSource(entry) {
+  if (entry?.sourceType !== "github" || typeof entry.source !== "string") return null;
+  const [owner, repo, ...rest] = entry.source.replace(/\.git$/, "").split("/");
+  return rest.length || !owner || !repo ? null : githubRepository(owner, repo);
+}
+
+/** The folder a lock entry's SKILL.md sits in, relative to its repository; null at the root or when odd. */
+function lockFolder(entry) {
+  if (typeof entry?.skillPath !== "string") return null;
+  const folder = entry.skillPath.replaceAll("\\", "/").replace(/(^|\/)SKILL\.md$/, "");
+  const segments = folder.split("/");
+  return folder && folder.length <= PATH_MAX && segments.every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..") ? folder : null;
+}
+
+/**
+ * An https address with no credentials, query or fragment, which an install prompt can print as it
+ * is, as the site keeps it; null for a path on disk or anything else.
+ */
+function httpsSource(value) {
+  if (typeof value !== "string") return null;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) return null;
+  if (url.hostname === "github.com" || url.hostname === "www.github.com") {
+    const [owner, repo, ...rest] = url.pathname.split("/").filter(Boolean);
+    return rest.length || !owner || !repo ? null : githubRepository(owner, repo.replace(/\.git$/, ""));
+  }
+  return url.href.length <= SOURCE_MAX && SAFE_URL_RE.test(url.href) ? url.href : null;
+}
+
+/** Where a marketplace in known_marketplaces.json comes from; a marketplace of local folders has no address to send. */
+function marketplaceSource(source) {
+  if (source?.source === "github" && typeof source.repo === "string") {
+    const [owner, repo, ...rest] = source.repo.split("/");
+    return rest.length || !owner || !repo ? null : githubRepository(owner, repo.replace(/\.git$/, ""));
+  }
+  if (source?.source === "git" || source?.source === "url") return httpsSource(source.url);
+  return null;
+}
+
+/** The folder name `npx skills` installs a skill under: its sanitizeName, read in the skills CLI 1.7.2 source. */
+const installFolderName = (name) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9._]+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "")
+    .slice(0, 255) || "unnamed-skill";
+
+/** A lock's entries by the folder each skill is installed in: a lock names a skill as its SKILL.md does, such as react:components. */
+function lockEntries(lock) {
+  const entries = new Map();
+  for (const [name, entry] of Object.entries(lock?.skills ?? {})) if (!entries.has(installFolderName(name))) entries.set(installFolderName(name), entry);
+  for (const [name, entry] of Object.entries(lock?.skills ?? {})) entries.set(name, entry);
+  return entries;
+}
+
+/**
+ * A skill folder as the sync sends it. A folder `npx skills` installed carries what its lock
+ * records: the repository, the folder in it and its hash; any other is hashed here.
+ */
+async function skillItem(folder, locked, lockHashKind) {
+  const entry = locked.get(folder.name);
+  const source = lockSource(entry);
+  const lockHash = lockHashKind === "git-tree" ? entry?.skillFolderHash : entry?.computedHash;
+  if (source && typeof lockHash === "string" && /^[0-9a-f]+$/.test(lockHash) && lockHash.length === (lockHashKind === "git-tree" ? 40 : 64)) {
+    return { kind: "skill", name: folder.name, source, skillPath: lockFolder(entry), hash: lockHash, hashKind: lockHashKind, version: null };
+  }
+  // A file that cannot be read, or vanished meanwhile, costs only this folder its hash.
+  const hash = await folderHash(folder.path).catch(() => null);
+  return { kind: "skill", name: folder.name, source, skillPath: source ? lockFolder(entry) : null, hash, hashKind: hash ? "sha256" : null, version: null };
+}
+
+async function skillItems(dir, lock, lockHashKind, skipped) {
+  const items = [];
+  const locked = lockEntries(lock);
+  for (const folder of await skillFolders(dir)) {
+    if (!NAME_RE.test(folder.name)) {
+      skipped.push(folder.name);
+      continue;
+    }
+    items.push(await skillItem(folder, locked, lockHashKind));
+  }
+  return items;
+}
+
+const real = (path) => realpath(path).catch(() => path);
+
+async function inFolders(path, folders) {
+  const target = await real(path);
+  for (const folder of folders) if ((await real(folder)) === target) return true;
+  return false;
+}
+
+/**
+ * The plugins Claude Code lists as installed, by `<plugin>@<marketplace>`: with no project, those
+ * installed for the user; with one, those installed in that project, from its root or a folder in
+ * it. A plugin whose installed copy is gone from disk is not counted.
+ */
+async function pluginItems(claudeDir, projectFolders, skipped) {
+  const installed = await readJson(join(claudeDir, "plugins", "installed_plugins.json"));
+  const marketplaces = (await readJson(join(claudeDir, "plugins", "known_marketplaces.json"))) ?? {};
+  const items = [];
+  for (const [key, installs] of Object.entries(installed?.plugins ?? {})) {
+    if (!Array.isArray(installs)) continue;
+    let install = null;
+    for (const candidate of installs) {
+      const here = projectFolders
+        ? (candidate?.scope === "project" || candidate?.scope === "local") && typeof candidate.projectPath === "string" && (await inFolders(candidate.projectPath, projectFolders))
+        : candidate?.scope === "user";
+      if (here && typeof candidate.installPath === "string" && (await stat(candidate.installPath).catch(() => null))?.isDirectory()) {
+        install = candidate;
+        break;
+      }
+    }
+    if (!install) continue;
+    if (!NAME_RE.test(key) || !key.includes("@")) {
+      skipped.push(key);
+      continue;
+    }
+    const version = typeof install.version === "string" && VERSION_RE.test(install.version) ? install.version : null;
+    const marketplace = key.slice(key.lastIndexOf("@") + 1);
+    items.push({
+      kind: "plugin",
+      name: key,
+      source: marketplaceSource(marketplaces[marketplace]?.source),
+      skillPath: null,
+      hash: null,
+      hashKind: version ? "version" : null,
+      version,
+    });
+  }
+  return items.sort(byName);
+}
+
+/**
+ * Where `npx skills` keeps its global lock: under XDG_STATE_HOME when that is set, else in
+ * ~/.agents, as the skills CLI 1.7.2 source chooses.
+ */
+export const globalLockPath = (home, env = process.env) =>
+  env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "skills", ".skill-lock.json") : join(home, ".agents", ".skill-lock.json");
+
+/** Items with one of each name per kind: a place's folders can name the same server or file twice. */
+function distinct(items) {
+  const seen = new Set();
+  return items.filter((item) => {
+    const key = `${item.kind}/${item.name}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * What every project on this computer loads: ~/.claude/skills, with the skills CLI's lock, the
+ * user's plugins and MCP servers, ~/.claude/CLAUDE.md and its rules, and its agents.
+ */
+export async function scanGlobal({ home, claudeDir, claudeJson }) {
+  const skipped = [];
+  const lock = await readJson(globalLockPath(home));
+  const items = [
+    ...(await skillItems(join(claudeDir, "skills"), lock, "git-tree", skipped)),
+    ...(await pluginItems(claudeDir, null, skipped)),
+    ...mcpItems(claudeJson?.mcpServers, skipped),
+    ...(await memoryItems(
+      [
+        { name: "CLAUDE.md", file: join(claudeDir, "CLAUDE.md") },
+        { name: "rules", dir: join(claudeDir, "rules"), deep: true },
+      ],
+      skipped,
+    )),
+    ...(await agentItems(join(claudeDir, "agents"), skipped)),
+  ];
+  return { items: distinct(items), skipped };
+}
+
+/**
+ * What one project has: its .claude/skills, with its skills-lock.json, the plugins installed
+ * there, its MCP servers (.mcp.json, and those Claude Code keeps for a folder in it), its
+ * CLAUDE.md, AGENTS.md and rules, the session memory of each folder Claude Code ran in, and its
+ * agents.
+ */
+export async function scanProject({ root, folders = [root], claudeDir, claudeJson }) {
+  const skipped = [];
+  const lock = await readJson(join(root, "skills-lock.json"));
+  const mcpJson = await readJson(join(root, ".mcp.json"));
+  const items = [
+    ...(await skillItems(join(root, ".claude", "skills"), lock, "sha256", skipped)),
+    ...(await pluginItems(claudeDir, [root, ...folders], skipped)),
+    ...mcpItems(mcpJson?.mcpServers, skipped),
+    ...folders.flatMap((folder) => mcpItems(claudeJson?.projects?.[folder]?.mcpServers, skipped)),
+    ...(await memoryItems(
+      [
+        { name: "CLAUDE.md", file: join(root, "CLAUDE.md") },
+        { name: "AGENTS.md", file: join(root, "AGENTS.md") },
+        { name: "rules", dir: join(root, ".claude", "rules"), deep: true },
+        // Claude Code's docs put a repository's memory under its root's name, and a session's files
+        // under its folder's: both are read.
+        ...[...new Set([root, ...folders])].map((folder) => ({ name: "memory", dir: join(claudeDir, "projects", sessionFolderName(folder), "memory"), deep: false })),
+      ],
+      skipped,
+    )),
+    ...(await agentItems(join(root, ".claude", "agents"), skipped)),
+  ];
+  return { items: distinct(items), skipped };
+}

package/src/skill.mjs

@@ -0,0 +1,21 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SKILL = new URL("../skill/SKILL.md", import.meta.url);
+
+/** Where Claude Code's skillcellar skill goes: its own folder in the global skills folder. */
+export const skillFolder = (claudeDir) => join(claudeDir, "skills", "skillcellar");
+
+/** Whether the skill in Claude Code's folder is this version's ("current"), another ("other"), or not there ("missing"). */
+export async function skillState(claudeDir) {
+  const [wanted, installed] = await Promise.all([readFile(SKILL, "utf8"), readFile(join(skillFolder(claudeDir), "SKILL.md"), "utf8").catch(() => null)]);
+  return installed === null ? "missing" : installed === wanted ? "current" : "other";
+}
+
+/** Writes this version's skill into Claude Code's skills folder, replacing an older copy. */
+export async function installSkill(claudeDir) {
+  const folder = skillFolder(claudeDir);
+  await mkdir(folder, { recursive: true });
+  await writeFile(join(folder, "SKILL.md"), await readFile(SKILL, "utf8"));
+  return folder;
+}