portable-agent-layer 0.85.15 → 0.85.16

package/package.json

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

package/src/cli/index.ts

@@ -524,6 +524,9 @@ async function install(targets: Targets, args: string[]): Promise<number> {
     log.warn("bun install failed — continuing anyway, but hooks may not work");
   }
 
+  const { applyPendingMigrations } = await import("./migrate");
+  for (const line of applyPendingMigrations()) log.info(line);
+
   // Uses `bun x` (not `bunx`) for Windows compatibility — bunx resolves unreliably under cmd.exe.
   if (process.env.PAL_SKIP_BROWSER_INSTALL !== "1") installChromium();
 

package/src/cli/leftovers.ts

@@ -0,0 +1,118 @@
+import { existsSync, lstatSync, readlinkSync, renameSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths, platform } from "../hooks/lib/paths";
+import { readJson, writeJson } from "../targets/lib";
+
+/** Something an older PAL wrote that the current one neither writes nor reads. */
+export interface Leftover {
+  id: string;
+  description: string;
+  find(): string[];
+  remove(): void;
+}
+
+type Json = Record<string, unknown>;
+
+const claudeSettings = () => resolve(platform.claudeDir(), "settings.json");
+const palSettings = () => resolve(paths.memory(), "pal-settings.json");
+
+function isPathScopedFileToolRule(rule: string): boolean {
+  return /^(?:Grep|Glob)\(/.test(rule);
+}
+
+function claudeAllowRules(): string[] {
+  const settings = readJson<Json>(claudeSettings(), {});
+  const allow = (settings.permissions as { allow?: unknown } | undefined)?.allow;
+  return Array.isArray(allow)
+    ? allow.filter((r): r is string => typeof r === "string")
+    : [];
+}
+
+const claudeFileToolRules: Leftover = {
+  id: "claude-file-tool-rules",
+  description:
+    "Remove Grep()/Glob() allow rules older templates wrote — Claude Code ignores them and warns on every prompt",
+  find: () => claudeAllowRules().filter(isPathScopedFileToolRule),
+  remove() {
+    const settings = readJson<Json>(claudeSettings(), {});
+    const permissions = settings.permissions as { allow: string[] };
+    permissions.allow = permissions.allow.filter(
+      (rule) => !isPathScopedFileToolRule(rule)
+    );
+    writeJson(claudeSettings(), settings);
+  },
+};
+
+function startupFiles(): string[] {
+  const settings = readJson<Json>(palSettings(), {});
+  const files = (settings.loadAtStartup as { files?: unknown } | undefined)?.files;
+  return Array.isArray(files)
+    ? files.filter((f): f is string => typeof f === "string")
+    : [];
+}
+
+const isProjectsFile = (file: string) => file.endsWith("PROJECTS.md");
+
+const startupProjectsFile: Leftover = {
+  id: "startup-projects-md",
+  description:
+    "Stop loading PROJECTS.md at startup — projects moved to the project store",
+  find: () => startupFiles().filter(isProjectsFile),
+  remove() {
+    const settings = readJson<Json>(palSettings(), {});
+    const startup = settings.loadAtStartup as { files: string[] };
+    startup.files = startup.files.filter((file) => !isProjectsFile(file));
+    writeJson(palSettings(), settings);
+  },
+};
+
+const oldOpencodePlugin = () =>
+  resolve(platform.opencodeDir(), "plugins", "pai-plugin.ts");
+
+const opencodePluginOldName: Leftover = {
+  id: "opencode-pai-plugin",
+  description: "Remove the opencode plugin under its old name, pai-plugin.ts",
+  find: () => (existsSync(oldOpencodePlugin()) ? [oldOpencodePlugin()] : []),
+  remove: () => unlinkSync(oldOpencodePlugin()),
+};
+
+const oldCopilotInstructions = () =>
+  resolve(platform.copilotDir(), "copilot-instructions.md");
+
+function linksToAgentsMd(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink() && readlinkSync(path).includes("AGENTS.md");
+  } catch {
+    return false;
+  }
+}
+
+const copilotInstructionsLink: Leftover = {
+  id: "copilot-instructions-link",
+  description:
+    "Remove the copilot-instructions.md link to AGENTS.md — Copilot now reads PAL's own instruction files",
+  find: () =>
+    linksToAgentsMd(oldCopilotInstructions()) ? [oldCopilotInstructions()] : [],
+  remove: () => unlinkSync(oldCopilotInstructions()),
+};
+
+const debugLog = () => resolve(paths.debug(), "debug.log");
+
+const debugLogPrev: Leftover = {
+  id: "debug-log-prev",
+  description: "Rename the old single rotated debug log, debug.log.prev, to debug.log.1",
+  find: () => (existsSync(`${debugLog()}.prev`) ? [`${debugLog()}.prev`] : []),
+  remove() {
+    const prev = `${debugLog()}.prev`;
+    if (existsSync(`${debugLog()}.1`)) unlinkSync(prev);
+    else renameSync(prev, `${debugLog()}.1`);
+  },
+};
+
+export const LEFTOVERS: Leftover[] = [
+  claudeFileToolRules,
+  startupProjectsFile,
+  opencodePluginOldName,
+  copilotInstructionsLink,
+  debugLogPrev,
+];

