portable-agent-layer 0.85.9 → 0.85.11

package/src/cli/doctor/environment.ts

@@ -0,0 +1,129 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { palPkg } from "../../hooks/lib/paths";
+import { findBinaryOnPath } from "../../hooks/lib/which";
+import type { ToolCheck } from "./agents";
+import { type Finding, type Fix, failing, optional, passed, warning } from "./finding";
+import { osReleaseField, readOsRelease } from "./os-release";
+import { versionControlFindings } from "./version-control";
+
+interface PlaywrightBuild {
+  version: string;
+  revision: string;
+}
+
+interface BrowserHost {
+  browsersPath: string;
+  playwright: PlaywrightBuild | null;
+  platform: NodeJS.Platform;
+  arch: string;
+  osRelease: string;
+}
+
+const NEWEST_UBUNTU_PLAYWRIGHT_KNOWS = 24.04;
+
+function playwrightBrowsersPath(): string {
+  if (process.env.PLAYWRIGHT_BROWSERS_PATH) return process.env.PLAYWRIGHT_BROWSERS_PATH;
+  const home = homedir();
+  if (process.platform === "darwin") return resolve(home, "Library/Caches/ms-playwright");
+  if (process.platform === "win32") return resolve(home, "AppData/Local/ms-playwright");
+  return resolve(home, ".cache/ms-playwright");
+}
+
+function installedPlaywright(): PlaywrightBuild | null {
+  try {
+    const pkg = Bun.resolveSync("playwright-core/package.json", palPkg());
+    const { version } = JSON.parse(readFileSync(pkg, "utf-8"));
+    const { browsers } = JSON.parse(
+      readFileSync(resolve(dirname(pkg), "browsers.json"), "utf-8")
+    );
+    const shell = (browsers as { name: string; revision: string }[]).find(
+      (b) => b.name === "chromium-headless-shell"
+    );
+    return shell ? { version, revision: shell.revision } : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasChromium(host: BrowserHost): boolean {
+  if (!existsSync(host.browsersPath)) return false;
+  const dirs = readdirSync(host.browsersPath);
+  const revision = host.playwright?.revision;
+  return revision
+    ? dirs.some(
+        (d) => d === `chromium_headless_shell-${revision}` || d === `chromium-${revision}`
+      )
+    : dirs.some((d) => d.startsWith("chromium"));
+}
+
+function playwrightPlatformOverride(host: BrowserHost): string {
+  if (host.platform !== "linux") return "";
+  if (osReleaseField(host.osRelease, "ID") !== "ubuntu") return "";
+  const version = Number.parseFloat(osReleaseField(host.osRelease, "VERSION_ID"));
+  if (!(version > NEWEST_UBUNTU_PLAYWRIGHT_KNOWS)) return "";
+  return `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-${host.arch === "arm64" ? "arm64" : "x64"} `;
+}
+
+export function playwrightFinding(host: BrowserHost): Finding {
+  if (hasChromium(host)) return passed("playwright", "Playwright Chromium installed");
+  const pinned = host.playwright ? `playwright@${host.playwright.version}` : "playwright";
+  const override = playwrightPlatformOverride(host);
+  return warning(
+    "playwright.missing",
+    "Playwright's Chromium is not installed — create-pdf, consulting-report and screenshots fail",
+    {
+      say: override
+        ? "Install it as Ubuntu 24.04, which Playwright supports"
+        : "Install it",
+      command: `${override}bun x ${pinned} install chromium`,
+    }
+  );
+}
+
+function palOnPathFinding(): Finding {
+  const pal = findBinaryOnPath("pal");
+  return pal
+    ? passed("pal.path", `pal on PATH — ${pal}`)
+    : failing("pal.path", "pal is not on PATH — skills that run 'pal cli …' fail", {
+        say: "Install PAL globally",
+        command: "bun add -g portable-agent-layer",
+      });
+}
+
+function rtkInstall(): Fix {
+  if (process.platform === "win32")
+    return {
+      say: "Download rtk.exe from https://github.com/rtk-ai/rtk/releases and add it to PATH",
+    };
+  if (process.platform === "darwin")
+    return { say: "Install rtk", command: "brew install rtk" };
+  return {
+    say: "Install rtk",
+    command:
+      "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh",
+  };
+}
+
+function rtkFinding(rtk: ToolCheck): Finding {
+  return rtk.available
+    ? passed("rtk", rtk.version || "rtk")
+    : optional("rtk.missing", "rtk — compresses long command output", rtkInstall());
+}
+
+export function environmentFindings(rtk: ToolCheck): Finding[] {
+  return [
+    passed("bun", `Bun ${Bun.version}`),
+    palOnPathFinding(),
+    playwrightFinding({
+      browsersPath: playwrightBrowsersPath(),
+      playwright: installedPlaywright(),
+      platform: process.platform,
+      arch: process.arch,
+      osRelease: readOsRelease(),
+    }),
+    rtkFinding(rtk),
+    ...versionControlFindings(),
+  ];
+}

package/src/cli/doctor/finding.ts

@@ -0,0 +1,35 @@
+/**
+ * One thing the doctor looked at. A problem carries the fix as a sentence and,
+ * where one exists, the exact command — so a later `--fix` can run it and an
+ * agent reading `--json` can propose it.
+ */
+
+export type Severity = "fail" | "warn" | "optional" | "ok";
+
+export interface Fix {
+  say: string;
+  command?: string;
+}
+
+export interface Finding {
+  id: string;
+  severity: Severity;
+  title: string;
+  fix?: Fix;
+}
+
+export function passed(id: string, title: string): Finding {
+  return { id, severity: "ok", title };
+}
+
+export function failing(id: string, title: string, fix?: Fix): Finding {
+  return { id, severity: "fail", title, fix };
+}
+
+export function warning(id: string, title: string, fix?: Fix): Finding {
+  return { id, severity: "warn", title, fix };
+}
+
+export function optional(id: string, title: string, fix: Fix): Finding {
+  return { id, severity: "optional", title, fix };
+}

package/src/cli/doctor/health.ts

@@ -0,0 +1,54 @@
+import { resolve } from "node:path";
+import { cachedStatus, type UpdateCache } from "../../hooks/handlers/update-check";
+import { type HookErrorGroup, recentHookErrors } from "../../hooks/lib/log";
+import { palHome } from "../../hooks/lib/paths";
+import { checkPendingMigrations } from "../migrate";
+import { type Finding, passed, warning } from "./finding";
+
+interface PendingMigration {
+  id: string;
+  description: string;
+  detail?: string;
+}
+
+export function hookErrorFindings(groups: HookErrorGroup[]): Finding[] {
+  if (groups.length === 0)
+    return [passed("hook-errors", "No hook errors in the last 24h")];
+  const log = resolve(palHome(), "debug", "debug.log");
+  return groups.map((group) => {
+    const times = group.count === 1 ? "once" : `${group.count} times`;
+    return warning(
+      `hook-errors.${group.source}`,
+      `${group.source} failed ${times} in the last 24h — last: ${group.last}`,
+      { say: `Full trace in ${log}` }
+    );
+  });
+}
+
+export function migrationFindings(pending: PendingMigration[]): Finding[] {
+  if (pending.length === 0) return [passed("migrations", "No pending migrations")];
+  return pending.map((migration) => {
+    const detail = migration.detail ? ` (${migration.detail})` : "";
+    return warning(
+      `migration.${migration.id}`,
+      `Migration pending: ${migration.description}${detail}`,
+      { say: "Run it", command: "pal cli migrate" }
+    );
+  });
+}
+
+export function updateFinding(cache: UpdateCache | null): Finding {
+  if (!cache?.available) return passed("update", "PAL is up to date");
+  return warning("update", `PAL ${cache.latest} is out (${cache.current} installed)`, {
+    say: "Update",
+    command: "pal cli update",
+  });
+}
+
+export function healthFindings(): Finding[] {
+  return [
+    ...hookErrorFindings(recentHookErrors()),
+    ...migrationFindings(checkPendingMigrations()),
+    updateFinding(cachedStatus()),
+  ];
+}

package/src/cli/doctor/inference.ts

@@ -0,0 +1,91 @@
+import { resolve } from "node:path";
+import { previewInferenceRoute } from "../../hooks/lib/inference";
+import { opencodeBackgroundModel } from "../../hooks/lib/opencode-config";
+import { platform } from "../../hooks/lib/paths";
+import type { AgentName } from "./agents";
+import { type Finding, failing, optional, passed, warning } from "./finding";
+
+type Env = Record<string, string | undefined>;
+
+const SUBPROCESS_ONLY = {
+  PAL_SPAWNED_INFERENCE: "every inference call refuses",
+  PAL_INFERENCE_DEPTH: "the depth breaker fires on the first call",
+  PAL_INFERENCE_DISABLED: "every inference call fails",
+} as const;
+
+const API_KEYS = {
+  PAL_ANTHROPIC_API_KEY: "fallback when the claude CLI cannot answer",
+  PAL_OPENAI_API_KEY: "fallback when the codex CLI cannot answer",
+  PAL_GEMINI_API_KEY: "YouTube analysis and Gemini research",
+  PAL_XAI_API_KEY: "the Grok researcher",
+  PAL_PERPLEXITY_API_KEY: "the Perplexity researcher",
+} as const;
+
+function unsetCommand(name: string, os: NodeJS.Platform): string {
+  return os === "win32" ? `Remove-Item Env:${name}` : `unset ${name}`;
+}
+
+export function leakedEnvFindings(env: Env, os: NodeJS.Platform): Finding[] {
+  return Object.entries(SUBPROCESS_ONLY).map(([name, effect]) =>
+    env[name]
+      ? failing(
+          `env.${name}`,
+          `${name}=${env[name]} leaked into your shell — ${effect}`,
+          {
+            say: "Clear it, and remove it from your shell profile if it is set there",
+            command: unsetCommand(name, os),
+          }
+        )
+      : passed(`env.${name}`, `${name} not set`)
+  );
+}
+
+export function apiKeyFindings(env: Env): Finding[] {
+  return Object.entries(API_KEYS).map(([name, unlocks]) =>
+    env[name]
+      ? passed(`key.${name}`, `${name} set`)
+      : optional(`key.${name}`, `${name} — ${unlocks}`, {
+          say: "set it in your shell profile",
+        })
+  );
+}
+
+function routeFinding(): Finding | null {
+  const preview = previewInferenceRoute();
+  if (preview.route === "disabled") return null;
+  if (preview.route === "none")
+    return failing(
+      "inference.none",
+      `Background inference has no route for ${preview.agent} — ${preview.reason}`,
+      { say: "Install the agent's CLI, or set an API key PAL can fall back to" }
+    );
+  if (preview.route.endsWith("-api"))
+    return warning(
+      "inference.api",
+      `Background inference goes through ${preview.route} (${preview.reason}) — it bills the API key`,
+      { say: "Put the agent's CLI on PATH to use your subscription instead" }
+    );
+  return passed("inference", `Inference: ${preview.route} (${preview.reason})`);
+}
+
+function opencodeModelFinding(): Finding {
+  return opencodeBackgroundModel()
+    ? passed("opencode.model", "opencode background model pinned")
+    : warning(
+        "opencode.model",
+        "opencode background model is not pinned — background inference uses whatever the TUI last picked",
+        {
+          say: `Pin one with "model" in ${resolve(platform.opencodeDir(), "config.json")}`,
+        }
+      );
+}
+
+export function inferenceFindings(agents: AgentName[]): Finding[] {
+  const route = routeFinding();
+  return [
+    ...(route ? [route] : []),
+    ...(agents.includes("opencode") ? [opencodeModelFinding()] : []),
+    ...leakedEnvFindings(process.env, process.platform),
+    ...apiKeyFindings(process.env),
+  ];
+}

package/src/cli/doctor/os-release.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+
+export type LinuxFamily = "debian" | "fedora" | "arch" | "alpine" | "suse";
+
+export function osReleaseField(osRelease: string, key: string): string {
+  return osRelease.match(new RegExp(String.raw`^${key}="?([^"\n]*)"?$`, "m"))?.[1] ?? "";
+}
+
+export function linuxFamily(osRelease: string): LinuxFamily | null {
+  const ids = `${osReleaseField(osRelease, "ID")} ${osReleaseField(osRelease, "ID_LIKE")}`
+    .split(/\s+/)
+    .filter(Boolean);
+  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;
+}
+
+export function readOsRelease(): string {
+  if (process.platform !== "linux") return "";
+  try {
+    return readFileSync("/etc/os-release", "utf-8");
+  } catch {
+    return "";
+  }
+}

package/src/cli/doctor/render.ts

@@ -0,0 +1,82 @@
+import type { Finding, Fix, Severity } from "./finding";
+
+export interface DoctorReport {
+  version: string;
+  agents: string[];
+  findings: Finding[];
+}
+
+interface RenderOptions {
+  verbose: boolean;
+  color: boolean;
+}
+
+const MARK: Record<Severity, { glyph: string; ansi: string }> = {
+  fail: { glyph: "✗", ansi: "\x1b[31m" },
+  warn: { glyph: "⚠", ansi: "\x1b[33m" },
+  optional: { glyph: "·", ansi: "\x1b[90m" },
+  ok: { glyph: "✓", ansi: "\x1b[32m" },
+};
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+function fixText(fix: Fix): string {
+  return fix.command ? `${fix.say}: ${fix.command}` : fix.say;
+}
+
+function headline(report: DoctorReport, passedCount: number): string {
+  const agents = report.agents.length > 0 ? report.agents.join(", ") : "no agent";
+  return `PAL ${report.version} · ${agents} · ${plural(passedCount, "check")} passed`;
+}
+
+function summary(failCount: number, warnCount: number, passedCount: number): string {
+  return [
+    failCount > 0 ? `${failCount} failing` : "",
+    warnCount > 0 ? plural(warnCount, "warning") : "",
+    `${plural(passedCount, "check")} passed`,
+  ]
+    .filter(Boolean)
+    .join(" · ");
+}
+
+export function renderReport(report: DoctorReport, options: RenderOptions): string[] {
+  const mark = (severity: Severity) =>
+    options.color
+      ? `${MARK[severity].ansi}${MARK[severity].glyph}\x1b[0m`
+      : MARK[severity].glyph;
+  const of = (severity: Severity) =>
+    report.findings.filter((finding) => finding.severity === severity);
+  const fails = of("fail");
+  const warns = of("warn");
+  const optionals = of("optional");
+  const passes = of("ok");
+
+  const lines = [headline(report, passes.length)];
+  if (options.verbose) {
+    lines.push("", ...passes.map((finding) => `  ${mark("ok")} ${finding.title}`));
+  }
+  const problems = [...fails, ...warns];
+  if (problems.length > 0) lines.push("");
+  for (const problem of problems) {
+    lines.push(`  ${mark(problem.severity)} ${problem.title}`);
+    if (problem.fix) lines.push(`    → ${fixText(problem.fix)}`);
+  }
+  if (optionals.length > 0) {
+    lines.push("", "Optional — not set up:");
+    for (const item of optionals) {
+      const how = item.fix?.command ?? item.fix?.say;
+      const suffix = how ? `: ${how}` : "";
+      lines.push(`  ${mark("optional")} ${item.title}${suffix}`);
+    }
+  }
+  if (problems.length > 0) {
+    lines.push("", summary(fails.length, warns.length, passes.length));
+  }
+  return lines;
+}
+
+export function doctorExitCode(findings: Finding[]): 0 | 1 {
+  return findings.some((finding) => finding.severity === "fail") ? 1 : 0;
+}

package/src/cli/doctor/run.ts

@@ -0,0 +1,46 @@
+import { getInstalledVersion } from "../../hooks/handlers/update-check";
+import {
+  agentFindings,
+  type DoctorResult,
+  detectAgents,
+  installedAgents,
+  rosterFindings,
+} from "./agents";
+import { environmentFindings } from "./environment";
+import type { Finding } from "./finding";
+import { healthFindings } from "./health";
+import { inferenceFindings } from "./inference";
+import { doctorExitCode, renderReport } from "./render";
+import { stateFindings } from "./state";
+
+function doctorFindings(health: DoctorResult): Finding[] {
+  const agents = installedAgents(health);
+  return [
+    ...rosterFindings(agents),
+    ...environmentFindings(health.rtk),
+    ...stateFindings(),
+    ...agentFindings(agents),
+    ...inferenceFindings(agents),
+    ...healthFindings(),
+  ];
+}
+
+/** `pal cli doctor [--verbose] [--json]` — prints the report and returns the exit code. */
+export function runDoctor(args: string[], health: DoctorResult = detectAgents()): number {
+  if (process.env.PAL_SKIP_DOCTOR === "1") return 0;
+  const report = {
+    version: getInstalledVersion(),
+    agents: installedAgents(health),
+    findings: doctorFindings(health),
+  };
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    const lines = renderReport(report, {
+      verbose: args.includes("--verbose"),
+      color: process.stdout.isTTY === true,
+    });
+    console.log(lines.join("\n"));
+  }
+  return doctorExitCode(report.findings);
+}