portable-agent-layer 0.41.1 → 0.42.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/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")),

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,28 +328,7 @@ 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;
 }