portable-agent-layer 0.90.0 → 0.91.0

package/package.json

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

package/src/cli/doctor/agents.ts

@@ -8,7 +8,11 @@ import {
   skillsDirOf,
 } from "../../hooks/lib/agent-registry";
 import { palPkg, platform } from "../../hooks/lib/paths";
-import { nativeAgentsDir, staleShippedAgents } from "../../targets/lib";
+import {
+  installedShippedAgentCount,
+  nativeAgentsDir,
+  staleShippedAgents,
+} from "../../targets/lib";
 import { NO_SESSION_AGENT_MESSAGE } from "../session-agent";
 import { type Finding, type Fix, failing, optional, passed, warning } from "./finding";
 
@@ -231,7 +235,13 @@ function hookFindings(agent: AgentName, file: string, contextHook: string): Find
       ),
     ];
 
-  const findings = [passed(`${agent}.hooks`, `${label}: ${pal.length} hooks registered`)];
+  const findings = [
+    passed(
+      `${agent}.hooks`,
+      `${label}: ${pal.length} hooks registered`,
+      `${pal.length} hooks`
+    ),
+  ];
   const undeclared = pal.filter((c) => !declaresAgent(c, agent));
   if (undeclared.length > 0)
     findings.push(
@@ -272,14 +282,20 @@ function opencodePluginFindings(): Finding[] {
         reinstall("opencode")
       ),
     ];
