altalandi 0.6.0 → 0.6.2

package/update.mjs

@@ -1,273 +1,315 @@
-// `altalandi update` — check for a newer CLI, ask before installing it, then
-// offer to install or refresh the /altalandi skill for Claude Code.
-//
-// Nothing is ever changed without consent. Interactive terminals get a y/N
-// prompt; non-interactive callers (agents, CI, pipes) are only told what is
-// available, unless they pass --yes, which is itself the explicit consent.
-//
-// Zero dependencies, like the rest of the CLI.
-
-import { spawn } from "node:child_process";
-import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
-import path from "node:path";
-import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
-
-export const PACKAGE = "altalandi";
-export const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
-
-// Exit codes. 10 is deliberately distinct from the refine command's 1/2/3 so a
-// script can tell "an update exists" apart from "something failed".
-export const EXIT_OK = 0;
-export const EXIT_CHECK_FAILED = 1;
-export const EXIT_UPDATE_AVAILABLE = 10;
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-export const BUNDLED_SKILL = path.join(HERE, "skill", "SKILL.md");
-
-export async function currentVersion() {
-  const pkg = JSON.parse(await readFile(path.join(HERE, "package.json"), "utf8"));
-  return pkg.version;
-}
-
-/** Semver-ish compare: -1 if a<b, 0 if equal, 1 if a>b. A prerelease sorts
- *  before its release (0.2.0-beta < 0.2.0). */
-export function compareVersions(a, b) {
-  const parse = (v) => {
-    const [core, pre = ""] = String(v).trim().replace(/^v/, "").split("-", 2);
-    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
-  };
-  const x = parse(a);
-  const y = parse(b);
-  for (let i = 0; i < 3; i++) {
-    const d = (x.nums[i] || 0) - (y.nums[i] || 0);
-    if (d !== 0) return d < 0 ? -1 : 1;
-  }
-  if (x.pre === y.pre) return 0;
-  if (!x.pre) return 1;
-  if (!y.pre) return -1;
-  return x.pre < y.pre ? -1 : 1;
-}
-
-export async function fetchLatestVersion({ fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetchImpl(REGISTRY_URL, {
-      signal: controller.signal,
-      headers: { accept: "application/json" },
-    });
-    if (!res.ok) throw new Error(`npm registry answered ${res.status}`);
-    const body = JSON.parse(await res.text());
-    if (!body || typeof body.version !== "string") throw new Error("npm registry returned no version");
-    return body.version;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-const norm = (p) => {
-  let out = path.resolve(p);
-  try { out = realpathSync(out); } catch { /* keep the resolved path */ }
-  return process.platform === "win32" ? out.toLowerCase() : out;
-};
-
-/** How is this copy of the CLI being run? That decides what "update" means.
- *
- *  npx    — lives in npm's _npx cache; there is nothing to install, but a bare
- *           `npx altalandi` can keep reusing an old cached copy
- *  global — `npm install -g altalandi`
- *  local  — a project dependency
- *  source — a checkout of the repository; npm cannot update that
- */
-export function detectInstall({ scriptPath, globalRoot }) {
-  const p = norm(scriptPath);
-  const sep = path.sep === "\\" ? /[\\/]/ : /\//;
-  const parts = p.split(sep);
-  if (parts.includes("_npx")) return "npx";
-  const nm = parts.lastIndexOf("node_modules");
-  if (nm === -1) return "source";
-  if (globalRoot && p.startsWith(norm(globalRoot) + (process.platform === "win32" ? "\\" : "/"))) {
-    return "global";
-  }
-  return "local";
-}
-
-/** The exact command that updates this install. Constants only — never built
- *  from user input. */
-export function updatePlan(kind, { projectDir } = {}) {
-  switch (kind) {
-    case "global":
-      return { cmd: "npm", args: ["install", "-g", `${PACKAGE}@latest`], show: `npm install -g ${PACKAGE}@latest` };
-    case "local":
-      return { cmd: "npm", args: ["install", `${PACKAGE}@latest`], cwd: projectDir, show: `npm install ${PACKAGE}@latest` };
-    case "npx":
-      return { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "--version"], show: `npx ${PACKAGE}@latest` };
-    default:
-      return null;
-  }
-}
-
-/** Where Claude Code looks for personal skills. */
-export function skillTarget({ env = process.env, home = homedir() } = {}) {
-  const root = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
-  return { root, file: path.join(root, "skills", PACKAGE, "SKILL.md") };
-}
-
-/** missing | current | outdated. `absent` means Claude Code itself is not set
- *  up, in which case the skill is not offered at all — never create ~/.claude
- *  for someone who does not use it. */
-export async function skillStatus({ bundled = BUNDLED_SKILL, target = skillTarget() } = {}) {
-  if (!existsSync(bundled)) return "unbundled";
-  if (!existsSync(target.root)) return "absent";
-  if (!existsSync(target.file)) return "missing";
-  const [a, b] = await Promise.all([readFile(bundled, "utf8"), readFile(target.file, "utf8")]);
-  const clean = (s) => s.replace(/\r\n/g, "\n").trim();
-  return clean(a) === clean(b) ? "current" : "outdated";
-}
-
-/** Install or refresh the skill. An existing copy is always backed up first:
- *  people edit their skills, and an update must never silently eat that. */
-export async function writeSkill({ bundled = BUNDLED_SKILL, target = skillTarget(), now = new Date() } = {}) {
-  await mkdir(path.dirname(target.file), { recursive: true });
-  let backup = null;
-  if (existsSync(target.file)) {
-    const stamp = now.toISOString().replace(/[:.]/g, "-");
-    backup = `${target.file}.bak-${stamp}`;
-    await copyFile(target.file, backup);
-  }
-  await writeFile(target.file, await readFile(bundled, "utf8"), "utf8");
-  return { file: target.file, backup };
-}
-
-function run(plan) {
-  return new Promise((resolve) => {
-    // npm and npx are .cmd shims on Windows, which need a shell. The arguments
-    // are constants from updatePlan(), so there is nothing to inject.
-    const child = spawn(plan.cmd, plan.args, {
-      cwd: plan.cwd,
-      stdio: "inherit",
-      shell: process.platform === "win32",
-    });
-    child.on("error", () => resolve(1));
-    child.on("close", (code) => resolve(code ?? 1));
-  });
-}
-
-function npmGlobalRoot() {
-  return new Promise((resolve) => {
-    const child = spawn("npm", ["root", "-g"], { shell: process.platform === "win32" });
-    let out = "";
-    child.stdout?.setEncoding("utf8").on("data", (c) => { out += c; });
-    child.on("error", () => resolve(null));
-    child.on("close", () => resolve(out.trim() || null));
-  });
-}
-
-/** A y/N question on stderr; only y/yes (or j/já) is a yes. Shared with the
- *  folder and site runs, which ask before sending anything. */
-export async function ask(question, { input = process.stdin, output = process.stderr } = {}) {
-  const rl = createInterface({ input, output });
-  try {
-    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
-    return answer === "y" || answer === "yes" || answer === "j" || answer === "já";
-  } finally {
-    rl.close();
-  }
-}
-
-/**
- * The whole command. Every side effect is injectable so it can be tested
- * without touching npm, the network or the real home directory.
- */
-export async function runUpdate(flags, io = {}) {
-  const log = io.log || ((m) => process.stderr.write(`${m}\n`));
-  const interactive = io.interactive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
-  const confirm = io.confirm || ask;
-  const execute = io.run || run;
-  const target = io.skillTarget || skillTarget();
-  const bundled = io.bundledSkill || BUNDLED_SKILL;
-
-  // --check never changes anything. Without a terminal and without --yes there
-  // is nobody to ask, so the same rule applies: report, don't act.
-  const mayAct = !flags.check && (flags.yes || interactive);
-  const consent = async (q) => (flags.yes ? true : confirm(q));
-
-  const installed = io.currentVersion || await currentVersion();
-
-  if (!flags.skillOnly) {
-    let latest;
-    try {
-      latest = io.latestVersion || await fetchLatestVersion({ fetchImpl: io.fetch });
-    } catch (e) {
-      log(`Could not check for updates: ${e.message}`);
-      return EXIT_CHECK_FAILED;
-    }
-
-    if (compareVersions(installed, latest) < 0) {
-      const scriptPath = io.scriptPath || fileURLToPath(new URL("./altalandi.mjs", import.meta.url));
-      // `npm root -g` spawns npm, so only ask it when the answer matters: a copy
-      // inside some node_modules that is not npx's cache.
-      const inNodeModules = /[\\/]node_modules[\\/]/.test(scriptPath) && !/[\\/]_npx[\\/]/.test(scriptPath);
-      const globalRoot = io.globalRoot !== undefined ? io.globalRoot
-        : (inNodeModules ? await (io.npmGlobalRoot || npmGlobalRoot)() : null);
-      const kind = io.installKind || detectInstall({ scriptPath, globalRoot });
-      const plan = updatePlan(kind, { projectDir: io.projectDir || process.cwd() });
-      log(`A new version of ${PACKAGE} is available: ${installed} → ${latest}`);
-
-      if (!plan) {
-        log("This copy runs from a source checkout, so npm cannot update it. Pull the repository instead.");
-        return EXIT_UPDATE_AVAILABLE;
-      }
-      if (!mayAct) {
-        log(`Update with:  ${plan.show}`);
-        return EXIT_UPDATE_AVAILABLE;
-      }
-      if (!(await consent(`Update ${PACKAGE} to ${latest} now?`))) {
-        log(`Skipped. Update later with:  ${plan.show}`);
-        return EXIT_UPDATE_AVAILABLE;
-      }
-      log(`Running: ${plan.show}`);
-      const code = await execute(plan);
-      if (code !== 0) {
-        log(`Update failed (exit ${code}). Try running it yourself:  ${plan.show}`);
-        return EXIT_CHECK_FAILED;
-      }
-      log(`Updated to ${latest}.`);
-      // The skill that ships with the NEW version is the one worth installing,
-      // and this process is still the old one. Hand over to the new CLI.
-      const handoff = kind === "npx"
-        ? { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] }
-        : { cmd: PACKAGE, args: ["update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] };
-      await execute(handoff);
-      return EXIT_OK;
-    }
-    log(`${PACKAGE} ${installed} is up to date.`);
-  }
-
-  const status = await skillStatus({ bundled, target });
-  if (status === "unbundled" || status === "absent") return EXIT_OK;
-  if (status === "current") {
-    log("The /altalandi skill for Claude Code is up to date.");
-    return EXIT_OK;
-  }
-  const what = status === "missing"
-    ? `Install the /altalandi skill for Claude Code (${target.file})?`
-    : "Your /altalandi skill for Claude Code differs from this version. Replace it (your copy is backed up first)?";
-  if (!mayAct) {
-    log(status === "missing"
-      ? "The /altalandi skill for Claude Code is not installed. Run `altalandi update` in a terminal to install it."
-      : "Your /altalandi skill for Claude Code is out of date. Run `altalandi update` in a terminal to refresh it.");
-    return flags.skillOnly ? EXIT_OK : EXIT_UPDATE_AVAILABLE;
-  }
-  if (!(await consent(what))) {
-    log("Skill left unchanged.");
-    return EXIT_OK;
-  }
-  const written = await writeSkill({ bundled, target, now: io.now });
-  log(`Skill ${status === "missing" ? "installed" : "updated"}: ${written.file}`);
-  if (written.backup) log(`Previous copy saved as: ${written.backup}`);
-  return EXIT_OK;
-}
+// `altalandi update` — check for a newer CLI, ask before installing it, then
+// offer to install or refresh the /altalandi skill for Claude Code.
+//
+// Nothing is ever changed without consent. Interactive terminals get a y/N
+// prompt; non-interactive callers (agents, CI, pipes) are only told what is
+// available, unless they pass --yes, which is itself the explicit consent.
+//
+// Zero dependencies, like the rest of the CLI.
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE = "altalandi";
+export const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE}/latest`;
+
+// Exit codes. 10 is deliberately distinct from the refine command's 1/2/3 so a
+// script can tell "an update exists" apart from "something failed".
+export const EXIT_OK = 0;
+export const EXIT_CHECK_FAILED = 1;
+export const EXIT_UPDATE_AVAILABLE = 10;
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const BUNDLED_SKILL = path.join(HERE, "skill", "SKILL.md");
+
+export async function currentVersion() {
+  const pkg = JSON.parse(await readFile(path.join(HERE, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+/** Semver-ish compare: -1 if a<b, 0 if equal, 1 if a>b. A prerelease sorts
+ *  before its release (0.2.0-beta < 0.2.0). */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ""] = String(v).trim().replace(/^v/, "").split("-", 2);
+    return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (x.nums[i] || 0) - (y.nums[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  if (x.pre === y.pre) return 0;
+  if (!x.pre) return 1;
+  if (!y.pre) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+export async function fetchLatestVersion({ fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`npm registry answered ${res.status}`);
+    const body = JSON.parse(await res.text());
+    if (!body || typeof body.version !== "string") throw new Error("npm registry returned no version");
+    return body.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const norm = (p) => {
+  let out = path.resolve(p);
+  try { out = realpathSync(out); } catch { /* keep the resolved path */ }
+  return process.platform === "win32" ? out.toLowerCase() : out;
+};
+
+/** How is this copy of the CLI being run? That decides what "update" means.
+ *
+ *  npx    — lives in npm's _npx cache; there is nothing to install, but a bare
+ *           `npx altalandi` can keep reusing an old cached copy
+ *  global — `npm install -g altalandi`
+ *  local  — a project dependency
+ *  source — a checkout of the repository; npm cannot update that
+ */
+export function detectInstall({ scriptPath, globalRoot }) {
+  const p = norm(scriptPath);
+  const sep = path.sep === "\\" ? /[\\/]/ : /\//;
+  const parts = p.split(sep);
+  if (parts.includes("_npx")) return "npx";
+  const nm = parts.lastIndexOf("node_modules");
+  if (nm === -1) return "source";
+  if (globalRoot && p.startsWith(norm(globalRoot) + (process.platform === "win32" ? "\\" : "/"))) {
+    return "global";
+  }
+  return "local";
+}
+
+/** The exact command that updates this install. Constants only — never built
+ *  from user input. */
+export function updatePlan(kind, { projectDir } = {}) {
+  switch (kind) {
+    case "global":
+      return { cmd: "npm", args: ["install", "-g", `${PACKAGE}@latest`], show: `npm install -g ${PACKAGE}@latest` };
+    case "local":
+      return { cmd: "npm", args: ["install", `${PACKAGE}@latest`], cwd: projectDir, show: `npm install ${PACKAGE}@latest` };
+    case "npx":
+      return { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "--version"], show: `npx ${PACKAGE}@latest` };
+    default:
+      return null;
+  }
+}
+
+/** Where Claude Code looks for personal skills. */
+export function skillTarget({ env = process.env, home = homedir() } = {}) {
+  const root = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+  return { root, file: path.join(root, "skills", PACKAGE, "SKILL.md") };
+}
+
+/** missing | current | outdated. `absent` means Claude Code itself is not set
+ *  up, in which case the skill is not offered at all — never create ~/.claude
+ *  for someone who does not use it. */
+export async function skillStatus({ bundled = BUNDLED_SKILL, target = skillTarget() } = {}) {
+  if (!existsSync(bundled)) return "unbundled";
+  if (!existsSync(target.root)) return "absent";
+  if (!existsSync(target.file)) return "missing";
+  const [a, b] = await Promise.all([readFile(bundled, "utf8"), readFile(target.file, "utf8")]);
+  const clean = (s) => s.replace(/\r\n/g, "\n").trim();
+  return clean(a) === clean(b) ? "current" : "outdated";
+}
+
+// Fingerprints (sha256 of the text with LF line ends, trimmed; first 16 hex)
+// of every SKILL.md a published version shipped. A skill that matches one is
+// ours, unedited, so it may be refreshed without asking; anything else was
+// changed by its owner and is only reported. Add the old fingerprint here in
+// every release that changes the skill.
+export const SHIPPED_SKILLS = new Set([
+  "1a64ea93bfae71cc", // 0.2.0
+  "51920af235d23f02", // 0.3.0, 0.3.1
+  "f7de208557f519a4", // 0.4.0
+  "4bd64565d251641e", // 0.5.0
+  "aeb88010599539fd", // 0.6.0
+  "ebfc4ef17a614973", // 0.6.1
+  "9def55ecc6b30785", // 0.6.2
+]);
+
+export function skillFingerprint(text) {
+  return createHash("sha256").update(text.replace(/\r\n/g, "\n").trim()).digest("hex").slice(0, 16);
+}
+
+/** On every ordinary run: the skill calls `npx altalandi@latest`, so this is
+ *  already the newest CLI. An installed skill that is an unedited older copy
+ *  of ours is brought up to date (backed up first), so people get the new
+ *  skill without doing anything; an edited one is left alone with a hint.
+ *  Never throws, never creates ~/.claude. ALTALANDI_NO_SKILL_REFRESH=1 opts out. */
+export async function refreshShippedSkill({ bundled = BUNDLED_SKILL, target = skillTarget(), env = process.env, log = () => {} } = {}) {
+  try {
+    if (env.ALTALANDI_NO_SKILL_REFRESH === "1") return "skipped";
+    const status = await skillStatus({ bundled, target });
+    if (status !== "outdated") return status;
+    if (!SHIPPED_SKILLS.has(skillFingerprint(await readFile(target.file, "utf8")))) {
+      log("Altalandi: your /altalandi skill has your own edits, so it was not updated. Run `npx altalandi@latest update` to refresh it.");
+      return "edited";
+    }
+    await writeSkill({ bundled, target });
+    log("Altalandi: the /altalandi skill was updated to the newest version (it applies from your next session).");
+    return "refreshed";
+  } catch {
+    return "failed";
+  }
+}
+
+/** Install or refresh the skill. An existing copy is always backed up first:
+ *  people edit their skills, and an update must never silently eat that. */
+export async function writeSkill({ bundled = BUNDLED_SKILL, target = skillTarget(), now = new Date() } = {}) {
+  await mkdir(path.dirname(target.file), { recursive: true });
+  let backup = null;
+  if (existsSync(target.file)) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    backup = `${target.file}.bak-${stamp}`;
+    await copyFile(target.file, backup);
+  }
+  await writeFile(target.file, await readFile(bundled, "utf8"), "utf8");
+  return { file: target.file, backup };
+}
+
+function run(plan) {
+  return new Promise((resolve) => {
+    // npm and npx are .cmd shims on Windows, which need a shell. The arguments
+    // are constants from updatePlan(), so there is nothing to inject.
+    const child = spawn(plan.cmd, plan.args, {
+      cwd: plan.cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => resolve(1));
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+function npmGlobalRoot() {
+  return new Promise((resolve) => {
+    const child = spawn("npm", ["root", "-g"], { shell: process.platform === "win32" });
+    let out = "";
+    child.stdout?.setEncoding("utf8").on("data", (c) => { out += c; });
+    child.on("error", () => resolve(null));
+    child.on("close", () => resolve(out.trim() || null));
+  });
+}
+
+/** A y/N question on stderr; only y/yes (or j/já) is a yes. Shared with the
+ *  folder and site runs, which ask before sending anything. */
+export async function ask(question, { input = process.stdin, output = process.stderr } = {}) {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+    return answer === "y" || answer === "yes" || answer === "j" || answer === "já";
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * The whole command. Every side effect is injectable so it can be tested
+ * without touching npm, the network or the real home directory.
+ */
+export async function runUpdate(flags, io = {}) {
+  const log = io.log || ((m) => process.stderr.write(`${m}\n`));
+  const interactive = io.interactive ?? Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  const confirm = io.confirm || ask;
+  const execute = io.run || run;
+  const target = io.skillTarget || skillTarget();
+  const bundled = io.bundledSkill || BUNDLED_SKILL;
+
+  // --check never changes anything. Without a terminal and without --yes there
+  // is nobody to ask, so the same rule applies: report, don't act.
+  const mayAct = !flags.check && (flags.yes || interactive);
+  const consent = async (q) => (flags.yes ? true : confirm(q));
+
+  const installed = io.currentVersion || await currentVersion();
+
+  if (!flags.skillOnly) {
+    let latest;
+    try {
+      latest = io.latestVersion || await fetchLatestVersion({ fetchImpl: io.fetch });
+    } catch (e) {
+      log(`Could not check for updates: ${e.message}`);
+      return EXIT_CHECK_FAILED;
+    }
+
+    if (compareVersions(installed, latest) < 0) {
+      const scriptPath = io.scriptPath || fileURLToPath(new URL("./altalandi.mjs", import.meta.url));
+      // `npm root -g` spawns npm, so only ask it when the answer matters: a copy
+      // inside some node_modules that is not npx's cache.
+      const inNodeModules = /[\\/]node_modules[\\/]/.test(scriptPath) && !/[\\/]_npx[\\/]/.test(scriptPath);
+      const globalRoot = io.globalRoot !== undefined ? io.globalRoot
+        : (inNodeModules ? await (io.npmGlobalRoot || npmGlobalRoot)() : null);
+      const kind = io.installKind || detectInstall({ scriptPath, globalRoot });
+      const plan = updatePlan(kind, { projectDir: io.projectDir || process.cwd() });
+      log(`A new version of ${PACKAGE} is available: ${installed} → ${latest}`);
+
+      if (!plan) {
+        log("This copy runs from a source checkout, so npm cannot update it. Pull the repository instead.");
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      if (!mayAct) {
+        log(`Update with:  ${plan.show}`);
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      if (!(await consent(`Update ${PACKAGE} to ${latest} now?`))) {
+        log(`Skipped. Update later with:  ${plan.show}`);
+        return EXIT_UPDATE_AVAILABLE;
+      }
+      log(`Running: ${plan.show}`);
+      const code = await execute(plan);
+      if (code !== 0) {
+        log(`Update failed (exit ${code}). Try running it yourself:  ${plan.show}`);
+        return EXIT_CHECK_FAILED;
+      }
+      log(`Updated to ${latest}.`);
+      // The skill that ships with the NEW version is the one worth installing,
+      // and this process is still the old one. Hand over to the new CLI.
+      const handoff = kind === "npx"
+        ? { cmd: "npx", args: ["--yes", `${PACKAGE}@latest`, "update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] }
+        : { cmd: PACKAGE, args: ["update", "--skill-only", ...(flags.yes ? ["--yes"] : [])] };
+      await execute(handoff);
+      return EXIT_OK;
+    }
+    log(`${PACKAGE} ${installed} is up to date.`);
+  }
+
+  const status = await skillStatus({ bundled, target });
+  if (status === "unbundled" || status === "absent") return EXIT_OK;
+  if (status === "current") {
+    log("The /altalandi skill for Claude Code is up to date.");
+    return EXIT_OK;
+  }
+  const what = status === "missing"
+    ? `Install the /altalandi skill for Claude Code (${target.file})?`
+    : "Your /altalandi skill for Claude Code differs from this version. Replace it (your copy is backed up first)?";
+  if (!mayAct) {
+    log(status === "missing"
+      ? "The /altalandi skill for Claude Code is not installed. Run `altalandi update` in a terminal to install it."
+      : "Your /altalandi skill for Claude Code is out of date. Run `altalandi update` in a terminal to refresh it.");
+    return flags.skillOnly ? EXIT_OK : EXIT_UPDATE_AVAILABLE;
+  }
+  if (!(await consent(what))) {
+    log("Skill left unchanged.");
+    return EXIT_OK;
+  }
+  const written = await writeSkill({ bundled, target, now: io.now });
+  log(`Skill ${status === "missing" ? "installed" : "updated"}: ${written.file}`);
+  if (written.backup) log(`Previous copy saved as: ${written.backup}`);
+  return EXIT_OK;
+}