@linchpinagency/skills 0.1.7 → 0.1.8

package/README.md

@@ -12,7 +12,7 @@ GitHub Copilot, and other compatible coding agents.
 ![Zero dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)
 
 <!-- x-release-please-start-version -->
-### Latest release: 0.1.7
+### Latest release: 0.1.8
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |
@@ -191,6 +191,33 @@ npx @linchpinagency/skills --skip-upstream
 **Updating:** re-run the same command. The installer overwrites each skill in place, so a
 fresh run always pulls the latest published version.
 
+### Keeping skills current
+
+Installed skills are a snapshot — nothing about a copy in `.claude/skills/` knows a newer
+release exists. So every install writes a stamp beside the skills, in
+`<skills-dir>/.linchpin-skills/`: `version.json` (the version, the date, the agent, the exact
+command that produced the install, and the upstream ref that was vendored) plus a
+self-contained copy of the update checker.
+
+```bash
+# Are these skills behind? One line if yes, nothing if no.
+node .claude/skills/.linchpin-skills/update-check.mjs
+
+# Print the Claude Code SessionStart hook that runs it for you
+node .claude/skills/.linchpin-skills/update-check.mjs --hook
+```
+
+With the hook installed, a stale install announces itself at the start of a session —
+`SessionStart` stdout becomes context, so the agent sees it too and can offer to run the
+update command the stamp recorded. Hooks are a Claude Code feature; under Copilot, Codex, or
+Cursor the same check still runs, just when you ask it to.
+
+The check is deliberately unobtrusive: it queries the npm registry at most once a day (a
+known-newer version keeps surfacing from cache in between), stays silent when it can't reach
+the network, and always exits 0 — a session never fails to start because of it. It reports;
+it never upgrades anything. Set `LINCHPIN_SKILLS_UPDATE_CHECK=0` to switch it off, and it
+skips itself whenever `CI` is set.
+
 ### Where skills land
 
 | Agent (`--agent`) | Project scope | Global scope (`--global`) |

package/bin/install.mjs

@@ -15,6 +15,13 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
 const SKILLS_ROOT = path.join(PKG_ROOT, 'skills');
 const UPSTREAM_MANIFEST = path.join(PKG_ROOT, 'upstream.json');
+const PKG_MANIFEST = path.join(PKG_ROOT, 'package.json');
+
+// Version stamp + a self-contained copy of the update checker, written into each install
+// directory. Dot-prefixed and without a SKILL.md, so no agent mistakes it for a skill.
+const STAMP_DIR = '.linchpin-skills';
+const STAMP_FILE = 'version.json';
+const CHECKER = 'update-check.mjs';
 
 // Per-agent install locations. `project` paths are relative to cwd, `global` to home.
 // These follow the Agent Skills conventions each tool reads from. An agent may read more
@@ -80,6 +87,50 @@ function readUpstreamManifest() {
   }
 }
 
+function packageVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(PKG_MANIFEST, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+// The exact command that reproduces this install, recorded in the stamp so the update
+// checker can tell someone how to re-run it with the flags they actually used.
+function updateCommand(opts) {
+  const parts = ['npx @linchpinagency/skills'];
+  if (opts.skills.length) parts.push(...opts.skills);
+  if (opts.agent !== 'claude-code') parts.push('--agent', opts.agent);
+  if (opts.global) parts.push('--global');
+  if (opts.skipUpstream) parts.push('--skip-upstream');
+  return parts.join(' ');
+}
+
+// Record what landed here and leave the checker beside it. Best-effort: a stamp we can't
+// write costs an upgrade nudge, not the install.
+function writeStamp(target, { version, opts, skills, upstream }) {
+  const dir = path.join(target.dir, STAMP_DIR);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = {
+      package: '@linchpinagency/skills',
+      version,
+      installedAt: new Date().toISOString(),
+      agent: target.agent,
+      scope: opts.global ? 'global' : 'project',
+      updateCommand: updateCommand(opts),
+      skills,
+      upstream,
+    };
+    fs.writeFileSync(path.join(dir, STAMP_FILE), JSON.stringify(stamp, null, 2) + '\n');
+    fs.copyFileSync(path.join(__dirname, CHECKER), path.join(dir, CHECKER));
+    return true;
+  } catch (err) {
+    console.warn(`  ! Could not write the version stamp in ${dir}: ${err.message}`);
+    return false;
+  }
+}
+
 // Fetch a repo tarball at a pinned ref, extract it once, and copy the requested skill
 // dirs into every directory in `bases`. Best-effort: any failure (offline, no `tar`,
 // missing skill) warns and returns false rather than aborting the Linchpin install.
