skillcellar 0.0.0-stage → 0.6.0

package/src/scan.mjs

@@ -0,0 +1,297 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { join, relative } 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);
+}
+
+/**
+ * Where a lock entry's SKILL.md sits in its repository: `{ folder }`, null for the repository's
+ * root; or null for an entry whose folder the sync cannot send as it is (odd characters, over 200
+ * characters, or no path at all), which must not pass for the root.
+ */
+export function lockFolder(entry) {
+  if (typeof entry?.skillPath !== "string") return null;
+  const folder = entry.skillPath.replaceAll("\\", "/").replace(/(^|\/)SKILL\.md$/, "");
+  if (!folder) return { folder: null };
+  const segments = folder.split("/");
+  return 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, as is one
+ * whose lock names a folder the sync cannot send, since a tree hash without its folder would be
+ * read as the root's.
+ */
+async function skillItem(folder, locked, lockHashKind, tracked) {
+  const entry = locked.get(folder.name);
+  const source = lockSource(entry);
+  const located = lockFolder(entry);
+  const lockHash = lockHashKind === "git-tree" ? entry?.skillFolderHash : entry?.computedHash;
+  if (source && located && typeof lockHash === "string" && /^[0-9a-f]+$/.test(lockHash) && lockHash.length === (lockHashKind === "git-tree" ? 40 : 64)) {
+    return { kind: "skill", name: folder.name, source, skillPath: located.folder, hash: lockHash, hashKind: lockHashKind, version: null, tracked };
+  }
+  // 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 ? (located?.folder ?? null) : null, hash, hashKind: hash ? "sha256" : null, version: null, tracked };
+}
+
+/** Whether a project's git tracks a file, by its path from the project's root. */
+export const isTracked = (tracked, root, path) => tracked.has(relative(root, path).split("\\").join("/"));
+
+async function skillItems(dir, lock, lockHashKind, skipped, trackedIn = null) {
+  const items = [];
+  const locked = lockEntries(lock);
+  for (const folder of await skillFolders(dir)) {
+    if (!NAME_RE.test(folder.name)) {
+      skipped.push(folder.name);
+      continue;
+    }
+    // A skill is the project's own when its SKILL.md is.
+    const tracked = trackedIn ? isTracked(trackedIn.tracked, trackedIn.root, join(folder.path, "SKILL.md")) : false;
+    items.push(await skillItem(folder, locked, lockHashKind, tracked));
+  }
+  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,
+      tracked: false,
+    });
+  }
+  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, tracked = new Set() }) {
+  const skipped = [];
+  const lock = await readJson(join(root, "skills-lock.json"));
+  const mcpJson = await readJson(join(root, ".mcp.json"));
+  const own = { tracked, root };
+  const items = [
+    ...(await skillItems(join(root, ".claude", "skills"), lock, "sha256", skipped, own)),
+    ...(await pluginItems(claudeDir, [root, ...folders], skipped)),
+    ...mcpItems(mcpJson?.mcpServers, skipped).map((item) => ({ ...item, tracked: tracked.has(".mcp.json") })),
+    ...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,
+      own,
+    )),
+    ...(await agentItems(join(root, ".claude", "agents"), skipped, own)),
+  ];
+  return { items: distinct(items), skipped };
+}

package/src/secrets.mjs

