skillpass 0.1.0 → 0.2.0

package/README.md

@@ -25,6 +25,8 @@ skillpass scan <path> [--json]
 skillpass report <slug>[@version] [--json]
 skillpass add <slug>[@version] [--target <tool> [--global] | --dir <path>] [--yes]
 skillpass remove <slug> [--target <tool> [--global] | --dir <path>]
+skillpass update <slug>[@version] [--target <tool> [--global]] [--yes]
+skillpass outdated
 skillpass list
 skillpass --version | --help
 ```
@@ -63,11 +65,22 @@ skills in one verified step.
 
 ### Manage
 
-`skillpass list` shows what is installed in the known skills areas.
-`skillpass remove <slug>` deletes an installed skill; it refuses anything that
-does not look like an installed skill, so a stray `--dir` can never wipe a
-real folder. `skillpass scan <path>` runs the same validator the directory
-uses on any local skill folder before you submit it.
+Installs into the known skills areas are recorded in a per-area
+`.skillpass.json` receipt, so the CLI knows what it installed and at which
+version - your own hand-made skills in the same folders are left alone.
+
+- `skillpass list` shows installed skills with their versions
+- `skillpass outdated` compares them to the directory (exits 1 when updates
+  exist, handy in scripts)
+- `skillpass update <slug>` re-runs the whole trust gate - including a
+  permission diff against the version you currently have - then swaps the
+  install atomically; updating a pack swaps, adds, and removes members as
+  the pack changed
+- `skillpass remove <slug>` deletes an installed skill (a pack removes its
+  whole family); it refuses anything that does not look like an installed
+  skill, so a stray `--dir` can never wipe a real folder
+- `skillpass scan <path>` runs the same validator the directory uses on any
+  local skill folder before you submit it
 
 ## Configuration
 

package/dist/cli.mjs

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 import { createInterface } from "node:readline/promises";
 
 // ../../node_modules/.pnpm/fflate@0.8.3/node_modules/fflate/esm/index.mjs
@@ -494,15 +494,15 @@ function unzipSync(data, opts) {
 // src/add.ts
 import {
   existsSync,
-  mkdirSync,
+  mkdirSync as mkdirSync2,
   readdirSync as readdirSync2,
   renameSync,
   rmdirSync,
   rmSync,
   statSync as statSync2,
-  writeFileSync
+  writeFileSync as writeFileSync2
 } from "node:fs";
-import { dirname, isAbsolute, join as join3, resolve } from "node:path";
+import { dirname, isAbsolute, join as join4, resolve as resolve2 } from "node:path";
 
 // ../validator/src/load.ts
 import { createHash } from "node:crypto";
@@ -16103,7 +16103,8 @@ async function validatePackage(dir, opts = {}) {
 // src/api.ts
 var DEFAULT_API_URL = "https://api.skillpass.dev";
 function resolveApiUrl(override) {
-  return (override ?? process.env.SKILLPASS_API ?? DEFAULT_API_URL).replace(/\/$/, "");
+  const url2 = override ?? process.env.SKILLPASS_API;
+  return (url2 || DEFAULT_API_URL).replace(/\/$/, "");
 }
 function parseSkillRef(ref) {
   const at = ref.indexOf("@");
@@ -16177,6 +16178,53 @@ function resolvePackMembers(members, target) {
   return { installs, skipped };
 }
 
+// src/receipts.ts
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+var RECEIPT_FILE = ".skillpass.json";
+function looksLikeReceipt(value) {
+  return typeof value === "object" && value !== null && typeof value.version === "string" && typeof value.sourceHash === "string";
+}
+function readReceipts(areaDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(join2(areaDir, RECEIPT_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {};
+  }
+  const index = {};
+  for (const [slug, receipt] of Object.entries(parsed)) {
+    if (looksLikeReceipt(receipt)) {
+      index[slug] = receipt;
+    }
+  }
+  return index;
+}
+function writeReceipts(areaDir, index) {
+  try {
+    mkdirSync(areaDir, { recursive: true });
+    writeFileSync(join2(areaDir, RECEIPT_FILE), `${JSON.stringify(index, null, "	")}
+`);
+  } catch {
+  }
+}
+function recordReceipt(areaDir, slug, receipt) {
+  const index = readReceipts(areaDir);
+  index[slug] = receipt;
+  writeReceipts(areaDir, index);
+}
+function removeReceipt(areaDir, slug) {
+  const index = readReceipts(areaDir);
+  if (!(slug in index)) {
+    return;
+  }
+  delete index[slug];
+  writeReceipts(areaDir, index);
+}
+
 // src/style.ts
 var wrap = (open, close) => (text) => `\x1B[${open}m${text}\x1B[${close}m`;
 var ANSI = {
@@ -16285,11 +16333,11 @@ function renderDiff(diff) {
 
 // src/targets.ts
 import { homedir } from "node:os";
-import { join as join2 } from "node:path";
+import { join as join3, resolve } from "node:path";
 function installAreas(home = homedir()) {
   return {
-    "claude-code": { project: join2(".claude", "skills"), global: join2(home, ".claude", "skills") },
-    codex: { project: join2(".agents", "skills") }
+    "claude-code": { project: join3(".claude", "skills"), global: join3(home, ".claude", "skills") },
+    codex: { project: join3(".agents", "skills") }
   };
 }
 var MAPPED_TARGETS = Object.keys(installAreas());
@@ -16320,11 +16368,31 @@ function resolveTargetArea(target, global = false, home) {
 }
 function resolveTargetDir(target, slug, global = false, home) {
   const area = resolveTargetArea(target, global, home);
-  return area.ok ? { ok: true, dir: join2(area.dir, slug) } : area;
+  return area.ok ? { ok: true, dir: join3(area.dir, slug) } : area;
 }
 function mappableDeclaredTargets(declared) {
   return declared.filter((t) => MAPPED_TARGETS.includes(t));
 }
+function knownAreas(cwd, home) {
+  const areas = [];
+  const byTarget = installAreas(home);
+  for (const tool of MAPPED_TARGETS) {
+    const area = byTarget[tool];
+    if (!area) {
+      continue;
+    }
+    areas.push({
+      tool,
+      global: false,
+      label: `${tool} project (${area.project})`,
+      dir: resolve(cwd, area.project)
+    });
+    if (area.global) {
+      areas.push({ tool, global: true, label: `${tool} user (${area.global})`, dir: area.global });
+    }
+  }
+  return areas;
+}
 
 // src/add.ts
 function unsafeEntryPath(path) {
@@ -16391,11 +16459,11 @@ function writeTree(files, target) {
   const tempDir = `${target}.tmp-${process.pid}`;
   try {
     for (const file2 of files) {
-      const filePath = join3(tempDir, file2.path);
-      mkdirSync(dirname(filePath), { recursive: true });
-      writeFileSync(filePath, file2.content);
+      const filePath = join4(tempDir, file2.path);
+      mkdirSync2(dirname(filePath), { recursive: true });
+      writeFileSync2(filePath, file2.content);
     }
-    mkdirSync(dirname(target), { recursive: true });
+    mkdirSync2(dirname(target), { recursive: true });
     if (existsSync(target)) {
       rmdirSync(target);
     }
@@ -16565,9 +16633,9 @@ async function runAdd(ref, opts = {}) {
     }
   }
   if (packTool !== void 0) {
-    const area = resolveTargetArea(packTool, packGlobal);
-    if (!area.ok) {
-      push("", `error: ${area.message}`);
+    const area2 = resolveTargetArea(packTool, packGlobal);
+    if (!area2.ok) {
+      push("", `error: ${area2.message}`);
       return done(2);
     }
     const { installs, skipped } = resolvePackMembers(members, packTool);
@@ -16575,8 +16643,8 @@ async function runAdd(ref, opts = {}) {
       push("", `error: none of this pack's skills support ${packTool}`);
       return done(2);
     }
-    const areaAbs = resolve(opts.cwd ?? process.cwd(), area.dir);
-    const conflicts = installs.map((m) => join3(areaAbs, m.name)).filter(
+    const areaAbs = resolve2(opts.cwd ?? process.cwd(), area2.dir);
+    const conflicts = installs.map((m) => join4(areaAbs, m.name)).filter(
       (dest) => existsSync(dest) && (!statSync2(dest).isDirectory() || readdirSync2(dest).length > 0)
     );
     if (conflicts.length > 0) {
@@ -16610,7 +16678,7 @@ async function runAdd(ref, opts = {}) {
     const written = [];
     try {
       for (const plan of plans) {
-        writeTree(plan.files, join3(areaAbs, plan.name));
+        writeTree(plan.files, join4(areaAbs, plan.name));
         written.push(plan.name);
       }
     } catch {
@@ -16620,6 +16688,14 @@ async function runAdd(ref, opts = {}) {
       );
       return done(2);
     }
+    for (const name of written) {
+      recordReceipt(areaAbs, name, {
+        version: preflight.version,
+        sourceHash: preflight.sourceHash,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        pack: { slug, version: preflight.version }
+      });
+    }
     push(
       "",
       `Installed ${written.length} skills to ${areaAbs}`,
@@ -16648,7 +16724,7 @@ async function runAdd(ref, opts = {}) {
       }
     }
   }
-  const target = resolve(opts.cwd ?? process.cwd(), targetDir);
+  const target = resolve2(opts.cwd ?? process.cwd(), targetDir);
   if (existsSync(target)) {
     if (!statSync2(target).isDirectory()) {
       push("", `error: target ${target} already exists and is not a directory`);
@@ -16676,6 +16752,14 @@ async function runAdd(ref, opts = {}) {
     push("", "error: could not write the install; nothing was installed");
     return done(2);
   }
+  const area = knownAreas(opts.cwd ?? process.cwd()).find((a) => a.dir === dirname(target));
+  if (area) {
+    recordReceipt(area.dir, slug, {
+      version: preflight.version,
+      sourceHash: preflight.sourceHash,
+      installedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
   push(
     "",
     `Installed ${download.files.length} file(s) to ${target}`,
@@ -16686,27 +16770,12 @@ async function runAdd(ref, opts = {}) {
 
 // src/list.ts
 import { existsSync as existsSync2, readdirSync as readdirSync3, statSync as statSync3 } from "node:fs";
-import { join as join4, resolve as resolve2 } from "node:path";
-function knownAreas(cwd, home) {
-  const areas = [];
-  const byTarget = installAreas(home);
-  for (const tool of MAPPED_TARGETS) {
-    const area = byTarget[tool];
-    if (!area) {
-      continue;
-    }
-    areas.push({ label: `${tool} project (${area.project})`, dir: resolve2(cwd, area.project) });
-    if (area.global) {
-      areas.push({ label: `${tool} user (${area.global})`, dir: area.global });
-    }
-  }
-  return areas;
-}
+import { join as join5 } from "node:path";
 function installedIn(dir) {
   if (!existsSync2(dir)) {
     return [];
   }
-  return readdirSync3(dir).sort().filter((name) => statSync3(join4(dir, name)).isDirectory());
+  return readdirSync3(dir).sort().filter((name) => statSync3(join5(dir, name)).isDirectory());
 }
 function runList(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -16720,8 +16789,10 @@ function runList(opts = {}) {
       lines.push("");
     }
     lines.push(area.label);
+    const receipts = readReceipts(area.dir);
     for (const name of names) {
-      lines.push(`  ${name}`);
+      const version2 = receipts[name]?.version;
+      lines.push(version2 ? `  ${name}  ${version2}` : `  ${name}`);
     }
   }
   if (lines.length === 0) {
@@ -16730,11 +16801,136 @@ function runList(opts = {}) {
   return { lines, exitCode: 0 };
 }
 
+// src/outdated.ts
+import { join as join6 } from "node:path";
+async function identifyByHash(fetchImpl, apiUrl, slug, dir) {
+  let hash2;
+  try {
+    hash2 = loadPackage(dir).sourceHash;
+  } catch {
+    return void 0;
+  }
+  const detail = await getParsed(
+    fetchImpl,
+    `${apiUrl}/skills/${encodeURIComponent(slug)}`,
+    publicSkillDetailSchema
+  );
+  if (!detail.ok) {
+    return void 0;
+  }
+  for (const version2 of detail.data.versions) {
+    const preflight = await getParsed(
+      fetchImpl,
+      `${apiUrl}/skills/${encodeURIComponent(slug)}/${encodeURIComponent(version2.version)}/preflight`,
+      publicPreflightSchema
+    );
+    if (preflight.ok && preflight.data.sourceHash === hash2) {
+      return version2.version;
+    }
+  }
+  return void 0;
+}
+async function runOutdated(opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  const cwd = opts.cwd ?? process.cwd();
+  const fetched = await getParsed(fetchImpl, `${apiUrl}/skills`, publicSkillListSchema);
+  if (!fetched.ok) {
+    return { lines: [`error: ${fetched.message}`], exitCode: 2 };
+  }
+  const latestBySlug = new Map(fetched.data.map((s) => [s.slug, s]));
+  const lines = [];
+  let outdatedCount = 0;
+  let tracked = 0;
+  for (const area of knownAreas(cwd, opts.home)) {
+    const names = installedIn(area.dir);
+    if (names.length === 0) {
+      continue;
+    }
+    const receipts = readReceipts(area.dir);
+    const rows = [];
+    const seenPacks = /* @__PURE__ */ new Set();
+    let unrelated = 0;
+    for (const name of names) {
+      const receipt = receipts[name];
+      if (receipt?.pack) {
+        if (seenPacks.has(receipt.pack.slug)) {
+          continue;
+        }
+        seenPacks.add(receipt.pack.slug);
+        tracked += 1;
+        const members = Object.values(receipts).filter(
+          (r) => r.pack?.slug === receipt.pack?.slug
+        ).length;
+        const latest = latestBySlug.get(receipt.pack.slug)?.version;
+        if (latest === void 0) {
+          rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  not in the directory`);
+        } else if (latest === receipt.pack.version) {
+          rows.push(`  ${receipt.pack.slug}  ${receipt.pack.version}  current (pack, ${members} skills)`);
+        } else {
+          outdatedCount += 1;
+          rows.push(
+            `  ${receipt.pack.slug}  ${receipt.pack.version} -> ${latest}  (pack, ${members} skills)`
+          );
+        }
+        continue;
+      }
+      if (receipt) {
+        tracked += 1;
+        const latest = latestBySlug.get(name)?.version;
+        if (latest === void 0) {
+          rows.push(`  ${name}  ${receipt.version}  not in the directory`);
+        } else if (latest === receipt.version) {
+          rows.push(`  ${name}  ${receipt.version}  current`);
+        } else {
+          outdatedCount += 1;
+          rows.push(`  ${name}  ${receipt.version} -> ${latest}`);
+        }
+        continue;
+      }
+      if (!latestBySlug.has(name)) {
+        unrelated += 1;
+        continue;
+      }
+      const identified = await identifyByHash(fetchImpl, apiUrl, name, join6(area.dir, name));
+      if (identified !== void 0) {
+        tracked += 1;
+        const latest = latestBySlug.get(name)?.version;
+        if (latest === identified) {
+          rows.push(`  ${name}  ${identified}  current (identified by hash)`);
+        } else {
+          outdatedCount += 1;
+          rows.push(`  ${name}  ${identified} -> ${latest}  (identified by hash)`);
+        }
+        continue;
+      }
+      rows.push(`  ${name}  ?  no receipt - reinstall to track updates`);
+    }
+    if (rows.length > 0) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(area.label, ...rows);
+      if (unrelated > 0) {
+        lines.push(`  (${unrelated} folder(s) not from the directory)`);
+      }
+    }
+  }
+  if (tracked === 0 && lines.length === 0) {
+    return { lines: ["No skills installed in the known install areas."], exitCode: 0 };
+  }
+  lines.push(
+    "",
+    outdatedCount === 0 ? "Everything is current." : `${outdatedCount} update(s) available - skillpass update <slug>`
+  );
+  return { lines, exitCode: outdatedCount === 0 ? 0 : 1 };
+}
+
 // src/remove.ts
 import { existsSync as existsSync3, rmSync as rmSync2, statSync as statSync4 } from "node:fs";
-import { join as join5, resolve as resolve3 } from "node:path";
+import { dirname as dirname2, join as join7, resolve as resolve3 } from "node:path";
 function looksLikeInstalledSkill(dir) {
-  return existsSync3(join5(dir, "SKILL.md")) || existsSync3(join5(dir, "skill.json"));
+  return existsSync3(join7(dir, "SKILL.md")) || existsSync3(join7(dir, "skill.json"));
 }
 function candidateDirs(slug, cwd, home) {
   const dirs = [];
@@ -16744,9 +16940,9 @@ function candidateDirs(slug, cwd, home) {
     if (!area) {
       continue;
     }
-    dirs.push(resolve3(cwd, join5(area.project, slug)));
+    dirs.push(resolve3(cwd, join7(area.project, slug)));
     if (area.global) {
-      dirs.push(join5(area.global, slug));
+      dirs.push(join7(area.global, slug));
     }
   }
   dirs.push(resolve3(cwd, slug));
@@ -16760,6 +16956,39 @@ function runRemove(slug, opts = {}) {
     return { lines: ["error: --global needs --target (e.g. --target claude-code)"], exitCode: 2 };
   }
   const cwd = opts.cwd ?? process.cwd();
+  if (!opts.dir) {
+    let areas = knownAreas(cwd, opts.home);
+    if (opts.target) {
+      areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+    }
+    const packHits = areas.map((area) => ({
+      area,
+      members: Object.entries(readReceipts(area.dir)).filter(([, r]) => r.pack?.slug === slug).map(([name]) => name)
+    })).filter((hit) => hit.members.length > 0);
+    if (packHits.length > 1) {
+      return {
+        lines: [
+          `error: the ${slug} pack is installed in more than one place; pick one with --target:`,
+          ...packHits.map((hit) => `  ${hit.area.dir}`)
+        ],
+        exitCode: 2
+      };
+    }
+    if (packHits.length === 1) {
+      const { area, members } = packHits[0];
+      for (const name of members) {
+        rmSync2(join7(area.dir, name), { recursive: true, force: true });
+        removeReceipt(area.dir, name);
+      }
+      return {
+        lines: [
+          `Removed pack ${slug} (${members.length} skills) from ${area.dir}`,
+          `  ${members.sort().join(", ")}`
+        ],
+        exitCode: 0
+      };
+    }
+  }
   let dir;
   if (opts.target) {
     const resolved = resolveTargetDir(opts.target, slug, opts.global, opts.home);
@@ -16800,6 +17029,7 @@ function runRemove(slug, opts = {}) {
     };
   }
   rmSync2(dir, { recursive: true });
+  removeReceipt(dirname2(dir), slug);
   return { lines: [`Removed ${slug} from ${dir}`], exitCode: 0 };
 }
 
@@ -16928,6 +17158,288 @@ async function runSearch(opts = {}) {
   };
 }
 
+// src/update.ts
+import { existsSync as existsSync4, readdirSync as readdirSync4, renameSync as renameSync2, rmSync as rmSync3, statSync as statSync5 } from "node:fs";
+import { join as join8 } from "node:path";
+async function locate(slug, opts, fetchImpl, apiUrl) {
+  const cwd = opts.cwd ?? process.cwd();
+  let areas = knownAreas(cwd, opts.home);
+  if (opts.target) {
+    areas = areas.filter((a) => a.tool === opts.target && a.global === (opts.global ?? false));
+  }
+  const hits = [];
+  for (const area of areas) {
+    const receipts = readReceipts(area.dir);
+    const receipt = receipts[slug];
+    const dir = join8(area.dir, slug);
+    if (receipt) {
+      hits.push({
+        area,
+        dir,
+        installedVersion: receipt.version,
+        packSlug: receipt.pack?.slug
+      });
+      continue;
+    }
+    const packMember = Object.values(receipts).find((r) => r.pack?.slug === slug);
+    if (packMember?.pack) {
+      hits.push({ area, dir: area.dir, installedVersion: packMember.pack.version, packSlug: slug });
+      continue;
+    }
+    if (existsSync4(dir)) {
+      const identified = await identifyByHash(fetchImpl, apiUrl, slug, dir);
+      if (identified !== void 0) {
+        hits.push({ area, dir, installedVersion: identified });
+      }
+    }
+  }
+  return hits;
+}
+function permissionChanges(installed, target) {
+  const flat = (sets) => /* @__PURE__ */ new Set([...sets.declared, ...sets.detected]);
+  const before = flat(installed);
+  const after = flat(target);
+  return {
+    added: [...after].filter((key) => !before.has(key)).sort(),
+    removed: [...before].filter((key) => !after.has(key)).sort()
+  };
+}
+function swapTree(files, dir) {
+  const fresh = `${dir}.new-${process.pid}`;
+  const aside = `${dir}.old-${process.pid}`;
+  writeTree(files, fresh);
+  renameSync2(dir, aside);
+  try {
+    renameSync2(fresh, dir);
+  } catch (err2) {
+    renameSync2(aside, dir);
+    rmSync3(fresh, { recursive: true, force: true });
+    throw err2;
+  }
+  rmSync3(aside, { recursive: true, force: true });
+}
+async function runUpdate(ref, opts = {}) {
+  const lines = [];
+  const streamed = opts.emit !== void 0;
+  const push = (...next) => {
+    lines.push(...next);
+    if (next.length > 0) {
+      opts.emit?.(next.join("\n"));
+    }
+  };
+  const done = (exitCode) => ({ lines, exitCode, streamed });
+  const st = opts.style ?? PLAIN;
+  if (opts.global && !opts.target) {
+    push("error: --global needs --target (e.g. --target claude-code)");
+    return done(2);
+  }
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  const apiUrl = resolveApiUrl(opts.apiUrl);
+  const { slug } = parseSkillRef(ref);
+  if (!slug) {
+    push(`error: invalid skill reference "${ref}"`);
+    return done(2);
+  }
+  const hits = await locate(slug, opts, fetchImpl, apiUrl);
+  const memberHit = hits.find((h) => h.packSlug !== void 0 && h.packSlug !== slug);
+  if (memberHit?.packSlug !== void 0) {
+    push(
+      `error: ${slug} is part of the ${memberHit.packSlug} pack; run skillpass update ${memberHit.packSlug}`
+    );
+    return done(2);
+  }
+  if (hits.length === 0) {
+    push(
+      `error: ${slug} is not installed in a known skills area (only receipted or hash-identifiable installs can update)`
+    );
+    return done(2);
+  }
+  if (hits.length > 1) {
+    push(
+      `error: ${slug} is installed in more than one place; pick one with --target [--global]:`,
+      ...hits.map((h) => `  ${h.dir}`)
+    );
+    return done(2);
+  }
+  const installed = hits[0];
+  const fetched = await fetchPreflight(fetchImpl, apiUrl, ref);
+  if (!fetched.ok) {
+    push(...fetched.result.lines);
+    return done(fetched.result.exitCode);
+  }
+  const { detail, preflight } = fetched;
+  if ((detail.packMembers?.length ?? 0) > 0 || installed.packSlug === slug) {
+    return runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl, apiUrl, st, push, done);
+  }
+  if (installed.installedVersion === preflight.version) {
+    push(`${slug} is already at ${preflight.version}.`);
+    return done(0);
+  }
+  push(...renderPreflightReport(detail, preflight, opts.style));
+  push("", ...await changesVsInstalled(fetchImpl, apiUrl, slug, installed, preflight, st));
+  if (preflight.blocked) {
+    return done(1);
+  }
+  if (preflight.riskLevel !== "low" && !opts.yes) {
+    if (!opts.confirmImpl) {
+      push("", `error: a ${preflight.riskLevel}-risk skill needs confirmation; rerun with --yes`);
+      return done(2);
+    }
+    const confirmed = await opts.confirmImpl(
+      `Update ${slug} to ${preflight.version} (${preflight.riskLevel} risk)? [y/N] `
+    );
+    if (!confirmed) {
+      push("", "Update aborted; the installed version was left in place.");
+      return done(2);
+    }
+  }
+  const download = await downloadVerified(fetchImpl, apiUrl, slug, preflight.version, preflight.sourceHash);
+  if (!download.ok) {
+    push("", `error: ${download.message}`);
+    return done(2);
+  }
+  try {
+    swapTree(download.files, installed.dir);
+  } catch {
+    push("", "error: could not replace the install; the installed version was left in place");
+    return done(2);
+  }
+  recordReceipt(installed.area.dir, slug, {
+    version: preflight.version,
+    sourceHash: preflight.sourceHash,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  push(
+    "",
+    `Updated ${slug} ${installed.installedVersion ?? "?"} -> ${preflight.version} in ${installed.dir}`,
+    "Source hash verified against the Skill Passport."
+  );
+  return done(0);
+}
+async function changesVsInstalled(fetchImpl, apiUrl, slug, installed, target, st) {
+  if (installed.installedVersion === void 0) {
+    return ["Changes vs installed: unknown (no version identified)"];
+  }
+  const before = await getParsed(
+    fetchImpl,
+    `${apiUrl}/skills/${encodeURIComponent(slug)}/${encodeURIComponent(installed.installedVersion)}/preflight`,
+    publicPreflightSchema
+  );
+  if (!before.ok) {
+    return [
+      `Changes vs installed v${installed.installedVersion}: unavailable (that version is no longer published)`
+    ];
+  }
+  const { added, removed } = permissionChanges(before.data.permissions, target.permissions);
+  if (added.length === 0 && removed.length === 0) {
+    return [`Changes vs installed v${installed.installedVersion}: no permission changes`];
+  }
+  return [
+    `Changes vs installed v${installed.installedVersion}`,
+    ...added.map((key) => st.red(`  + ${key} (new)`)),
+    ...removed.map((key) => `  - ${key} (no longer requested)`)
+  ];
+}
+async function runPackUpdate(slug, installed, detail, preflight, opts, fetchImpl, apiUrl, st, push, done) {
+  if (installed.packSlug !== slug) {
+    push(`error: ${slug} is a pack but this install is not tracked as one; reinstall with skillpass add`);
+    return done(2);
+  }
+  if (installed.installedVersion === preflight.version) {
+    push(`${slug} is already at ${preflight.version}.`);
+    return done(0);
+  }
+  push(...renderPreflightReport(detail, preflight, opts.style));
+  push("", ...await changesVsInstalled(fetchImpl, apiUrl, slug, installed, preflight, st));
+  if (preflight.blocked) {
+    return done(1);
+  }
+  if (preflight.riskLevel !== "low" && !opts.yes) {
+    if (!opts.confirmImpl) {
+      push("", `error: a ${preflight.riskLevel}-risk skill needs confirmation; rerun with --yes`);
+      return done(2);
+    }
+    const confirmed = await opts.confirmImpl(
+      `Update ${slug} to ${preflight.version} (${preflight.riskLevel} risk)? [y/N] `
+    );
+    if (!confirmed) {
+      push("", "Update aborted; the installed version was left in place.");
+      return done(2);
+    }
+  }
+  const areaDir = installed.area.dir;
+  const { installs, skipped } = resolvePackMembers(detail.packMembers ?? [], installed.area.tool);
+  if (installs.length === 0) {
+    push("", `error: none of the new version's skills support ${installed.area.tool}`);
+    return done(2);
+  }
+  const receipts = readReceipts(areaDir);
+  const currentMembers = Object.entries(receipts).filter(([, r]) => r.pack?.slug === slug).map(([name]) => name);
+  const newNames = new Set(installs.map((m) => m.name));
+  const toRemove = currentMembers.filter((name) => !newNames.has(name));
+  const additions = installs.filter((m) => !currentMembers.includes(m.name));
+  const conflicts = additions.map((m) => join8(areaDir, m.name)).filter(
+    (dest) => existsSync4(dest) && (!statSync5(dest).isDirectory() || readdirSync4(dest).length > 0)
+  );
+  if (conflicts.length > 0) {
+    push(
+      "",
+      "error: these destinations already exist and are not empty; nothing was changed:",
+      ...conflicts.map((c) => `  ${c}`)
+    );
+    return done(2);
+  }
+  const download = await downloadVerified(fetchImpl, apiUrl, slug, preflight.version, preflight.sourceHash);
+  if (!download.ok) {
+    push("", `error: ${download.message}`);
+    return done(2);
+  }
+  const plans = installs.map((m) => ({ ...m, files: memberFiles(download.files, m.sourceDir) }));
+  const missing = plans.find((p) => p.files.length === 0);
+  if (missing) {
+    push("", `error: the snapshot has no files for "${missing.name}"; nothing was changed`);
+    return done(2);
+  }
+  for (const name of skipped) {
+    push("", `note: ${name} does not support ${installed.area.tool}; skipped`);
+  }
+  const done1 = [];
+  try {
+    for (const plan of plans) {
+      const dest = join8(areaDir, plan.name);
+      if (existsSync4(dest)) {
+        swapTree(plan.files, dest);
+      } else {
+        writeTree(plan.files, dest);
+      }
+      done1.push(plan.name);
+      recordReceipt(areaDir, plan.name, {
+        version: preflight.version,
+        sourceHash: preflight.sourceHash,
+        installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        pack: { slug, version: preflight.version }
+      });
+    }
+  } catch {
+    push(
+      "",
+      `error: could not write ${plans[done1.length].name}; updated before the failure: ${done1.join(", ") || "none"}`
+    );
+    return done(2);
+  }
+  for (const name of toRemove) {
+    rmSync3(join8(areaDir, name), { recursive: true, force: true });
+    removeReceipt(areaDir, name);
+  }
+  push(
+    "",
+    `Updated ${slug} ${installed.installedVersion ?? "?"} -> ${preflight.version} in ${areaDir}`,
+    `  ${done1.length} skill(s)${additions.length > 0 ? `, added: ${additions.map((m) => m.name).join(", ")}` : ""}${toRemove.length > 0 ? `, removed: ${toRemove.join(", ")}` : ""}`,
+    "Source hash verified against the Skill Passport."
+  );
+  return done(0);
+}
+
 // src/scan.ts
 async function runScan(path, opts = {}) {
   let report;
@@ -16970,7 +17482,7 @@ async function runScan(path, opts = {}) {
 }
 
 // src/index.ts
-var VERSION = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8")).version;
+var VERSION = JSON.parse(readFileSync3(new URL("../package.json", import.meta.url), "utf8")).version;
 var USAGE = [
   "skillpass - validate AI agent skills locally and inspect hosted passports",
   "",
@@ -16984,6 +17496,9 @@ var USAGE = [
   "  skillpass remove <slug> [--target <tool> [--global] | --dir <path>]",
   "                                             remove an installed skill",
   "  skillpass list                              show installed skills in the known areas",
+  "  skillpass outdated                          compare installed skills to the directory",
+  "  skillpass update <slug>[@version] [--target <tool> [--global]] [--yes]",
+  "                                             update an installed skill through the gate",
   "",
   "Flags:",
   "  --json    print machine-readable JSON instead of the readable report",
@@ -16998,7 +17513,8 @@ var USAGE = [
   "  --help    show this message",
   "",
   "The search, report, and add commands read the API base URL from SKILLPASS_API.",
-  "Exit codes: 0 ok/warning, 1 failed or blocked, 2 usage/load/network errors."
+  "Exit codes: 0 ok/warning, 1 failed or blocked, 2 usage/load/network errors",
+  "(outdated exits 1 when updates are available)."
 ].join("\n");
 var COMMAND_FLAGS = {
   scan: ["--json"],
@@ -17006,6 +17522,8 @@ var COMMAND_FLAGS = {
   add: ["--yes", "--target", "--dir", "--global"],
   remove: ["--target", "--dir", "--global"],
   list: [],
+  outdated: [],
+  update: ["--yes", "--target", "--global"],
   search: ["--target", "--category", "--packs", "--json"]
 };
 function parseCliArgs(argv) {
@@ -17124,6 +17642,27 @@ async function run(argv) {
     }
     return runList();
   }
+  if (args.command === "update") {
+    const [ref] = args.positional;
+    if (!ref) {
+      return { lines: ["error: update needs a skill slug", "", USAGE], exitCode: 2 };
+    }
+    const tty = Boolean(process.stdin.isTTY);
+    return runUpdate(ref, {
+      yes: args.yes,
+      target: args.target,
+      global: args.global,
+      style: styler(Boolean(process.stdout.isTTY)),
+      confirmImpl: tty ? confirmViaTty : void 0,
+      emit: (text) => console.log(text)
+    });
+  }
+  if (args.command === "outdated") {
+    if (args.positional.length > 0) {
+      return { lines: ["error: outdated takes no arguments", "", USAGE], exitCode: 2 };
+    }
+    return runOutdated();
+  }
   if (args.command === "report") {
     const [ref] = args.positional;
     if (!ref) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillpass",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Validation-first installer for AI agent skills: search the SkillPass directory, inspect a skill's passport, and install hash-verified skills and packs for Claude Code, Codex, and more.",
   "keywords": [
     "ai",
@@ -36,8 +36,8 @@
     "esbuild": "^0.28.1",
     "fflate": "^0.8.3",
     "typescript": "^6.0.3",
-    "skill-schema": "0.1.0",
-    "validator": "0.3.0"
+    "validator": "0.3.0",
+    "skill-schema": "0.1.0"
   },
   "scripts": {
     "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=dist/cli.mjs --log-level=warning",