portable-agent-layer 0.41.1 → 0.43.0

package/src/cli/migrate.ts

@@ -10,9 +10,9 @@
  * pending work without running anything.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
 import { resolve } from "node:path";
-import { paths } from "../hooks/lib/paths";
+import { palHome, paths } from "../hooks/lib/paths";
 import {
   legacyJsonToProgress,
   type ProjectProgress,
@@ -21,6 +21,14 @@ import {
   writeProject,
 } from "../hooks/lib/projects";
 import { readThreads, type Thread, writeThreads } from "../tools/agent/thread";
+import { appendSourceLog } from "../tools/knowledge/ingest";
+import {
+  type Entity,
+  type EntityFrontmatter,
+  exists as knowledgeExists,
+  save as knowledgeSave,
+  slugify,
+} from "../tools/knowledge/lib";
 
 // ── Types ─────────────────────────────────────────────────────────
 
@@ -175,9 +183,186 @@ const v2ThreadsToIsc: Migration = {
   },
 };
 
+// ── v3-entities-to-knowledge: entity-index.json → knowledge/*.md ──
+
+interface LegacyPerson {
+  id: string;
+  name: string;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+interface LegacyCompany {
+  id: string;
+  name: string;
+  domain: string | null;
+  first_seen: string;
+  occurrences: number;
+  source_ids: string[];
+}
+
+interface LegacyIndex {
+  version?: string;
+  people?: Record<string, LegacyPerson>;
+  companies?: Record<string, LegacyCompany>;
+  links?: Record<string, unknown>;
+  sources?: Record<string, unknown>;
+}
+
+function legacyEntitiesPath(): string {
+  // Read from PAL_HOME-aware location to match where the legacy store lived;
+  // computed locally now that paths.entities() is being retired alongside this migration.
+  const home = palHome();
+  const dir = resolve(home, "memory", "entities");
+  return resolve(dir, "entity-index.json");
+}
+
+function readLegacyIndex(): LegacyIndex | null {
+  const p = legacyEntitiesPath();
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf-8")) as LegacyIndex;
+  } catch {
+    return null;
+  }
+}
+
+function countLegacyEntries(idx: LegacyIndex): number {
+  return Object.keys(idx.people ?? {}).length + Object.keys(idx.companies ?? {}).length;
+}
+
+function legacyPersonToEntity(legacy: LegacyPerson): Entity {
+  const fm: EntityFrontmatter = {
+    title: legacy.name,
+    type: "person",
+    tags: [],
+    created: legacy.first_seen,
+    updated: legacy.first_seen,
+    quality: 5,
+    status: "seedling",
+    related: [],
+    legacy_id: legacy.id,
+    occurrences: legacy.occurrences,
+  };
+  let body = "";
+  for (const sourceId of legacy.source_ids) {
+    body = appendSourceLog(body, sourceId, null, {}, legacy.first_seen);
+  }
+  return { domain: "People", slug: slugify(legacy.name), frontmatter: fm, body };
+}
+
+function legacyCompanyToEntity(legacy: LegacyCompany): Entity {
+  const baseKey = legacy.domain?.trim() ? legacy.domain : legacy.name;
+  const fm: EntityFrontmatter = {
+    title: legacy.name,
+    type: "company",
+    tags: [],
+    created: legacy.first_seen,
+    updated: legacy.first_seen,
+    quality: 5,
+    status: "seedling",
+    related: [],
+    legacy_id: legacy.id,
+    occurrences: legacy.occurrences,
+  };
+  if (legacy.domain) fm.domain_name = legacy.domain;
+  let body = "";
+  for (const sourceId of legacy.source_ids) {
+    body = appendSourceLog(body, sourceId, null, {}, legacy.first_seen);
+  }
+  return { domain: "Companies", slug: slugify(baseKey), frontmatter: fm, body };
+}
+
+const v3EntitiesToKnowledge: Migration = {
+  id: "v3-entities-to-knowledge",
+  description: "Migrate legacy entity-index.json to knowledge/{People,Companies}/*.md",
+
+  check() {
+    const idx = readLegacyIndex();
+    if (!idx) return { pending: false };
+    const total = countLegacyEntries(idx);
+    if (total === 0) return { pending: false };
+    // Skip if every entity already exists in the new store (idempotent).
+    let remaining = 0;
+    for (const p of Object.values(idx.people ?? {})) {
+      if (!knowledgeExists("People", slugify(p.name))) remaining++;
+    }
+    for (const c of Object.values(idx.companies ?? {})) {
+      const key = c.domain?.trim() ? c.domain : c.name;
+      if (!knowledgeExists("Companies", slugify(key))) remaining++;
+    }
+    return {
+      pending: remaining > 0,
+      detail: remaining > 0 ? `${remaining} of ${total} entries to migrate` : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const idx = readLegacyIndex();
+    if (!idx) return { migrated: 0, skipped: 0, results: [] };
+
+    let migrated = 0;
+    let skipped = 0;
+    const results: string[] = [];
+
+    // Refuse to silently drop links/sources if a future legacy index has them.
+    const linksCount = Object.keys(idx.links ?? {}).length;
+    const sourcesCount = Object.keys(idx.sources ?? {}).length;
+    if (linksCount > 0 || sourcesCount > 0) {
+      results.push(
+        `aborted: legacy index has ${linksCount} link(s) and ${sourcesCount} source(s) — no destination in new store`
+      );
+      return { migrated: 0, skipped: linksCount + sourcesCount, results };
+    }
+
+    for (const legacy of Object.values(idx.people ?? {})) {
+      const entity = legacyPersonToEntity(legacy);
+      if (knowledgeExists(entity.domain, entity.slug)) {
+        skipped++;
+        results.push(`People/${entity.slug}: skipped (already in new store)`);
+        continue;
+      }
+      if (!dryRun) knowledgeSave(entity);
+      migrated++;
+      results.push(`People/${entity.slug}: ${dryRun ? "would migrate" : "migrated"}`);
+    }
+
+    for (const legacy of Object.values(idx.companies ?? {})) {
+      const entity = legacyCompanyToEntity(legacy);
+      if (knowledgeExists(entity.domain, entity.slug)) {
+        skipped++;
+        results.push(`Companies/${entity.slug}: skipped (already in new store)`);
+        continue;
+      }
+      if (!dryRun) knowledgeSave(entity);
+      migrated++;
+      results.push(`Companies/${entity.slug}: ${dryRun ? "would migrate" : "migrated"}`);
+    }
+
+    // After a successful, non-dry-run migration, archive the legacy file so
+    // re-runs don't repeatedly load and skip its contents.
+    if (!dryRun && migrated > 0) {
+      const src = legacyEntitiesPath();
+      if (existsSync(src)) {
+        const date = new Date().toISOString().slice(0, 10);
+        const archived = `${src}.migrated-${date}`;
+        try {
+          renameSync(src, archived);
+          results.push(`archived legacy index → ${archived}`);
+        } catch (e) {
+          results.push(`warn: could not rename legacy index (${(e as Error).message})`);
+        }
+      }
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
 // ── Registry ──────────────────────────────────────────────────────
 
-const MIGRATIONS: Migration[] = [v1Projects, v2ThreadsToIsc];
+const MIGRATIONS: Migration[] = [v1Projects, v2ThreadsToIsc, v3EntitiesToKnowledge];
 
 // ── Public API ────────────────────────────────────────────────────
 

package/src/hooks/lib/claude-md.ts

@@ -13,6 +13,7 @@ import {
   lstatSync,
   readdirSync,
   readFileSync,
+  readlinkSync,
   statSync,
   symlinkSync,
   unlinkSync,
@@ -54,8 +55,11 @@ function latestMtime(...filePaths: string[]): number {
 function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
     const stat = lstatSync(linkPath);
-    if (!stat.isSymbolicLink()) unlinkSync(linkPath);
-    else return; // already a symlink, leave it
+    if (stat.isSymbolicLink()) {
+      const currentTarget = resolve(dirname(linkPath), readlinkSync(linkPath));
+      if (currentTarget === targetPath) return;
+    }
+    unlinkSync(linkPath);
   } catch {
     // doesn't exist — create it
   }

package/src/hooks/lib/export.ts

@@ -1,6 +1,6 @@
 /**
  * Shared export logic — zips user state directories.
- * Used by tools/export.ts (manual) and handlers/backup.ts (automatic).
+ * Used by cli/index.ts (pal cli export) and handlers/backup.ts (automatic).
  */
 
 import { existsSync, readdirSync } from "node:fs";

package/src/hooks/lib/paths.ts

@@ -47,7 +47,8 @@ export const paths = {
   wisdom: () => ensureDir(home("memory", "wisdom", "frames")),
   wisdomState: () => ensureDir(home("memory", "wisdom", "state")),
   relationship: () => ensureDir(home("memory", "relationship")),
-  entities: () => ensureDir(home("memory", "entities")),
+  knowledge: () => ensureDir(home("memory", "knowledge")),
+  knowledgeDomain: (d: string) => ensureDir(home("memory", "knowledge", d)),
   failures: () => ensureDir(home("memory", "learning", "failures")),
   retrievalIndex: () => home("memory", "learning", ".retrieval-index.json"),
   progress: () => ensureDir(home("memory", "state", "progress")),
@@ -80,6 +81,7 @@ export const assets = {
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
+  codexRulesTemplate: () => pkg("assets", "templates", "rules.codex.rules"),
   agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/codex/install.ts

@@ -19,8 +19,10 @@ import {
   countSkills,
   generateSkillIndex,
   loadCodexHooksTemplate,
+  loadCodexRulesTemplate,
   log,
   mergeCodexHooks,
+  mergeCodexRules,
   readJson,
   scaffoldPalSettings,
   writeJson,
@@ -56,6 +58,7 @@ function enableCodexHooks(configPath: string): void {
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CODEX_DIR = platform.codexDir();
 const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 
 // --- Ensure ~/.codex/ exists ---
 mkdirSync(CODEX_DIR, { recursive: true });
@@ -73,6 +76,17 @@ const merged = mergeCodexHooks(existing, template);
 writeJson(HOOKS_FILE, merged);
 log.success("Merged PAL hooks into ~/.codex/hooks.json");
 
+// --- Merge allowlist rules ---
+mkdirSync(resolve(CODEX_DIR, "rules"), { recursive: true });
+if (existsSync(RULES_FILE)) {
+  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
+  log.info("Backed up rules/default.rules");
+}
+const rulesTemplate = loadCodexRulesTemplate(assets.codexRulesTemplate());
+const existingRules = existsSync(RULES_FILE) ? readFileSync(RULES_FILE, "utf-8") : "";
+writeFileSync(RULES_FILE, mergeCodexRules(existingRules, rulesTemplate), "utf-8");
+log.success("Merged PAL allowlist rules into ~/.codex/rules/default.rules");
+
 // --- Symlink skills to ~/.codex/skills/ ---
 const codexSkillsDir = resolve(CODEX_DIR, "skills");
 copySkills(codexSkillsDir);

package/src/targets/codex/uninstall.ts

@@ -13,6 +13,7 @@ import {
   readJson,
   removeSkills,
   unmergeCodexHooks,
+  unmergeCodexRules,
   writeJson,
 } from "../lib";
 
@@ -38,6 +39,7 @@ function disableCodexHooks(configPath: string): void {
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CODEX_DIR = platform.codexDir();
 const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 
 // --- Remove PAL hooks from hooks.json ---
 if (existsSync(HOOKS_FILE)) {
@@ -54,6 +56,18 @@ if (existsSync(HOOKS_FILE)) {
   log.info("No hooks.json found, nothing to do");
 }
 
+// --- Remove PAL allowlist rules from default.rules ---
+if (existsSync(RULES_FILE)) {
+  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
+  log.info("Backed up rules/default.rules");
+
+  const cleanedRules = unmergeCodexRules(readFileSync(RULES_FILE, "utf-8"));
+  writeFileSync(RULES_FILE, cleanedRules, "utf-8");
+  log.success("Removed PAL allowlist rules from ~/.codex/rules/default.rules");
+} else {
+  log.info("No default.rules found, nothing to do");
+}
+
 // --- Remove PAL skill symlinks ---
 const codexSkillsDir = resolve(CODEX_DIR, "skills");
 const removed = removeSkills(codexSkillsDir);

package/src/targets/lib.ts

@@ -273,22 +273,22 @@ export function loadCodexHooksTemplate(
   }
 }
 
-/** Merge PAL hooks into an existing Codex hooks.json. Deduplicates by canonical command path. */
-export function mergeCodexHooks(existing: CodexHooks, template: CodexHooks): CodexHooks {
-  const result: CodexHooks = { ...existing };
-  if (!template.hooks) return result;
-  result.hooks ??= {};
-
-  // Collect canonical paths of PAL template commands so we can evict stale variants
-  const palCanonical = new Set(
-    Object.values(template.hooks).flatMap((groups) =>
+/** Collect canonical command paths from a Codex hooks template (PAL-managed commands). */
+function collectPalCanonical(template: CodexHooks): Set<string> {
+  return new Set(
+    Object.values(template.hooks ?? {}).flatMap((groups) =>
       groups.flatMap((g) => g.hooks.map((h) => canonicalCmd(h.command)))
     )
   );
+}
 
-  // Strip any existing entries (nested or flat) whose canonical path matches a PAL command
-  for (const event of Object.keys(result.hooks)) {
-    result.hooks[event] = (result.hooks[event] ?? [])
+/** Strip entries (nested or flat) whose canonical command matches a PAL-managed command. */
+function stripPalHooks(
+  hooks: Record<string, CodexHookGroup[]>,
+  palCanonical: Set<string>
+): void {
+  for (const event of Object.keys(hooks)) {
+    hooks[event] = (hooks[event] ?? [])
       .map((g) => {
         const flat = g as unknown as CodexHookCommand;
         if (!g.hooks && flat.command && palCanonical.has(canonicalCmd(flat.command))) {
@@ -300,10 +300,18 @@ export function mergeCodexHooks(existing: CodexHooks, template: CodexHooks): Cod
         return filtered.length > 0 ? { ...g, hooks: filtered } : null;
       })
       .filter((g): g is CodexHookGroup => g !== null);
-    if (result.hooks[event].length === 0) delete result.hooks[event];
+    if (hooks[event].length === 0) delete hooks[event];
   }
+}
+
+/** Merge PAL hooks into an existing Codex hooks.json. Deduplicates by canonical command path. */
+export function mergeCodexHooks(existing: CodexHooks, template: CodexHooks): CodexHooks {
+  const result: CodexHooks = { ...existing };
+  if (!template.hooks) return result;
+  result.hooks ??= {};
+
+  stripPalHooks(result.hooks, collectPalCanonical(template));
 
-  // Add fresh template entries
   for (const [event, groups] of Object.entries(template.hooks)) {
     const current = result.hooks[event] ?? [];
     for (const group of groups) current.push(group);
@@ -320,32 +328,41 @@ export function unmergeCodexHooks(
   const result: CodexHooks = { ...existing };
   if (!template.hooks || !result.hooks) return result;
 
-  // Match by canonical path so prefix variants (PAL_AGENT=codex, etc.) are all removed
-  const palCanonical = new Set(
-    Object.values(template.hooks).flatMap((groups) =>
-      groups.flatMap((g) => g.hooks.map((h) => canonicalCmd(h.command)))
-    )
-  );
-
-  for (const event of Object.keys(result.hooks)) {
-    result.hooks[event] = (result.hooks[event] ?? [])
-      .map((g) => {
-        const flat = g as unknown as CodexHookCommand;
-        if (!g.hooks && flat.command && palCanonical.has(canonicalCmd(flat.command))) {
-          return null;
-        }
-        const filtered = (g.hooks ?? []).filter(
-          (h) => !palCanonical.has(canonicalCmd(h.command))
-        );
-        return filtered.length > 0 ? { ...g, hooks: filtered } : null;
-      })
-      .filter((g): g is CodexHookGroup => g !== null);
-    if (result.hooks[event].length === 0) delete result.hooks[event];
-  }
+  stripPalHooks(result.hooks, collectPalCanonical(template));
   if (Object.keys(result.hooks).length === 0) delete result.hooks;
   return result;
 }
 
+// --- Codex rules (Starlark .rules file) ---
+
+const CODEX_RULES_BEGIN = "# BEGIN PAL MANAGED CODEX RULES";
+const CODEX_RULES_END = "# END PAL MANAGED CODEX RULES";
+
+export function loadCodexRulesTemplate(templatePath: string): string {
+  return readFileSync(templatePath, "utf-8").trim();
+}
+
+function stripPalCodexRules(content: string): string {
+  const escapedBegin = CODEX_RULES_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedEnd = CODEX_RULES_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const block = new RegExp(String.raw`\n?${escapedBegin}[\s\S]*?${escapedEnd}\n?`, "g");
+  return content
+    .replace(block, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function mergeCodexRules(existing: string, template: string): string {
+  const preserved = stripPalCodexRules(existing);
+  const prefix = preserved ? `${preserved}\n\n` : "";
+  return `${prefix}${template.trim()}\n`;
+}
+
+export function unmergeCodexRules(existing: string): string {
+  const cleaned = stripPalCodexRules(existing);
+  return cleaned ? `${cleaned}\n` : "";
+}
+
 // --- TELOS scaffolding ---
 
 /** Copy template files into telos/ without overwriting existing ones */