@esneiderbravo/speclaw 2.0.0 → 2.0.1

package/README.md

@@ -332,14 +332,19 @@ review from Code Owners* when you declare `team.owners`.
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date
 
 speclaw checks for new releases in the background (at most once a day) and nudges
-you when one lands. To upgrade:
+you when one lands. To bring a project up to date (migrations only — never runs
+`npm install -g`):
 
 ```bash
 speclaw update
 ```
 
-`update` upgrades the global package **and** brings the current project up to date
-without a re-init, splitting files by who owns them:
+If a newer binary is on npm, `update` prints an advisory (`current → latest`) and
+how to upgrade the binary separately (`npm i -g @esneiderbravo/speclaw@latest`, or
+prefer `npx @esneiderbravo/speclaw@latest update`), then still migrates the project.
+
+`update` brings the current project up to date without a re-init, splitting files
+by who owns them:
 
 - **Managed files** (skills/commands/rules under `ai-specs/`) are **refreshed**.
   Pass `--backup` to keep a `<file>.bak` before overwrite.
@@ -348,7 +353,8 @@ without a re-init, splitting files by who owns them:
   prints a prompt for the agent you're using.
 - **`speclaw.lock`** and the CODEOWNERS owners block are refreshed when configured.
 
-- `speclaw update --check` — report whether an update exists, change nothing.
+- `speclaw update --check` — report version status only; do not migrate.
+- `speclaw update --migrate-only` — silent no-op alias of the default (compat).
 - `NO_UPDATE_NOTIFIER=1` — silence the reminder.
 
 <br/>

package/dist/cli/commands/init.js

