portable-agent-layer 0.16.0 → 0.18.0

package/src/tools/agent/wisdom-frame.ts

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+/**
+ * WisdomFrameUpdater — Update wisdom frames with new observations.
+ *
+ * Takes a domain and observation, updates the appropriate frame file.
+ * Creates the frame if it doesn't exist. Tracks observation count and
+ * evolution log. Principles are marked [CRYSTAL: N%] manually when
+ * confidence is high enough.
+ *
+ * Usage:
+ *   bun run tool:wisdom-frame --domain communication --observation "prefers bullet points"
+ *   bun run tool:wisdom-frame --domain development --observation "refactoring without tests caused regressions" --type anti-pattern
+ *   bun run tool:wisdom-frame --domain workflow --observation "always run type-check after edits" --type principle
+ *
+ * Types: principle, contextual-rule, anti-pattern, evolution (default)
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { paths } from "../../hooks/lib/paths";
+
+// ── Types ──
+
+type ObservationType = "principle" | "contextual-rule" | "anti-pattern" | "evolution";
+
+interface UpdateResult {
+  success: boolean;
+  domain: string;
+  type: ObservationType;
+  message: string;
+  framePath: string;
+}
+
+// ── Helpers ──
+
+function date(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function parseObservationCount(content: string): number {
+  const match = content.match(/\*\*Observation Count:\*\*\s*(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+function incrementCount(content: string): string {
+  const current = parseObservationCount(content);
+  return content.replace(/(\*\*Observation Count:\*\*\s*)\d+/, `$1${current + 1}`);
+}
+
+function updateDate(content: string): string {
+  return content.replace(/(\*\*Last Updated:\*\*\s*)\S+/, `$1${date()}`);
+}
+
+function appendToSection(
+  content: string,
+  sectionHeader: string,
+  entry: string,
+  fallbackBefore?: string
+): string {
+  const idx = content.indexOf(sectionHeader);
+
+  if (idx === -1) {
+    // Section doesn't exist — insert before fallback or at end
+    const insertAt = fallbackBefore ? content.indexOf(fallbackBefore) : -1;
+    const pos = insertAt !== -1 ? insertAt : content.length;
+    return `${content.slice(0, pos)}${sectionHeader}\n\n${entry}\n\n${content.slice(pos)}`;
+  }
+
+  // Find end of section (next ## or EOF)
+  const afterSection = content.slice(idx + sectionHeader.length);
+  const nextSection = afterSection.indexOf("\n## ");
+  const insertPoint =
+    nextSection === -1 ? content.length : idx + sectionHeader.length + nextSection;
+
+  return `${content.slice(0, insertPoint)}\n${entry}${content.slice(insertPoint)}`;
+}
+
+// ── Core Update ──
+
+export function updateFrame(
+  domain: string,
+  observation: string,
+  type: ObservationType = "evolution"
+): UpdateResult {
+  const framesDir = paths.wisdom();
+  const framePath = resolve(framesDir, `${domain}.md`);
+
+  // Create frame if it doesn't exist
+  if (!existsSync(framePath)) {
+    mkdirSync(framesDir, { recursive: true });
+
+    const content = `# Frame: ${domain.charAt(0).toUpperCase() + domain.slice(1)}
+
+## Meta
+- **Domain:** ${domain}
+- **Observation Count:** 1
+- **Last Updated:** ${date()}
+
+---
+
+## Core Principles
+
+*No crystallized principles yet. Observations accumulating.*
+
+---
+
+## Contextual Rules
+
+${type === "contextual-rule" ? `- ${observation} (${date()})` : "*None yet.*"}
+
+---
+
+## Anti-Patterns
+
+${type === "anti-pattern" ? `### ${observation}\n- **Severity:** Medium\n- **Frequency:** Observed` : "*None yet.*"}
+
+---
+
+## Evolution Log
+- ${date()}: Frame created — ${observation}
+`;
+
+    writeFileSync(framePath, content);
+    return {
+      success: true,
+      domain,
+      type,
+      message: `Created new frame "${domain}" with initial observation`,
+      framePath,
+    };
+  }
+
+  // Update existing frame
+  let content = readFileSync(framePath, "utf-8");
+  content = incrementCount(content);
+  content = updateDate(content);
+
+  const evolutionEntry = `- ${date()}: ${observation}`;
+
+  switch (type) {
+    case "anti-pattern":
+      content = appendToSection(
+        content,
+        "## Anti-Patterns",
+        `\n### ${observation}\n- **Severity:** Medium\n- **Frequency:** Observed`,
+        "## Evolution Log"
+      );
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+
+    case "contextual-rule":
+      content = appendToSection(
+        content,
+        "## Contextual Rules",
+        `- ${observation} (${date()})`,
+        "## Anti-Patterns"
+      );
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+
+    case "principle":
+      // Principles logged for manual crystallization — don't auto-add to Core Principles
+      content = appendToSection(
+        content,
+        "## Evolution Log",
+        `- ${date()}: Principle candidate — ${observation}`
+      );
+      break;
+
+    case "evolution":
+    default:
+      content = appendToSection(content, "## Evolution Log", evolutionEntry);
+      break;
+  }
+
+  writeFileSync(framePath, content);
+
+  return {
+    success: true,
+    domain,
+    type,
+    message: `Updated "${domain}" frame with ${type}: ${observation}`,
+    framePath,
+  };
+}
+
+// ── CLI ──
+
+function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      domain: { type: "string", short: "d" },
+      observation: { type: "string", short: "o" },
+      type: { type: "string", short: "t" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+WisdomFrameUpdater — Update wisdom frames with observations
+
+Usage:
+  bun run tool:wisdom-frame --domain <domain> --observation "text" [--type <type>]
+
+Domains:
+  development, workflow, communication, infrastructure, integration, or any custom domain
+
+Types:
+  principle        High-confidence pattern (logged for manual crystallization)
+  contextual-rule  Context-specific behavioral rule
+  anti-pattern     Something to avoid
+  evolution        General observation (default)
+
+Examples:
+  bun run tool:wisdom-frame -d workflow -o "always run type-check after edits"
+  bun run tool:wisdom-frame -d development -o "mocking DB hides migration bugs" -t anti-pattern
+  bun run tool:wisdom-frame -d communication -o "user prefers terse summaries" -t principle
+`);
+    process.exit(0);
+  }
+
+  if (!values.domain || !values.observation) {
+    console.error("Required: --domain and --observation");
+    process.exit(1);
+  }
+
+  const cliType = (values.type || "evolution") as ObservationType;
+  const result = updateFrame(values.domain, values.observation, cliType);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (import.meta.main) run();

package/src/tools/export.ts

@@ -10,25 +10,31 @@ import { resolve } from "node:path";
 import { collectExportFiles, exportZip, timestamp } from "../hooks/lib/export";
 import { palHome } from "../hooks/lib/paths";
 
-const args = process.argv.slice(2);
-const dryRun = args.includes("--dry-run");
-const pathArg = args.find((a) => a !== "--dry-run");
+export { collectExportFiles, exportZip };
 
-const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+function run() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const pathArg = args.find((a) => a !== "--dry-run");
 
-if (dryRun) {
-  const files = collectExportFiles();
-  if (files.length === 0) {
-    console.log("Nothing to export — no gitignored personal files found.");
-  } else {
-    console.log(`Would export ${files.length} files → ${outputPath}\n`);
-    for (const f of files) console.log(`  ${f}`);
-  }
-} else {
-  const count = exportZip(outputPath);
-  if (count === 0) {
-    console.log("Nothing to export — no gitignored personal files found.");
+  const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+
+  if (dryRun) {
+    const files = collectExportFiles();
+    if (files.length === 0) {
+      console.log("Nothing to export — no gitignored personal files found.");
+    } else {
+      console.log(`Would export ${files.length} files → ${outputPath}\n`);
+      for (const f of files) console.log(`  ${f}`);
+    }
   } else {
-    console.log(`Exported ${count} files → ${outputPath}`);
+    const count = exportZip(outputPath);
+    if (count === 0) {
+      console.log("Nothing to export — no gitignored personal files found.");
+    } else {
+      console.log(`Exported ${count} files → ${outputPath}`);
+    }
   }
 }
+
+if (import.meta.main) run();

package/src/tools/import.ts

@@ -13,53 +13,21 @@ import { createInterface } from "node:readline";
 import AdmZip from "adm-zip";
 import { palHome } from "../hooks/lib/paths";
 
-const repoRoot = palHome();
-const args = process.argv.slice(2);
-const dryRun = args.includes("--dry-run");
-const pathArg = args.find((a) => a !== "--dry-run");
+export function findLatestExport(root: string): string | null {
+  const candidates: string[] = [];
 
-async function confirm(message: string): Promise<boolean> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((res) => {
-    rl.question(`${message} [y/N] `, (answer) => {
-      rl.close();
-      res(answer.trim().toLowerCase() === "y");
-    });
-  });
-}
-
-function findLatestExport(): string | null {
-  const files = readdirSync(repoRoot)
-    .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
-    .sort()
-    .reverse();
-
-  // Also check backups/
   try {
-    const backupDir = resolve(repoRoot, "backups");
-    const backups = readdirSync(backupDir)
-      .filter(
-        (f) =>
-          (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
-          f.endsWith(".zip")
-      )
-      .map((f) => ({ name: f, path: resolve(backupDir, f) }))
-      .sort((a, b) => b.name.localeCompare(a.name));
-    if (backups.length > 0) files.push(backups[0].name);
+    candidates.push(
+      ...readdirSync(root)
+        .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
+        .map((f) => resolve(root, f))
+    );
   } catch {
-    // No backups dir
+    /* empty */
   }
 