@@ -193,12 +244,15 @@ async function main() {
     process.exit(1);
   }
 
-  // One flat list of destination dirs across every selected agent.
-  const bases = agentIds.flatMap((id) =>
-    (opts.global ? AGENTS[id].global : AGENTS[id].project).map((rel) =>
-      opts.global ? path.join(os.homedir(), rel) : path.join(process.cwd(), rel)
-    )
+  // Every destination across every selected agent, each tagged with the agent it belongs to
+  // (the stamp records it; the copy loops only need the directory).
+  const targets = agentIds.flatMap((id) =>
+    (opts.global ? AGENTS[id].global : AGENTS[id].project).map((rel) => ({
+      agent: id,
+      dir: opts.global ? path.join(os.homedir(), rel) : path.join(process.cwd(), rel),
+    }))
   );
+  const bases = targets.map((t) => t.dir);
 
   const wanted = opts.skills.length ? opts.skills : all;
   const unknown = wanted.filter((s) => !all.includes(s));
@@ -221,11 +275,26 @@ async function main() {
   const labels = agentIds.map((id) => AGENTS[id].label).join(', ');
   console.log(`\nInstalled ${wanted.length} Linchpin skill(s) for ${labels}.`);
 
+  const upstream = [];
   if (!opts.skipUpstream && sources.length) {
     console.log('\nVendoring pinned base layer (upstream WordPress/agent-skills):');
-    for (const s of sources) await installUpstreamSource(s, bases);
+    for (const s of sources) {
+      const installed = await installUpstreamSource(s, bases);
+      upstream.push({ repo: s.repo, ref: s.ref, installed });
+    }
     console.log('\nTip: --skip-upstream installs Linchpin skills only.');
   }
+
+  // Stamp last, so `upstream` reflects what actually landed rather than what was intended.
+  const version = packageVersion();
+  const stamped = targets.filter((t) => writeStamp(t, { version, opts, skills: wanted, upstream }));
+  if (stamped.length && agentIds.includes('claude-code')) {
+    const rel = path.join(STAMP_DIR, CHECKER);
+    console.log(
+      `\nStamped v${version}. To be told when these skills go stale, add a SessionStart hook:` +
+        `\n  node ${path.join(opts.global ? '~/.claude/skills' : '.claude/skills', rel)} --hook`
+    );
+  }
 }
 
 main();

package/bin/update-check.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// @linchpinagency/skills — installed-version check.
+//
+// Prints ONE line when a newer release is published, and nothing at all otherwise. Exits 0
+// on every path — offline, unwritable cache, missing stamp, malformed JSON — because this is
+// meant to be wired into a Claude Code `SessionStart` hook, where stdout becomes session
+// context. A failure here must never be the first thing an agent reads.
+//
+//   node .claude/skills/.linchpin-skills/update-check.mjs
+//   node .claude/skills/.linchpin-skills/update-check.mjs --force   # ignore the throttle
+//   node .claude/skills/.linchpin-skills/update-check.mjs --json    # always emit a status
+//   node .claude/skills/.linchpin-skills/update-check.mjs --hook    # print the hook snippet
+//
+// Off switch: LINCHPIN_SKILLS_UPDATE_CHECK=0. Also silent when CI is set.
+//
+// `bin/install.mjs` copies this file next to the `version.json` stamp it writes, so the
+// installed copy is self-contained — it reads the stamp as a sibling, not from the package.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = '@linchpinagency/skills';
+// Overridable so this is testable offline, and usable behind a private registry mirror.
+const REGISTRY = process.env.LINCHPIN_SKILLS_REGISTRY || `https://registry.npmjs.org/${PKG}/latest`;
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 3000;
+const OFF = new Set(['0', 'false', 'off', 'no']);
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The installed version, from the stamp `install.mjs` wrote alongside this file. Falls back
+ * to the package's own version so the script is still exercisable from a checkout, where no
+ * install stamp exists.
+ */
+function readStamp() {
+  const stamp = readJson(path.join(HERE, 'version.json'));
+  if (stamp?.version) return stamp;
+  const pkg = readJson(path.join(HERE, '..', 'package.json'));
+  if (pkg?.version) return { version: pkg.version, updateCommand: `npx ${PKG}`, source: 'package' };
+  return null;
+}
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'linchpin-skills', 'update-check.json');
+}
+
+function readCache() {
+  const c = readJson(cacheFile());
+  return typeof c?.checkedAt === 'number' && c.latest ? c : null;
+}
+
+function writeCache(entry) {
+  try {
+    const file = cacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(entry) + '\n');
+  } catch {
+    // A read-only or missing HOME just means we check again next time.
+  }
+}
+
+async function fetchLatest() {
+  try {
+    const res = await fetch(REGISTRY, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const { version } = await res.json();
+    return typeof version === 'string' ? version : null;
+  } catch {
+    return null; // offline, DNS, timeout, private registry — all the same answer here.
+  }
+}
+
+/** -1 / 0 / 1. Release beats prerelease at the same core version; build metadata ignored. */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = String(v).trim().replace(/^v/, '').split('+')[0].split('-');
+    const parts = core.split('.').map((n) => Number.parseInt(n, 10));
+    return { nums: [0, 1, 2].map((i) => (Number.isFinite(parts[i]) ? parts[i] : 0)), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+async function evaluate({ force }) {
+  if (OFF.has(String(process.env.LINCHPIN_SKILLS_UPDATE_CHECK ?? '').toLowerCase())) {
+    return { status: 'disabled', reason: 'LINCHPIN_SKILLS_UPDATE_CHECK' };
+  }
+  // No human reads a CI log for upgrade nudges, and headless runs shouldn't reach the network.
+  if (process.env.CI && !force) return { status: 'disabled', reason: 'CI' };
+
+  const stamp = readStamp();
+  if (!stamp) return { status: 'unknown', reason: 'no-version-stamp' };
+
+  // Throttle the network call, not the message: a known-newer version keeps surfacing on
+  // later sessions from cache, so the nudge survives without re-hitting the registry.
+  const cache = force ? null : readCache();
+  const cached = cache && Date.now() - cache.checkedAt < THROTTLE_MS;
+  const latest = cached ? cache.latest : await fetchLatest();
+  if (!latest) return { status: 'unknown', reason: 'registry-unreachable', installed: stamp.version };
+  if (!cached) writeCache({ checkedAt: Date.now(), latest });
+
+  const command = stamp.updateCommand || `npx ${PKG}`;
+  const result = { installed: stamp.version, latest, command, installedAt: stamp.installedAt ?? null };
+  return compareVersions(latest, stamp.version) > 0
+    ? { status: 'update-available', ...result }
+    : { status: 'up-to-date', ...result };
+}
+
+function hookSnippet() {
+  const run =
+    'f=.claude/skills/.linchpin-skills/update-check.mjs; ' +
+    '[ -f "$f" ] || f=$HOME/.claude/skills/.linchpin-skills/update-check.mjs; ' +
+    '[ -f "$f" ] && node "$f" || true';
+  return `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [{
+          "type": "command",
+          "command": ${JSON.stringify(`bash -c '${run}'`)},
+          "timeout": 10
+        }]
+      }
+    ]
+  }
+}`;
+}
+
+function printHook() {
+  console.log(`Add to .claude/settings.json (project) or ~/.claude/settings.json (global):\n`);
+  console.log(hookSnippet());
+  console.log(`
+The command prefers the project install and falls back to the global one, and swallows its
+own failures — a session never fails to start because of this check.`);
+}
+
+function help() {
+  console.log(
+    `
+${PKG} — report when the installed skills are behind the published release.
+
+Usage:
+  node update-check.mjs [options]
+
+Options:
+  --force    Ignore the 24h throttle (and the CI opt-out) and query the registry now
+  --json     Always print a status object, even when up to date
+  --hook     Print the Claude Code SessionStart hook snippet that runs this check
+  -h, --help Show this help
+
+Environment:
+  LINCHPIN_SKILLS_UPDATE_CHECK=0   Disable the check entirely
+  LINCHPIN_SKILLS_REGISTRY=<url>   Query a different registry endpoint
+
+Prints one line when an update is available, nothing otherwise. Always exits 0.
+`.trimStart()
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) return help();
+  if (args.includes('--hook')) return printHook();
+
+  const asJson = args.includes('--json');
+  const result = await evaluate({ force: args.includes('--force') });
+
+  if (asJson) return console.log(JSON.stringify(result));
+  if (result.status !== 'update-available') return;
+
+  const when = result.installedAt ? ` (installed ${String(result.installedAt).slice(0, 10)})` : '';
+  console.log(
+    `Linchpin skills ${result.installed} → ${result.latest} available${when}. Update with: ${result.command}`
+  );
+}
+
+main().catch(() => {}); // Never let this be the reason a session start fails.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {