canon-ai 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-09-05
+
+### Changed
+
+- **`canon update` installs stable releases from the npm registry.** It resolves the latest release tag on GitHub as before, confirms that version is published to npm, then installs `canon-ai@<version>` from the registry; a project-local install is pinned to the exact version. A tagged release that has not reached npm yet refuses with a retry note and the `--ref v<version>` GitHub fallback. `--channel main`, `--ref`, and `CANON_UPSTREAM_REPO` fork overrides still install from GitHub, since those builds are not on the registry.
+
+### Removed
+
+- **No install scripts in the published package.** The `postinstall` hook installer only ever set up canon-ai's own contributor pre-commit hook and did nothing in adopter repos, but it triggered npm's install-scripts warning on every install. Contributors run `npm run hooks` once after cloning instead.
+
 ## [3.0.0] — 2026-09-04
 
 ### Changed

package/README.md

@@ -98,7 +98,7 @@ npm install -g --install-links github:tstraub89/canon-ai
 
 > When installing from GitHub, `--install-links` is required because npm otherwise symlinks the global install to its git cache rather than copying the committed `dist/`, which leaves the `canon` bin pointing at a transient path and command-not-found after the install reports success. The flag packs+installs as a regular dependency, which is what you want for a stable global CLI.
 
-> **Updating.** Once installed, use `canon update` rather than re-running `npm install` by hand — it resolves the exact install this binary is running from, pins to the latest tagged release by default (or a labeled development commit via `--channel main` / `--ref <ref|sha>`), and records what it installed in `provenance.json` under `.canon` for future tooling to read.
+> **Updating.** Once installed, use `canon update` rather than re-running `npm install` by hand — it resolves the exact install this binary is running from and installs the latest release from the npm registry by default. Use `--channel main` or `--ref <ref|sha>` for a GitHub development commit; each update records what it installed in `provenance.json` under `.canon` for future tooling to read. A project-local update pins the exact version (`--save-exact`); a global update has no manifest to pin.
 
 ### Set up in a repo
 
@@ -254,7 +254,7 @@ Run canon on repositories where you would be comfortable running your test suite
 | `canon run <id> --dry-run` | Print each planned phase and exit without spawning any agent |
 | `canon stop <id>` | Stop a detached canon run (SIGTERM → SIGKILL after 10s). Waits up to 30s — override via `CANON_STOP_WAIT_MS` — for the orchestrator's first heartbeat to verify the PID before signaling. |
 | `canon upgrade` | Sync vendored canon-owned files to match the installed version. It does not touch adopter-owned `AGENTS.md` or `CLAUDE.md`. Refuses to overwrite canon-owned targets that are locally modified, untracked but present, or whose git state cannot be verified unless `--force` is set. Use `--check` (or `--dry-run`) to preview, `--no-stage` to skip the auto-`git add`. |
-| `canon update` | Update the canon-ai package itself. Targets the install's own root (never the invocation directory) and pins to the latest final release by default; refuses rather than installing an unpinned branch. `--channel main` / `--ref <ref\|sha>` pin a labeled development commit instead. Writes `provenance.json` in `.canon` after a successful install — recorded for future tooling, nothing reads it yet. |
+| `canon update` | Update the canon-ai package itself. Targets the install's own root (never the invocation directory) and installs the latest final release from npm by default. `--channel main` / `--ref <ref\|sha>` install a pinned GitHub development commit instead. Writes `provenance.json` in `.canon` after a successful install — recorded for future tooling, nothing reads it yet. |
 
 Full `canon task` subcommand reference is in `docs/pipeline-orchestrator.md`.
 

package/dist/cli/index.js

@@ -1245,7 +1245,7 @@ function checkTemplates(cwd) {
 }
 function checkCanonVersion(cwd) {
   const versionPath = join(cwd, ".canon", "version");
-  const installedVersion = "3.0.0";
+  const installedVersion = "3.1.0";
   if (!existsSync(versionPath)) {
     return { label: ".canon/version", status: "warn", detail: "missing \u2014 run `canon upgrade`" };
   }
@@ -1715,7 +1715,7 @@ function initCmd(_args) {
 }
 function writeCanonVersion(cwd) {
   const versionPath = join2(cwd, ".canon", "version");
-  const version = "3.0.0";
+  const version = "3.1.0";
   mkdirSync(dirname2(versionPath), { recursive: true });
   writeFileSync(versionPath, version + "\n");
 }
@@ -2709,7 +2709,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.0.0" ?? "dev";
+  return explicit ?? "3.1.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);
@@ -4628,7 +4628,6 @@ function defaultGitRunner(args2) {
 var CANON_AI_DEP_KEYS = ["dependencies", "devDependencies", "optionalDependencies"];
 var STRICT_FINAL_TAG_RE = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 var FULL_SHA_RE = /^[0-9a-f]{40}$/i;
-var CANONICAL_NPX_SOURCE = "github:tstraub89/canon-ai";
 function layoutGate(installRoot) {
   if (!existsSync4(join4(installRoot, "package.json"))) {
     return {
@@ -4775,10 +4774,6 @@ function resolveNamedRef(slug, refspec, runGit2) {
   }
   return { ok: true, sha: [...distinctShas][0] };
 }
-function resolveEffectiveSlug() {
-  const envSlug = process.env.CANON_UPSTREAM_REPO?.trim();
-  return envSlug ? envSlug : CANON_UPSTREAM_REPO;
-}
 function currentPinFromManifest(manifest) {
   for (const key of CANON_AI_DEP_KEYS) {
     const block = manifest[key];
@@ -4787,11 +4782,50 @@ function currentPinFromManifest(manifest) {
     if (typeof value !== "string") continue;
     const match = /#([0-9a-f]{40})$/i.exec(value.trim());
     if (match) return match[1].toLowerCase();
+    const versionMatch = /^[~^]?((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?)$/.exec(value.trim());
+    if (versionMatch) return versionMatch[1];
   }
   return "unknown";
 }
 function bakedVersion() {
-  return "3.0.0";
+  return "3.1.0";
+}
+function ownPackageName(pkgDir) {
+  try {
+    const manifest = JSON.parse(readFileSync3(join4(pkgDir, "package.json"), "utf8"));
+    return typeof manifest.name === "string" && manifest.name ? manifest.name : "canon-ai";
+  } catch {
+    return "canon-ai";
+  }
+}
+var NPM_VIEW_TIMEOUT_MS = 3e4;
+function defaultNpmViewRunner(args2, cwd) {
+  const result = spawnSync8("npm", args2, { encoding: "utf8", timeout: NPM_VIEW_TIMEOUT_MS, ...cwd ? { cwd } : {} });
+  if (result.error) return { status: null, stdout: "", stderr: result.error.message };
+  return { status: result.status, stdout: result.stdout ?? "", stderr: (result.stderr ?? "").trim() };
+}
+function checkRegistryVersion(pkgName, version, runner, cwd, global = false) {
+  const args2 = global ? ["view", "--global", `${pkgName}@${version}`, "version", "--json"] : ["view", `${pkgName}@${version}`, "version", "--json"];
+  const result = runner(args2, cwd);
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    parsed = void 0;
+  }
+  if (result.status === 0 && typeof parsed === "string" && parsed === version) return { ok: true };
+  if (typeof parsed === "object" && parsed !== null && parsed.error?.code === "E404") {
+    return {
+      ok: false,
+      absent: true,
+      message: `canon update: ${pkgName}@${version} is not yet on the npm registry. This release exists on GitHub but has not reached npm yet \u2014 retry shortly, or install it directly with \`canon update --ref v${version}\`.`
+    };
+  }
+  return {
+    ok: false,
+    absent: false,
+    message: `canon update: could not verify ${pkgName}@${version} on the npm registry (${result.stderr || "no output"}). Aborting \u2014 no npm install run.`
+  };
 }
 function formatAnnouncement(input) {
   const where = input.installType === "local" ? `local install at ${input.installRoot}` : "global install";
@@ -4819,6 +4853,7 @@ function updateCmd(args2, deps = {}) {
     console.error(message);
   });
   const pkgDir = deps.packageDir ?? packageDir3;
+  const pkgName = ownPackageName(pkgDir);
   const cwd = deps.cwd ?? process.cwd();
   const spawn2 = deps.spawnRunner ?? ((cmd, cmdArgs, opts) => spawnSync8(cmd, cmdArgs, { stdio: "inherit", cwd: opts.cwd }));
   const runGit2 = deps.gitRunner ?? defaultGitRunner;
@@ -4834,7 +4869,7 @@ function updateCmd(args2, deps = {}) {
   if (detection.type === "npx") {
     stdout("\nRunning via npx \u2014 no persistent install to update.");
     stdout("To apply the latest templates, re-run from the latest source:\n");
-    stdout(`  npx --install-links ${CANONICAL_NPX_SOURCE} upgrade
+    stdout(`  npx ${pkgName}@latest upgrade
 `);
     return;
   }
@@ -4855,7 +4890,10 @@ function updateCmd(args2, deps = {}) {
     manifest = dependency.manifest;
     dependencyBlock = dependency.dependencyBlock;
   }
-  const slug = resolveEffectiveSlug();
+  const upstreamOverride = process.env.CANON_UPSTREAM_REPO?.trim();
+  const slug = upstreamOverride ? upstreamOverride : CANON_UPSTREAM_REPO;
+  const usesRegistry = options.channel !== "main" && !options.ref && !upstreamOverride;
+  const npmView = deps.npmViewRunner ?? defaultNpmViewRunner;
   let channel;
   let resolvedSha;
   let stableVersion;
@@ -4888,7 +4926,15 @@ function updateCmd(args2, deps = {}) {
     resolvedSha = result.sha;
     stableVersion = result.version;
   }
-  const target = `github:${slug}#${resolvedSha}`;
+  if (usesRegistry) {
+    const registryCwd = detection.type === "local" ? detection.installRoot : cwd;
+    const registryCheck = checkRegistryVersion(pkgName, stableVersion, npmView, registryCwd, detection.type !== "local");
+    if (!registryCheck.ok) {
+      stderr(registryCheck.message);
+      return exit(1);
+    }
+  }
+  const target = usesRegistry ? `${pkgName}@${stableVersion}` : `github:${slug}#${resolvedSha}`;
   const currentSha = manifest ? currentPinFromManifest(manifest) : "unknown";
   stdout(formatAnnouncement({
     installType: detection.type,
@@ -4909,7 +4955,8 @@ function updateCmd(args2, deps = {}) {
   if (detection.type === "local") {
     const installRoot = detection.installRoot;
     const saveFlag = dependencyBlock === "dependencies" ? "--save" : dependencyBlock === "optionalDependencies" ? "--save-optional" : "--save-dev";
-    const result = spawn2("npm", ["install", saveFlag, "--install-links", target], { cwd: installRoot });
+    const installArgs = usesRegistry ? ["install", saveFlag, "--save-exact", target] : ["install", saveFlag, "--install-links", target];
+    const result = spawn2("npm", installArgs, { cwd: installRoot });
     if (result.status !== 0) return exit(result.status ?? 1);
     try {
       writeProvenance(installRoot, provenance);
@@ -4918,7 +4965,8 @@ function updateCmd(args2, deps = {}) {
       stderr(`canon update: npm install succeeded, but provenance could not be recorded at ${join4(installRoot, ".canon", "provenance.json")}${detail}.`);
     }
   } else {
-    const result = spawn2("npm", ["install", "-g", "--install-links", target], { cwd });
+    const installArgs = usesRegistry ? ["install", "-g", target] : ["install", "-g", "--install-links", target];
+    const result = spawn2("npm", installArgs, { cwd });
     if (result.status !== 0) return exit(result.status ?? 1);
     if (existsSync4(join4(cwd, ".canon"))) {
       try {
@@ -5206,7 +5254,7 @@ function runUpgrade(cwd, pkgDir, options = {}) {
     cutoverWarnings.push(docsRefsCheckRel);
   }
   const versionPath = join5(cwd, ".canon", "version");
-  const newVersion = "3.0.0";
+  const newVersion = "3.1.0";
   const currentVersion = existsSync5(versionPath) ? readFileSync4(versionPath, "utf8").trim() : null;
   if (currentVersion !== newVersion) {
     pending.push({ rel: ".canon/version", projectPath: versionPath, content: newVersion + "\n" });
@@ -5513,7 +5561,7 @@ Global:
 `);
 }
 function printVersion() {
-  console.log("3.0.0");
+  console.log("3.1.0");
 }
 switch (command) {
   case "doctor":

package/dist/orchestrator/run-task.js

@@ -4880,7 +4880,7 @@ function isInstalledSourcePath(sourcePath) {
   return sourcePath.includes("/node_modules/") || sourcePath.includes("\\node_modules\\") || sourcePath.includes("/_npx/") || sourcePath.includes("\\_npx\\");
 }
 function resolveCanonVersion(explicit) {
-  return explicit ?? "3.0.0" ?? "dev";
+  return explicit ?? "3.1.0" ?? "dev";
 }
 function resolveOrchestratorCommit(repoRoot, upstreamCommit, runGitAt) {
   const ownToplevel = captureGitOutput(repoRoot, ["rev-parse", "--show-toplevel"], runGitAt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canon-ai",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "A spec-first, multi-agent coding pipeline you drop into any repo. The law your agents work under.",
   "engines": {
@@ -12,13 +12,12 @@
   "files": [
     "dist/",
     "templates/",
-    "scripts/install-git-hooks.mjs",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsup",
     "postbuild": "node scripts/normalize-dist-paths.mjs",
-    "postinstall": "node scripts/install-git-hooks.mjs",
+    "hooks": "node scripts/install-git-hooks.mjs",
     "test": "node --test --import ./tests/md-loader-register.mjs --import tsx tests/*.test.ts",
     "sync-templates": "tsx scripts/sync-canon-templates.mjs",
     "sync-templates:check": "tsx scripts/sync-canon-templates.mjs --check",

package/scripts/install-git-hooks.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-/**
- * install-git-hooks.mjs
- *
- * Postinstall wrapper around `simple-git-hooks` that handles environments
- * where the bare CLI would fail.
- *
- * Skip cases (silent exit 0 — install proceeds, no hooks installed):
- *
- *   1. **No `.git/` at all.** Adopters consuming canon-ai as a dependency
- *      (`npm install canon-ai` in their project, or `npm install -g
- *      canon-ai`) have no `.git/` at this script's cwd (which is canon-ai's
- *      install dir under `node_modules/canon-ai/`). Adopters should never
- *      have canon-ai-dev's pre-commit hook installed.
- *
- *   2. **`simple-git-hooks` binary not installed.** Global install
- *      (`npm install -g canon-ai`) strips devDependencies; the bare CLI
- *      would emit "command not found" (exit 127) and tank the install.
- *
- *   3. **`.git` is a file (git worktree).** simple-git-hooks's `_setHook`
- *      uses `path.join(projectRoot, '.git', 'hooks')` unconditionally
- *      (see `node_modules/simple-git-hooks/simple-git-hooks.js:177-198`)
- *      and fails with ENOTDIR on the worktree's `.git` file. Skip
- *      silently here — running the CLI would tank the install.
- *
- * Known limitation of skip case 3: a developer who only ever `npm install`s
- * in a worktree (and never in the main checkout) ends up with a clean
- * install but no pre-commit hook in the shared gitdir. Mitigation: canon
- * dev workflow includes running `npm install` in the main checkout at
- * least once; once the hook is in `<main>/.git/hooks/pre-commit`, every
- * worktree inherits it via git's hook resolution. A more aggressive fix
- * (writing the worktree's hook to the shared gitdir directly) was rejected
- * because it would break commits in main pre-merge of any task that adds
- * a new hook command — `<main>/.git/hooks/pre-commit` would call a script
- * that doesn't exist in main's `package.json` yet.
- *
- * Lives in `scripts/` (not in `CANON_OWNED`) — ships in the npm tarball
- * via the `files` glob but isn't installed into adopter repos.
- */
-
-import { existsSync, statSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-
-const cwd = process.cwd();
-const gitPath = path.join(cwd, '.git');
-
-// Skip case 1: no `.git/` at all — adopter / global install.
-if (!existsSync(gitPath)) process.exit(0);
-
-// Skip case 2: simple-git-hooks not installed (devDeps stripped).
-const binPath = path.join(cwd, 'node_modules', '.bin', 'simple-git-hooks');
-if (!existsSync(binPath)) process.exit(0);
-
-// Skip case 3: worktree (`.git` is a file). simple-git-hooks would
-// fail with ENOTDIR. See the docstring above for the known limitation.
-if (!statSync(gitPath).isDirectory()) process.exit(0);
-
-// Main checkout: delegate to simple-git-hooks CLI.
-// `status === null` when the child couldn't be spawned or was killed by
-// a signal — treat as failure so npm doesn't silently report success on
-// a broken hook install. (Previously `?? 0` masked this — Codex P3 on
-// canon-docs-dedup PR #102.)
-const result = spawnSync(binPath, [], { cwd, stdio: 'inherit' });
-process.exit(result.status === null ? 1 : result.status);