-  if (files.length === 0) return null;
-
-  // Find the most recent by mtime across both locations
-  const candidates = [
-    ...readdirSync(repoRoot)
-      .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
-      .map((f) => resolve(repoRoot, f)),
-  ];
   try {
-    const backupDir = resolve(repoRoot, "backups");
+    const backupDir = resolve(root, "backups");
     candidates.push(
       ...readdirSync(backupDir)
         .filter(
@@ -70,54 +38,74 @@ function findLatestExport(): string | null {
         .map((f) => resolve(backupDir, f))
     );
   } catch {
-    // No backups dir
+    /* empty */
   }
 
   if (candidates.length === 0) return null;
   return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
 }
 
-// Resolve zip path
-let zipPath: string;
+export function importZip(zipPath: string, targetDir: string, dryRun: boolean): number {
+  const zip = new AdmZip(zipPath);
+  const entries = zip.getEntries();
 
-if (pathArg) {
-  zipPath = resolve(pathArg);
-} else {
-  const latest = findLatestExport();
-  if (!latest) {
-    console.error(
-      "No export or backup files found. Provide a path: bun run tool:import <path-to-zip>"
-    );
-    process.exit(1);
+  if (entries.length === 0) {
+    console.log("Archive is empty — nothing to import.");
+    return 0;
   }
-  console.log(`Found: ${latest}`);
-  const zip = new AdmZip(latest);
-  const entries = zip.getEntries();
-  console.log(
-    `Contains ${entries.length} files, created ${statSync(latest).mtime.toISOString().slice(0, 16).replace("T", " ")}`
-  );
 
-  if (!(await confirm("Import this file?"))) {
-    console.log("Cancelled.");
-    process.exit(0);
+  if (dryRun) {
+    console.log(`Would import ${entries.length} files → ${targetDir}\n`);
+    for (const e of entries) console.log(`  ${e.entryName}`);
+    return entries.length;
   }
-  zipPath = latest;
+
+  zip.extractAllTo(targetDir, true);
+  console.log(`Imported ${entries.length} files → ${targetDir}`);
+  console.log("\nRun 'bun run install:all' to re-create symlinks and hooks.");
+  return entries.length;
 }
 
-// Import
-const zip = new AdmZip(zipPath);
-const entries = zip.getEntries();
+async function run() {
+  const repoRoot = palHome();
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const pathArg = args.find((a) => a !== "--dry-run");
 
-if (entries.length === 0) {
-  console.log("Archive is empty — nothing to import.");
-  process.exit(0);
-}
+  let zipPath: string;
 
-if (dryRun) {
-  console.log(`Would import ${entries.length} files → ${repoRoot}\n`);
-  for (const e of entries) console.log(`  ${e.entryName}`);
-} else {
-  zip.extractAllTo(repoRoot, true);
-  console.log(`Imported ${entries.length} files → ${repoRoot}`);
-  console.log("\nRun 'bun run install:all' to re-create symlinks and hooks.");
+  if (pathArg) {
+    zipPath = resolve(pathArg);
+  } else {
+    const latest = findLatestExport(repoRoot);
+    if (!latest) {
+      console.error(
+        "No export or backup files found. Provide a path: bun run tool:import <path-to-zip>"
+      );
+      process.exit(1);
+    }
+    console.log(`Found: ${latest}`);
+    const zip = new AdmZip(latest);
+    const entries = zip.getEntries();
+    console.log(
+      `Contains ${entries.length} files, created ${statSync(latest).mtime.toISOString().slice(0, 16).replace("T", " ")}`
+    );
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise<string>((res) => {
+      rl.question("Import this file? [y/N] ", (a) => {
+        rl.close();
+        res(a);
+      });
+    });
+    if (answer.trim().toLowerCase() !== "y") {
+      console.log("Cancelled.");
+      process.exit(0);
+    }
+    zipPath = latest;
+  }
+
+  importZip(zipPath, repoRoot, dryRun);
 }
+
+if (import.meta.main) run();