portable-agent-layer 0.85.9 → 0.85.11

package/README.md

@@ -81,7 +81,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 |
+| `pal cli doctor` | Find what is wrong and the command that fixes each problem (`--verbose` lists every check, `--json` for agents); exits 1 on any failure |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |

package/assets/skills/consulting-report/SKILL.md

@@ -87,7 +87,7 @@ Wraps `bun run dev` in the report directory. Open the URL printed by Next, edit
 ### 4. Render the PDF
 
 ```bash
-pal cli skill run consulting-report generate-pdf.mjs <report-dir>
+pal cli skill run consulting-report generate-pdf <report-dir>
 ```
 
 Runs `next build` (which produces a static export at `out/`), then Playwright loads it via a tiny in-process HTTP server and prints the PDF with page-numbered header/footer. Output:
@@ -98,8 +98,6 @@ Runs `next build` (which produces a static export at `out/`), then Playwright lo
 
 Override with `--pdf <path>`. Pass `--skip-build` to re-render the PDF from the existing `out/` without re-building.
 
-Run with **Node**, not Bun — Playwright's `chromium.launch()` hangs under Bun on Windows.
-
 ## Directory Layout
 
 ```
@@ -149,14 +147,13 @@ Run with **Node**, not Bun — Playwright's `chromium.launch()` hangs under Bun
 ## Demo
 
 ```bash
-pal cli skill run consulting-report generate-pdf.mjs ~/.pal/skills/consulting-report/demo
+pal cli skill run consulting-report generate-pdf ~/.pal/skills/consulting-report/demo
 ```
 
 Renders the bundled Acme Industries example end-to-end. Inspect the resulting PDF to see the full layout before authoring your own.
 
 ## Important
 
-- Runs on Node (Playwright); the tool ships as a compiled `.mjs`, and `pal cli skill run` picks Node for that extension so no `--experimental-strip-types` is needed
 - Bundled fonts come from Google Fonts via `next/font/google` — no licensing surface, no CDN at runtime, glyphs embedded at build time
 - Reports are disposable artifacts of `lib/report-data.ts` + `app/page.tsx`; commit the source, not the PDF
 - The scaffolder runs `bun install` inside the target by default — pass `--no-install` to skip

package/assets/skills/consulting-report/tools/generate-pdf.ts

@@ -1,25 +1,18 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 
 // consulting-report skill tool: build the Next.js report and render it to PDF.
 // Pipeline: `next build` produces a static export at out/ — Playwright loads
 // out/index.html and prints a PDF with branded header/footer/page numbers.
 //
-// Run with Node (not Bun) — Playwright's chromium.launch() hangs under Bun on
-// Windows because it uses --remote-debugging-pipe over stdio and Bun's Windows
-// child-process pipe handling doesn't complete the CDP handshake.
-//
-// pal-build:mjs — ships as a compiled generate-pdf.mjs sibling (scripts/build-skill-tools.ts)
-// and is invoked as that .mjs: a .ts under node_modules can't be type-stripped by Node.
-//
 // Usage:
-//   pal cli skill run consulting-report generate-pdf.mjs <report-dir> [--pdf <out>] [--html <out>] [--skip-build]
+//   pal cli skill run consulting-report generate-pdf <report-dir> [--pdf <out>] [--html <out>] [--skip-build]
 
 import { spawnSync } from "node:child_process";
-import { createReadStream, constants as fsConstants, realpathSync } from "node:fs";
+import { createReadStream, constants as fsConstants } from "node:fs";
 import { access, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Server } from "node:http";
 import { extname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { pathToFileURL } from "node:url";
 import { PDFDocument } from "pdf-lib";
 import { chromium } from "playwright";
 
@@ -312,22 +305,4 @@ async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
   console.log(`PDF:  ${pdfPath} (${(pdfStat.size / 1024).toFixed(1)} KB)`);
 }
 
-// Node ≥ 22.6 doesn't expose import.meta.main; gate on argv[1] instead.
-// Use realpathSync on both sides so symlinked skill paths (e.g. ~/.pal/skills →
-// PAL repo) match the resolved import.meta.url.
-// fileURLToPath, never new URL().pathname: on Windows the latter yields
-// "/C:/Users/..." — leading slash, forward slashes — which can never equal argv[1]'s
-// "C:\Users\...", so the gate silently failed and run() never executed there.
-function realResolve(p: string): string {
-  try {
-    return realpathSync(resolve(p));
-  } catch {
-    return resolve(p);
-  }
-}
-const isMain =
-  process.argv[1] &&
-  realResolve(process.argv[1]) === realResolve(fileURLToPath(import.meta.url));
-if (isMain) {
-  await run();
-}
+if (import.meta.main) await run();

package/assets/skills/consulting-report/tools/scaffold.ts

@@ -100,7 +100,7 @@ async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
   console.log(`  2. Edit lib/report-data.ts (metadata) and app/page.tsx (layout)`);
   console.log(`  3. Live preview:    bun run dev`);
   console.log(
-    `  4. Generate PDF:    pal cli skill run consulting-report generate-pdf.mjs ${opts.targetDir}`
+    `  4. Generate PDF:    pal cli skill run consulting-report generate-pdf ${opts.targetDir}`
   );
 }
 

package/assets/skills/create-pdf/SKILL.md

@@ -68,13 +68,13 @@ Invoke the skill tool. Flags:
 Single-file example:
 
 ```bash