@@ -0,0 +1,65 @@
+// What stops a backup: a line that looks like a key, a token or a password. Each pattern is bounded,
+// so a line of any length is read in one pass, and a placeholder such as ${NAME}, $NAME, <your key>
+// or your_api_key is not a secret. A finding is a reason to look, not proof: the backup stops either
+// way, and a key of a shape no pattern knows is not found.
+
+// A key stands alone: nothing alphanumeric right before or after it, so STRIPE_API_KEY= and "apiKey"
+// count, which a word boundary would miss between _ and a letter.
+const EDGE = String.raw`(?<![A-Za-z0-9])`;
+const END = String.raw`(?![A-Za-z0-9])`;
+// A value that is not a placeholder, a variable, a template, an example or a reference into config or code.
+const NOT_PLACEHOLDER = String.raw`(?!\$\{|\$[A-Za-z_]|<|\{\{|%|your[_-]|xxx|example|placeholder|change[_-]?me|redacted|none\b|null\b|true\b|false\b|\*{3}|process\.|os\.|env\.|config\.|settings\.|this\.|self\.)`;
+
+const PATTERNS = [
+  ["a private key", /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/],
+  ["an AWS access key", new RegExp(String.raw`${EDGE}AKIA[0-9A-Z]{16}${END}`)],
+  ["a GitHub token", new RegExp(String.raw`${EDGE}(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{22,255})${END}`)],
+  ["an OpenAI or Anthropic key", new RegExp(String.raw`${EDGE}sk-(?:proj-|ant-|svcacct-)?[A-Za-z0-9_-]{20,255}(?![A-Za-z0-9_-])`)],
+  ["a Slack token", new RegExp(String.raw`${EDGE}xox[abeprs]-[A-Za-z0-9-]{10,255}(?![A-Za-z0-9-])`)],
+  ["a Stripe key", new RegExp(String.raw`${EDGE}(?:[sr]k_(?:live|test)_[A-Za-z0-9]{16,255}|whsec_[A-Za-z0-9]{16,255})${END}`)],
+  ["a Google API key", new RegExp(String.raw`${EDGE}AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9_-])`)],
+  ["a SkillCellar API key", new RegExp(String.raw`${EDGE}skc_[A-Za-z0-9]{64}${END}`)],
+  ["an npm token", new RegExp(String.raw`${EDGE}npm_[A-Za-z0-9]{36}${END}`)],
+  ["a Neon API key", new RegExp(String.raw`${EDGE}napi_[a-z0-9]{40,255}${END}`)],
+  ["a Resend, Hugging Face or Groq key", new RegExp(String.raw`${EDGE}(?:re_[A-Za-z0-9_]{20,255}|hf_[A-Za-z0-9]{20,255}|gsk_[A-Za-z0-9]{20,255})${END}`)],
+  ["a JSON Web Token", new RegExp(String.raw`${EDGE}eyJ[A-Za-z0-9_-]{10,2000}\.[A-Za-z0-9_-]{10,2000}\.[A-Za-z0-9_-]{10,2000}(?![A-Za-z0-9_-])`)],
+  // user:password@host in an address of any scheme, unless the password is a placeholder.
+  ["a password in an address", /[a-z][a-z0-9+.-]{0,30}:\/\/[^\s/@:'"]{1,100}:(?!\$\{)[^\s/@'"]{1,200}@/i],
+  ["a bearer or basic credential", new RegExp(String.raw`\b(?:Bearer|Basic)\s{1,5}(?!\$\{|\$[A-Za-z_]|<)[A-Za-z0-9_\-./+=]{16,2000}(?![A-Za-z0-9_\-./+=])`)],
+  // A key named as one, assigned a value with a digit in it, as random keys have; the name may be quoted, as in JSON.
+  [
+    "a key or password in an assignment",
+    new RegExp(
+      String.raw`${EDGE}(?:api[_-]?key|apikey|secret[_-]?(?:access[_-]?)?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|password|passwd|secret|token)${END}["'\x60]?\s{0,5}[:=]\s{0,5}["'\x60]?${NOT_PLACEHOLDER}(?=[A-Za-z0-9_\-./+=]{0,254}[0-9])[A-Za-z0-9_\-./+=]{8,255}`,
+      "i",
+    ),
+  ],
+];
+
+/**
+ * The first line of a text that looks like a secret, as `{ line, kind }` (the line counted from
+ * 1), or null. Lines are read one by one, so the file's size sets the cost, never a pattern.
+ */
+export function findSecret(text) {
+  const lines = text.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    for (const [kind, pattern] of PATTERNS) if (pattern.test(line)) return { line: index + 1, kind };
+  }
+  return null;
+}
+
+/** The placeholders a sanitized MCP config holds, such as ${CONTEXT7_KEY}, in order and once each. */
+export function placeholdersIn(text) {
+  return [...new Set(Array.from(text.matchAll(/\$\{([A-Z0-9_]{1,80})\}/g), (match) => match[0]))];
+}
+
+/**
+ * References in an MCP config that Claude Code would expand from the environment and that are not
+ * plain placeholders: `${VAR:-default}`, `$VAR`, or a placeholder of another shape. Each is a reason
+ * to read the server's config before adding it, since it reaches into the user's environment.
+ */
+export function oddReferencesIn(text) {
+  const all = Array.from(text.matchAll(/\$\{[^}]{0,200}\}|\$[A-Za-z_][A-Za-z0-9_]{0,80}/g), (match) => match[0]);
+  return [...new Set(all.filter((reference) => !/^\$\{[A-Z0-9_]{1,80}\}$/.test(reference)))];
+}

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