package/src/cli/migrate.ts

@@ -1,13 +1,13 @@
 /**
- * pal cli migrate — versioned, non-destructive data migrations.
+ * pal cli migrate — the only place PAL knows about its own past.
  *
  * Each Migration has:
- *   check() — returns whether this migration is needed (safe to call repeatedly)
- *   run()   — applies the migration; NEVER deletes source data
+ *   check() — reads what is on disk, so it is safe to call on every install
+ *   run()   — applies it; user data is moved, never deleted, while leftovers
+ *             PAL itself wrote and no longer reads are removed
  *
- * Add new migrations by appending to MIGRATIONS. Registry is ordered; migrations
- * run in declaration order. Doctor calls checkPendingMigrations() to surface
- * pending work without running anything.
+ * Retiring a setting, hook, file or name means adding a migration that removes
+ * its leftovers. Install runs pending migrations first; the doctor lists them.
  */
 
 import {
@@ -40,6 +40,7 @@ import {
   slugify,
 } from "../tools/knowledge/lib";
 import { readThreads, type Thread, writeThreads } from "../tools/lib/thread";
+import { LEFTOVERS, type Leftover } from "./leftovers";
 
 // ── Types ─────────────────────────────────────────────────────────
 
@@ -715,6 +716,29 @@ const v7RetiredSettingsKeys: Migration = {
   },
 };
 
