skillcellar 0.6.1 → 0.8.0

package/src/restore.mjs

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { lstat, mkdir, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { ensureMirror, git, gitBuffer, parseBackupRepo, refusePublic } from "./backup.mjs";
 import { sessionFolderName } from "./places.mjs";
@@ -16,6 +16,9 @@ const BYTES_MAX = 256 * 1024 * 1024;
 // The install commands a copy may hand over, in the shapes the site's plan gives them.
 const NPX_SKILLS_RE = /^npx skills add https:\/\/github\.com\/[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}(?: --skill [A-Za-z0-9][A-Za-z0-9._@+-]{0,127})?$/;
 const PLUGIN_RE = /^\/plugin (?:marketplace add [A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}, then \/plugin install |marketplace add https:\/\/[A-Za-z0-9._~:/%+-]+, then \/plugin install |install )[A-Za-z0-9][A-Za-z0-9._@+-]{0,127}$/;
+// A skill's name as its SKILL.md gives it, which `npx skills add --skill` matches on; printed in a command, so only these characters.
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,127}$/;
+const ANTIVIRUS = "an antivirus may have removed it (on Windows, see Windows Security, Protection history)";
 
 /** A path that stays inside its base folder, or null. */
 function inside(base, ...segments) {
@@ -24,6 +27,8 @@ function inside(base, ...segments) {
   return from && !from.startsWith("..") && !isAbsolute(from) ? path : null;
 }
 
+const isFile = async (path) => (await stat(path).catch(() => null))?.isFile() === true;
+
 /**
  * The backup's files at one commit, by path: the mode and the blob of each entry. Read from the
  * mirror's objects, never a checkout, so a link in the repository is listed and never followed.
@@ -82,6 +87,43 @@ function placeFolder(found, task) {
   return `${found.folder}/${place.folder}`;
 }
 
+/**
+ * What the backup holds in one place, as the items a sync reports: each skill folder, agent and
+ * memory file (CLAUDE.md, AGENTS.md, rules and session memory). MCP servers are left out: their
+ * config is one file per place, read only for a server the site names.
+ */
+function backupItems(tree, place, project) {
+  const items = new Map();
+  for (const path of tree.keys()) {
+    if (!path.startsWith(`${place}/`)) continue;
+    const rest = path.slice(place.length + 1);
+    const [first, ...more] = rest.split("/");
+    let item = null;
+    if (first === "skills") item = more.length > 1 ? { kind: "skill", name: more[0] } : null;
+    else if (first === "agents") item = rest.endsWith(".md") ? { kind: "agent", name: more.join("/").slice(0, -3) } : null;
+    else if (first !== "mcp.json" && first !== "mcp.local.json") item = { kind: "memory", name: rest };
+    if (item && sentName(item.kind, item.name, project)) items.set(`${item.kind}/${item.name}`, item);
+  }
+  return [...items.values()];
+}
+
+/**
+ * Where a skill, agent or memory file goes on this computer: a skill's folder, or a file's path;
+ * null for a name that would leave its folder.
+ */
+function targetOf({ kind, name }, { root, claudeDir }) {
+  const own = (...segments) => join(root ?? claudeDir, ...(root ? [".claude"] : []), ...segments);
+  if (kind === "skill") return join(own("skills"), name);
+  if (kind === "agent") return inside(own("agents"), `${name}.md`);
+  const [first, ...rest] = name.split("/");
+  if (first === "rules") return inside(own("rules"), ...rest);
+  if (first === "memory" && root) return inside(join(claudeDir, "projects", sessionFolderName(root), "memory"), ...rest);
+  return join(root ?? claudeDir, name);
+}
+
+/** Whether an item is on this computer already: a skill as a folder with its SKILL.md, a file as anything at its path. */
+const presentAt = async (target, kind) => (kind === "skill" ? isFile(join(target, "SKILL.md")) : (await lstat(target).catch(() => null)) !== null);
+
 const sha256 = (content) => createHash("sha256").update(content).digest("hex");
 
 /** Writes one file into place; "exists" when one is there already and `force` is not set, "link" when the target is a link. */
@@ -94,6 +136,15 @@ async function placeFile(content, target, force) {
   return "copied";
 }
 
+/** Whether every file of the backup's copy of a skill is in its folder here, byte for byte. */
+async function sameFiles(target, files) {
+  for (const file of files) {
+    const there = await readFile(join(target, ...file.segments)).catch(() => null);
+    if (!there?.equals(file.content)) return false;
+  }
+  return true;
+}
+
 const ENVIRONMENTS = [
   ["package.json", "npm install"],
   ["requirements.txt", "pip install -r requirements.txt"],
@@ -105,7 +156,7 @@ const ENVIRONMENTS = [
 /** The environments a restored skill folder names, each with the command that rebuilds it. */
 async function environmentsOf(folder) {
   const hints = [];
-  for (const [file, command] of ENVIRONMENTS) if ((await stat(join(folder, file)).catch(() => null))?.isFile()) hints.push(`${file} (${command})`);
+  for (const [file, command] of ENVIRONMENTS) if (await isFile(join(folder, file))) hints.push(`${file} (${command})`);
   return hints;
 }
 
@@ -116,13 +167,34 @@ async function checkProjectFolder(root, sub) {
   if ((await lstat(path).catch(() => null))?.isSymbolicLink()) throw new Error(`${path} is a link, so a file could land outside the project.`);
 }
 
+/** The name a SKILL.md's frontmatter gives, when a command can print it as it is; null otherwise. */
+async function skillMdName(mirror, entry, budget) {
+  if (!regular(entry)) return null;
+  const text = (await blobOf(mirror, entry, budget)).toString("utf8");
+  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+  const name = /^name:[ \t]*["']?([^"'\r\n]*?)["']?[ \t]*$/m.exec(front)?.[1];
+  return name && SKILL_NAME_RE.test(name) ? name : null;
+}
+
+/**
+ * The `npx skills add` command of a skill from a repository, under the name its SKILL.md gives in the
+ * backup: the skills CLI matches on that name, which can differ from the folder's (react:components
+ * installs as react-components). Globally it adds -g, without which the skills CLI installs into the
+ * folder it runs in, and -y.
+ */
+async function skillCommand(command, name, { mirror, tree, budget, place, scope }) {
+  const named = await skillMdName(mirror, tree.get(`${place}/skills/${name}/SKILL.md`), budget);
+  const renamed = named && / --skill \S+$/.test(command) ? command.replace(/ --skill \S+$/, () => ` --skill ${named}`) : command;
+  return scope === "global" ? `${renamed} -g -y` : renamed;
+}
+
 /**
  * One item of a copy, in one place: files from the backup are written into Claude Code's folders,
- * once they match what the source reported and hold nothing that looks like a secret, and what a
- * command installs, a plugin, a skill from a repository or an MCP server, is answered as that
- * command for Claude Code or the user to run. Nothing is run here.
+ * once they match what the source reported (or the user takes the backup's copy) and hold nothing
+ * that looks like a secret, and what a command installs, a plugin, a skill from a repository or an
+ * MCP server, is answered as that command for Claude Code or the user to run. Nothing is run here.
  */
-async function restoreItem(item, { mirror, tree, budget, place, scope, root, claudeDir, force, dryRun, allowed }) {
+async function restoreItem(item, { mirror, tree, budget, place, scope, root, claudeDir, force, dryRun, allowed, takeBackup, fromBackup }) {
   // A file that looks like it holds a secret is copied only as the source's user allowed it, byte for byte.
   const secretIn = (path, content) => {
     const found = findSecret(content.toString("utf8"));
@@ -130,14 +202,15 @@ async function restoreItem(item, { mirror, tree, budget, place, scope, root, cla
   };
   const { kind, name } = item;
   if (item.tracked) return { outcome: "repository" };
-  if (kind === "plugin" || (kind === "skill" && item.install)) {
+  if (kind === "plugin" || (kind === "skill" && item.install && !fromBackup.has(name))) {
     const command = item.install?.command;
     if (typeof command !== "string") return { outcome: "missing" };
-    return (kind === "plugin" ? PLUGIN_RE : NPX_SKILLS_RE).test(command) ? { outcome: "command", command } : { outcome: "odd-command", command };
+    if (!(kind === "plugin" ? PLUGIN_RE : NPX_SKILLS_RE).test(command)) return { outcome: "odd-command", command };
+    if (kind === "plugin") return { outcome: "command", command, plugin: true };
+    return { outcome: "command", command: await skillCommand(command, name, { mirror, tree, budget, place, scope }), inBackup: tree.has(`${place}/skills/${name}/SKILL.md`) };
   }
   if (!["skill", "mcp", "memory", "agent"].includes(kind)) return { outcome: "unknown-kind" };
   if (!sentName(kind, name, scope === "project")) return { outcome: "unsendable" };
-  const own = (...segments) => join(root ?? claudeDir, ...(root ? [".claude"] : []), ...segments);
   if (kind === "mcp") {
     const local = await readJsonBlob(mirror, tree.get(`${place}/mcp.local.json`), budget);
     const shared = await readJsonBlob(mirror, tree.get(`${place}/mcp.json`), budget);
@@ -164,43 +237,41 @@ async function restoreItem(item, { mirror, tree, budget, place, scope, root, cla
     }
     if (!files.length) return { outcome: "missing" };
     if (root) await checkProjectFolder(root, "skills");
-    const skills = own("skills");
-    const target = join(skills, name);
-    if (dryRun) return { outcome: (await lstat(target).catch(() => null)) && !force ? "exists" : "copied", target };
+    const skills = join(root ?? claudeDir, ...(root ? [".claude"] : []), "skills");
+    const target = targetOf(item, { root, claudeDir });
+    if ((await lstat(target).catch(() => null)) && !force) {
+      // A folder without its SKILL.md is not a skill Claude Code loads, so it is not "there already".
+      if (!(await isFile(join(target, "SKILL.md")))) return { outcome: "incomplete", target };
+      return { outcome: "exists", target, same: await sameFiles(target, files) };
+    }
+    if (dryRun) return { outcome: "copied", target };
     try {
       await installPulled(skills, { slug: name, files }, force);
     } catch (error) {
-      if (/is there already/.test(error.message)) return { outcome: "exists", target };
+      if (/is there already/.test(error.message)) return { outcome: "exists", target, same: false };
       throw error;
     }
+    if (!(await isFile(join(target, "SKILL.md")))) return { outcome: "vanished", target };
     return { outcome: "copied", target, environments: await environmentsOf(target) };
   }
-  let path;
-  let target;
-  if (kind === "agent") {
-    path = `${place}/agents/${name}.md`;
-    if (root) await checkProjectFolder(root, "agents");
-    target = inside(own("agents"), `${name}.md`);
-  } else {
-    const [first, ...rest] = name.split("/");
-    path = `${place}/${name}`;
-    if (first === "rules") {
-      if (root) await checkProjectFolder(root, "rules");
-      target = inside(own("rules"), ...rest);
-    } else if (first === "memory" && root) target = inside(join(claudeDir, "projects", sessionFolderName(root), "memory"), ...rest);
-    else target = join(root ?? claudeDir, name);
-  }
+  if (kind === "agent" && root) await checkProjectFolder(root, "agents");
+  if (kind === "memory" && name.startsWith("rules/") && root) await checkProjectFolder(root, "rules");
+  const path = kind === "agent" ? `${place}/agents/${name}.md` : `${place}/${name}`;
+  const target = targetOf(item, { root, claudeDir });
   const entry = tree.get(path);
   if (!entry) return { outcome: "missing" };
   if (!regular(entry)) return { outcome: "link", path };
   if (!target) return { outcome: "unsendable" };
   const content = await blobOf(mirror, entry, budget);
-  // The site holds the file's hash as the source reported it: a file that differs is not the source's.
-  if (item.hash && sha256(content) !== item.hash) return { outcome: "differs" };
+  // The site holds the file's hash as the source reported it: a copy that differs is taken only on the user's word.
+  const differs = Boolean(item.hash) && sha256(content) !== item.hash;
+  if (differs && !takeBackup) return { outcome: "differs" };
   const found = secretIn(path, content);
   if (found) return { outcome: "secret", path, line: found.line, kind: found.kind };
-  if (dryRun) return { outcome: (await lstat(target).catch(() => null)) && !force ? "exists" : "copied", target };
-  return { outcome: await placeFile(content, target, force), target };
+  const there = await lstat(target).catch(() => null);
+  if (there && !force && !there.isSymbolicLink()) return { outcome: "exists", target, same: (await readFile(target).catch(() => null))?.equals(content) === true };
+  if (dryRun) return { outcome: there?.isSymbolicLink() ? "link" : "copied", target, differs };
+  return { outcome: await placeFile(content, target, force), target, differs };
 }
 
 const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
@@ -221,9 +292,13 @@ async function trustedRepo(repo, source, config, flags) {
 function describe(result, label, source, dryRun) {
   switch (result.outcome) {
     case "copied":
-      return `${dryRun ? "would copy" : "copied"} ${label} to ${result.target}`;
+      return `${dryRun ? "would copy" : "copied"} ${label} to ${result.target}${result.differs ? ` (the backup's copy, which is not the one ${source.device.name} last reported)` : ""}`;
     case "exists":
-      return `kept ${label}: ${result.target} is there already (run again with --force to replace it)`;
+      return `kept ${label}: ${result.target} is there already and differs from the backup's copy (run again with --force to replace it)`;
+    case "incomplete":
+      return `${label}: ${result.target} has no SKILL.md, so Claude Code does not load it: ${ANTIVIRUS}. Run again with --force to copy it again`;
+    case "vanished":
+      return `copied ${label} to ${result.target}, but its SKILL.md is gone already: ${ANTIVIRUS}`;
     case "odd-command":
       return `${label}: its install command is not one this tool hands over (${result.command.slice(0, 80)}); install it from the site's page`;
     case "repository":
@@ -239,7 +314,7 @@ function describe(result, label, source, dryRun) {
     case "secret":
       return `${label}: ${result.path}:${result.line} in the backup looks like ${result.kind}; not restored`;
     case "differs":
-      return `${label}: the backup's copy differs from what ${source.device.name} reported; run skillcellar backup there again`;
+      return `${label}: the backup's copy is not the one ${source.device.name} last reported (it changed after that sync, or in the backup since). If the backup is yours as you left it, run again with --take-backup to copy it`;
     default:
       return `${label}: not in the backup`;
   }
@@ -249,18 +324,21 @@ function describe(result, label, source, dryRun) {
  * Carries out the copy tasks of the plan whose source has a backup: refuses a public repository and
  * one this computer was not told to trust, fetches the backup into a bare mirror with the user's own
  * git, reads the commit the site recorded, writes skills, memory files and agents into place, and
- * lists the commands left to run.
+ * lists the commands left to run. Answers the project folders it restored, whatever was missing there, so a sync reads them and closes their tasks.
  */
 export async function runRestore({ plan, claudeDir, config, flags, version, print, warn }) {
   const force = flags.force === true;
   const dryRun = flags["dry-run"] === true;
+  const takeBackup = flags["take-backup"] === true;
+  const fromBackup = new Set(Array.isArray(flags["from-backup"]) ? flags["from-backup"] : []);
   const from = typeof flags.from === "string" ? flags.from.trim().toLowerCase() : null;
+  const folders = new Set();
   const wanted = (plan.tasks ?? []).filter(
     (task) => task.action === "copy" && task.copy && (!from || task.copy.from.device.slug === from || task.copy.from.device.name.toLowerCase() === from),
   );
   if (!wanted.length) {
     print(from ? `No copy task from ${flags.from} waits for ${plan.device.name}.` : `No copy task waits for ${plan.device.name}.`);
-    return;
+    return { folders };
   }
   const bySource = new Map();
   for (const task of wanted) bySource.set(task.copy.from.device.id, [...(bySource.get(task.copy.from.device.id) ?? []), task]);
@@ -303,6 +381,13 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
     const listed = Array.isArray(found.manifest?.allowed) ? found.manifest.allowed : [];
     const allowed = new Map(listed.filter((entry) => typeof entry?.path === "string" && typeof entry.sha256 === "string").map((entry) => [`${found.folder}/${entry.path}`, entry.sha256]));
     print(`${dryRun ? "Would restore" : "Restoring"} from ${source.device.name}'s backup, ${repo.name} at ${commit.slice(0, 7)}:`);
+    // What any task names in a place, so the backup's other items there are told apart from them.
+    const reported = new Set(
+      tasks.flatMap((task) => {
+        const place = placeFolder(found, task);
+        return place ? task.copy.items.map((item) => `${place}/${item.kind}/${item.name}`) : [];
+      }),
+    );
     for (const task of tasks) {
       const where = task.project ? `in ${task.project.name}` : "globally";
       if (task.problem) {
@@ -310,7 +395,7 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
         continue;
       }
       if (task.project && !task.folder) {
-        print(`  ${where}: this computer has no folder of ${task.project.name}; clone it, then run skillcellar restore from inside it.`);
+        print(`  ${where}: no folder of ${task.project.name} that Claude Code knows on this computer. If you cloned it, run skillcellar restore inside the clone.`);
         continue;
       }
       const place = placeFolder(found, task);
@@ -318,26 +403,50 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
         print(`  ${where}: the backup holds nothing for this place.`);
         continue;
       }
-      if (!task.copy.items.length) print(`  ${where}: nothing left to copy; the next sync closes the task.`);
-      for (const item of task.copy.items) {
+      if (task.folder && !dryRun) folders.add(task.folder);
+      const context = { mirror, tree, budget, place, scope: task.scope, root: task.folder, claudeDir, force, dryRun, allowed, takeBackup, fromBackup };
+      let inPlace = 0;
+      const bring = async (item, note = "") => {
         const label = `${item.kind} ${item.name}`;
         const key = `${place}/${label}`;
         if (done.has(key)) {
           print(`  ${label}: brought over above`);
-          continue;
+          return;
         }
         done.add(key);
-        const result = await restoreItem(item, { mirror, tree, budget, place, scope: task.scope, root: task.folder, claudeDir, force, dryRun, allowed });
+        const result = await restoreItem(item, context);
         if (result.outcome === "command") {
           commands.push({ task: where, label, ...result });
-          continue;
+          return;
+        }
+        if (result.outcome === "exists" && result.same) {
+          inPlace += 1;
+          return;
         }
         if (result.outcome === "copied") {
           copied += 1;
           for (const hint of result.environments ?? []) environments.push(`${item.name} has ${hint}`);
         }
-        print(`  ${describe(result, label, source, dryRun)}`);
+        print(`  ${describe(result, label, source, dryRun)}${note}`);
+      };
+      if (!task.copy.items.length) print(`  ${where}: nothing left to copy; the next sync closes the task.`);
+      for (const item of task.copy.items) await bring(item);
+      // A copy of everything also finds what the backup holds that the source's last sync did not report.
+      if (!task.item) {
+        const unlisted = [];
+        for (const item of backupItems(tree, place, task.scope === "project")) {
+          if (reported.has(`${place}/${item.kind}/${item.name}`)) continue;
+          const target = targetOf(item, { root: task.folder, claudeDir });
+          if (target && !(await presentAt(target, item.kind))) unlisted.push(item);
+        }
+        if (unlisted.length && !takeBackup) {
+          print(
+            `  ${where}: ${plural(unlisted.length, "item")} in the backup that ${source.device.name}'s last sync did not report (added after that sync, or removed before it): ${unlisted.map((item) => `${item.kind} ${item.name}`).join(", ")}. Run again with --take-backup to copy ${unlisted.length === 1 ? "it" : "them"}.`,
+          );
+        }
+        if (takeBackup) for (const item of unlisted) await bring(item, ` (in the backup, not in ${source.device.name}'s last sync)`);
       }
+      if (inPlace) print(`  ${where}: ${plural(inPlace, "item")} already in place, the same as in the backup.`);
     }
   }
   if (commands.length) {
@@ -346,7 +455,14 @@ export async function runRestore({ plan, claudeDir, config, flags, version, prin
       const notes = [...(entry.placeholders?.length ? [`needs ${entry.placeholders.join(", ")}`] : []), ...(entry.review?.length ? [`review: ${entry.review.join(", ")}`] : [])];
       print(`  ${entry.task}: ${entry.command}${notes.length ? `   (${notes.join("; ")})` : ""}`);
     }
+    if (commands.some((entry) => entry.inBackup)) {
+      print("If npx skills add finds no matching skill, the skill has left its repository: run skillcellar restore --from-backup <name> to copy the backup's copy instead.");
+    }
+    if (commands.some((entry) => entry.plugin)) {
+      print("If /plugin install says the plugin is not in its marketplace, the marketplace was renamed after the old computer added it: install the plugin under the name /plugin marketplace list shows for it.");
+    }
   }
   if (environments.length) print(`Rebuild: ${environments.join("; ")}.`);
   if (!dryRun) print(`${copied ? `Copied ${plural(copied, "item")}. ` : ""}Run skillcellar sync to close the tasks that are done.`);
+  return { folders };
 }

package/src/scan.mjs

@@ -42,8 +42,9 @@ 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.
+ * link to one, with a SKILL.md of its own. Hidden folders, `learned` and `synced` are skipped, and
+ * so is a folder whose skills sit deeper inside it, such as skill-creator's `*-workspace` folders;
+ * a folder with a SKILL.md of its own is a skill whatever its name.
  */
 export async function skillFolders(dir) {
   let entries;
@@ -56,7 +57,7 @@ export async function skillFolders(dir) {
   const folders = [];
   for (const entry of entries) {
     const { name } = entry;
-    if (name.startsWith(".") || SKIPPED_FOLDERS.has(name) || name.endsWith("-workspace")) continue;
+    if (name.startsWith(".") || SKIPPED_FOLDERS.has(name)) 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 });

package/src/tech.mjs

@@ -0,0 +1,242 @@
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { dirname, join, sep } from "node:path";
+import { dependencyNames, manifestEcosystem, normalizeName } from "./manifests.mjs";
+
+// Finds a project's technologies on this computer. The rules come from the site's public list at
+// /tech.json; they are names and paths compared by prefix and suffix, never a pattern the code
+// compiles, and only the ids they match leave the computer.
+
+export const RULES_BYTES_MAX = 512 * 1024;
+const RULES_VERSION = 1;
+const ECOSYSTEMS = ["npm", "pypi", "go", "cargo", "gem", "composer", "pub"];
+const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ID_MAX = 32;
+// The site's SYNC_TECH_MAX: the most one project reports.
+const PER_PROJECT_MAX = 32;
+const RULES_MAX = 500;
+const PATTERNS_MAX = 200;
+const PATTERN_MAX = 214;
+const SEGMENTS_MAX = 3;
+// A path counts up to this many segments deep: the manifests and markers that say what a project is sit near its root.
+const PATH_SEGMENTS_MAX = 4;
+const MANIFESTS_MAX = 40;
+const MANIFEST_BYTES_MAX = 1024 * 1024;
+const PROJECT_MS_MAX = 2000;
+// Never counted, whatever the list says.
+const ALWAYS_IGNORED = ["node_modules", ".git"];
+
+/** Whether a rule's name or path is one this code compares safely: one `*` at most, no `..`, no backslash, no control character. */
+const usable = (value) => typeof value === "string" && value !== "" && value.length <= PATTERN_MAX && value.split("*").length <= 2 && !value.includes("..") && !/[\\\s\p{Cc}]/u.test(value);
+
+/** A package name or a prefix of one ending in `*`, normalised as its registry compares names. */
+function namePattern(ecosystem, name) {
+  if (!usable(name)) return null;
+  const star = name.endsWith("*");
+  if (name.includes("*") && !star) return null;
+  const prefix = normalizeName(ecosystem, star ? name.slice(0, -1) : name);
+  return prefix ? { prefix, star } : null;
+}
+
+/** A path of 1 to 3 segments, tied to the project's root when it starts with `/`, a segment holding at most one `*`. */
+function filePattern(path) {
+  if (!usable(path)) return null;
+  const anchored = path.startsWith("/");
+  const segments = (anchored ? path.slice(1) : path).split("/");
+  if (segments.length > SEGMENTS_MAX || segments.some((segment) => segment === "" || segment === ".")) return null;
+  return {
+    anchored,
+    segments: segments.map((segment) => {
+      const at = segment.indexOf("*");
+      return at === -1 ? { literal: segment } : { prefix: segment.slice(0, at), suffix: segment.slice(at + 1) };
+    }),
+  };
+}
+
+/**
+ * The list the site serves, as rules this code can use, or null for a list of another version.
+ * It comes from the network, so every field is checked, and a rule it cannot read is left out.
+ */
+export function readRules(json) {
+  if (json?.version !== RULES_VERSION || !Array.isArray(json.tech)) return null;
+  const listed = Array.isArray(json.ignore) ? json.ignore.filter((name) => typeof name === "string" && name !== "" && name.length <= 64 && !name.includes("/")) : [];
+  const ignore = new Set([...ALWAYS_IGNORED, ...listed.slice(0, PATTERNS_MAX)]);
+  const tech = [];
+  const seen = new Set();
+  for (const entry of json.tech.slice(0, RULES_MAX)) {
+    if (typeof entry?.id !== "string" || entry.id.length > ID_MAX || !ID_RE.test(entry.id) || seen.has(entry.id)) continue;
+    const deps = {};
+    for (const ecosystem of ECOSYSTEMS) {
+      const names = Array.isArray(entry.deps?.[ecosystem]) ? entry.deps[ecosystem].slice(0, PATTERNS_MAX) : [];
+      const patterns = names.flatMap((name) => namePattern(ecosystem, name) ?? []);
+      if (patterns.length) deps[ecosystem] = patterns;
+    }
+    const files = (Array.isArray(entry.files) ? entry.files.slice(0, PATTERNS_MAX) : []).flatMap((path) => filePattern(path) ?? []);
+    if (!files.length && !Object.keys(deps).length) continue;
+    seen.add(entry.id);
+    tech.push({ id: entry.id, deps, files });
+  }
+  return { ignore, tech };
+}
+
+/**
+ * The site's list of technologies, downloaded without the key and never through a redirect, or
+ * null when it cannot be had: missing, moved, too large, not JSON, too slow or of another version.
+ */
+export async function loadRules(site, version, { timeout = 10_000 } = {}) {
+  try {
+    const response = await fetch(new URL("/tech.json", site), {
+      headers: { accept: "application/json", "user-agent": `skillcellar/${version}` },
+      redirect: "error",
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!response.ok || !response.body) return null;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+      size += chunk.length;
+      if (size > RULES_BYTES_MAX) return null;
+      chunks.push(chunk);
+    }
+    return readRules(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether the site serves /tech.json at all, whatever the list's version: it then takes `tech: false`,
+ * which needs no rules. A site without it, from before 0.8.0's server, would refuse the key.
+ */
+export async function techServed(site, version, { timeout = 10_000 } = {}) {
+  try {
+    const response = await fetch(new URL("/tech.json", site), {
+      headers: { accept: "application/json", "user-agent": `skillcellar/${version}` },
+      redirect: "error",
+      signal: AbortSignal.timeout(timeout),
+    });
+    await response.body?.cancel();
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether this computer reports technologies: what the config says, or the answer to the one
+ * question, asked only where it can be. `asked` says the answer is new, for the config to keep.
+ */
+export async function techChoice(saved, canAsk, askYes) {
+  if (saved === "on" || saved === "off" || saved === "clearing") return { tech: saved, asked: false };
+  if (!canAsk) return { tech: null, asked: false };
+  return { tech: (await askYes()) ? "on" : "off", asked: true };
+}
+
+/** A folder or file name a pattern's segment matches; a name starting with a dot only where the rule names the dot. */
+function segmentMatches(pattern, segment) {
+  const named = pattern.literal ?? pattern.prefix;
+  if (segment.startsWith(".") && !named.startsWith(".")) return false;
+  if (pattern.literal !== undefined) return segment === pattern.literal;
+  return segment.length >= pattern.prefix.length + pattern.suffix.length && segment.startsWith(pattern.prefix) && segment.endsWith(pattern.suffix);
+}
+
+/** Whether a path, as its segments, is one a file rule names: the whole path for a rule tied to the root, else its end, with no dot folder before it. */
+function pathMatches(pattern, path) {
+  const count = pattern.segments.length;
+  if (pattern.anchored ? path.length !== count : path.length < count) return false;
+  const tail = path.slice(-count);
+  if (!pattern.anchored && path.slice(0, -count).some((segment) => segment.startsWith("."))) return false;
+  return pattern.segments.every((segment, index) => segmentMatches(segment, tail[index]));
+}
+
+const nameMatches = (pattern, name) => (pattern.star ? name.startsWith(pattern.prefix) : name === pattern.prefix);
+
+/** The project's files as segments, from the list git tracks, or the root's own files when it lists none. */
+async function projectPaths(root, tracked, ignore) {
+  let listed = tracked?.size ? [...tracked] : [];
+  if (!listed.length) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    listed = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+  }
+  return listed.map((path) => path.split("/")).filter((path) => path.length <= PATH_SEGMENTS_MAX && path.every((segment) => segment !== "" && !ignore.has(segment)));
+}
+
+/** Whether a path, its links resolved, is the project's folder or inside it: a linked parent folder can point anywhere. */
+async function inside(base, path) {
+  const real = await realpath(path).catch(() => null);
+  return real !== null && (real === base || real.startsWith(base + sep));
+}
+
+/** A file or folder at the root, which git may not track, such as .neon; a link is not followed. */
+async function isThere(base, path) {
+  const found = await lstat(path).catch(() => null);
+  return Boolean(found && (found.isFile() || found.isDirectory()) && (await inside(base, dirname(path))));
+}
+
+/** A manifest's text, or null when it is missing, a link or under one, not a plain file, or over 1 MiB. */
+async function readManifest(base, path) {
+  const found = await lstat(path).catch(() => null);
+  if (!found?.isFile() || found.size > MANIFEST_BYTES_MAX || !(await inside(base, path))) return null;
+  let handle;
+  try {
+    handle = await open(path, "r");
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.size > MANIFEST_BYTES_MAX) return null;
+    return await handle.readFile("utf8");
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/**
+ * The ids of the technologies a project uses, as the rules find them in its files and manifests,
+ * in the rules' order, at most 32. Nothing it reads leaves this function but those ids, and it
+ * never throws. Null when it could not tell, because a read failed or took past its time: the
+ * sync then sends nothing for the project, and the site keeps what it had, rather than fewer ids.
+ */
+export async function detectTech(rules, root, tracked) {
+  try {
+    const started = Date.now();
+    const base = await realpath(root);
+    const paths = await projectPaths(root, tracked, rules.ignore);
+    const found = new Set();
+    for (const rule of rules.tech) {
+      if (rule.files.some((pattern) => paths.some((path) => pathMatches(pattern, path)))) found.add(rule.id);
+    }
+    // A file the rule ties to the root by its whole name is looked for on disk too: .neon and .vercel are rarely tracked.
+    for (const rule of rules.tech) {
+      if (found.has(rule.id)) continue;
+      for (const pattern of rule.files) {
+        if (pattern.anchored && pattern.segments.every((segment) => segment.literal !== undefined) && (await isThere(base, join(root, ...pattern.segments.map((segment) => segment.literal))))) {
+          found.add(rule.id);
+          break;
+        }
+      }
+    }
+
+    const wanted = new Set(rules.tech.flatMap((rule) => Object.keys(rule.deps)));
+    // A manifest in a dot folder belongs to a tool, such as a skill in .claude or a dev container, not the project.
+    const ecosystemOf = (path) => (path.slice(0, -1).some((segment) => segment.startsWith(".")) ? null : manifestEcosystem(path.at(-1), path.at(-2)));
+    const manifests = paths
+      .filter((path) => wanted.has(ecosystemOf(path)))
+      .sort((a, b) => a.length - b.length || (a.join("/") < b.join("/") ? -1 : 1))
+      .slice(0, MANIFESTS_MAX);
+    const names = new Map(ECOSYSTEMS.map((ecosystem) => [ecosystem, new Set()]));
+    for (const path of manifests) {
+      if (Date.now() - started > PROJECT_MS_MAX) return null;
+      const ecosystem = ecosystemOf(path);
+      const text = await readManifest(base, join(root, ...path));
+      if (text === null) continue;
+      for (const name of dependencyNames(ecosystem, path.at(-1), text)) names.get(ecosystem).add(normalizeName(ecosystem, name));
+    }
+    for (const rule of rules.tech) {
+      if (found.has(rule.id)) continue;
+      const uses = Object.entries(rule.deps).some(([ecosystem, patterns]) => [...names.get(ecosystem)].some((name) => patterns.some((pattern) => nameMatches(pattern, name))));
+      if (uses) found.add(rule.id);
+    }
+    return rules.tech.filter((rule) => found.has(rule.id)).map((rule) => rule.id).slice(0, PER_PROJECT_MAX);
+  } catch {
+    return null;
+  }
+}