portable-agent-layer 0.35.0 → 0.37.0

package/src/cli/index.ts

@@ -8,8 +8,8 @@
  *
  * Admin commands (pal cli ...):
  *   init                              Scaffold PAL home, install hooks for all targets
- *   install [--claude] [--opencode] [--cursor]   Register hooks/skills for targets
- *   uninstall [--claude] [--opencode] [--cursor] Remove hooks/skills for targets
+ *   install [--claude] [--opencode] [--cursor] [--codex]   Register hooks/skills for targets
+ *   uninstall [--claude] [--opencode] [--cursor] [--codex] 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
@@ -25,6 +25,7 @@ import { resolve } from "node:path";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
+import { checkPendingMigrations } from "./migrate";
 
 const allArgs = process.argv.slice(2);
 
@@ -169,6 +170,11 @@ async function runCli(command: string | undefined, args: string[]) {
     case "doctor":
       doctor();
       break;
+    case "migrate": {
+      const { runMigrate } = await import("./migrate");
+      runMigrate(args);
+      break;
+    }
     case "usage": {
       const { usage } = await import("../tools/token-cost");
       usage();
@@ -204,14 +210,15 @@ function showHelp() {
     pal cli <command> [options]             Admin commands
 
   Admin commands:
-    pal cli init [--claude] [--opencode] [--cursor]    Scaffold and install (default: all)
-    pal cli install [--claude] [--opencode] [--cursor] Register hooks for targets
-    pal cli uninstall [--claude] [--opencode] [--cursor] Remove hooks for targets
+    pal cli init [--claude] [--opencode] [--cursor] [--codex]    Scaffold and install (default: all)
+    pal cli install [--claude] [--opencode] [--cursor] [--codex] Register hooks for targets
+    pal cli uninstall [--claude] [--opencode] [--cursor] [--codex] 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
     pal cli doctor                          Check prerequisites and health
+    pal cli migrate [--list] [--dry-run]    Run pending data migrations
     pal cli usage                           Summarize token usage and cost
 
   Environment:
@@ -221,32 +228,42 @@ function showHelp() {
     PAL_OPENCODE_DIR      Override opencode config dir (default: ~/.config/opencode)
     PAL_CURSOR_DIR        Override Cursor config dir (default: ~/.cursor)
     PAL_COPILOT_DIR       Override Copilot config dir (default: ~/.copilot)
+    PAL_CODEX_DIR         Override Codex config dir (default: ~/.codex)
     PAL_AGENTS_DIR        Override agents dir (default: ~/.agents)
 `);
 }
 
-type Targets = { claude: boolean; opencode: boolean; cursor: boolean; copilot: boolean };
+type Targets = {
+  claude: boolean;
+  opencode: boolean;
+  cursor: boolean;
+  copilot: boolean;
+  codex: boolean;
+};
 
 function parseTargets(args: string[]): Targets {
   let claude = false;
   let opencode = false;
   let cursor = false;
   let copilot = false;
+  let codex = false;
   for (const arg of args) {
     if (arg === "--claude") claude = true;
     else if (arg === "--opencode") opencode = true;
     else if (arg === "--cursor") cursor = true;
     else if (arg === "--copilot") copilot = true;
+    else if (arg === "--codex") codex = true;
     else if (arg === "--all") {
       claude = true;
       opencode = true;
       cursor = true;
       copilot = true;
+      codex = true;
     }
   }
-  if (!claude && !opencode && !cursor && !copilot)
-    return { claude: true, opencode: true, cursor: true, copilot: true };
-  return { claude, opencode, cursor, copilot };
+  if (!claude && !opencode && !cursor && !copilot && !codex)
+    return { claude: true, opencode: true, cursor: true, copilot: true, codex: true };
+  return { claude, opencode, cursor, copilot, codex };
 }
 
 /** Resolve targets against available agents. Errors if explicitly requested but missing. */
@@ -259,6 +276,7 @@ function resolveTargets(args: string[], health?: DoctorResult): Targets {
       a === "--opencode" ||
       a === "--cursor" ||
       a === "--copilot" ||
+      a === "--codex" ||
       a === "--all"
   );
 
@@ -279,6 +297,10 @@ function resolveTargets(args: string[], health?: DoctorResult): Targets {
       log.error("Copilot is not installed. Run 'pal cli doctor' for details.");
       process.exit(1);
     }
+    if (requested.codex && !h.codex.available) {
+      log.error("Codex is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
     return requested;
   }
 
@@ -288,12 +310,14 @@ function resolveTargets(args: string[], health?: DoctorResult): Targets {
     opencode: h.opencode.available,
     cursor: h.cursor.available,
     copilot: h.copilot.available,
+    codex: h.codex.available,
   };
 
   if (!targets.claude) log.info("Skipping Claude Code (not installed)");
   if (!targets.opencode) log.info("Skipping opencode (not installed)");
   if (!targets.cursor) log.info("Skipping Cursor (not installed)");
   if (!targets.copilot) log.info("Skipping Copilot (not installed)");
+  if (!targets.codex) log.info("Skipping Codex (not installed)");
 
   return targets;
 }
@@ -341,6 +365,22 @@ function checkCopilotHooksRegistered(): boolean {
   return existsSync(resolve(platform.copilotDir(), "hooks", "pal-hooks.json"));
 }
 
+function checkCodexHooksRegistered(): boolean {
+  const hooksPath = resolve(platform.codexDir(), "hooks.json");
+  if (!existsSync(hooksPath)) return false;
+  try {
+    const data = JSON.parse(readFileSync(hooksPath, "utf-8"));
+    const entries = data?.hooks?.SessionStart;
+    if (!Array.isArray(entries)) return false;
+    return entries.some((entry: { command?: string; hooks?: { command?: string }[] }) => {
+      if (entry?.command?.includes("LoadContext")) return true;
+      return entry?.hooks?.some((h) => h?.command?.includes("LoadContext")) ?? false;
+    });
+  } catch {
+    return false;
+  }
+}
+
 function checkCopilotInstructionsPresent(): boolean {
   return existsSync(resolve(platform.copilotDir(), "copilot-instructions.md"));
 }
@@ -408,7 +448,7 @@ function checkHookHealth(home: string): HookHealth {
     // Filter to last 24h
     const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
     const recentErrors = lines.filter((line) => {
-      const match = line.match(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/);
+      const match = new RegExp(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/).exec(line);
       if (!match) return false;
       return new Date(match[1]) > cutoff;
     });
@@ -434,6 +474,7 @@ interface DoctorResult {
   opencode: ToolCheck;
   cursor: ToolCheck;
   copilot: ToolCheck;
+  codex: ToolCheck;
   hasAgent: boolean;
 }
 
@@ -446,6 +487,7 @@ function doctor(silent = false): DoctorResult {
       opencode: { name: "opencode", available: true },
       cursor: { name: "cursor", available: true },
       copilot: { name: "copilot", available: true },
+      codex: { name: "codex", available: true },
       hasAgent: true,
     };
   }
@@ -455,8 +497,13 @@ function doctor(silent = false): DoctorResult {
   const opencode = checkTool("opencode");
   const cursor = checkTool("cursor");
   const copilot = checkTool("copilot", ["version"]);
+  const codex = checkTool("codex");
   const hasAgent =
-    claude.available || opencode.available || cursor.available || copilot.available;
+    claude.available ||
+    opencode.available ||
+    cursor.available ||
+    copilot.available ||
+    codex.available;
 
   const home = palHome();
   const telosCount = (() => {
@@ -499,6 +546,9 @@ function doctor(silent = false): DoctorResult {
     copilot.available
       ? ok(`Copilot ${copilot.version || ""}`.trim())
       : fail("Copilot — not found");
+    codex.available
+      ? ok(`Codex ${codex.version || ""}`.trim())
+      : fail("Codex — not found");
     ok(`PAL home: ${home}`);
     telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
 
@@ -572,6 +622,12 @@ function doctor(silent = false): DoctorResult {
         ? ok(`Copilot skills: ${n}`)
         : warn("Copilot skills — none found (run 'pal cli install --copilot')");
     }
+    if (codex.available) {
+      const n = countSkillsIn(resolve(platform.codexDir(), "skills"));
+      n > 0
+        ? ok(`Codex skills: ${n}`)
+        : warn("Codex skills — none found (run 'pal cli install --codex')");
+    }
 
     // Dependencies
     const nodeModulesPath = resolve(palPkg(), "node_modules");
@@ -610,6 +666,11 @@ function doctor(silent = false): DoctorResult {
         ? ok("copilot-instructions.md present")
         : warn("copilot-instructions.md missing (run 'pal cli install --copilot')");
     }
+    if (codex.available) {
+      checkCodexHooksRegistered()
+        ? ok("Codex hooks registered")
+        : fail("Codex hooks — not registered (run 'pal cli install --codex')");
+    }
 
     // API key checks
     process.env.PAL_ANTHROPIC_API_KEY
@@ -636,6 +697,17 @@ function doctor(silent = false): DoctorResult {
       }
     }
 
+    // Pending migrations
+    const pendingMigrations = checkPendingMigrations();
+    if (pendingMigrations.length > 0) {
+      for (const m of pendingMigrations) {
+        const detail = m.detail ? ` (${m.detail})` : "";
+        warn(
+          `Migration pending: ${m.id} — ${m.description}${detail} → run 'pal cli migrate'`
+        );
+      }
+    }
+
     if (!hasAgent) {
       console.log("");
       log.error("No supported agent found. Install Claude Code or opencode.");
@@ -643,7 +715,7 @@ function doctor(silent = false): DoctorResult {
     console.log("");
   }
 
-  return { bun, claude, opencode, cursor, copilot, hasAgent };
+  return { bun, claude, opencode, cursor, copilot, codex, hasAgent };
 }
 
 // ── Commands ──
@@ -749,6 +821,12 @@ async function install(targets: Targets) {
     console.log("");
   }
 
+  if (targets.codex) {
+    console.log("━━━ Codex ━━━");
+    await import("../targets/codex/install");
+    console.log("");
+  }
+
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
@@ -779,6 +857,12 @@ async function uninstall(args: string[]) {
     console.log("");
   }
 
+  if (targets.codex) {
+    console.log("━━━ Codex ━━━");
+    await import("../targets/codex/uninstall");
+    console.log("");
+  }
+
   log.success(
     `PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`
   );
@@ -935,7 +1019,14 @@ async function update() {
     }
   }
 
-  const newPkg = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8"));
+  let newPkg: { version: string };
+  try {
+    newPkg = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8")) as {
+      version: string;
+    };
+  } catch (e) {
+    throw new Error(`Failed to read updated package.json: ${e}`);
+  }
   log.success(`Updated: ${result.current} → ${newPkg.version}`);
 
   log.info("Reinstalling...");
@@ -946,7 +1037,14 @@ async function status() {
   const home = palHome();
   const pkg = palPkg();
 
-  const pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8"));
+  let pkgJson: { version: string };
+  try {
+    pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8")) as {
+      version: string;
+    };
+  } catch (e) {
+    throw new Error(`Failed to read package.json: ${e}`);
+  }
 
   console.log("");
   log.info(`Version:  ${pkgJson.version}`);

package/src/cli/migrate.ts

@@ -0,0 +1,299 @@
+/**
+ * pal cli migrate — versioned, non-destructive data migrations.
+ *
+ * Each Migration has:
+ *   check() — returns whether this migration is needed (safe to call repeatedly)
+ *   run()   — applies the migration; NEVER deletes source data
+ *
+ * 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.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "../hooks/lib/paths";
+import {
+  type ProjectProgress,
+  type ProjectStatus,
+  readAllProjects,
+  readProject,
+  writeProject,
+} from "../hooks/lib/projects";
+import { readThreads, type Thread, writeThreads } from "../tools/agent/thread";
+
+// ── Types ─────────────────────────────────────────────────────────
+
+interface MigrationResult {
+  migrated: number;
+  skipped: number;
+  results: string[];
+}
+
+interface Migration {
+  id: string;
+  description: string;
+  check(): { pending: boolean; detail?: string };
+  run(dryRun?: boolean): MigrationResult;
+}
+
+// ── v1-projects: JSON progress files → ISA.md ─────────────────────
+
+interface LegacyDecision {
+  ts: string;
+  decision: string;
+  rationale: string;
+}
+
+interface LegacyProject {
+  name: string;
+  path: string;
+  status: ProjectStatus;
+  created: string;
+  updated: string;
+  facts?: string[];
+  objectives?: string[];
+  next_steps?: string[];
+  blockers?: string[];
+  handoff?: string;
+  decisions?: LegacyDecision[];
+}
+
+function pendingJsonFiles(): string[] {
+  const progressDir = paths.progress();
+  if (!existsSync(progressDir)) return [];
+  return readdirSync(progressDir)
+    .filter((f) => f.endsWith(".json"))
+    .filter((f) => !readProject(f.slice(0, -5)));
+}
+
+const v1Projects: Migration = {
+  id: "v1-projects",
+  description: "Migrate legacy JSON progress files to ISA.md format",
+
+  check() {
+    const pending = pendingJsonFiles();
+    return {
+      pending: pending.length > 0,
+      detail: pending.length > 0 ? `${pending.length} file(s) in progress/` : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const progressDir = paths.progress();
+    const files = pendingJsonFiles();
+
+    let migrated = 0;
+    let skipped = 0;
+    const results: string[] = [];
+
+    for (const file of files) {
+      const slug = file.slice(0, -5);
+      const filePath = resolve(progressDir, file);
+
+      try {
+        const raw = JSON.parse(readFileSync(filePath, "utf-8")) as LegacyProject;
+        if (!raw?.name || !raw?.path || !raw?.status) {
+          skipped++;
+          results.push(`${slug}: skipped (malformed JSON)`);
+          continue;
+        }
+
+        if (!dryRun) {
+          const p: ProjectProgress = {
+            name: raw.name,
+            path: raw.path,
+            status: raw.status,
+            created: raw.created ?? new Date().toISOString(),
+            updated: raw.updated ?? new Date().toISOString(),
+            ...(raw.handoff ? { handoff: raw.handoff } : {}),
+            ...(raw.next_steps?.length ? { next: raw.next_steps } : {}),
+            ...(raw.blockers?.length ? { blockers: raw.blockers } : {}),
+          };
+
+          if (raw.facts?.length) p.context = raw.facts.join("\n");
+          if (raw.objectives?.length)
+            p.goal = raw.objectives.map((o) => `- ${o}`).join("\n");
+          if (raw.decisions?.length) {
+            p.decisions = raw.decisions
+              .map((d) => `- ${d.ts.slice(0, 10)}: ${d.decision} (${d.rationale})`)
+              .join("\n");
+          }
+
+          writeProject(p);
+        }
+
+        migrated++;
+        results.push(`${slug}: ${dryRun ? "would migrate" : "migrated"} (source kept)`);
+      } catch {
+        skipped++;
+        results.push(`${slug}: skipped (read/write error)`);
+      }
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
+// ── v2-threads-to-isc: open threads → ISCs on matching project ────
+
+function nextIscId(criteria: string): number {
+  const ids: number[] = [];
+  for (const line of criteria.split("\n")) {
+    const m = new RegExp(/^-\s+\[[ x]\]\s+ISC-(\d+):/i).exec(line);
+    if (m) ids.push(Number(m[1]));
+  }
+  return ids.length > 0 ? Math.max(...ids) + 1 : 1;
+}
+
+function pendingThreadsForProjects(): { thread: Thread; project: ProjectProgress }[] {
+  const threads = readThreads().filter((t) => t.status === "open");
+  if (threads.length === 0) return [];
+  const projects = readAllProjects();
+  const results: { thread: Thread; project: ProjectProgress }[] = [];
+  for (const thread of threads) {
+    const project = projects.find((p) => resolve(p.path) === resolve(thread.cwd));
+    if (project) results.push({ thread, project });
+  }
+  return results;
+}
+
+const v2ThreadsToIsc: Migration = {
+  id: "v2-threads-to-isc",
+  description: "Migrate open project-scoped threads to ISCs on their project ISA",
+
+  check() {
+    const pending = pendingThreadsForProjects();
+    return {
+      pending: pending.length > 0,
+      detail: pending.length > 0 ? `${pending.length} thread(s) to migrate` : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const pending = pendingThreadsForProjects();
+    let migrated = 0;
+    let skipped = 0;
+    const results: string[] = [];
+
+    const threadUpdates: Map<string, Thread> = new Map();
+
+    for (const { thread, project } of pending) {
+      try {
+        if (!dryRun) {
+          const p = readProject(project.name);
+          if (!p) {
+            skipped++;
+            results.push(`${thread.id}: skipped (project "${project.name}" unreadable)`);
+            continue;
+          }
+          const current = p.criteria ?? "";
+          const id = nextIscId(current);
+          const newLine = `- [ ] ISC-${id}: ${thread.title}`;
+          p.criteria = current ? `${current.trimEnd()}\n${newLine}` : newLine;
+          p.updated = new Date().toISOString();
+          writeProject(p);
+          threadUpdates.set(thread.id, {
+            ...thread,
+            status: "resolved",
+            resolved: new Date().toISOString(),
+          });
+        }
+        migrated++;
+        results.push(
+          `${thread.id} → ${project.name} ISC: ${dryRun ? "would add" : "added"} "${thread.title}" (thread source kept)`
+        );
+      } catch {
+        skipped++;
+        results.push(`${thread.id}: skipped (error)`);
+      }
+    }
+
+    if (!dryRun && threadUpdates.size > 0) {
+      const all = readThreads().map((t) => threadUpdates.get(t.id) ?? t);
+      writeThreads(all);
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
+// ── Registry ──────────────────────────────────────────────────────
+
+const MIGRATIONS: Migration[] = [v1Projects, v2ThreadsToIsc];
+
+// ── Public API ────────────────────────────────────────────────────
+
+interface PendingMigration {
+  id: string;
+  description: string;
+  detail?: string;
+}
+
+/** Returns migrations that have pending work. Used by doctor. */
+export function checkPendingMigrations(): PendingMigration[] {
+  return MIGRATIONS.flatMap((m) => {
+    const { pending, detail } = m.check();
+    return pending ? [{ id: m.id, description: m.description, detail }] : [];
+  });
+}
+
+/** Entry point for `pal cli migrate`. */
+export function runMigrate(args: string[]): void {
+  const dryRun = args.includes("--dry-run");
+  const list = args.includes("--list");
+
+  if (list) {
+    const pending = checkPendingMigrations();
+    const done = MIGRATIONS.filter((m) => !m.check().pending);
+
+    console.log("");
+    if (pending.length > 0) {
+      console.log("  Pending migrations:");
+      for (const m of pending) {
+        const detail = m.detail ? ` (${m.detail})` : "";
+        console.log(`    ⚠ ${m.id} — ${m.description}${detail}`);
+      }
+    } else {
+      console.log("  No pending migrations.");
+    }
+    if (done.length > 0) {
+      console.log("  Done:");
+      for (const m of done) {
+        console.log(`    ✓ ${m.id} — ${m.description}`);
+      }
+    }
+    console.log("");
+    return;
+  }
+
+  const pending = MIGRATIONS.filter((m) => m.check().pending);
+  if (pending.length === 0) {
+    console.log("  Nothing to migrate — all up to date.");
+    return;
+  }
+
+  if (dryRun) console.log("  Dry run — no files will be written.\n");
+
+  let totalMigrated = 0;
+  let totalSkipped = 0;
+
+  for (const m of pending) {
+    console.log(`  Running: ${m.id} — ${m.description}`);
+    const result = m.run(dryRun);
+    totalMigrated += result.migrated;
+    totalSkipped += result.skipped;
+    for (const r of result.results) {
+      console.log(`    ${r}`);
+    }
+  }
+
+  console.log("");
+  console.log(
+    `  ${dryRun ? "Would migrate" : "Migrated"}: ${totalMigrated} | Skipped: ${totalSkipped}`
+  );
+  if (!dryRun && totalMigrated > 0) {
+    console.log("  Source files preserved — delete manually once verified.");
+  }
+  console.log("");
+}

package/src/cli/setup-identity.ts

@@ -16,9 +16,9 @@ export async function promptIdentity(): Promise<void> {
   if (!process.stdin.isTTY) return;
 
   const settings: PalSettingsData = { ...readSettings() };
-  if (!settings.identity) settings.identity = {};
-  if (!settings.identity.ai) settings.identity.ai = {};
-  if (!settings.identity.principal) settings.identity.principal = {};
+  settings.identity ??= {};
+  settings.identity.ai ??= {};
+  settings.identity.principal ??= {};
 
   const ai = settings.identity.ai;
   const principal = settings.identity.principal;