-pal cli skill run create-pdf md-to-html-pdf.mjs /path/to/report.md --pdf /path/to/report.pdf
+pal cli skill run create-pdf md-to-html-pdf /path/to/report.md --pdf /path/to/report.pdf
 ```
 
 Multi-file example (after Step 2):
 
 ```bash
-pal cli skill run create-pdf md-to-html-pdf.mjs /tmp/combined.md --pdf /path/to/report.pdf --html /path/to/report.html
+pal cli skill run create-pdf md-to-html-pdf /tmp/combined.md --pdf /path/to/report.pdf --html /path/to/report.html
 ```
 
 The tool writes the self-contained HTML (inline CSS, UTF-8) and the PDF, and prints both paths + sizes on stdout.
@@ -95,13 +95,13 @@ Default styling (A4, 25mm margins, GitHub-ish look, table-friendly, page-break-a
 - `--header <html|file>` / `--footer <html|file>` — running header/footer on every page. The value is either an inline HTML string or a path to an HTML file. Templates may use Playwright's injected classes: `pageNumber`, `totalPages`, `date`, `title`, `url`.
 
 ```bash
-pal cli skill run create-pdf md-to-html-pdf.mjs report.md --pdf report.pdf \
+pal cli skill run create-pdf md-to-html-pdf report.md --pdf report.pdf \
   --margin 18mm \
   --header '<div style="font-size:9px;width:100%;text-align:center;color:#888">CONFIDENTIAL</div>' \
   --footer '<div style="font-size:9px;width:100%;text-align:right;padding-right:12mm;color:#888"><span class="pageNumber"></span>/<span class="totalPages"></span></div>'
 ```
 
-Header/footer templates **need an explicit `font-size`** (Playwright defaults them to 0) and render *inside* the page margin — widen `--margin` so they have room. Do NOT also add CSS `@page` margin-box rules; they duplicate. For deeper changes (fonts, base CSS), edit the `css` string in `tools/md-to-html-pdf.ts` (the `.mjs` is generated from it — never edit the `.mjs`).
+Header/footer templates **need an explicit `font-size`** (Playwright defaults them to 0) and render *inside* the page margin — widen `--margin` so they have room. Do NOT also add CSS `@page` margin-box rules; they duplicate. For deeper changes (fonts, base CSS), edit the `css` string in `tools/md-to-html-pdf.ts`.
 
 ## Translation Variant
 

package/assets/skills/create-pdf/tools/md-to-html-pdf.ts

@@ -1,16 +1,9 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 // create-pdf skill tool: Markdown -> HTML (marked, GFM) -> PDF (Playwright).
 // Self-contained HTML: all CSS inlined, no CDN at render time.
 //
-// Run with Node (not Bun) — Playwright's chromium.launch hangs under Bun on Windows
-// because it uses --remote-debugging-pipe over stdio and Bun's Windows child-process
-// pipe handling doesn't complete the CDP handshake.
-//
-// pal-build:mjs — ships as a compiled md-to-html-pdf.mjs sibling (scripts/build-skill-tools.ts)
-// and is invoked as that .mjs: a .ts under node_modules can't be type-stripped by Node.
-//
 // Usage:
-//   pal cli skill run create-pdf md-to-html-pdf.mjs <input.md> \
+//   pal cli skill run create-pdf md-to-html-pdf <input.md> \
 //     [--html <out.html>] [--pdf <out.pdf>] [--margin <css>] [--header <html|file>] [--footer <html|file>]
 //   --margin defaults to 25mm (all sides). --header/--footer accept inline HTML or a file path.
 

package/assets/templates/rules.codex.rules

@@ -50,18 +50,6 @@ prefix_rule(
     ],
 )
 
-prefix_rule(
-    pattern = ["node", "--experimental-strip-types", "~/.pal/skills/consulting-report/tools/generate-pdf.ts"],
-    decision = "allow",
-    justification = "PAL consulting-report PDF generation requires Node for Playwright compatibility",
-    match = [
-        "node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
-    ],
-    not_match = [
-        "node ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
-    ],
-)
-
 prefix_rule(
     pattern = ["pal", "cli", "project"],
     decision = "allow",
@@ -120,7 +108,7 @@ prefix_rule(
     justification = "A skill's own tools ship with PAL and are safe to run without repeated approval",
     match = [
         "pal cli skill run presentation build ./deck",
-        "pal cli skill run consulting-report generate-pdf.mjs ./report",
+        "pal cli skill run consulting-report generate-pdf ./report",
     ],
     not_match = [
         "pal cli skill link my-skill",

package/assets/templates/settings.claude.json

@@ -34,7 +34,6 @@
       "Bash(rtk gain *)",
       "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
       "Bash(bun ~/.pal/tools/*.ts *)",
-      "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)",
       "Bash(pal cli skill run *)",
       "Bash(pal cli algorithm-reflect *)",
       "Bash(pal cli algorithm-synthesize *)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.85.9",
+  "version": "0.85.11",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -55,10 +55,9 @@
     "secretlint": "secretlint \"**/*\"",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
-    "build:skill-tools": "bun run scripts/build-skill-tools.ts",
     "build:ui": "bun run --filter @pal/control-room-ui build",
     "dev:ui": "bun run --filter @pal/control-room-ui dev",
-    "prepack": "bun run build:skill-tools && bun run build:ui",
+    "prepack": "bun run build:ui",
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:synthesize": "bun run src/tools/agent/synthesize.ts",

package/src/cli/doctor/agents.ts

@@ -0,0 +1,336 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { palPkg, platform } from "../../hooks/lib/paths";
+import { NO_SESSION_AGENT_MESSAGE } from "../session-agent";
+import { type Finding, failing, optional, passed, warning } from "./finding";
+
+export type AgentName = "claude" | "opencode" | "cursor" | "copilot" | "codex";
+
+const AGENT_NAMES: AgentName[] = ["claude", "codex", "copilot", "cursor", "opencode"];
+
+export interface ToolCheck {
+  name: string;
+  available: boolean;
+  version?: string;
+}
+
+export interface DoctorResult {
+  bun: ToolCheck;
+  claude: ToolCheck;
+  opencode: ToolCheck;
+  cursor: ToolCheck;
+  copilot: ToolCheck;
+  codex: ToolCheck;
+  rtk: ToolCheck;
+  hasAgent: boolean;
+}
+
+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 };
+}
+
+/**
+ * Copilot ships as a VS Code extension as well as a CLI, and the extension puts
+ * no `copilot` binary on PATH — but both read hooks, skills and agents out of
+ * ~/.copilot. Fall back to that directory so PAL's copilot checks still run.
+ */
+function checkCopilot(): ToolCheck {
+  const cli = checkTool("copilot", ["version"]);
+  if (cli.available) return cli;
+  if (existsSync(platform.copilotDir())) {
+    return { name: "copilot", available: true, version: "~/.copilot (no CLI on PATH)" };
+  }
+  return cli;
+}
+
+/**
+ * The Cursor CLI installs `cursor-agent` (and `agent`) and no `cursor` command;
+ * `cursor` is the editor's shell command. Both read ~/.cursor, so either counts.
+ */
+function checkCursor(): ToolCheck {
+  const cli = checkTool("cursor-agent");
+  if (cli.available) return cli;
+  return checkTool("cursor");
+}
+
+export function detectAgents(): DoctorResult {
+  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 },
+      cursor: { name: "cursor", available: true },
+      copilot: { name: "copilot", available: true },
+      codex: { name: "codex", available: true },
+      rtk: { name: "rtk", available: true },
+      hasAgent: true,
+    };
+  }
+  const claude = checkTool("claude");
+  const opencode = checkTool("opencode");
+  const cursor = checkCursor();
+  const copilot = checkCopilot();
+  const codex = checkTool("codex");
+  return {
+    bun: { name: "bun", available: true, version: Bun.version },
+    claude,
+    opencode,
+    cursor,
+    copilot,
+    codex,
+    rtk: checkTool("rtk"),
+    hasAgent: [claude, opencode, cursor, copilot, codex].some((tool) => tool.available),
+  };
+}
+
+export function installedAgents(result: DoctorResult): AgentName[] {
+  return AGENT_NAMES.filter((name) => result[name].available);
+}
+
+interface AgentLayout {
+  label: string;
+  skillsDir: () => string;
+  hookFile?: () => string;
+  instructions?: { file: () => string; name: string };
+}
+
+const LAYOUT: Record<AgentName, AgentLayout> = {
+  claude: {
+    label: "Claude Code",
+    skillsDir: () => resolve(platform.claudeDir(), "skills"),
+    hookFile: () => resolve(platform.claudeDir(), "settings.json"),
+    instructions: {
+      file: () => resolve(platform.claudeDir(), "CLAUDE.md"),
+      name: "CLAUDE.md",
+    },
+  },
+  codex: {
+    label: "Codex",
+    skillsDir: () => resolve(platform.codexDir(), "skills"),
+    hookFile: () => resolve(platform.codexDir(), "hooks.json"),
+  },
+  copilot: {
+    label: "Copilot",
+    skillsDir: () => resolve(platform.copilotDir(), "skills"),
+    hookFile: () => resolve(platform.copilotDir(), "hooks", "pal-hooks.json"),
+  },
+  cursor: {
+    label: "Cursor",
+    skillsDir: () => resolve(platform.cursorDir(), "skills"),
+    hookFile: () => resolve(platform.cursorDir(), "hooks.json"),
+  },
+  opencode: {
+    label: "opencode",
+    skillsDir: () => resolve(platform.agentsDir(), "skills"),
+  },
+};
+
+const reinstall = (agent: AgentName) => ({
+  say: `Reinstall PAL for ${LAYOUT[agent].label}`,
+  command: `pal cli install --${agent}`,
+});
+
+/** Hook-config keys that carry a shell command: cross-platform and per-shell variants. */
+function isHookCommandField(key: string): boolean {
+  return key === "command" || key === "bash" || key === "powershell";
+}
+
+function extractAllHookCommands(obj: unknown, out: string[] = []): string[] {
+  if (Array.isArray(obj)) {
+    for (const item of obj) extractAllHookCommands(item, out);
+  } else if (obj && typeof obj === "object") {
+    for (const [k, v] of Object.entries(obj)) {
+      if (isHookCommandField(k) && typeof v === "string") {
+        out.push(v);
+      } else {
+        extractAllHookCommands(v, out);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * True when a hook command names its agent, by env prefix or by argv flag.
+ *
+ * An env prefix only parses in one shell family, so hook configs whose host
+ * shell is unknown declare the agent with a shell-agnostic `--agent=` flag.
+ */
+function declaresAgent(cmd: string, agentName: string): boolean {
+  return (
+    cmd.startsWith(`PAL_AGENT=${agentName} `) ||
+    cmd.startsWith(`$env:PAL_AGENT='${agentName}'; `) ||
+    cmd.includes(`--agent=${agentName}`)
+  );
+}
+
+const SCRIPT =
+  /"([^"]+\.(?:ts|js|mjs|sh|ps1))"|'([^']+\.(?:ts|js|mjs|sh|ps1))'|(\S+\.(?:ts|js|mjs|sh|ps1))(?=\s|$)/g;
+
+function scriptPaths(cmd: string): string[] {
+  return Array.from(cmd.matchAll(SCRIPT), (m) => m[1] ?? m[2] ?? m[3] ?? "").filter(
+    isAbsolute
+  );
+}
+
+function isPalHook(cmd: string, agent: AgentName): boolean {
+  return (
+    declaresAgent(cmd, agent) ||
+    scriptPaths(cmd).some((path) => /[\\/]src[\\/]hooks[\\/][^\\/]+$/.test(path))
+  );
+}
+
+function readHookCommands(file: string): string[] | "missing" | "unreadable" {
+  if (!existsSync(file)) return "missing";
+  try {
+    const data = JSON.parse(readFileSync(file, "utf-8"));
+    return extractAllHookCommands(data.hooks ?? data);
+  } catch {
+    return "unreadable";
+  }
+}
+
+function hookFindings(agent: AgentName, file: string): Finding[] {
+  const label = LAYOUT[agent].label;
+  const commands = readHookCommands(file);
+  if (commands === "unreadable")
+    return [
+      failing(
+        `${agent}.hooks.unreadable`,
+        `${label} hook config is not valid JSON (${file})`,
+        {
+          say: `Fix the JSON in ${file}, then reinstall`,
+          command: `pal cli install --${agent}`,
+        }
+      ),
+    ];
+  const pal = commands === "missing" ? [] : commands.filter((c) => isPalHook(c, agent));
+  if (!pal.some((c) => c.includes("LoadContext")))
+    return [
+      failing(
+        `${agent}.hooks.missing`,
+        `${label} hooks are not registered`,
+        reinstall(agent)
+      ),
+    ];
+
+  const findings = [passed(`${agent}.hooks`, `${label}: ${pal.length} hooks registered`)];
+  const undeclared = pal.filter((c) => !declaresAgent(c, agent));
+  if (undeclared.length > 0)
+    findings.push(
+      failing(
+        `${agent}.hooks.undeclared`,
+        `${label}: ${undeclared.length} of ${pal.length} hooks do not name ${agent} as their agent`,
+        reinstall(agent)
+      )
+    );
+  const broken = pal.filter((c) => scriptPaths(c).some((path) => !existsSync(path)));
+  if (broken.length > 0)
+    findings.push(
+      failing(
+        `${agent}.hooks.scripts`,
+        `${label}: ${broken.length} of ${pal.length} hooks run a script that no longer exists (${scriptPaths(broken[0]).find((p) => !existsSync(p))})`,
+        reinstall(agent)
+      )
+    );
+  return findings;
+}
+
+function opencodePluginFindings(): Finding[] {
+  const installed = resolve(platform.opencodeDir(), "plugins", "pal-plugin.ts");
+  const source = resolve(palPkg(), "src", "targets", "opencode", "plugin.ts");
+  if (!existsSync(installed))
+    return [
+      failing(
+        "opencode.hooks.missing",
+        "opencode plugin is not installed",
+        reinstall("opencode")
+      ),
+    ];
+  if (existsSync(source) && statSync(installed).mtimeMs < statSync(source).mtimeMs)
+    return [
+      warning(
+        "opencode.plugin.stale",
+        "opencode plugin is older than PAL's — recent fixes have not reached opencode",
+        reinstall("opencode")
+      ),
+    ];
+  return [passed("opencode.hooks", "opencode plugin installed and current")];
+}
+
+function countSkills(dir: string): number {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => existsSync(resolve(dir, f, "SKILL.md"))).length;
+}
+
+function oneAgentFindings(agent: AgentName): Finding[] {
+  const layout = LAYOUT[agent];
+  const skills = countSkills(layout.skillsDir());
+  const findings = [
+    skills > 0
+      ? passed(`${agent}.skills`, `${layout.label}: ${skills} skills`)
+      : warning(`${agent}.skills`, `${layout.label} has no PAL skills`, reinstall(agent)),
+  ];
+  findings.push(
+    ...(layout.hookFile
+      ? hookFindings(agent, layout.hookFile())
+      : opencodePluginFindings())
+  );
+  if (layout.instructions) {
+    const { file, name } = layout.instructions;
+    findings.push(
+      existsSync(file())
+        ? passed(`${agent}.instructions`, `${name} present`)
+        : failing(`${agent}.instructions`, `${name} is missing`, reinstall(agent))
+    );
+  }
+  return findings;
+}
+
+export function agentFindings(agents: AgentName[]): Finding[] {
+  if (agents.length === 0) return [];
+  const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
+  return [
+    existsSync(agentsMd)
+      ? passed("agents-md", "AGENTS.md present")
+      : failing("agents-md", "AGENTS.md is missing", {
+          say: "Reinstall PAL",
+          command: "pal cli install",
+        }),
+    ...agents.flatMap(oneAgentFindings),
+  ];
+}
+
+export function rosterFindings(agents: AgentName[]): Finding[] {
+  if (agents.length === 0)
+    return [
+      failing("agents.none", "No supported agent is installed", {
+        say: NO_SESSION_AGENT_MESSAGE,
+      }),
+    ];
+  const others = AGENT_NAMES.filter((name) => !agents.includes(name));
+  if (others.length === 0) return [];
+  return [
+    optional(
+      "agents.others",
+      `Other agents PAL supports — ${others.map((name) => LAYOUT[name].label).join(", ")}`,
+      {
+        say: `install it, then run pal cli install --${others.length === 1 ? others[0] : "<agent>"}`,
+      }
+    ),
+  ];
+}