portable-agent-layer 0.85.7 → 0.85.9

package/package.json

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

package/src/cli/doctor-tools.ts

@@ -0,0 +1,133 @@
+/**
+ * The doctor's git and gh checks. Neither is required: without git, project
+ * matching by remote and the update checks skip; without gh, nothing does yet.
+ */
+
+import { readFileSync } from "node:fs";
+import { findBinaryOnPath } from "../hooks/lib/which";
+
+export interface DoctorLine {
+  level: "ok" | "warn" | "info";
+  text: string;
+}
+
+type LinuxFamily = "debian" | "fedora" | "arch" | "alpine" | "suse";
+
+interface Host {
+  platform: NodeJS.Platform;
+  osRelease: string;
+  timeoutMs: number;
+}
+
+const GH_LINUX_DOCS = "https://github.com/cli/cli/blob/trunk/docs/install_linux.md";
+
+function osReleaseIds(osRelease: string): string[] {
+  const field = (key: string) =>
+    osRelease.match(new RegExp(String.raw`^${key}="?([^"\n]*)"?$`, "m"))?.[1] ?? "";
+  return `${field("ID")} ${field("ID_LIKE")}`.split(/\s+/).filter(Boolean);
+}
+
+function linuxFamily(osRelease: string): LinuxFamily | null {
+  const ids = osReleaseIds(osRelease);
+  const families: [LinuxFamily, string[]][] = [
+    ["debian", ["debian", "ubuntu"]],
+    ["fedora", ["fedora", "rhel", "centos"]],
+    ["arch", ["arch"]],
+    ["alpine", ["alpine"]],
+    ["suse", ["suse", "opensuse"]],
+  ];
+  return families.find(([, names]) => names.some((n) => ids.includes(n)))?.[0] ?? null;
+}
+
+const GIT_ON_LINUX: Record<LinuxFamily, string> = {
+  debian: "sudo apt install git",
+  fedora: "sudo dnf install git",
+  arch: "sudo pacman -S git",
+  alpine: "sudo apk add git",
+  suse: "sudo zypper install git",
+};
+
+const GH_ON_LINUX: Partial<Record<LinuxFamily, string>> = {
+  fedora: "sudo dnf install gh",
+  arch: "sudo pacman -S github-cli",
+};
+
+export function gitInstallHint(platform: NodeJS.Platform, osRelease: string): string {
+  if (platform === "win32") return "`winget install Git.Git`";
+  if (platform === "darwin") return "`brew install git` or `xcode-select --install`";
+  const family = linuxFamily(osRelease);
+  return family ? `\`${GIT_ON_LINUX[family]}\`` : "install git with your package manager";
+}
+
+export function ghInstallHint(platform: NodeJS.Platform, osRelease: string): string {
+  if (platform === "win32") return "`winget install GitHub.cli`";
+  if (platform === "darwin") return "`brew install gh`";
+  const family = linuxFamily(osRelease);
+  const command = family && GH_ON_LINUX[family];
+  return command ? `\`${command}\`` : `see ${GH_LINUX_DOCS}`;
+}
+
+function run(binary: string, args: string[], timeoutMs: number) {
+  const result = Bun.spawnSync([binary, ...args], {
+    stdout: "pipe",
+    stderr: "ignore",
+    timeout: timeoutMs,
+    windowsHide: true,
+  });
+  return {
+    answered: !result.exitedDueToTimeout,
+    ok: result.success,
+    firstLine: result.stdout.toString().trim().split("\n")[0] ?? "",
+  };
+}
+
+function installed(name: string, timeoutMs: number) {
+  const binary = findBinaryOnPath(name);
+  if (!binary) return null;
+  const version = run(binary, ["--version"], timeoutMs);
+  return version.ok ? { binary, version: version.firstLine } : null;
+}
+
+function gitLine(host: Host): DoctorLine {
+  const git = installed("git", host.timeoutMs);
+  if (git) return { level: "ok", text: git.version };
+  return {
+    level: "warn",
+    text: `git — not found; project matching by remote, the update check and auto-update skip without it. ${gitInstallHint(host.platform, host.osRelease)}`,
+  };
+}
+
+function ghLine(host: Host): DoctorLine {
+  const gh = installed("gh", host.timeoutMs);
+  if (!gh)
+    return {
+      level: "info",
+      text: `gh — not installed (optional; lets PAL see PR, CI and release state — ${ghInstallHint(host.platform, host.osRelease)})`,
+    };
+  const auth = run(gh.binary, ["auth", "status"], host.timeoutMs);
+  if (!auth.answered)
+    return { level: "info", text: `${gh.version} — could not check the login in time` };
+  if (!auth.ok)
+    return {
+      level: "warn",
+      text: `${gh.version} — not logged in; run \`gh auth login\``,
+    };
+  return { level: "ok", text: `${gh.version}, logged in` };
+}
+
+function readOsRelease(): string {
+  try {
+    return readFileSync("/etc/os-release", "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function versionControlLines(host: Partial<Host> = {}): DoctorLine[] {
+  const resolved: Host = {
+    platform: host.platform ?? process.platform,
+    osRelease: host.osRelease ?? (process.platform === "linux" ? readOsRelease() : ""),
+    timeoutMs: host.timeoutMs ?? 5000,
+  };
+  return [gitLine(resolved), ghLine(resolved)];
+}

package/src/cli/index.ts

@@ -56,6 +56,7 @@ import { telosStatus } from "../hooks/lib/telos-topics";
 import { findBinaryOnPath } from "../hooks/lib/which";
 import { log } from "../targets/lib";
 import { builtinToolVerbs, runBuiltinTool } from "./builtin-tools";
+import { versionControlLines } from "./doctor-tools";
 import { checkPendingMigrations } from "./migrate";
 import { findSessionAgent, NO_SESSION_AGENT_MESSAGE } from "./session-agent";
 
@@ -842,6 +843,8 @@ function doctor(silent = false): DoctorResult {
       : info(
           `rtk — not installed (optional; enables Bash output compression — ${rtkInstallHint()})`
         );
+    const print = { ok, warn, info };
+    for (const line of versionControlLines()) print[line.level](line.text);
 
     console.log("");
     log.info("PAL state");

package/src/cli/migrate.ts

@@ -12,7 +12,6 @@
 
 import {
   existsSync,
-  mkdirSync,
   readdirSync,
   readFileSync,
   renameSync,
@@ -22,7 +21,7 @@ import {
 } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { readBindings } from "../hooks/lib/bindings";
-import { mergeJsonlLines } from "../hooks/lib/import-merge";
+import { foldHistoryInto } from "../hooks/lib/parked-history";
 import { palHome, paths } from "../hooks/lib/paths";
 import {
   legacyJsonToProgress,
@@ -55,6 +54,8 @@ interface Migration {
   description: string;
   check(): { pending: boolean; detail?: string };
   run(dryRun?: boolean): MigrationResult;
+  /** Moves its sources rather than copying them, so there is nothing left to delete. */
+  movesSources?: true;
 }
 
 // ── v1-projects: JSON progress files → ISA.md ─────────────────────
@@ -588,15 +589,6 @@ function destinationFor(item: StrandedHistory): string {
     : resolve(paths.unboundHistory(), `${item.slug}.jsonl`);
 }
 
-/** Union both sides so a destination that already has history keeps it. */
-function foldHistoryInto(target: string, source: string): number {
-  const local = existsSync(target) ? readFileSync(target, "utf-8") : "";
-  const { text, added } = mergeJsonlLines(local, readFileSync(source, "utf-8"));
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, text, "utf-8");
-  return added;
-}
-
 function discardEmptyFolder(dir: string): void {
   try {
     if (readdirSync(dir).length === 0) rmdirSync(dir);
@@ -608,6 +600,7 @@ function discardEmptyFolder(dir: string): void {
 const v6HistorySlugs: Migration = {
   id: "v6-history-slugs",
   description: "Re-file session history keyed on a cwd name onto its owning project",
+  movesSources: true,
 
   check() {
     const stranded = strandedHistory();
@@ -728,7 +721,7 @@ export function runMigrate(args: string[]): void {
   console.log(
     `  ${dryRun ? "Would migrate" : "Migrated"}: ${totalMigrated} | Skipped: ${totalSkipped}`
   );
-  if (!dryRun && totalMigrated > 0) {
+  if (!dryRun && totalMigrated > 0 && pending.some((m) => !m.movesSources)) {
     console.log("  Source files preserved — delete manually once verified.");
   }
   console.log("");

package/src/hooks/lib/bindings.ts

@@ -20,6 +20,7 @@
 import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { adoptParkedHistory } from "./parked-history";
 import { palHome, toPath } from "./paths";
 
 /** Project name → absolute path on this machine. */
@@ -91,6 +92,7 @@ export function writeBindings(bindings: Bindings, home: string = palHome()): voi
   const sorted: Bindings = {};
   for (const key of Object.keys(bindings).sort()) sorted[key] = bindings[key];
   writeFileSync(bindingsFilePath(home), `${JSON.stringify(sorted, null, 2)}\n`);
+  adoptParkedHistory(sorted, home);
 }
 
 /** The absolute path this machine has for `project`, or null when unbound. */

package/src/hooks/lib/parked-history.ts

@@ -0,0 +1,59 @@
+/**
+ * History from a directory no project claimed is parked under the directory's
+ * name. Once exactly one project is bound to a directory of that name, the
+ * parked history is its own and moves in.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { mergeJsonlLines } from "./import-merge";
+import { logError } from "./log";
+
+type Bindings = Record<string, string>;
+
+/** Union both sides so a destination that already has history keeps it. */
+export function foldHistoryInto(target: string, source: string): number {
+  const local = existsSync(target) ? readFileSync(target, "utf-8") : "";
+  const { text, added } = mergeJsonlLines(local, readFileSync(source, "utf-8"));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, text, "utf-8");
+  return added;
+}
+
+/** The project bound to a directory named `slug`, when exactly one is. */
+function projectBoundUnder(slug: string, bindings: Bindings): string | null {
+  const owners = Object.entries(bindings).filter(([, path]) => basename(path) === slug);
+  return owners.length === 1 ? owners[0][0] : null;
+}
+
+function parkedDir(home: string): string {
+  return resolve(home, "memory", "state", "unbound-history");
+}
+
+function recordedProjectDir(home: string, project: string): string | null {
+  const dir = resolve(home, "memory", "projects", project);
+  return existsSync(resolve(dir, "ISA.md")) ? dir : null;
+}
+
+export function adoptParkedHistory(bindings: Bindings, home: string): void {
+  const dir = parkedDir(home);
+  if (!existsSync(dir)) return;
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".jsonl"))) {
+    const owner = projectBoundUnder(file.slice(0, -".jsonl".length), bindings);
+    const projectDir = owner && recordedProjectDir(home, owner);
+    if (!projectDir) continue;
+    try {
+      foldHistoryInto(resolve(projectDir, "history.jsonl"), resolve(dir, file));
+      unlinkSync(resolve(dir, file));
+    } catch (err) {
+      logError("parked-history:adopt", err);
+    }
+  }
+}

package/src/hooks/lib/projects.ts

@@ -267,11 +267,6 @@ export function writeProject(p: ProjectProgress): void {
     const detected = detectRemote(p.path);
     if (detected) p.remote = detected;
   }
-  // Only a path that exists here may be bound. Saving a record is not a claim
-  // about this machine's disk — `path` may have arrived from an imported record
-  // written elsewhere, and binding it would recreate the very leak bindings exist
-  // to prevent. An explicit `writeBinding` from the user stays unguarded.
-  if (p.path && existsSync(p.path)) writeBinding(p.name, p.path);
   const meta: Record<string, unknown> = {
     name: p.name,
     status: p.status,
@@ -290,6 +285,11 @@ export function writeProject(p: ProjectProgress): void {
   if (p.placed) meta.placed = p.placed;
   if (p.placed_by) meta.placed_by = p.placed_by;
   writeFileSync(ensureAndGetIsaFile(p.name), stringify(meta, buildBody(p)), "utf-8");
+  // Only a path that exists here may be bound. Saving a record is not a claim
+  // about this machine's disk — `path` may have arrived from an imported record
+  // written elsewhere, and binding it would recreate the very leak bindings exist
+  // to prevent. An explicit `writeBinding` from the user stays unguarded.
+  if (p.path && existsSync(p.path)) writeBinding(p.name, p.path);
 }
 
 export function deleteProject(name: string): boolean {