portable-agent-layer 0.89.1 → 0.91.0

package/src/cli/setup-identity.ts

@@ -21,10 +21,10 @@ export function timezoneProblem(input: string | undefined): string | undefined {
   return `Not a timezone Intl recognises: ${input}`;
 }
 
-/** Prompt for missing identity fields. Skips any field that already has a value. */
-export async function promptIdentity(): Promise<void> {
+/** Prompt for missing identity fields; true when it asked anything. */
+export async function promptIdentity(): Promise<boolean> {
   // Skip interactive prompts in non-TTY environments (tests, CI)
-  if (!process.stdin.isTTY) return;
+  if (!process.stdin.isTTY) return false;
 
   const settings: PalSettingsData = { ...readSettings() };
   settings.identity ??= {};
@@ -40,12 +40,7 @@ export async function promptIdentity(): Promise<void> {
   const needsCatchphrase = !ai.catchphrase;
   const needsTimezone = !principal.timezone;
 
-  if (!needsPrincipal && !needsAi && !needsCatchphrase && !needsTimezone) {
-    clack.log.info("Identity already configured");
-    return;
-  }
-
-  clack.intro("Identity Setup");
+  if (!needsPrincipal && !needsAi && !needsCatchphrase && !needsTimezone) return false;
 
   if (needsPrincipal) {
     const name = await clack.text({
@@ -55,20 +50,20 @@ export async function promptIdentity(): Promise<void> {
     });
     if (clack.isCancel(name)) {
       clack.cancel("Setup cancelled");
-      return;
+      return true;
     }
     principal.name = name;
   }
 
   if (needsAi) {
     const name = await clack.text({
-      message: "Name your AI",
+      message: "Name your assistant",
       defaultValue: "Assistant",
       placeholder: "e.g. Jarvis, Friday, Atlas",
     });
     if (clack.isCancel(name)) {
       clack.cancel("Setup cancelled");
-      return;
+      return true;
     }
     ai.name = name;
     ai.fullName = `${name} — Personal AI`;
@@ -83,7 +78,7 @@ export async function promptIdentity(): Promise<void> {
     });
     if (clack.isCancel(catchphrase)) {
       clack.cancel("Setup cancelled");
-      return;
+      return true;
     }
     ai.catchphrase = catchphrase;
   }
@@ -97,11 +92,11 @@ export async function promptIdentity(): Promise<void> {
     });
     if (clack.isCancel(tz)) {
       clack.cancel("Setup cancelled");
-      return;
+      return true;
     }
     principal.timezone = tz;
   }
 
   writeSettings(settings);
-  clack.outro("Identity saved ✓");
+  return true;
 }

package/src/cli/ui/banner.ts

@@ -0,0 +1,50 @@
+import { mix, PALETTE, type Style } from "./style";
+
+const WORDMARK = [
+  "██████╗  █████╗ ██╗     ",
+  "██╔══██╗██╔══██╗██║     ",
+  "██████╔╝███████║██║     ",
+  "██╔═══╝ ██╔══██║██║     ",
+  "██║     ██║  ██║███████╗",
+  "╚═╝     ╚═╝  ╚═╝╚══════╝",
+];
+
+const FULL_BANNER_WIDTH = 64;
+const TAGLINE = "Your context, in every agent.";
+
+function wordmarkRow(style: Style, row: string): string {
+  const chars = [...row];
+  const span = chars.length - 1;
+  return chars
+    .map((ch, i) => {
+      if (ch === " ") return ch;
+      const color = mix(PALETTE.violet, PALETTE.cyan, i / span);
+      return style.paint(ch === "█" ? color : mix(color, PALETTE.shade, 0.55), ch);
+    })
+    .join("");
+}
+
+export function compactBanner(style: Style, version: string): string {
+  const mark = `${style.glyph.ask} PAL`;
+  const name = `${style.glyph.dot} Portable Agent Layer`;
+  return `${style.gradient(mark)} ${style.soft(version)} ${style.dim(name)}`;
+}
+
+export function banner(style: Style, version: string): string[] {
+  const { term } = style;
+  if (!term.unicode || term.width < FULL_BANNER_WIDTH)
+    return ["", compactBanner(style, version), ""];
+  const side = [
+    "",
+    style.bold(style.gradient("Portable Agent Layer")),
+    style.soft(`v${version}`),
+    style.italic(style.soft(TAGLINE)),
+    "",
+    "",
+  ];
+  return [
+    "",
+    ...WORDMARK.map((row, i) => `  ${wordmarkRow(style, row)}   ${side[i]}`.trimEnd()),
+    "",
+  ];
+}

