portable-agent-layer 0.6.2 → 0.8.0

package/README.md

@@ -77,6 +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 |
 | `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.6.2",
+  "version": "0.8.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -10,6 +10,7 @@
  *   init                              Scaffold PAL home, install hooks for all targets
  *   install [--claude] [--opencode]   Register hooks/skills for targets
  *   uninstall [--claude] [--opencode] Remove hooks/skills for targets
+ *   update                             Update PAL (git pull or npm update)
  *   export [path] [--dry-run]         Export user state to zip
  *   import [path] [--dry-run]         Import user state from zip
  *   status                            Show current PAL configuration
@@ -122,6 +123,18 @@ async function session(sessionArgs: string[]) {
     // Silently ignore summary errors
   }
 
+  // Check for updates and display notice
+  try {
+    const { checkForUpdate, getUpdateNotice } = await import(
+      "../hooks/handlers/update-check"
+    );
+    await checkForUpdate();
+    const notice = getUpdateNotice();
+    if (notice) console.log(`\n${notice}`);
+  } catch {
+    // Non-critical
+  }
+
   process.exit(exitCode);
 }
 
@@ -145,6 +158,9 @@ async function runCli(command: string | undefined, args: string[]) {
     case "import":
       await importState(args);
       break;
+    case "update":
+      await update();
+      break;
     case "status":
       await status();
       break;
@@ -184,6 +200,7 @@ function showHelp() {
     pal cli init [--claude] [--opencode]    Scaffold and install (default: all)
     pal cli install [--claude] [--opencode] Register hooks for targets
     pal cli uninstall [--claude] [--opencode] Remove hooks for targets
+    pal cli update                          Update PAL (git pull or npm update)
     pal cli export [path] [--dry-run]       Export state to zip
     pal cli import [path] [--dry-run]       Import state from zip
     pal cli status                          Show PAL configuration
@@ -562,6 +579,45 @@ async function importState(args: string[]) {
   }
 }
 
+async function update() {
+  const { checkForUpdate } = await import("../hooks/handlers/update-check");
+  const result = await checkForUpdate(true);
+
+  log.info(`Current: ${result.current} (${result.mode} mode)`);
+
+  if (!result.available) {
+    log.success("Already up to date.");
+    return;
+  }
+
+  log.info(`Available: ${result.latest}`);
+
+  const pkg = palPkg();
+  if (result.mode === "repo") {
+    log.info("Pulling updates...");
+    const pull = spawnSync("git", ["pull", "--ff-only"], { cwd: pkg, stdio: "inherit" });
+    if (pull.status !== 0) {
+      log.error("git pull failed. You may have local changes — try pulling manually.");
+      process.exit(1);
+    }
+  } else {
+    log.info("Updating via npm...");
+    const up = spawnSync("bun", ["update", "-g", "portable-agent-layer"], {
+      stdio: "inherit",
+    });
+    if (up.status !== 0) {
+      log.error("Update failed. Try: bun update -g portable-agent-layer");
+      process.exit(1);
+    }
+  }
+
+  const newPkg = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8"));
+  log.success(`Updated: ${result.current} → ${newPkg.version}`);
+
+  log.info("Reinstalling...");
+  await install(resolveTargets([]));
+}
+
 async function status() {
   const home = palHome();
   const pkg = palPkg();

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

@@ -0,0 +1,193 @@
+/**
+ * Update checker — detects if a newer version of PAL is available.
+ *
+ * Repo mode (.palroot exists): git fetch + compare HEAD vs origin/main
+ * Package mode: fetch npm registry for latest version vs installed
+ *
+ * Caches result in state/update-available.json. Checked at most once per hour.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug } from "../lib/log";
+import { ensureDir, palPkg, paths } from "../lib/paths";
+
+interface UpdateCache {
+  checkedAt: string;
+  available: boolean;
+  current: string;
+  latest: string;
+  mode: "repo" | "package";
+}
+
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+function cachePath(): string {
+  return resolve(ensureDir(paths.state()), "update-available.json");
+}
+
+function readCache(): UpdateCache | null {
+  try {
+    const fp = cachePath();
+    if (!existsSync(fp)) return null;
+    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
+    if (Date.now() - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS) return cache;
+    return null; // expired
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cache: UpdateCache): void {
+  try {
+    writeFileSync(cachePath(), JSON.stringify(cache, null, 2), "utf-8");
+  } catch {
+    /* non-critical */
+  }
+}
+
+function isRepoMode(): boolean {
+  return existsSync(resolve(palPkg(), ".palroot"));
+}
+
+function getInstalledVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(palPkg(), "package.json"), "utf-8"));
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+async function checkRepo(): Promise<UpdateCache> {
+  const repoDir = palPkg();
+  const current = getInstalledVersion();
+
+  try {
+    const fetch = Bun.spawn(["git", "fetch", "--quiet"], {
+      cwd: repoDir,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    await fetch.exited;
+
+    const local = Bun.spawn(["git", "rev-parse", "HEAD"], {
+      cwd: repoDir,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const localHash = (await new Response(local.stdout).text()).trim();
+
+    const remote = Bun.spawn(["git", "rev-parse", "origin/main"], {
+      cwd: repoDir,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const remoteHash = (await new Response(remote.stdout).text()).trim();
+
+    const available = localHash !== remoteHash && remoteHash.length > 0;
+
+    // Get remote version from package.json on origin/main
+    let latest = current;
+    if (available) {
+      try {
+        const show = Bun.spawn(["git", "show", "origin/main:package.json"], {
+          cwd: repoDir,
+          stdout: "pipe",
+          stderr: "ignore",
+        });
+        const remotePkg = JSON.parse(await new Response(show.stdout).text());
+        latest = remotePkg.version || current;
+      } catch {
+        latest = `${remoteHash.slice(0, 7)} (ahead)`;
+      }
+    }
+
+    return {
+      checkedAt: new Date().toISOString(),
+      available,
+      current,
+      latest,
+      mode: "repo",
+    };
+  } catch {
+    return {
+      checkedAt: new Date().toISOString(),
+      available: false,
+      current,
+      latest: current,
+      mode: "repo",
+    };
+  }
+}
+
+async function checkNpm(): Promise<UpdateCache> {
+  const current = getInstalledVersion();
+
+  try {
+    const response = await fetch(
+      "https://registry.npmjs.org/portable-agent-layer/latest",
+      { signal: AbortSignal.timeout(5000) }
+    );
+
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const data = (await response.json()) as { version?: string };
+    const latest = data.version || current;
+
+    return {
+      checkedAt: new Date().toISOString(),
+      available: latest !== current,
+      current,
+      latest,
+      mode: "package",
+    };
+  } catch {
+    return {
+      checkedAt: new Date().toISOString(),
+      available: false,
+      current,
+      latest: current,
+      mode: "package",
+    };
+  }
+}
+
+/** 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) {
+    const cached = readCache();
+    if (cached) {
+      logDebug("update-check", "Using cached result");
+      return cached;
+    }
+  }
+
+  const result = isRepoMode() ? await checkRepo() : await checkNpm();
+  writeCache(result);
+
+  if (result.available) {
+    logDebug(
+      "update-check",
+      `Update available: ${result.current} → ${result.latest} (${result.mode})`
+    );
+  }
+
+  return result;
+}
+
+/** Read cached update status for greeting display. Returns null if no update. */
+export function getUpdateNotice(): string | null {
+  try {
+    const fp = cachePath();
+    if (!existsSync(fp)) return null;
+    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
+    if (!cache.available) return null;
+
+    if (cache.mode === "repo") {
+      return `📦 Update available: ${cache.current} → ${cache.latest} (git pull)`;
+    }
+    return `📦 Update available: ${cache.current} → ${cache.latest} (bun update -g portable-agent-layer)`;
+  } catch {
+    return null;
+  }
+}

package/src/hooks/lib/security.ts

@@ -30,6 +30,7 @@ export const HOOK_MANAGED_FILES = [
   "pending-failure.json",
   "token-usage.jsonl",
   "graduated.json",
+  "update-available.json",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */