portable-agent-layer 0.63.3 → 0.65.0

package/src/hooks/lib/anchor.ts

@@ -0,0 +1,90 @@
+/**
+ * Path anchors — `{proj:slug}/relative` instead of an absolute path.
+ *
+ * An absolute cwd stamp never matches across machines: same project,
+ * different mount, different username, different OS. An anchor replaces the
+ * absolute prefix with the project's registry slug, so resolution happens
+ * locally at read time — the same trick machine.ts uses for labels, applied
+ * to paths. Relocating a project (`project.ts set-path`) then fixes every
+ * memory that ever referenced it, because none of them stored the path.
+ */
+
+import { relative, resolve, sep } from "node:path";
+import type { ProjectProgress } from "./projects";
+import {
+  projectPathOnThisMachine,
+  readAllProjects,
+  resolveProjectFromCwd,
+} from "./projects";
+
+const ANCHOR_RE = /^\{proj:([a-z0-9_-]+)\}(\/.*)?$/;
+
+export function isAnchor(value: string): boolean {
+  return ANCHOR_RE.test(value);
+}
+
+/**
+ * Absolute path → `{proj:slug}/relative`, if it falls inside a registered
+ * project. A path outside every registered project passes through
+ * unchanged — most cwd stamps from ad hoc commands will never resolve to a
+ * project, and that is fine; they simply do not benefit yet.
+ */
+export function encodeAnchor(
+  absPath: string,
+  projects: ProjectProgress[] = readAllProjects()
+): string {
+  const proj = resolveProjectFromCwd(absPath, projects);
+  if (!proj) return absPath;
+
+  // The same effective path the resolver matched on, not the record's own field:
+  // a bound project's path lives in bindings, so anchoring off proj.path directly
+  // would measure the relative segment against the wrong root.
+  const root = projectPathOnThisMachine(proj);
+  if (!root) return absPath;
+
+  const rel = relative(root, resolve(absPath));
+  if (rel.startsWith("..")) return absPath;
+
+  const relPosix = rel.split(sep).join("/");
+  return relPosix ? `{proj:${proj.name}}/${relPosix}` : `{proj:${proj.name}}`;
+}
+
+export type AnchorResolution =
+  | { state: "anchored"; path: string }
+  | { state: "plain"; path: string }
+  | { state: "unresolvable"; slug: string };
+
+/**
+ * `{proj:slug}/relative` → absolute path on THIS machine, via the local
+ * registry. A plain (non-anchor) value is returned as-is — either an
+ * already-local absolute path, or a record captured before this feature
+ * shipped. There is no backfill, so pre-anchor records are handled exactly
+ * as they were before.
+ */
+export function resolveAnchor(
+  value: string,
+  projects: ProjectProgress[] = readAllProjects()
+): AnchorResolution {
+  const match = ANCHOR_RE.exec(value);
+  if (!match) return { state: "plain", path: value };
+
+  const [, slug, rel] = match;
+  const proj = projects.find((p) => p.name === slug);
+  if (!proj) return { state: "unresolvable", slug };
+
+  const root = projectPathOnThisMachine(proj);
+  if (!root) return { state: "unresolvable", slug };
+  const path = rel ? resolve(root, `.${rel}`) : root;
+  return { state: "anchored", path };
+}
+
+/** Does `value` (anchored or plain) refer to `cwd` on this machine? */
+export function anchorMatchesCwd(
+  value: string,
+  cwd: string,
+  projects: ProjectProgress[] = readAllProjects()
+): boolean {
+  const resolved = resolveAnchor(value, projects);
+  if (resolved.state === "unresolvable") return false;
+  return resolve(resolved.path) === resolve(cwd);
+}

package/src/hooks/lib/bindings.ts