-  return [passed("opencode.hooks", "opencode plugin installed and current")];
+  return [
+    passed("opencode.hooks", "opencode plugin installed and current", "plugin current"),
+  ];
 }
 
 function subagentFinding(agent: AgentName): Finding {
   const label = labelOf(agent);
   const stale = staleShippedAgents(nativeAgentsDir(agent), agent);
   if (stale.length === 0)
-    return passed(`${agent}.subagents`, `${label}: subagents match this PAL version`);
+    return passed(
+      `${agent}.subagents`,
+      `${label}: subagents match this PAL version`,
+      "subagents current"
+    );
   return warning(
     `${agent}.subagents`,
     `${label}: installed subagents differ from this PAL version — ${stale.join(", ")}`,
@@ -298,7 +314,7 @@ function oneAgentFindings(agent: AgentName): Finding[] {
   const skills = countSkills(skillsDirOf(agent));
   const findings = [
     skills > 0
-      ? passed(`${agent}.skills`, `${label}: ${skills} skills`)
+      ? passed(`${agent}.skills`, `${label}: ${skills} skills`, `${skills} skills`)
       : warning(`${agent}.skills`, `${label} has no PAL skills`, reinstall(agent)),
   ];
   findings.push(
@@ -311,13 +327,31 @@ function oneAgentFindings(agent: AgentName): Finding[] {
     const { file, name } = layout.instructions;
     findings.push(
       existsSync(file())
-        ? passed(`${agent}.instructions`, `${name} present`)
+        ? passed(`${agent}.instructions`, `${name} present`, name)
         : failing(`${agent}.instructions`, `${name} is missing`, reinstall(agent))
     );
   }
   return findings;
 }
 
+function palHookCount(agent: AgentName): number {
+  const file = WIRING[agent].hookFile?.();
+  const commands = file ? readHookCommands(file) : "missing";
+  return Array.isArray(commands) ? commands.filter((c) => isPalHook(c, agent)).length : 0;
+}
+
+/** What PAL put into an agent, in the few words an install step reports it in. */
+export function agentInventory(agent: AgentName): string[] {
+  const plural = (count: number, noun: string) =>
+    `${count} ${noun}${count === 1 ? "" : "s"}`;
+  const wiring = WIRING[agent].hookFile ? plural(palHookCount(agent), "hook") : "plugin";
+  return [
+    plural(countSkills(skillsDirOf(agent)), "skill"),
+    wiring,
+    plural(installedShippedAgentCount(agent), "agent"),
+  ];
+}
+
 export function agentFindings(agents: AgentName[]): Finding[] {
   if (agents.length === 0) return [];
   const agentsMd = resolve(platform.opencodeDir(), "AGENTS.md");
@@ -345,7 +379,7 @@ export function rosterFindings(agents: AgentName[]): Finding[] {
   return [
     optional(
       "agents.others",
-      `Other agents PAL supports — ${others.map(labelOf).join(", ")}`,
+      `${others.map(labelOf).join(", ")} — other agents PAL supports`,
       {
         say: `install it, then run pal cli install --${others.length === 1 ? others[0] : "<agent>"}`,
       }

package/src/cli/doctor/environment.ts

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
@@ -98,16 +98,24 @@ function thisBrowserHost(): BrowserHost {
   };
 }
 
-function runInShell(command: string): boolean {
-  return spawnSync(command, { cwd: palPkg(), shell: true, stdio: "ignore" }).status === 0;
+function runInShell(command: string): Promise<boolean> {
+  return new Promise((done) => {
+    const child = spawn(command, { cwd: palPkg(), shell: true, stdio: "ignore" });
+    child.on("error", () => done(false));
+    child.on("close", (code) => done(code === 0));
+  });
 }
 
-/** A failure is left to the doctor's report that follows, which names the fix. */
-export function installChromium(
+/**
+ * Null when the right build is already there. A failure is left to the
+ * doctor's report that follows, which names the fix.
+ */
+export async function installChromium(
   host: BrowserHost = thisBrowserHost(),
-  run: (command: string) => boolean = runInShell
-): void {
-  if (!hasChromium(host)) run(chromiumInstallCommand(host));
+  run: (command: string) => Promise<boolean> | boolean = runInShell
+): Promise<boolean | null> {
+  if (hasChromium(host)) return null;
+  return run(chromiumInstallCommand(host));
 }
 
 interface PalInstall {

package/src/cli/doctor/finding.ts

@@ -11,15 +11,20 @@ export type Fix =
   | { say: string; command?: undefined }
   | { say: string; command: string; external: boolean };
 
+export type Group = "Environment" | "Agents" | "Inference" | "State";
+
 export interface Finding {
   id: string;
   severity: Severity;
   title: string;
   fix?: Fix;
+  group?: Group;
+  /** The few words a passing check takes up when its agent's checks share one line. */
+  brief?: string;
 }
 
-export function passed(id: string, title: string): Finding {
-  return { id, severity: "ok", title };
+export function passed(id: string, title: string, brief?: string): Finding {
+  return brief ? { id, severity: "ok", title, brief } : { id, severity: "ok", title };
 }
 
 export function failing(id: string, title: string, fix?: Fix): Finding {

package/src/cli/doctor/inference.ts

@@ -183,7 +183,11 @@ export function cursorPlanFinding(about: string): Finding | null {
       `Cursor is set to ${model}, but its free plan only runs Auto — background inference fails`,
       { say: "Switch Cursor's model to Auto, or upgrade the plan" }
     );
-  return passed("cursor.model", `Cursor model ${model} runs on the ${tier} plan`);
+  return passed(
+    "cursor.model",
+    `Cursor model ${model} runs on the ${tier} plan`,
+    `model ${model} on the ${tier} plan`
+  );
 }
 
 function cursorAbout(): string {

package/src/cli/doctor/render.ts

@@ -1,80 +1,261 @@
-import type { Finding, Fix, Severity } from "./finding";
+import { AGENT_REGISTRY, type AgentName } from "../../hooks/lib/agent-registry";
+import { healthBadge, mark, seconds } from "../ui/rail";
+import { homeShortened, type Style, visibleWidth } from "../ui/style";
+import { wrapWords } from "../ui/wrap";
+import type { Finding, Fix, Group, Severity } from "./finding";
 
 export interface DoctorReport {
   version: string;
   agents: string[];
   findings: Finding[];
+  elapsedMs?: number;
 }
 
 interface RenderOptions {
   verbose: boolean;
-  color: boolean;
+  style: Style;
 }
 
-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" },
-};
+export interface Tally {
+  fails: Finding[];
+  warns: Finding[];
+  optionals: Finding[];
+  passes: Finding[];
+}
+
+export function tally(findings: Finding[]): Tally {
+  const of = (severity: Severity) => findings.filter((f) => f.severity === severity);
+  return {
+    fails: of("fail"),
+    warns: of("warn"),
+    optionals: of("optional"),
+    passes: of("ok"),
+  };
+}
 
 function plural(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 
+export function plainSummary({ fails, warns, passes }: Tally): string {
+  return [
+    fails.length > 0 ? `${fails.length} failing` : "",
+    warns.length > 0 ? plural(warns.length, "warning") : "",
+    `${plural(passes.length, "check")} passed`,
+  ]
+    .filter(Boolean)
+    .join(", ");
+}
+
+const PLAIN_LEVEL: Record<Severity, string> = {
+  fail: "fail",
+  warn: "warn",
+  optional: "optional",
+  ok: "ok  ",
+};
+
 function fixText(fix: Fix): string {
   return fix.command ? `${fix.say}: ${fix.command}` : fix.say;
 }
 
-function headline(report: DoctorReport, passedCount: number): string {
+function plainLine(finding: Finding): string {
+  const fix = finding.fix ? ` -> ${fixText(finding.fix)}` : "";
+  return `${PLAIN_LEVEL[finding.severity]} ${finding.title}${fix}`;
+}
+
+export function plainProblemLines(t: Tally): string[] {
+  return [...t.fails, ...t.warns].map(plainLine);
+}
+
+function plainReport(report: DoctorReport, verbose: boolean): string[] {
+  const t = tally(report.findings);
   const agents = report.agents.length > 0 ? report.agents.join(", ") : "no agent";
-  return `PAL ${report.version} · ${agents} · ${plural(passedCount, "check")} passed`;
+  return [
+    `PAL ${report.version} · ${agents} · ${plainSummary(t)}`,
+    ...(verbose ? t.passes.map(plainLine) : []),
+    ...plainProblemLines(t),
+    ...t.optionals.map(plainLine),
+  ];
+}
+
+const TITLE_REST = " — ";
+
+interface Segment {
+  text: string;
+  paint: (text: string) => string;
+}
+
+const asIs = (text: string) => text;
+
+/** Wraps the words of several differently coloured pieces as if they were one sentence. */
+export function wrapSegments(segments: Segment[], width: number): string[] {
+  const text = segments.map((s) => s.text).join("");
+  let end = 0;
+  const bounds = segments.map((s) => {
+    end += s.text.length;
+    return end;
+  });
+  return wrapWords(text, width).map(({ text: chunk, start }) =>
+    segments
+      .map((segment, i) => {
+        const from = Math.max(start, bounds[i - 1] ?? 0);
+        const to = Math.min(start + chunk.length, bounds[i]);
+        return to > from ? segment.paint(text.slice(from, to)) : "";
+      })
+      .join("")
+  );
 }
 
-function summary(failCount: number, warnCount: number, passedCount: number): string {
+/** A title reads "what — more about it"; the part after the dash is quieter. */
+function titleSegments(
+  style: Style,
+  title: string,
+  main: (text: string) => string,
+  separator = TITLE_REST
+): Segment[] {
+  const text = homeShortened(title);
+  const split = text.indexOf(TITLE_REST);
+  if (split < 0) return [{ text, paint: main }];
   return [
-    failCount > 0 ? `${failCount} failing` : "",
-    warnCount > 0 ? plural(warnCount, "warning") : "",
-    `${plural(passedCount, "check")} passed`,
-  ]
-    .filter(Boolean)
-    .join(" · ");
+    { text: text.slice(0, split), paint: main },
+    { text: `${separator}${text.slice(split + TITLE_REST.length)}`, paint: style.dim },
+  ];
+}
+
+function hanging(lines: string[], first: string, rest: string): string[] {
+  return lines.map((line, i) => `${i === 0 ? first : rest}${line}`);
+}
+
+function fixLines(style: Style, fix: Fix, width: number, indent: string): string[] {
+  const arrow = `${indent}${style.dim(style.glyph.arrow)} `;
+  const pad = " ".repeat(indent.length + style.glyph.arrow.length + 1);
+  const segment = fix.command
+    ? { text: fix.command, paint: style.cmd }
+    : { text: homeShortened(fix.say), paint: asIs };
+  return hanging(wrapSegments([segment], width), arrow, pad);
+}
+
+const textWidth = (style: Style, indent: string) =>
+  Math.max(30, style.term.width - indent.length - 4);
+
+export function problemLines(style: Style, t: Tally, indent = "  "): string[] {
+  const width = textWidth(style, indent);
+  return [...t.fails, ...t.warns].flatMap((problem) => {
+    const kind = problem.severity === "fail" ? "fail" : "warn";
+    const main = kind === "fail" ? style.bold : asIs;
+    const head = `${indent}${mark(style, kind)} `;
+    return [
+      ...hanging(
+        wrapSegments(titleSegments(style, problem.title, main), width),
+        head,
+        `${indent}  `
+      ),
+      ...(problem.fix ? fixLines(style, problem.fix, width, `${indent}  `) : []),
+    ];
+  });
+}
+
+function optionalLines(style: Style, item: Finding): string[] {
+  const name = homeShortened(item.title.split(TITLE_REST)[0]);
+  const how = item.fix?.command
+    ? { text: item.fix.command, paint: style.cmd }
+    : { text: homeShortened(item.fix?.say ?? ""), paint: style.dim };
+  const segments = [
+    { text: name, paint: style.soft },
+    { text: ` ${style.glyph.dash} `, paint: style.dim },
+    how,
+  ];
+  return hanging(
+    wrapSegments(segments, textWidth(style, "  ")),
+    `  ${style.dim(style.glyph.dot)} `,
+    "    "
+  );
+}
+
+const GROUP_ORDER: Group[] = ["Environment", "Agents", "Inference", "State"];
+
+function agentOf(finding: Finding, agents: string[]): string | undefined {
+  return agents.find((agent) => finding.id.startsWith(`${agent}.`));
+}
+
+function passLines(style: Style, finding: Finding): string[] {
+  const segments = titleSegments(style, finding.title, asIs, ` ${style.glyph.dot} `);
+  return hanging(
+    wrapSegments(segments, textWidth(style, "  ")),
+    `  ${mark(style, "ok")} `,
+    "    "
+  );
+}
+
+function agentLines(style: Style, agent: string, passes: Finding[]): string[] {
+  const label = (AGENT_REGISTRY[agent as AgentName]?.label ?? agent).padEnd(12);
+  const briefs = passes.map((f) => f.brief ?? f.title).join(` ${style.glyph.dot} `);
+  const width = textWidth(style, "  ") - label.length - 1;
+  return hanging(
+    wrapSegments([{ text: briefs, paint: style.dim }], width),
+    `  ${mark(style, "ok")} ${label} `,
+    " ".repeat(label.length + 5)
+  );
+}
+
+function groupLines(style: Style, group: Group, passes: Finding[], agents: string[]) {
+  const inGroup = passes.filter((f) => (f.group ?? "State") === group);
+  if (inGroup.length === 0) return [];
+  const own = inGroup.filter((f) => !agentOf(f, agents));
+  const perAgent = agents
+    .map((agent) => [agent, inGroup.filter((f) => agentOf(f, agents) === agent)] as const)
+    .filter(([, found]) => found.length > 0);
+  return [
+    `  ${style.bold(style.gradient(group))}`,
+    ...own.flatMap((f) => passLines(style, f)),
+    ...perAgent.flatMap(([agent, found]) => agentLines(style, agent, found)),
+    "",
+  ];
+}
+
+function headline(style: Style, t: Tally, report: DoctorReport): string[] {
+  const count = { fails: t.fails.length, warns: t.warns.length };
+  const agents = style.soft(
+    report.agents.length > 0 ? report.agents.join(` ${style.glyph.dot} `) : "no agent"
+  );
+  const pal = style.bold(`PAL ${report.version}`);
+  const head = `  ${healthBadge(style, count, true)}  ${pal}`;
+  const oneLine = `${head}  ${agents}`;
+  return visibleWidth(oneLine) <= style.term.width ? [oneLine] : [head, `  ${agents}`];
+}
+
+function richReport(report: DoctorReport, verbose: boolean, style: Style): string[] {
+  const t = tally(report.findings);
+  const elapsed =
+    report.elapsedMs === undefined
+      ? ""
+      : ` ${style.glyph.dot} ${seconds(report.elapsedMs)}`;
+  const footer = `${plural(t.passes.length, "check")} passed${elapsed}`;
+  const problems = problemLines(style, t);
+  return [
+    "",
+    ...headline(style, t, report),
+    "",
+    ...(verbose
+      ? GROUP_ORDER.flatMap((g) => groupLines(style, g, t.passes, report.agents))
+      : []),
+    ...(problems.length > 0 ? [...problems, ""] : []),
+    ...(t.optionals.length > 0
+      ? [
+          `  ${style.dim("Optional")}`,
+          ...t.optionals.flatMap((o) => optionalLines(style, o)),
+          "",
+        ]
+      : []),
+    `  ${style.dim(footer)}`,
+    "",
+  ];
 }
 
 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;
+  return options.style.term.rich
+    ? richReport(report, options.verbose, options.style)
+    : plainReport(report, options.verbose);
 }
 
 export function doctorExitCode(findings: Finding[]): 0 | 1 {

package/src/cli/doctor/run.ts

@@ -1,4 +1,5 @@
 import { getInstalledVersion } from "../../hooks/handlers/update-check";
+import { createStyle } from "../ui/style";
 import {
   agentFindings,
   type DoctorResult,
@@ -7,38 +8,55 @@ import {
   rosterFindings,
 } from "./agents";
 import { environmentFindings } from "./environment";
-import type { Finding } from "./finding";
+import type { Finding, Group } from "./finding";
 import { healthFindings } from "./health";
 import { inferenceFindings } from "./inference";
-import { doctorExitCode, renderReport } from "./render";
+import { type DoctorReport, doctorExitCode, renderReport } from "./render";
 import { stateFindings } from "./state";
 
+const inGroup = (group: Group, findings: Finding[]) =>
+  findings.map((finding) => ({ ...finding, group }));
+
+const healthGroup = (finding: Finding): Group =>
+  finding.id.startsWith("hook-errors") ? "Inference" : "State";
+
 function doctorFindings(health: DoctorResult): Finding[] {
   const agents = installedAgents(health);
   return [
-    ...rosterFindings(agents),
-    ...environmentFindings(health.rtk),
-    ...stateFindings(),
-    ...agentFindings(agents),
-    ...inferenceFindings(agents),
-    ...healthFindings(),
+    ...inGroup("Agents", rosterFindings(agents)),
+    ...inGroup("Environment", environmentFindings(health.rtk)),
+    ...inGroup("State", stateFindings()),
+    ...inGroup("Agents", agentFindings(agents)),
+    ...inGroup("Inference", inferenceFindings(agents)),
+    ...healthFindings().map((finding) => ({ ...finding, group: healthGroup(finding) })),
   ];
 }
 
-/** `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 = {
+export function doctorReport(
+  health: DoctorResult,
+  started = performance.now()
+): DoctorReport {
+  const findings = doctorFindings(health);
+  return {
     version: getInstalledVersion(),
     agents: installedAgents(health),
-    findings: doctorFindings(health),
+    findings,
+    elapsedMs: performance.now() - started,
   };
+}
+
+/** `pal cli doctor [--verbose] [--json]` — prints the report and returns the exit code. */
+export function runDoctor(args: string[], health?: DoctorResult): number {
+  if (process.env.PAL_SKIP_DOCTOR === "1") return 0;
+  const started = performance.now();
+  const report = doctorReport(health ?? detectAgents(), started);
   if (args.includes("--json")) {
-    console.log(JSON.stringify(report, null, 2));
+    const { elapsedMs: _elapsed, ...json } = report;
+    console.log(JSON.stringify(json, null, 2));
   } else {
     const lines = renderReport(report, {
       verbose: args.includes("--verbose"),
-      color: process.stdout.isTTY === true,
+      style: createStyle(),
     });
     console.log(lines.join("\n"));
   }