+function leftoverMigration(leftover: Leftover): Migration {
+  return {
+    id: leftover.id,
+    description: leftover.description,
+    movesSources: true,
+    check() {
+      const found = leftover.find();
+      return { pending: found.length > 0, detail: found.join(", ") || undefined };
+    },
+    run(dryRun = false): MigrationResult {
+      const found = leftover.find();
+      if (found.length === 0) return { migrated: 0, skipped: 0, results: [] };
+      if (!dryRun) leftover.remove();
+      const verb = dryRun ? "would remove" : "removed";
+      return {
+        migrated: found.length,
+        skipped: 0,
+        results: [`${verb} ${found.join(", ")}`],
+      };
+    },
+  };
+}
+
 const MIGRATIONS: Migration[] = [
   v1Projects,
   v2ThreadsToIsc,
@@ -723,6 +747,7 @@ const MIGRATIONS: Migration[] = [
   v5AttributionKeys,
   v6HistorySlugs,
   v7RetiredSettingsKeys,
+  ...LEFTOVERS.map(leftoverMigration),
 ];
 
 // ── Public API ────────────────────────────────────────────────────
@@ -733,6 +758,13 @@ interface PendingMigration {
   detail?: string;
 }
 
+/** Install runs these first, so one install leaves nothing an older PAL wrote. */
+export function applyPendingMigrations(): string[] {
+  return MIGRATIONS.filter((m) => m.check().pending).flatMap((m) =>
+    m.run(false).results.map((line) => `${m.id}: ${line}`)
+  );
+}
+
 /** Returns migrations that have pending work. Used by doctor. */
 export function checkPendingMigrations(): PendingMigration[] {
   return MIGRATIONS.flatMap((m) => {

package/src/hooks/lib/log.ts

@@ -36,22 +36,10 @@ function timestamp(): string {
  * .MAX_ROTATED (oldest). Each rotation shifts .N-1 → .N, drops the oldest,
  * and renames the current log to .1. Total disk footprint bounded at
  * (MAX_ROTATED + 1) * MAX_LOG_SIZE ≈ 300KB.
- *
- * Migrates legacy .prev → .1 on first new rotation so existing history
- * survives the format change.
  */
 function rotateIfNeeded(path: string): void {
   try {
     if (!existsSync(path) || statSync(path).size <= MAX_LOG_SIZE) return;
-    // Backward-compat migration: legacy .prev was the single old rotation file.
-    const legacyPrev = `${path}.prev`;
-    if (existsSync(legacyPrev) && !existsSync(`${path}.1`)) {
-      try {
-        renameSync(legacyPrev, `${path}.1`);
-      } catch {
-        /* ignore */
-      }
-    }
     // Drop the oldest, then shift .N-1 → .N for N from MAX_ROTATED down to 2.
     const oldest = `${path}.${MAX_ROTATED}`;
     if (existsSync(oldest)) {
@@ -99,7 +87,7 @@ function logFilesOldestFirst(): string[] {
     { length: MAX_ROTATED },
     (_, i) => `${path}.${MAX_ROTATED - i}`
   );
-  return [...rotated, `${path}.prev`, path];
+  return [...rotated, path];
 }
 
 function readAllLogs(): string {

package/src/targets/copilot/uninstall.ts

@@ -4,7 +4,7 @@
  * and the VS Code chat.instructionsFilesLocations entry.
  */
 
-import { copyFileSync, existsSync, lstatSync, readlinkSync, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { platform } from "../../hooks/lib/paths";
 import {
@@ -63,22 +63,6 @@ log.success(
   `Removed ${removedInstructions.length} ~/.copilot/instructions/pal-*.instructions.md`
 );
 
-// --- Backward compat: remove old copilot-instructions.md symlink if present ---
-const legacyPath = resolve(COPILOT_DIR, "copilot-instructions.md");
-if (existsSync(legacyPath)) {
-  try {
-    if (
-      lstatSync(legacyPath).isSymbolicLink() &&
-      readlinkSync(legacyPath).includes("AGENTS.md")
-    ) {
-      unlinkSync(legacyPath);
-      log.success("Removed legacy copilot-instructions.md symlink");
-    }
-  } catch {
-    /* ignore */
-  }
-}
-
 // --- Remove ~/.copilot/instructions entry from VS Code settings ---
 const vsSettingsPath = vscodeSettingsFile();
 if (vsSettingsPath && existsSync(vsSettingsPath)) {

package/src/targets/lib.ts

@@ -211,7 +211,7 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
     }
   }
 
-  // Merge permissions.allow (deduplicate), then drop deprecated entries.
+  // Merge permissions.allow (deduplicate)
   if (template.permissions?.allow) {
     result.permissions ??= {};
     result.permissions.allow ??= [];
@@ -221,15 +221,6 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
       }
     }
   }
-  // Strip ineffective Grep(...)/Glob(...) rules left by older templates. Claude Code
-  // governs Grep/Glob via Read(...) rules, so a path-scoped Grep()/Glob() entry never
-  // matches and Claude Code warns about it on every prompt. Read(//*) already covers them.
-  if (result.permissions?.allow) {
-    result.permissions.allow = result.permissions.allow.filter(
-      (perm) => !isIneffectiveFileToolRule(perm)
-    );
-  }
-
   // Merge skillOverrides (object with skill name keys, add if not present)
   if (template.skillOverrides && typeof template.skillOverrides === "object") {
     result.skillOverrides ??= {};
@@ -488,15 +479,6 @@ function isOutdatedPalHook(cmd: string, palCanonical: Set<string>): boolean {
   return palCanonical.has(canonicalPalCmd(cmd)) || runsRemovedPalHook(cmd);
 }
 
-/**
- * True for path-scoped Grep()/Glob() allow rules, which Claude Code cannot honor —
- * it resolves Grep/Glob permission through Read(...) rules, so these never match and
- * trigger a warning on every prompt. Bare "Grep"/"Glob" tool allows are left intact.
- */
-function isIneffectiveFileToolRule(perm: string): boolean {
-  return /^(?:Grep|Glob)\(/.test(perm);
-}
-
 export function loadCodexHooksTemplate(
   templatePath: string,
   pkgRoot: string
@@ -697,21 +679,6 @@ export function scaffoldPalSettings(): void {
     copyFileSync(src, dst);
     log.info("Created pal-settings.json from template");
   }
-
-  // Strip deprecated loadAtStartup.files entries from existing installs.
-  // mergeSettings only adds, never removes — deprecated entries persist indefinitely otherwise.
-  try {
-    const raw = JSON.parse(readFileSync(dst, "utf-8"));
-    const files: string[] = raw?.loadAtStartup?.files ?? [];
-    const cleaned = files.filter((f: string) => !f.endsWith("PROJECTS.md"));
-    if (cleaned.length !== files.length) {
-      raw.loadAtStartup.files = cleaned;
-      writeFileSync(dst, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
-      log.info("Removed deprecated PROJECTS.md from loadAtStartup.files");
-    }
-  } catch {
-    /* non-fatal — malformed settings left as-is */
-  }
 }
 
 // --- PAL docs (modular context routing files) ---

package/src/targets/opencode/install.ts

@@ -3,14 +3,7 @@
  * Deploys plugin, installs skills, generates AGENTS.md.
  */
 
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { palPkg, platform } from "../../hooks/lib/paths";
 import { getSemiStaticSources } from "../../hooks/lib/semi-static";
@@ -22,11 +15,7 @@ const OC_PLUGINS_DIR = resolve(OC_GLOBAL_DIR, "plugins");
 
 mkdirSync(OC_PLUGINS_DIR, { recursive: true });
 
-// --- 1. Deploy plugin (clean up legacy filename) ---
-const legacyPlugin = resolve(OC_PLUGINS_DIR, "pai-plugin.ts");
-if (existsSync(legacyPlugin)) {
-  unlinkSync(legacyPlugin);
-}
+// --- 1. Deploy plugin ---
 const pluginSrc = resolve(PKG_ROOT, "src", "targets", "opencode", "plugin.ts");
 const pluginDst = resolve(OC_PLUGINS_DIR, "pal-plugin.ts");
 // Embed PKG_ROOT as a hardcoded constant so no env config is needed