portable-agent-layer 0.112.0 → 0.113.0

package/README.md

@@ -77,7 +77,7 @@ pal cli status        # check your setup
 | `pal cli init` | Scaffold PAL home directory and install hooks |
 | `pal cli install` | Register hooks/skills for targets |
 | `pal cli uninstall` | Remove hooks/skills for targets |
-| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes |
+| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes. `--canary` installs the latest prerelease from the `canary` branch instead; auto-update always follows the stable release |
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -49,7 +49,7 @@ const tree = cliTree({
     process.exit(await install(resolveTargets(argv), argv));
   },
   uninstall: ({ argv }) => uninstall(argv),
-  update: () => update(),
+  update: ({ values }) => update(values.canary === true),
   export: ({ argv }) => exportState(argv),
   import: ({ argv }) => importState(argv),
   status: () => status(),
@@ -553,15 +553,23 @@ async function importState(args: string[]) {
   log.info("Run 'pal cli install' to re-register hooks.");
 }
 
-async function update() {
-  const { checkForUpdate, clearUpdateCache } = await import(
+async function update(canary: boolean) {
+  const { checkCanary, checkForUpdate, clearUpdateCache, isRepoMode } = await import(
     "../hooks/handlers/update-check"
   );
   const { reinstallInFreshProcess } = await import("./reinstall");
-  const { runUpdate } = await import("./update-flow");
+  const { CANARY_NEEDS_PACKAGE, runUpdate, updateCheck } = await import("./update-flow");
+  const check = updateCheck(canary, isRepoMode(), {
+    stable: () => checkForUpdate(true),
+    canary: checkCanary,
+  });
+  if (!check) {
+    log.error(CANARY_NEEDS_PACKAGE);
+    process.exit(1);
+  }
   process.exit(
     await runUpdate({
-      check: () => checkForUpdate(true),
+      check,
       reinstall: (env) => {
         clearUpdateCache();
         return reinstallInFreshProcess(process.argv[1], env);

package/src/cli/tree.ts

@@ -109,7 +109,17 @@ function adminCommands(admin: AdminHandlers): Record<string, Leaf | Group> {
       options: agentOptions("Uninstall from"),
       run: admin.uninstall,
     }),
-    update: leaf({ summary: "Update PAL (git pull or bun add -g)", run: admin.update }),
+    update: leaf({
+      summary: "Update PAL (git pull or bun add -g)",
+      options: {
+        canary: {
+          type: "boolean",
+          description:
+            "Install the latest canary prerelease instead of the stable release",
+        },
+      },
+      run: admin.update,
+    }),
     export: leaf({
       summary: "Export your state to a zip",
       args: "[path]",

package/src/cli/update-flow.ts

@@ -33,6 +33,21 @@ export interface UpdateSteps {
   run?: Run;
 }
 
+export const CANARY_NEEDS_PACKAGE =
+  "--canary installs from npm. A repo install follows its git checkout: check out the canary branch there instead.";
+
+type Check = UpdateSteps["check"];
+
+/** Null when --canary is asked of a repo install, which has no npm channel to follow. */
+export function updateCheck(
+  canary: boolean,
+  repoMode: boolean,
+  checks: { stable: Check; canary: Check }
+): Check | null {
+  if (!canary) return checks.stable;
+  return repoMode ? null : checks.canary;
+}
+
 /** `bun update -g` keeps the caret range, and on 0.x a caret allows only patch bumps. */
 export function downloadCommand(
   update: UpdateCache

package/src/cli/whats-new.ts

@@ -15,16 +15,22 @@ export interface WhatsNew {
 
 const SHOWN = 3;
 
-function parts(version: string): number[] {
-  return version.replace(/^v/, "").split(".").map(Number);
+function bare(version: string): string {
+  return version.replace(/^v/, "");
 }
 
 export function newer(a: string, b: string): boolean {
-  const [x, y] = [parts(a), parts(b)];
-  for (let i = 0; i < 3; i++) {
-    if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
-  }
-  return false;
+  return Bun.semver.order(bare(a), bare(b)) === 1;
+}
+
+function isPrerelease(version: string): boolean {
+  return bare(version).includes("-");
+}
+
+/** A stable release's notes already cover the canaries before it, so a stable update skips them. */
+function inRange(tag: string, from: string, to: string): boolean {
+  if (isPrerelease(tag) && !isPrerelease(to)) return false;
+  return newer(tag, from) && !newer(tag, to);
 }
 
 /** "* **rating:** confirm corrections ([abc](url))" reads "Confirm corrections". */
@@ -71,7 +77,7 @@ export function summarizeReleases(
   slug: string
 ): WhatsNew | null {
   const items = releases
-    .filter((r) => newer(r.tag_name, from) && !newer(r.tag_name, to))
+    .filter((r) => inRange(r.tag_name, from, to))
     .flatMap((r) => releaseNotes(r.body ?? ""));
   if (items.length === 0) return null;
   return {

package/src/hooks/handlers/update-check.ts

@@ -139,12 +139,18 @@ export function isNewerRelease(latest: string, current: string): boolean {
   return Bun.semver.order(latest, current) === 1;
 }
 
-async function checkNpm(): Promise<UpdateCache> {
+/** latest is the stable release from main; canary is the prerelease from the canary branch. */
+export type Channel = "latest" | "canary";
+
+export async function checkNpm(
+  channel: Channel = "latest",
+  fetchImpl: typeof fetch = fetch
+): Promise<UpdateCache> {
   const current = getInstalledVersion();
 
   try {
-    const response = await fetch(
-      "https://registry.npmjs.org/portable-agent-layer/latest",
+    const response = await fetchImpl(
+      `https://registry.npmjs.org/portable-agent-layer/${channel}`,
       { signal: AbortSignal.timeout(5000) }
     );
 
@@ -170,6 +176,11 @@ async function checkNpm(): Promise<UpdateCache> {
   }
 }
 
+/** The canary check is never cached: the cache feeds the stable update notice. */
+export function checkCanary(fetchImpl: typeof fetch = fetch): Promise<UpdateCache> {
+  return checkNpm("canary", fetchImpl);
+}
+
 /** Run update check. Caches result. Use force=true to skip cache (e.g. for `pal cli update`). */
 export async function checkForUpdate(force = false): Promise<UpdateCache> {
   if (!force) {