@@ -45,7 +45,8 @@ export async function runInit(flags) {
     const upd = await checkForUpdates();
     if (upd.updateAvailable && upd.latest) {
         ui.warn(`You're on ${c.muted(upd.current)} — latest is ${c.bold(c.cyan(upd.latest))}.`);
-        ui.info(`Recommended: run ${ui.code("speclaw update")} first, then ${ui.code("speclaw init")} again.`);
+        ui.info(`Recommended: refresh the binary with ${ui.code("npx @esneiderbravo/speclaw@latest init")} ` +
+            `(or ${ui.code("npm i -g @esneiderbravo/speclaw@latest")}), then run ${ui.code("speclaw init")} again.`);
         ui.plain();
     }
     if (interactive) {

package/dist/cli/commands/update.js

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { ui, c } from "../lib/ui.js";
@@ -11,6 +10,17 @@ import { readManifest } from "../../shared/manifest.js";
 import { loadPacks } from "../../modules/tools/packs.js";
 import { detectProjectName } from "./init.js";
 import { reportTrackedLocalContent } from "../lib/untrack.js";
+/**
+ * How to upgrade the installed binary without this command spawning `npm install -g`.
+ *
+ * @param name - Package name on npm (usually `pkgName()`).
+ * @returns One-line advisory for the terminal.
+ */
+export function binaryUpgradeHint(name) {
+    return (`Upgrade the binary separately with ${ui.code(`npm i -g ${name}@latest`)} ` +
+        `(or prefer ${ui.code(`npx ${name}@latest update`)}). ` +
+        `This command only migrates the project.`);
+}
 // The first migration must be tagged at the version that introduces this
 // mechanism (0.1.12): `isNewer` is strict, so an entry tagged at an already-
 // shipped version (e.g. 0.1.11) would never fire for projects already on it.
@@ -196,70 +206,56 @@ const MIGRATIONS = [
             "`esneiderbravo/speclaw@v2`. See `docs/cortex.md`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.1",
+        describe: "speclaw update no longer upgrades the global npm package",
+        agentPrompt: "- `speclaw update` applies **project** migrations only — it does **not** run " +
+            "`npm install -g`. If a newer binary exists on npm it prints an advisory; " +
+            "upgrade the CLI separately (`npm i -g @esneiderbravo/speclaw@latest` or " +
+            "`npx @esneiderbravo/speclaw@latest update`). Prefer `npx @…@latest` when the " +
+            "installed binary is stale so migrations match the latest package.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
- * Update speclaw and bring the current project up to date without a full re-init:
- * upgrade the global package, then additively apply any new standards, skills,
- * commands, and feature steps this project is missing (existing files untouched).
+ * Bring the current project up to date without a full re-init: check whether a
+ * newer binary exists on npm (advisory only — never runs `npm install -g`), then
+ * additively apply any new standards, skills, commands, and feature steps this
+ * project is missing (existing files untouched).
  *
- * @param flags - `--check` reports without changing anything; `--migrate-only`
- *   skips the global upgrade and only applies project changes (used internally
- *   after the package is upgraded, so migrations run from the new version).
+ * @param flags - `--check` reports version status only (no migrate);
+ *   `--migrate-only` is a silent no-op alias of the default (compat).
+ * @param hooks - Optional test seams for the version check and migrate path.
  */
-export async function runUpdate(flags) {
+export async function runUpdate(flags, hooks = {}) {
     const cwd = process.cwd();
-    const migrateOnly = Boolean(flags["migrate-only"]);
+    // `--migrate-only` is accepted for compat but is a no-op alias of default
+    // (version check + project migrations). It no longer skips the version check.
     const checkOnly = Boolean(flags.check);
     const backup = Boolean(flags.backup);
-    const winShell = process.platform === "win32";
-    if (!migrateOnly) {
-        ui.step("Checking for updates");
-        const { current, latest, updateAvailable } = await checkForUpdates({ force: true });
-        if (!latest) {
-            ui.warn("Could not reach the npm registry — skipping the version check.");
-        }
-        else if (updateAvailable) {
-            ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
-            if (checkOnly) {
-                ui.info(`Run ${ui.code("speclaw update")} to upgrade and apply what's new.`);
-                return;
-            }
-            ui.step(`Updating ${pkgName()} globally`);
-            const install = spawnSync("npm", ["install", "-g", `${pkgName()}@latest`], {
-                stdio: "inherit",
-                shell: winShell,
-            });
-            if (install.status !== 0) {
-                ui.err("Global update failed. Try again with elevated permissions (e.g. sudo), or check your npm setup.");
-                process.exit(1);
-            }
-            ui.ok(`Updated to ${latest}`);
-            // Re-exec the NEWLY installed binary so migrations run with the new assets
-            // and any new feature steps — not this (now-stale) process. Carry --backup
-            // through so the refresh honors it after the upgrade.
-            const reArgs = [
-                "update",
-                "--migrate-only",
-                ...(backup ? ["--backup"] : []),
-                ...(flags.minimal ? ["--minimal"] : []),
-            ];
-            const re = spawnSync("speclaw", reArgs, {
-                stdio: "inherit",
-                shell: winShell,
-            });
-            if (re.error) {
-                ui.warn(`Upgraded — now run ${ui.code("speclaw update --migrate-only")} to apply project changes.`);
-                return;
-            }
-            process.exit(re.status ?? 0);
-        }
-        else {
-            ui.ok(`Already on the latest version (${current}).`);
-            if (checkOnly)
-                return;
+    const check = hooks.checkForUpdates ?? checkForUpdates;
+    const migrate = hooks.applyProjectMigrations ?? applyProjectMigrations;
+    ui.step("Checking for updates");
+    const { current, latest, updateAvailable } = await check({ force: true });
+    if (!latest) {
+        ui.warn("Could not reach the npm registry — skipping the version check.");
+    }
+    else if (updateAvailable) {
+        ui.info(`${c.muted(current)} ${c.muted("→")} ${c.cyan(latest)}`);
+        ui.info(binaryUpgradeHint(pkgName()));
+        if (checkOnly) {
+            ui.info(`Run ${ui.code("speclaw update")} to apply project migrations with the binary you have.`);
+            return;
         }
     }
-    applyProjectMigrations(cwd, backup, flags.minimal ? true : undefined);
+    else {
+        ui.ok(`Already on the latest version (${current}).`);
+        if (checkOnly)
+            return;
+    }
+    if (checkOnly)
+        return;
+    migrate(cwd, backup, flags.minimal ? true : undefined);
 }
 /**
  * Additively apply the current version's content and feature steps to a project.

package/dist/cli/index.js

@@ -12,8 +12,8 @@ Install globally so the command is always available:
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
                            (--minimal omits setup/lifecycle MCP tools)
-  update                   Upgrade speclaw and apply only what's new (no re-init)
-                           (--minimal persists minimal exposure; omit to keep prior)
+  update                   Apply project migrations (advisory if a newer binary exists)
+                           (--check reports version only; --minimal persists minimal exposure)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 

package/dist/cli/lib/update-check.js

@@ -102,15 +102,16 @@ export function npmPackageUrl(name) {
 /**
  * Build the two-line "update available" notice. The latest version is rendered
  * as a clickable link to the package's npm page, so a capable terminal lets the
- * user open the release with a single click while `speclaw update` remains the
- * command that performs the upgrade.
+ * user open the release with a single click. Project migrations stay
+ * `speclaw update`; the binary is upgraded separately (prefer npx).
  *
  * @param current - The installed version.
  * @param latest - The newest published version.
  * @returns The formatted, styled notice (no leading/trailing blank lines).
  */
 export function upgradeNotice(current, latest) {
-    const latestLink = c.cyan(link(latest, npmPackageUrl(pkgName())));
+    const name = pkgName();
+    const latestLink = c.cyan(link(latest, npmPackageUrl(name)));
     return ("  " +
         c.amber("⬆ speclaw ") +
         c.muted(current + " → ") +
@@ -118,9 +119,11 @@ export function upgradeNotice(current, latest) {
         c.muted(" available") +
         "\n" +
         "  " +
-        c.muted("run ") +
+        c.muted("prefer ") +
+        c.cyan(`npx ${name}@latest update`) +
+        c.muted(" — or ") +
         c.cyan("speclaw update") +
-        c.muted(" — upgrades and applies only what's new"));
+        c.muted(" to migrate this project"));
 }
 /**
  * Print the "update available" notice to stderr when a newer version exists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "publishConfig": {
     "access": "public"
   },