package/src/cli/ui/live.ts

@@ -0,0 +1,112 @@
+import { mark, railNotes, railRow, seconds } from "./rail";
+import type { Style } from "./style";
+
+type NoteLevel = "fail" | "warn" | "info";
+
+export interface Note {
+  level: NoteLevel;
+  text: string;
+}
+
+export interface Done {
+  detail: string[];
+  notes?: Note[];
+}
+
+type Work = () => Promise<Done | null> | Done | null;
+
+const FRAME_MS = 90;
+const CLEAR_LINE = "\r\x1b[2K";
+
+const INSTANT_MS = 50;
+
+export const stepTime = (ms: number) => (ms < INSTANT_MS ? "" : seconds(ms));
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Prints the steps of a long command. At a terminal each step spins while it
+ * runs and settles into one line; anywhere else it prints one plain line when done.
+ */
+export class LiveRail {
+  constructor(
+    private readonly style: Style,
+    private readonly write: (text: string) => void = (text) => {
+      process.stdout.write(text);
+    }
+  ) {}
+
+  line(text = ""): void {
+    this.write(`${text}\n`);
+  }
+
+  async step(name: string, pending: string, work: Work): Promise<Done | null> {
+    return this.style.term.rich
+      ? this.richStep(name, pending, work)
+      : this.plainStep(name, work);
+  }
+
+  private noteLines(note: Note): string[] {
+    if (note.level === "info") return railNotes(this.style, note.text, this.style.dim);
+    return railNotes(
+      this.style,
+      note.text,
+      (text) => text,
+      `${mark(this.style, note.level)} `
+    );
+  }
+
+  private async richStep(
+    name: string,
+    pending: string,
+    work: Work
+  ): Promise<Done | null> {
+    let frame = 0;
+    const draw = () =>
+      this.write(
+        `${CLEAR_LINE}${railRow(this.style, "spin", name, pending, "", frame)[0]}`
+      );
+    draw();
+    const spinner = setInterval(() => {
+      frame += 1;
+      draw();
+    }, FRAME_MS);
+    const started = performance.now();
+    try {
+      const done = await work();
+      clearInterval(spinner);
+      this.write(CLEAR_LINE);
+      if (done) this.settle(name, done, stepTime(performance.now() - started));
+      return done;
+    } catch (error) {
+      clearInterval(spinner);
+      this.write(CLEAR_LINE);
+      this.settle(name, { detail: [errorText(error)] }, "", "fail");
+      throw error;
+    }
+  }
+
+  private settle(name: string, done: Done, time: string, kind: "ok" | "fail" = "ok") {
+    const detail = done.detail.join(` ${this.style.glyph.dot} `);
+    for (const row of railRow(this.style, kind, name, detail, time)) this.line(row);
+    for (const note of done.notes ?? [])
+      for (const line of this.noteLines(note)) this.line(line);
+  }
+
+  private async plainStep(name: string, work: Work): Promise<Done | null> {
+    try {
+      const done = await work();
+      if (done) {
+        this.line(`ok   ${name}: ${done.detail.join(", ")}`);
+        for (const note of done.notes ?? [])
+          this.line(`${note.level.padEnd(4)} ${note.text}`);
+      }
+      return done;
+    } catch (error) {
+      this.line(`fail ${name}: ${errorText(error)}`);
+      throw error;
+    }
+  }
+}

package/src/cli/ui/rail.ts