@@ -0,0 +1,117 @@
+/**
+ * Bindings — where each project lives on THIS machine.
+ *
+ * A project record answers two questions in one field today: what the project
+ * is (portable — name, goal, criteria, decisions) and where it sits on disk
+ * (true on exactly one machine). The second answer rides inside `memory/`,
+ * which is exported, so one machine's filesystem layout travels to every other
+ * machine as though it were a fact about the project.
+ *
+ * This module holds the second answer separately. Memory becomes the union of
+ * all work; bindings are one machine's intersection with its disk, so "that
+ * project is not checked out here" turns into an ordinary state rather than a
+ * dead path.
+ *
+ * `bindings.json` lives at the PAL_HOME root for the same reason `machine.json`
+ * does: export walks `telos`, `memory`, `skills` and `agents`, so anything
+ * under those would sync and defeat the point.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+/** Project name → absolute path on this machine. */
+export type Bindings = Record<string, string>;
+
+export function bindingsFilePath(home: string = palHome()): string {
+  return resolve(home, "bindings.json");
+}
+
+/**
+ * Where the previous bindings are kept.
+ *
+ * Once a record stops storing its own path, this file is the only place a
+ * project's location lives, and it is deliberately excluded from exports — so
+ * losing it loses every location. One rolling copy of the last good content
+ * makes that recoverable by renaming a file, and never goes stale the way a
+ * one-off backup taken at migration time would.
+ */
+export function bindingsBackupPath(home: string = palHome()): string {
+  return resolve(home, "bindings.backup.json");
+}
+
+function isBindingMap(value: unknown): value is Bindings {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+/**
+ * A malformed or unreadable file reads as empty rather than throwing. Bindings
+ * are a lookup aid, so a corrupt one degrades to "nothing is bound here" — the
+ * same state a fresh machine starts in — instead of breaking every caller.
+ */
+export function readBindings(home: string = palHome()): Bindings {
+  const file = bindingsFilePath(home);
+  if (!existsSync(file)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    if (!isBindingMap(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Seeding writes on the first project read, which makes an unsandboxed test a
+ * silent writer into the developer's own ~/.pal. The suite sets PAL_TEST_SANDBOX,
+ * so refuse there and name the file — a test that forgets to point PAL_HOME at a
+ * temp dir fails loudly instead of editing the machine running it.
+ */
+function assertNotRealHomeDuringTests(home: string): void {
+  if (!process.env.PAL_TEST_SANDBOX) return;
+  if (resolve(home) !== resolve(homedir(), ".pal")) return;
+  throw new Error(
+    "Refusing to write bindings.json into the real ~/.pal during a test run. " +
+      "Point PAL_HOME at a temp directory in this test's setup."
+  );
+}
+
+export function writeBindings(bindings: Bindings, home: string = palHome()): void {
+  assertNotRealHomeDuringTests(home);
+  const file = bindingsFilePath(home);
+  // Only a differing, non-empty predecessor is worth keeping: backing up an
+  // identical file is noise, and backing up an empty one would let a bad write
+  // erase the copy that made it recoverable.
+  if (existsSync(file) && readFileSync(file, "utf-8").trim().length > 0) {
+    copyFileSync(file, bindingsBackupPath(home));
+  }
+  const sorted: Bindings = {};
+  for (const key of Object.keys(bindings).sort()) sorted[key] = bindings[key];
+  writeFileSync(bindingsFilePath(home), `${JSON.stringify(sorted, null, 2)}\n`);
+}
+
+/** The absolute path this machine has for `project`, or null when unbound. */
+export function bindingFor(project: string, home: string = palHome()): string | null {
+  return readBindings(home)[project] ?? null;
+}
+
+/** Bind `project` to `path`, replacing any existing binding for it. */
+export function writeBinding(
+  project: string,
+  path: string,
+  home: string = palHome()
+): void {
+  const bindings = readBindings(home);
+  bindings[project] = resolve(path);
+  writeBindings(bindings, home);
+}
+
+export function removeBinding(project: string, home: string = palHome()): void {
+  const bindings = readBindings(home);
+  if (!(project in bindings)) return;
+  delete bindings[project];
+  writeBindings(bindings, home);
+}

package/src/hooks/lib/export.ts

@@ -6,6 +6,7 @@
 import { existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import AdmZip from "adm-zip";
+import { ensureRegistered } from "./machine";
 import { palHome } from "./paths";
 
 /**
@@ -59,9 +60,41 @@ export function collectExportFiles(): string[] {
   return files;
 }
 
-/** Zip the given files and write to outputPath. Returns file count. */
+/** Archive metadata naming the machine that produced it. */
+export const MANIFEST_NAME = "export-manifest.json";
+
+export interface ExportManifest {
+  machineId: string;
+  label: string;
+  os: string;
+  exportedAt: string;
+  fileCount: number;
+}
+
+export function buildManifest(
+  identity: { id: string; label: string; os: string },
+  fileCount: number
+): ExportManifest {
+  return {
+    machineId: identity.id,
+    label: identity.label,
+    os: identity.os,
+    exportedAt: new Date().toISOString(),
+    fileCount,
+  };
+}
+
+/**
+ * Zip the given files and write to outputPath. Returns file count.
+ *
+ * The archive declares its source machine in a manifest. Registry entries under
+ * memory/machines/ travel with the corpus, so the manifest exists to say which
+ * machine produced THIS archive — after a merge an archive can carry entries
+ * for several machines.
+ */
 export function exportZip(outputPath: string): number {
   const root = palHome();
+  const identity = ensureRegistered(root);
   const files = collectExportFiles();
   if (files.length === 0) return 0;
 
@@ -71,6 +104,10 @@ export function exportZip(outputPath: string): number {
     const dir = file.includes("/") ? file.slice(0, file.lastIndexOf("/")) : "";
     zip.addLocalFile(fullPath, dir);
   }
+  zip.addFile(
+    MANIFEST_NAME,
+    Buffer.from(`${JSON.stringify(buildManifest(identity, files.length), null, 2)}\n`)
+  );
 
   zip.writeZip(outputPath);
   return files.length;

package/src/hooks/lib/import-merge.ts

@@ -0,0 +1,220 @@
+/**
+ * Import merge — fold an export archive into an existing PAL home without
+ * destroying local records.
+ *
+ * `extractAllTo(home, true)` overwrites every colliding path, so importing
+ * machine A onto machine B silently discards B's side of every append-only log.
+ * This module replaces that with a per-type policy:
+ *
+ *   *.jsonl      union of both sides, deduplicated by exact line
+ *   new files    written as-is
+ *   identical    no-op
+ *   diverged     local kept in place, incoming quarantined under backups/
+ *   denylisted   never written (machine identity, rebuildable indexes)
+ *
+ * Every policy is idempotent: re-importing the same archive is a no-op on the
+ * corpus.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { type ExportManifest, MANIFEST_NAME } from "./export";
+
+/** One file inside an export archive, decoupled from the zip library. */
+export interface ArchiveEntry {
+  path: string;
+  data(): Buffer;
+}
+
+export interface MergeResult {
+  created: string[];
+  merged: string[];
+  identical: string[];
+  conflicts: string[];
+  skipped: string[];
+  linesAdded: number;
+  quarantineDir: string | null;
+}
+
+/**
+ * Paths that must never cross machines. `machine.json` carries this install's
+ * identity — importing it would give two machines one id and silently break
+ * every origin-scoped read. The retrieval index is rebuilt from its sources.
+ */
+const NEVER_IMPORT = [
+  "machine.json",
+  "export-manifest.json",
+  "memory/learning/.retrieval-index.json",
+];
+
+function normalize(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+export function isNeverImport(path: string): boolean {
+  const rel = normalize(path);
+  return NEVER_IMPORT.some((deny) => rel === deny || rel.endsWith(`/${deny}`));
+}
+
+function isJsonl(path: string): boolean {
+  return normalize(path).endsWith(".jsonl");
+}
+
+function splitLines(raw: string): string[] {
+  return raw.split("\n").filter((l) => l.trim().length > 0);
+}
+
+/**
+ * Union of two JSONL bodies, local order preserved, incoming lines appended
+ * only when not already present. Exact-line identity is the dedupe key — no
+ * schema is shared across PAL's jsonl files, and every writer serializes a
+ * record the same way, so byte equality is the only key that holds for all of
+ * them.
+ */
+export function mergeJsonlLines(
+  localRaw: string,
+  incomingRaw: string
+): { text: string; added: number } {
+  const local = splitLines(localRaw);
+  const seen = new Set(local);
+  const added: string[] = [];
+  for (const line of splitLines(incomingRaw)) {
+    if (seen.has(line)) continue;
+    seen.add(line);
+    added.push(line);
+  }
+  const all = [...local, ...added];
+  return { text: all.length > 0 ? `${all.join("\n")}\n` : "", added: added.length };
+}
+
+function writeFileEnsuringDir(target: string, data: Buffer | string): void {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, data);
+}
+
+function quarantine(quarantineDir: string, rel: string, data: Buffer): void {
+  writeFileEnsuringDir(resolve(quarantineDir, rel), data);
+}
+
+/**
+ * Merge every archive entry into `home`. `quarantineDir` receives the incoming
+ * copy of any file that diverged from its local counterpart, so a conflict
+ * loses neither side.
+ */
+export function mergeArchive(
+  entries: ArchiveEntry[],
+  home: string,
+  quarantineDir: string
+): MergeResult {
+  const result: MergeResult = {
+    created: [],
+    merged: [],
+    identical: [],
+    conflicts: [],
+    skipped: [],
+    linesAdded: 0,
+    quarantineDir: null,
+  };
+
+  for (const entry of entries) {
+    const rel = normalize(entry.path);
+    if (rel.length === 0 || rel.endsWith("/")) continue;
+
+    if (isNeverImport(rel)) {
+      result.skipped.push(rel);
+      continue;
+    }
+
+    const target = resolve(home, rel);
+    const incoming = entry.data();
+
+    if (!existsSync(target)) {
+      writeFileEnsuringDir(target, incoming);
+      result.created.push(rel);
+      continue;
+    }
+
+    const localRaw = readFileSync(target);
+    if (localRaw.equals(incoming)) {
+      result.identical.push(rel);
+      continue;
+    }
+
+    if (isJsonl(rel)) {
+      const { text, added } = mergeJsonlLines(
+        localRaw.toString("utf-8"),
+        incoming.toString("utf-8")
+      );
+      writeFileSync(target, text);
+      result.merged.push(rel);
+      result.linesAdded += added;
+      continue;
+    }
+
+    quarantine(quarantineDir, rel, incoming);
+    result.conflicts.push(rel);
+    result.quarantineDir = quarantineDir;
+  }
+
+  return result;
+}
+
+/**
+ * The source machine declared by an archive's manifest, or null when the
+ * archive predates manifests.
+ */
+export function readManifest(entries: ArchiveEntry[]): ExportManifest | null {
+  const hit = entries.find((e) => normalize(e.path) === MANIFEST_NAME);
+  if (!hit) return null;
+  try {
+    const parsed = JSON.parse(hit.data().toString("utf-8")) as Partial<ExportManifest>;
+    if (typeof parsed.machineId !== "string" || parsed.machineId.length === 0)
+      return null;
+    return {
+      machineId: parsed.machineId,
+      label: parsed.label ?? parsed.machineId,
+      os: parsed.os ?? "",
+      exportedAt: parsed.exportedAt ?? "",
+      fileCount: parsed.fileCount ?? 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface ImportLogEntry {
+  ts: string;
+  archive: string;
+  mode: "merge" | "overwrite";
+  created: number;
+  merged: number;
+  identical: number;
+  conflicts: number;
+  skipped: number;
+  linesAdded: number;
+  quarantineDir: string | null;
+  sourceMachineId?: string | null;
+}
+
+/** Append one record per import so a merged corpus stays attributable. */
+export function appendImportLog(home: string, entry: ImportLogEntry): void {
+  const logPath = resolve(home, "memory", "state", "import-log.jsonl");
+  mkdirSync(dirname(logPath), { recursive: true });
+  const line = `${JSON.stringify(entry)}\n`;
+  if (existsSync(logPath)) {
+    writeFileSync(logPath, readFileSync(logPath, "utf-8") + line);
+    return;
+  }
+  writeFileSync(logPath, line);
+}
+
+export function summarize(result: MergeResult): string {
+  const parts = [
+    `${result.created.length} new`,
+    `${result.merged.length} merged (+${result.linesAdded} records)`,
+    `${result.identical.length} unchanged`,
+  ];
+  if (result.conflicts.length > 0) parts.push(`${result.conflicts.length} conflicts`);
+  if (result.skipped.length > 0) parts.push(`${result.skipped.length} skipped`);
+  return parts.join(", ");
+}