portable-agent-layer 0.2.1 → 0.3.0

package/README.md

@@ -30,7 +30,10 @@ With PAL, you can:
 
 ### Prerequisites
 
+> **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
+
 - [Bun](https://bun.sh) >= 1.3.0
+- At least one of: [Claude Code](https://claude.ai/code) or [opencode](https://opencode.ai)
 
 ### Package mode (recommended)
 
@@ -77,6 +80,7 @@ pal cli status        # check your setup
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |
+| `pal cli doctor` | Check prerequisites and system health |
 
 ### Target flags
 
@@ -111,6 +115,27 @@ pal cli install               # both (default)
 
 ---
 
+## Skills
+
+PAL ships with built-in skills that extend your agent's capabilities:
+
+| Skill | Description |
+|-------|-------------|
+| `analyze-pdf` | Download and analyze PDF files |
+| `analyze-youtube` | Analyze YouTube videos using Gemini |
+| `council` | Multi-perspective parallel debate on decisions |
+| `create-skill` | Scaffold a new skill from a description |
+| `extract-entities` | Extract people and companies from content |
+| `extract-wisdom` | Extract structured insights from content |
+| `first-principles` | Break down problems to fundamentals |
+| `fyzz-chat-api` | Query Fyzz Chat conversations via API |
+| `reflect` | Diagnose why a PAL behavior didn't trigger |
+| `research` | Multi-agent parallel research |
+| `review` | Security-focused code review |
+| `summarize` | Structured summarization |
+
+---
+
 ## Core idea
 
 PAL stands for **Portable Agent Layer**.

package/package.json

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

package/src/cli/index.ts

@@ -13,6 +13,7 @@
  *   export [path] [--dry-run]         Export user state to zip
  *   import [path] [--dry-run]         Import user state from zip
  *   status                            Show current PAL configuration
+ *   doctor                            Check prerequisites and system health
  */
 
 import { spawnSync } from "node:child_process";
@@ -35,18 +36,53 @@ if (allArgs[0] === "cli") {
   await session(allArgs);
 }
 
-// ── Session: pal [claude-args] ──
+// ── Session: pal [args] ──
 
-async function session(claudeArgs: string[]) {
-  // Run claude with all args, inheriting stdio for interactive TTY
-  const result = spawnSync("claude", claudeArgs, {
+interface ToolCheck {
+  name: string;
+  available: boolean;
+  version?: string;
+}
+
+function checkTool(cmd: string, versionArgs: string[] = ["--version"]): ToolCheck {
+  try {
+    const result = spawnSync(cmd, versionArgs, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      timeout: 5000,
+    });
+    if (result.status === 0) {
+      const version = (result.stdout?.toString() || "").trim().split("\n")[0];
+      return { name: cmd, available: true, version };
+    }
+  } catch {
+    // not found
+  }
+  return { name: cmd, available: false };
+}
+
+function detectAgent(): string | null {
+  if (checkTool("claude").available) return "claude";
+  if (checkTool("opencode").available) return "opencode";
+  return null;
+}
+
+async function session(sessionArgs: string[]) {
+  const agent = detectAgent();
+  if (!agent) {
+    log.error("No supported agent found. Install Claude Code or opencode.");
+    process.exit(1);
+  }
+
+  const result = spawnSync(agent, sessionArgs, {
     stdio: "inherit",
     shell: true,
   });
 
   const exitCode = result.status ?? 1;
 
-  // Find the most recent transcript and extract session ID
+  // Session summary (Claude only)
+  if (agent !== "claude") process.exit(exitCode);
   try {
     const projectsDir = resolve(homedir(), ".claude", "projects");
     if (!existsSync(projectsDir)) process.exit(exitCode);
@@ -98,7 +134,7 @@ async function runCli(command: string | undefined, args: string[]) {
       break;
     case "install":
       banner();
-      await install(parseTargets(args));
+      await install(resolveTargets(args));
       break;
     case "uninstall":
       await uninstall(args);
@@ -112,6 +148,9 @@ async function runCli(command: string | undefined, args: string[]) {
     case "status":
       await status();
       break;
+    case "doctor":
+      doctor();
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -148,6 +187,7 @@ function showHelp() {
     pal cli export [path] [--dry-run]       Export state to zip
     pal cli import [path] [--dry-run]       Import state from zip
     pal cli status                          Show PAL configuration
+    pal cli doctor                          Check prerequisites and health
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -176,6 +216,103 @@ function parseTargets(args: string[]): {
   return { claude, opencode };
 }
 
+/** Resolve targets against available agents. Errors if explicitly requested but missing. */
+function resolveTargets(
+  args: string[],
+  health?: DoctorResult
+): { claude: boolean; opencode: boolean } {
+  const requested = parseTargets(args);
+  const h = health || doctor(true);
+  const explicit = args.some(
+    (a) => a === "--claude" || a === "--opencode" || a === "--all"
+  );
+
+  if (explicit) {
+    // User explicitly requested — error if not available
+    if (requested.claude && !h.claude.available) {
+      log.error("Claude Code is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    if (requested.opencode && !h.opencode.available) {
+      log.error("opencode is not installed. Run 'pal cli doctor' for details.");
+      process.exit(1);
+    }
+    return requested;
+  }
+
+  // Default (no flags) — install for available agents only
+  const targets = {
+    claude: h.claude.available,
+    opencode: h.opencode.available,
+  };
+
+  if (!targets.claude) log.info("Skipping Claude Code (not installed)");
+  if (!targets.opencode) log.info("Skipping opencode (not installed)");
+
+  return targets;
+}
+
+// ── Doctor ──
+
+interface DoctorResult {
+  bun: ToolCheck;
+  claude: ToolCheck;
+  opencode: ToolCheck;
+  hasAgent: boolean;
+}
+
+function doctor(silent = false): DoctorResult {
+  // Allow CI/tests to skip agent detection
+  if (process.env.PAL_SKIP_DOCTOR === "1") {
+    return {
+      bun: { name: "bun", available: true, version: Bun.version },
+      claude: { name: "claude", available: true },
+      opencode: { name: "opencode", available: true },
+      hasAgent: true,
+    };
+  }
+
+  const bun = { name: "bun", available: true, version: Bun.version };
+  const claude = checkTool("claude");
+  const opencode = checkTool("opencode");
+  const hasAgent = claude.available || opencode.available;
+
+  const home = palHome();
+  const isRepo = existsSync(resolve(palPkg(), ".palroot"));
+  const telosCount = (() => {
+    try {
+      return readdirSync(resolve(home, "telos")).filter((f) => f.endsWith(".md")).length;
+    } catch {
+      return 0;
+    }
+  })();
+
+  if (!silent) {
+    const ok = (msg: string) => log.info(`  \u2713 ${msg}`);
+    const fail = (msg: string) => log.warn(`  \u2717 ${msg}`);
+
+    console.log("");
+    log.info("Doctor");
+    ok(`Bun ${bun.version}`);
+    claude.available
+      ? ok(`Claude Code ${claude.version || ""}`.trim())
+      : fail("Claude Code — not found");
+    opencode.available
+      ? ok(`opencode ${opencode.version || ""}`.trim())
+      : fail("opencode — not found");
+    ok(`PAL home: ${home} (${isRepo ? "repo" : "package"} mode)`);
+    telosCount > 0 ? ok(`TELOS: ${telosCount} files`) : fail("TELOS: not scaffolded");
+
+    if (!hasAgent) {
+      console.log("");
+      log.error("No supported agent found. Install Claude Code or opencode.");
+    }
+    console.log("");
+  }
+
+  return { bun, claude, opencode, hasAgent };
+}
+
 // ── Commands ──
 
 async function init(args: string[]) {
@@ -184,6 +321,12 @@ async function init(args: string[]) {
 
   banner();
 
+  // Run doctor first — abort if no agents available
+  const health = doctor(false);
+  if (!health.hasAgent) {
+    process.exit(1);
+  }
+
   const home = palHome();
   const isRepo = existsSync(resolve(palPkg(), ".palroot"));
 
@@ -196,7 +339,9 @@ async function init(args: string[]) {
   scaffoldTelos();
   ensureSetupState();
 
-  await install(parseTargets(args));
+  // Auto-detect available targets
+  const targets = resolveTargets(args, health);
+  await install(targets);
 
   console.log("");
   const state = ensureSetupState();

package/src/hooks/StopOrchestrator.ts

@@ -6,6 +6,7 @@
  * Transcript is read from the file at transcript_path, NOT from stdin.
  */
 
+import { checkReadmeSync } from "./handlers/readme-sync";
 import { logError } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 import { runStopHandlers } from "./lib/stop";
@@ -17,6 +18,17 @@ interface StopHookInput {
   last_assistant_message?: string;
 }
 
+// Check README sync before anything else — may block the session
+try {
+  const decision = checkReadmeSync();
+  if (decision.decision === "block") {
+    console.log(JSON.stringify(decision));
+    process.exit(0);
+  }
+} catch (err) {
+  logError("StopOrchestrator:readme-sync", err);
+}
+
 const input = await readStdinJSON<StopHookInput>();
 if (!input?.transcript_path) {
   logError("StopOrchestrator", "No transcript_path in hook input");

package/src/hooks/handlers/readme-sync.ts

@@ -0,0 +1,61 @@
+/**
+ * Stop handler: check if README.md is out of sync with code.
+ *
+ * Runs git diff to see if documentable files changed in this session.
+ * If they did and README is stale, returns a block decision.
+ */
+
+import { execSync } from "node:child_process";
+import { logDebug } from "../lib/log";
+import { palPkg } from "../lib/paths";
+import { validateReadmeSync, WATCHED_PATHS } from "../lib/readme-sync";
+
+/** Check if any watched files have uncommitted changes. */
+function hasDocumentableChanges(): boolean {
+  try {
+    const diff = execSync("git diff --name-only HEAD", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const staged = execSync("git diff --name-only --cached", {
+      cwd: palPkg(),
+      encoding: "utf-8",
+    }).trim();
+
+    const changed = `${diff}\n${staged}`.split("\n").filter((f) => f.length > 0);
+
+    return changed.some((file) =>
+      WATCHED_PATHS.some((watched) => file === watched || file.startsWith(`${watched}/`))
+    );
+  } catch {
+    return false;
+  }
+}
+
+export interface ReadmeSyncDecision {
+  decision?: "block";
+  reason?: string;
+}
+
+/** Returns a block decision if README is stale, or empty object to allow stop. */
+export function checkReadmeSync(): ReadmeSyncDecision {
+  if (!hasDocumentableChanges()) {
+    logDebug("readme-sync", "No documentable changes detected");
+    return {};
+  }
+
+  logDebug("readme-sync", "Documentable files changed — validating README");
+  const result = validateReadmeSync();
+
+  if (!result.ok) {
+    logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
+    return {
+      decision: "block",
+      reason: `README.md is out of date. Please update it before finishing:\n${result.issues.map((i) => `- ${i}`).join("\n")}`,
+    };
+  }
+
+  logDebug("readme-sync", "README is in sync");
+  return {};
+}

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

@@ -18,7 +18,7 @@ import {
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { loadTelos } from "./context";
-import { assets, palHome, paths, platform } from "./paths";
+import { assets, ensureDir, palHome, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
@@ -116,6 +116,7 @@ export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
   ensureSymlink();
   if (!needsRebuild()) return false;
+  ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
   return true;
 }

package/src/hooks/lib/readme-sync.ts

@@ -0,0 +1,129 @@
+/**
+ * README sync validation — ensures README.md reflects current code surfaces.
+ *
+ * Checks CLI commands, environment variables, and skills against README content.
+ * Used by tests (CI/pre-commit) and the Stop hook (blocks session if stale).
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { palPkg } from "./paths";
+
+export interface SyncResult {
+  ok: boolean;
+  issues: string[];
+}
+
+/** Files that, when changed, should trigger a README check. */
+export const WATCHED_PATHS = [
+  "src/cli/index.ts",
+  "src/hooks/lib/paths.ts",
+  "src/hooks/lib/inference.ts",
+  "src/tools/youtube-analyze.ts",
+  "assets/skills",
+  "assets/agents",
+];
+
+/** Extract CLI command names from the switch statement in index.ts */
+function extractCliCommands(): string[] {
+  const pkg = palPkg();
+  const cliPath = resolve(pkg, "src", "cli", "index.ts");
+  if (!existsSync(cliPath)) return [];
+
+  const content = readFileSync(cliPath, "utf-8");
+  const matches = content.matchAll(/case\s+"([^"]+)":/g);
+  const commands: string[] = [];
+
+  for (const match of matches) {
+    const cmd = match[1];
+    // Skip help aliases and internal routing
+    if (["--help", "-h", "help", "cli"].includes(cmd)) continue;
+    commands.push(cmd);
+  }
+
+  return [...new Set(commands)];
+}
+
+/** Extract PAL_* env var names from paths.ts + API keys from source */
+function extractEnvVars(): string[] {
+  const pkg = palPkg();
+  const vars: Set<string> = new Set();
+
+  // PAL_* from paths.ts
+  const pathsFile = resolve(pkg, "src", "hooks", "lib", "paths.ts");
+  if (existsSync(pathsFile)) {
+    const content = readFileSync(pathsFile, "utf-8");
+    for (const match of content.matchAll(/process\.env\.(PAL_\w+)/g)) {
+      vars.add(match[1]);
+    }
+  }
+
+  // ANTHROPIC_API_KEY from inference.ts
+  const inferenceFile = resolve(pkg, "src", "hooks", "lib", "inference.ts");
+  if (existsSync(inferenceFile)) {
+    const content = readFileSync(inferenceFile, "utf-8");
+    if (content.includes("ANTHROPIC_API_KEY")) {
+      vars.add("ANTHROPIC_API_KEY");
+    }
+  }
+
+  // GEMINI_API_KEY from youtube-analyze.ts
+  const youtubeFile = resolve(pkg, "src", "tools", "youtube-analyze.ts");
+  if (existsSync(youtubeFile)) {
+    const content = readFileSync(youtubeFile, "utf-8");
+    if (content.includes("GEMINI_API_KEY")) {
+      vars.add("GEMINI_API_KEY");
+    }
+  }
+
+  return [...vars];
+}
+
+/** Extract skill names from assets/skills/ */
+function extractSkillNames(): string[] {
+  const pkg = palPkg();
+  const skillsDir = resolve(pkg, "assets", "skills");
+  if (!existsSync(skillsDir)) return [];
+
+  return readdirSync(skillsDir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""));
+}
+
+/** Validate that README.md documents all code surfaces. */
+export function validateReadmeSync(): SyncResult {
+  const pkg = palPkg();
+  const readmePath = resolve(pkg, "README.md");
+
+  if (!existsSync(readmePath)) {
+    return { ok: false, issues: ["README.md not found"] };
+  }
+
+  const readme = readFileSync(readmePath, "utf-8");
+  const issues: string[] = [];
+
+  // Check CLI commands
+  for (const cmd of extractCliCommands()) {
+    if (!readme.includes(`pal cli ${cmd}`)) {
+      issues.push(`CLI command "${cmd}" exists in code but not documented in README`);
+    }
+  }
+
+  // Check environment variables
+  for (const envVar of extractEnvVars()) {
+    if (!readme.includes(envVar)) {
+      issues.push(
+        `Environment variable "${envVar}" used in code but not documented in README`
+      );
+    }
+  }
+
+  // Check skills — just verify the count is mentioned or each name appears
+  const skills = extractSkillNames();
+  const undocumentedSkills = skills.filter((name) => !readme.includes(name));
+  if (undocumentedSkills.length > 0) {
+    issues.push(`Skills not documented in README: ${undocumentedSkills.join(", ")}`);
+  }
+
+  return { ok: issues.length === 0, issues };
+}

package/src/targets/lib.ts

@@ -48,6 +48,7 @@ export function scaffoldTelos(): void {
   const templatesDir = assets.telosTemplates();
   const telosDir = resolve(palHome(), "telos");
   if (!existsSync(templatesDir)) return;
+  mkdirSync(telosDir, { recursive: true });
 
   for (const file of readdirSync(templatesDir).filter((f) => f.endsWith(".md"))) {
     const src = resolve(templatesDir, file);