@@ -0,0 +1,119 @@
+import { PALETTE, type Style, visibleWidth } from "./style";
+import { wrapWords } from "./wrap";
+
+const RAIL_WIDTH = 60;
+const NAME_WIDTH = 13;
+
+export type Mark = "ok" | "fail" | "warn" | "info" | "ask" | "todo" | "spin";
+
+export function mark(style: Style, kind: Mark, frame = 0): string {
+  const { glyph, paint } = style;
+  switch (kind) {
+    case "ok":
+      return paint(PALETTE.green, glyph.ok);
+    case "fail":
+      return paint(PALETTE.rose, glyph.fail);
+    case "warn":
+      return paint(PALETTE.amber, glyph.warn);
+    case "info":
+      return paint(PALETTE.indigo, glyph.info);
+    case "ask":
+      return paint(PALETTE.cyan, glyph.ask);
+    case "todo":
+      return style.dim(glyph.todo);
+    case "spin":
+      return paint(PALETTE.violet, glyph.spinner[frame % glyph.spinner.length]);
+  }
+}
+
+const railGlyph = (style: Style, glyph: string) => style.paint(PALETTE.rail, glyph);
+
+export const railTop = (style: Style, title: string) =>
+  `${railGlyph(style, style.glyph.top)}  ${style.bold(title)}`;
+
+export const railGap = (style: Style) => railGlyph(style, style.glyph.rail);
+
+export const railNote = (style: Style, text: string) => `${railGap(style)}  ${text}`;
+
+export const railEnd = (style: Style, text: string) =>
+  `${railGlyph(style, style.glyph.end)}  ${text}`;
+
+function padBetween(left: string, right: string, width: number): string {
+  const room = width - visibleWidth(left) - visibleWidth(right);
+  return right ? `${left}${" ".repeat(Math.max(2, room))}${right}` : left;
+}
+
+/** One finished step: what it did on the same line, or under the name when the terminal is too narrow. */
+export function railRow(
+  style: Style,
+  kind: Mark,
+  name: string,
+  detail: string,
+  time = "",
+  frame = 0
+): string[] {
+  const head = `${mark(style, kind, frame)}  ${name.padEnd(NAME_WIDTH)}`;
+  const width = Math.min(style.term.width - 2, RAIL_WIDTH);
+  const wide = `${head}${style.soft(detail)}`;
+  if (visibleWidth(wide) + time.length + 2 <= width)
+    return [padBetween(wide, style.dim(time), width)];
+  const first = padBetween(
+    `${mark(style, kind, frame)}  ${name}`,
+    style.dim(time),
+    width
+  );
+  return [first, ...railNotes(style, detail, style.dim)];
+}
+
+/** Text under a step, wrapped to the terminal so the rail stays unbroken. */
+export function railNotes(
+  style: Style,
+  text: string,
+  paint: (text: string) => string,
+  lead = ""
+): string[] {
+  const width = Math.max(10, style.term.width - 3 - visibleWidth(lead));
+  const pad = " ".repeat(visibleWidth(lead));
+  return wrapWords(text, width).map((chunk, i) =>
+    railNote(style, `${i === 0 ? lead : pad}${paint(chunk.text)}`)
+  );
+}
+
+export interface HealthCount {
+  fails: number;
+  warns: number;
+}
+
+export function healthBadge(
+  style: Style,
+  { fails, warns }: HealthCount,
+  withGlyph = false
+) {
+  const { glyph } = style;
+  const lead = (g: string) => (withGlyph ? `${g} ` : "");
+  if (fails > 0) return style.badge(PALETTE.rose, `${lead(glyph.fail)}${fails} FAILING`);
+  if (warns > 0)
+    return style.badge(
+      PALETTE.amber,
+      `${lead(glyph.warn)}${warns} WARNING${warns === 1 ? "" : "S"}`
+    );
+  return style.badge(PALETTE.green, `${lead(glyph.healthy)}HEALTHY`);
+}
+
+/** A card when it fits; on a narrow terminal the same lines, unframed. */
+export function box(style: Style, lines: string[], inner = 50): string[] {
+  if (style.term.width < inner + 4) return lines.map((line) => `  ${line}`.trimEnd());
+  const { box: b } = style.glyph;
+  const edge = (text: string) => railGlyph(style, text);
+  const padded = (line: string) =>
+    `${line}${" ".repeat(Math.max(0, inner - 2 - visibleWidth(line)))}`;
+  return [
+    edge(`  ${b.tl}${b.h.repeat(inner)}${b.tr}`),
+    ...lines.map((line) => `  ${edge(b.v)}  ${padded(line)}${edge(b.v)}`),
+    edge(`  ${b.bl}${b.h.repeat(inner)}${b.br}`),
+  ];
+}
+
+export function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}

package/src/cli/ui/style.ts

@@ -0,0 +1,132 @@
+import { homedir } from "node:os";
+import { detectTerminal, type Terminal } from "./terminal";
+
+export type Rgb = readonly [number, number, number];
+
+export const PALETTE = {
+  violet: [167, 139, 250],
+  indigo: [129, 140, 248],
+  cyan: [34, 211, 238],
+  green: [52, 211, 153],
+  amber: [251, 191, 36],
+  rose: [251, 113, 133],
+  dim: [100, 116, 139],
+  rail: [71, 85, 105],
+  soft: [148, 163, 184],
+  ink: [15, 23, 42],
+  shade: [11, 17, 32],
+} as const satisfies Record<string, Rgb>;
+
+const UNICODE_GLYPHS = {
+  ok: "✓",
+  fail: "✖",
+  warn: "▲",
+  healthy: "●",
+  info: "◇",
+  ask: "◆",
+  todo: "○",
+  spinner: ["◐", "◓", "◑", "◒"],
+  rail: "│",
+  top: "┌",
+  end: "└",
+  arrow: "→",
+  sparkle: "✦",
+  dot: "·",
+  dash: "—",
+  box: { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│" },
+};
+
+type Glyphs = typeof UNICODE_GLYPHS;
+
+const ASCII_GLYPHS: Glyphs = {
+  ok: "v",
+  fail: "x",
+  warn: "!",
+  healthy: "*",
+  info: "*",
+  ask: "*",
+  todo: "o",
+  spinner: ["-", "\\", "|", "/"],
+  rail: "|",
+  top: "+",
+  end: "+",
+  arrow: "->",
+  sparkle: "*",
+  dot: "-",
+  dash: "-",
+  box: { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|" },
+};
+
+const RESET = "\x1b[0m";
+
+export function visibleWidth(text: string): number {
+  return Bun.stringWidth(text);
+}
+
+export function mix(from: Rgb, to: Rgb, t: number): Rgb {
+  return [0, 1, 2].map((i) =>
+    Math.round(from[i] + (to[i] - from[i]) * t)
+  ) as unknown as Rgb;
+}
+
+function cubeLevel(channel: number): number {
+  return Math.round((channel / 255) * 5);
+}
+
+/** The nearest colour in the 6x6x6 cube of a 256-colour terminal. */
+export function to256([r, g, b]: Rgb): number {
+  return 16 + 36 * cubeLevel(r) + 6 * cubeLevel(g) + cubeLevel(b);
+}
+
+function sgr(term: Terminal, layer: 38 | 48, rgb: Rgb): string {
+  if (term.color === "truecolor") return `\x1b[${layer};2;${rgb.join(";")}m`;
+  return `\x1b[${layer};5;${to256(rgb)}m`;
+}
+
+export function homeShortened(text: string, home = homedir()): string {
+  return home.length > 1 ? text.replaceAll(home, "~") : text;
+}
+
+export interface Style {
+  term: Terminal;
+  glyph: Glyphs;
+  paint: (rgb: Rgb, text: string) => string;
+  badge: (rgb: Rgb, text: string) => string;
+  bold: (text: string) => string;
+  italic: (text: string) => string;
+  gradient: (text: string) => string;
+  dim: (text: string) => string;
+  soft: (text: string) => string;
+  cmd: (text: string) => string;
+}
+
+export function createStyle(term: Terminal = detectTerminal()): Style {
+  const colored = term.color !== "none";
+  const wrap = (open: string, text: string) =>
+    colored && text ? `${open}${text}${RESET}` : text;
+  const paint = (rgb: Rgb, text: string) => wrap(sgr(term, 38, rgb), text);
+  const gradientChar = (ch: string, i: number, span: number) =>
+    ch === " "
+      ? ch
+      : `${sgr(term, 38, mix(PALETTE.violet, PALETTE.cyan, i / span))}${ch}`;
+  return {
+    term,
+    glyph: term.unicode ? UNICODE_GLYPHS : ASCII_GLYPHS,
+    paint,
+    badge: (rgb, text) =>
+      colored
+        ? `${sgr(term, 48, rgb)}${sgr(term, 38, PALETTE.ink)}\x1b[1m ${text} ${RESET}`
+        : `[${text}]`,
+    bold: (text) => wrap("\x1b[1m", text),
+    italic: (text) => wrap("\x1b[3m", text),
+    gradient: (text) => {
+      if (!colored) return text;
+      const chars = [...text];
+      const span = Math.max(1, chars.length - 1);
+      return `${chars.map((ch, i) => gradientChar(ch, i, span)).join("")}${RESET}`;
+    },
+    dim: (text) => paint(PALETTE.dim, text),
+    soft: (text) => paint(PALETTE.soft, text),
+    cmd: (text) => paint(PALETTE.cyan, text),
+  };
+}

package/src/cli/ui/terminal.ts

@@ -0,0 +1,81 @@
+/**
+ * What the terminal PAL is printing to can show. Rich output (the banner, the
+ * rail, colours) is for a person at a terminal; anything else, an agent's tool
+ * call or a CI log, gets short plain lines.
+ */
+
+type ColorDepth = "none" | "256" | "truecolor";
+
+export interface Terminal {
+  rich: boolean;
+  color: ColorDepth;
+  unicode: boolean;
+  width: number;
+}
+
+export interface TerminalProbe {
+  env: Record<string, string | undefined>;
+  isTTY: boolean;
+  columns?: number;
+  platform: NodeJS.Platform;
+}
+
+const TRUECOLOR_PROGRAMS = new Set([
+  "iTerm.app",
+  "vscode",
+  "WezTerm",
+  "ghostty",
+  "Hyper",
+]);
+const TRUECOLOR_TERMS = /truecolor|24bit|direct|kitty|alacritty|ghostty|wezterm/;
+
+function forcedColor(env: TerminalProbe["env"]): ColorDepth | undefined {
+  const force = env.FORCE_COLOR;
+  if (force === undefined) return undefined;
+  if (force === "0" || force === "false") return "none";
+  return force === "3" ? "truecolor" : "256";
+}
+
+function supportsTruecolor({ env }: TerminalProbe): boolean {
+  return (
+    env.COLORTERM === "truecolor" ||
+    env.COLORTERM === "24bit" ||
+    env.WT_SESSION !== undefined ||
+    TRUECOLOR_PROGRAMS.has(env.TERM_PROGRAM ?? "") ||
+    TRUECOLOR_TERMS.test(env.TERM ?? "")
+  );
+}
+
+function colorDepth(probe: TerminalProbe, rich: boolean): ColorDepth {
+  if (probe.env.NO_COLOR) return "none";
+  const forced = forcedColor(probe.env);
+  if (forced === "none") return "none";
+  if (!rich && !forced) return "none";
+  if (forced === "truecolor" || supportsTruecolor(probe)) return "truecolor";
+  return "256";
+}
+
+/** The legacy Windows console draws box and block characters as question marks. */
+function supportsUnicode({ env, platform }: TerminalProbe): boolean {
+  if (platform !== "win32") return true;
+  return Boolean(env.WT_SESSION || env.TERM_PROGRAM || env.ConEmuTask || env.TERM);
+}
+
+export function detectTerminal(probe: TerminalProbe = currentProbe()): Terminal {
+  const rich = probe.isTTY && probe.env.TERM !== "dumb";
+  return {
+    rich,
+    color: colorDepth(probe, rich),
+    unicode: supportsUnicode(probe),
+    width: probe.columns && probe.columns > 0 ? probe.columns : 80,
+  };
+}
+
+function currentProbe(): TerminalProbe {
+  return {
+    env: process.env,
+    isTTY: process.stdout.isTTY === true,
+    columns: process.stdout.columns,
+    platform: process.platform,
+  };
+}

package/src/cli/ui/wrap.ts

@@ -0,0 +1,19 @@
+export interface Chunk {
+  text: string;
+  start: number;
+}
+
+export function wrapWords(text: string, width: number): Chunk[] {
+  const chunks: Chunk[] = [];
+  let line: Chunk | null = null;
+  for (const word of text.matchAll(/\S+/g)) {
+    const start = word.index ?? 0;
+    if (line && start + word[0].length - line.start <= width) {
+      line.text = text.slice(line.start, start + word[0].length);
+      continue;
+    }
+    line = { text: word[0], start };
+    chunks.push(line);
+  }
+  return chunks;
+}

package/src/cli/update-flow.ts

@@ -0,0 +1,98 @@
+/**
+ * `pal cli update`: the version jump, the download, then a fresh process that
+ * reinstalls and continues the same rail.
+ */
+
+import type { UpdateCache } from "../hooks/handlers/update-check";
+import { palPkg } from "../hooks/lib/paths";
+import { type Captured, runCaptured } from "./install-flow";
+import { type Done, LiveRail } from "./ui/live";
+import { mark, railGap, railTop } from "./ui/rail";
+import { createStyle, type Style } from "./ui/style";
+
+const PACKAGE = "portable-agent-layer";
+
+function upToDate(style: Style, version: string): string {
+  if (!style.term.rich) return `Already up to date: PAL ${version} is the latest`;
+  const checked = `${style.glyph.dot} checked just now`;
+  return `  ${mark(style, "ok")} ${style.gradient("PAL")} ${style.bold(version)} ${style.soft("is the latest")} ${style.dim(checked)}`;
+}
+
+function versionJump(style: Style, from: string, to: string): string {
+  if (!style.term.rich) return `PAL ${from} -> ${to}`;
+  const arrow = style.dim(style.glyph.arrow);
+  const pal = `${style.glyph.ask} PAL`;
+  return `  ${style.gradient(pal)}  ${style.soft(from)} ${arrow} ${style.bold(style.gradient(to))}`;
+}
+
+type Run = (cmd: string, args: string[], cwd?: string) => Promise<Captured>;
+
+export interface UpdateSteps {
+  check: () => Promise<UpdateCache>;
+  reinstall: (env: Record<string, string>) => number;
+  run?: Run;
+}
+
+/** `bun update -g` keeps the caret range, and on 0.x a caret allows only patch bumps. */
+export function downloadCommand(
+  update: UpdateCache
+): [string, string[], string | undefined] {
+  return update.mode === "repo"
+    ? ["git", ["pull", "--ff-only"], palPkg()]
+    : ["bun", ["add", "-g", `${PACKAGE}@${update.latest}`], undefined];
+}
+
+class DownloadFailed extends Error {
+  constructor(
+    update: UpdateCache,
+    readonly output: string
+  ) {
+    super(
+      update.mode === "repo"
+        ? "git pull failed — local changes? Pull manually"
+        : `try: bun add -g ${PACKAGE}@${update.latest}`
+    );
+  }
+}
+
+async function download(update: UpdateCache, run: Run): Promise<Done> {
+  const [cmd, args, cwd] = downloadCommand(update);
+  const result = await run(cmd, args, cwd);
+  if (result.code !== 0) throw new DownloadFailed(update, result.output);
+  return { detail: [`${PACKAGE} ${update.latest}`] };
+}
+
+async function downloaded(rail: LiveRail, style: Style, update: UpdateCache, run: Run) {
+  try {
+    await rail.step("Download", "downloading…", () => download(update, run));
+    return true;
+  } catch (error) {
+    if (!(error instanceof DownloadFailed)) throw error;
+    for (const line of error.output.trim().split("\n").slice(-6))
+      rail.line(style.dim(`   ${line}`));
+    return false;
+  }
+}
+
+/** Exit code for the parent; the reinstall runs in a fresh process that reads PAL_UPDATED_FROM. */
+export async function runUpdate(
+  { check, reinstall, run = runCaptured }: UpdateSteps,
+  style: Style = createStyle(),
+  rail: LiveRail = new LiveRail(style)
+): Promise<number> {
+  const update = await check();
+  rail.line();
+  if (!update.available) {
+    rail.line(upToDate(style, update.current));
+    rail.line();
+    return 0;
+  }
+  rail.line(versionJump(style, update.current, update.latest));
+  rail.line();
+  if (style.term.rich) {
+    rail.line(railTop(style, "Updating"));
+    rail.line(railGap(style));
+  }
+  if (!(await downloaded(rail, style, update, run))) return 1;
+  return reinstall({ PAL_UPDATED_FROM: update.current });
+}