@aaroncql/pim-agent 0.0.1

package/src/shared/PimSettings.test.ts

@@ -0,0 +1,90 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PimSettings } from "./PimSettings";
+
+let previousExaApiKey: string | undefined;
+let previousJinaApiKey: string | undefined;
+let previousPimHomeDir: string | undefined;
+let testPimHomeDir: string | undefined;
+
+beforeAll(async () => {
+  previousExaApiKey = process.env.EXA_API_KEY;
+  previousJinaApiKey = process.env.JINA_API_KEY;
+  previousPimHomeDir = process.env.PIM_HOME_DIR;
+  testPimHomeDir = await mkdtemp(join(tmpdir(), "pim-settings-home-"));
+  delete process.env.EXA_API_KEY;
+  delete process.env.JINA_API_KEY;
+  process.env.PIM_HOME_DIR = testPimHomeDir;
+});
+
+afterAll(async () => {
+  if (previousExaApiKey === undefined) {
+    delete process.env.EXA_API_KEY;
+  } else {
+    process.env.EXA_API_KEY = previousExaApiKey;
+  }
+  if (previousJinaApiKey === undefined) {
+    delete process.env.JINA_API_KEY;
+  } else {
+    process.env.JINA_API_KEY = previousJinaApiKey;
+  }
+  if (previousPimHomeDir === undefined) {
+    delete process.env.PIM_HOME_DIR;
+  } else {
+    process.env.PIM_HOME_DIR = previousPimHomeDir;
+  }
+  if (testPimHomeDir) {
+    await rm(testPimHomeDir, { recursive: true, force: true });
+  }
+});
+
+describe("PimSettings", () => {
+  test("loads defaults from ~/.pim/settings.json", async () => {
+    expect(PimSettings.path()).toBe(join(testPimHomeDir!, "settings.json"));
+    await expect(PimSettings.get("tps")).resolves.toEqual({ enabled: false });
+    await expect(PimSettings.get("powerline")).resolves.toEqual({
+      enabled: true,
+    });
+    await expect(PimSettings.get("exa")).resolves.toEqual({});
+    await expect(PimSettings.get("jina")).resolves.toEqual({});
+  });
+
+  test("writes settings with private directory and file modes", async () => {
+    await PimSettings.set("exa", { apiKey: "exa-test" });
+    await PimSettings.set("jina", { apiKey: "jina-test" });
+
+    const path = PimSettings.path();
+    expect(path).toBe(join(testPimHomeDir!, "settings.json"));
+    expect(await Bun.file(path).json()).toEqual({
+      tps: { enabled: false },
+      powerline: { enabled: true },
+      exa: { apiKey: "exa-test" },
+      jina: { apiKey: "jina-test" },
+    });
+
+    expect((await stat(testPimHomeDir!)).mode & 0o777).toBe(0o700);
+    expect((await stat(path)).mode & 0o777).toBe(0o600);
+  });
+
+  test("resolves API keys from env vars before settings", async () => {
+    await PimSettings.set("exa", { apiKey: "exa-test" });
+    await PimSettings.set("jina", { apiKey: "jina-test" });
+
+    await expect(PimSettings.getExaApiKey()).resolves.toBe("exa-test");
+    await expect(PimSettings.getJinaApiKey()).resolves.toBe("jina-test");
+
+    process.env.EXA_API_KEY = "  exa-env  ";
+    process.env.JINA_API_KEY = "";
+
+    await expect(PimSettings.getExaApiKey()).resolves.toBe("exa-env");
+    await expect(PimSettings.getJinaApiKey()).resolves.toBe("jina-test");
+  });
+
+  test("rejects invalid root setting values", async () => {
+    await expect(
+      PimSettings.set("exa", { apiKey: 123 } as never)
+    ).rejects.toThrow('Invalid value for pim setting "exa"');
+  });
+});

package/src/shared/PimSettings.ts

@@ -0,0 +1,124 @@
+import { chmod, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { Fs } from "./Fs";
+import { Paths } from "./Paths";
+
+const Schema = Type.Object({
+  tps: Type.Object(
+    {
+      enabled: Type.Boolean({ default: false }),
+    },
+    { default: { enabled: false } }
+  ),
+  powerline: Type.Object(
+    {
+      enabled: Type.Boolean({ default: true }),
+    },
+    { default: { enabled: true } }
+  ),
+  exa: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  jina: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+});
+
+type Settings = Static<typeof Schema>;
+
+export class PimSettings {
+  private static cache: Settings | undefined;
+  private static cachePath: string | undefined;
+  private static loadPromise: Promise<Settings> | undefined;
+  private static loadPromisePath: string | undefined;
+  private static writeQueue: Promise<unknown> = Promise.resolve();
+
+  public static path(): string {
+    return join(Paths.pimHomeDir(), "settings.json");
+  }
+
+  private static async load(): Promise<Settings> {
+    const path = PimSettings.path();
+    if (PimSettings.cache !== undefined && PimSettings.cachePath === path) {
+      return PimSettings.cache;
+    }
+    if (PimSettings.loadPromisePath !== path) {
+      PimSettings.loadPromise = undefined;
+      PimSettings.loadPromisePath = path;
+    }
+    PimSettings.loadPromise ??= (async () => {
+      let raw: unknown;
+      try {
+        raw = await Bun.file(path).json();
+      } catch {
+        raw = {};
+      }
+      const filled = Value.Default(Schema, raw);
+      const settings: Settings = Value.Check(Schema, filled)
+        ? filled
+        : Value.Create(Schema);
+      PimSettings.cache = settings;
+      PimSettings.cachePath = path;
+      return settings;
+    })();
+    return PimSettings.loadPromise;
+  }
+
+  private static async ensureHomeDir(): Promise<void> {
+    const dir = Paths.pimHomeDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700);
+  }
+
+  public static async getExaApiKey(): Promise<string | undefined> {
+    return (
+      PimSettings.normalize(process.env["EXA_API_KEY"]) ??
+      PimSettings.normalize((await PimSettings.get("exa")).apiKey)
+    );
+  }
+
+  public static async getJinaApiKey(): Promise<string | undefined> {
+    return (
+      PimSettings.normalize(process.env["JINA_API_KEY"]) ??
+      PimSettings.normalize((await PimSettings.get("jina")).apiKey)
+    );
+  }
+
+  private static normalize(value: string | undefined): string | undefined {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+  }
+
+  static async get<K extends keyof Settings>(key: K): Promise<Settings[K]> {
+    return (await PimSettings.load())[key];
+  }
+
+  static async set<K extends keyof Settings>(
+    key: K,
+    value: Settings[K]
+  ): Promise<void> {
+    const task = async (): Promise<void> => {
+      const current = await PimSettings.load();
+      const next: Settings = { ...current, [key]: value };
+      if (!Value.Check(Schema, next)) {
+        throw new Error(`Invalid value for pim setting "${String(key)}"`);
+      }
+      const path = PimSettings.path();
+      PimSettings.cache = next;
+      PimSettings.cachePath = path;
+      await PimSettings.ensureHomeDir();
+      await Fs.writeAtomic(path, `${JSON.stringify(next, null, 2)}\n`, 0o600);
+    };
+    PimSettings.writeQueue = PimSettings.writeQueue.then(task, task);
+    await PimSettings.writeQueue;
+  }
+}

package/src/shared/Renderer.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AgentToolResult,
+  Theme,
+  ThemeColor,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { Renderer } from "./Renderer";
+
+const stubTheme = {
+  bold: (text: string) => text,
+  fg: (_color: string, text: string) => text,
+} as unknown as Theme;
+
+function tracingTheme(): {
+  readonly theme: Theme;
+  readonly calls: { readonly color: ThemeColor; readonly text: string }[];
+} {
+  const calls: { color: ThemeColor; text: string }[] = [];
+  return {
+    calls,
+    theme: {
+      bold: (text: string) => text,
+      fg: (color: ThemeColor, text: string) => {
+        calls.push({ color, text });
+        return text;
+      },
+    } as unknown as Theme,
+  };
+}
+
+const expandedOptions = {
+  expanded: true,
+  isPartial: false,
+} satisfies ToolRenderResultOptions;
+
+const rendererContext = {
+  lastComponent: undefined,
+  isPartial: false,
+  isError: false,
+} as const;
+
+function textResult(text: string): AgentToolResult<unknown> {
+  return { content: [{ type: "text", text }], details: undefined };
+}
+
+describe("Renderer.markerColorFor", () => {
+  test("partial wins over error", () => {
+    expect(Renderer.markerColorFor(true, true)).toBe("warning");
+  });
+  test("error when not partial", () => {
+    expect(Renderer.markerColorFor(false, true)).toBe("error");
+  });
+  test("success otherwise", () => {
+    expect(Renderer.markerColorFor(false, false)).toBe("success");
+  });
+});
+
+describe("Renderer.buildPreviewLines", () => {
+  test("returns body unchanged when within limit", () => {
+    expect(Renderer.buildPreviewLines("a\nb\nc", 5)).toEqual({
+      preview: "a\nb\nc",
+      overflow: 0,
+    });
+  });
+  test("truncates and reports overflow", () => {
+    const body = "1\n2\n3\n4\n5\n6\n7";
+    expect(Renderer.buildPreviewLines(body, 3)).toEqual({
+      preview: "1\n2\n3",
+      overflow: 4,
+    });
+  });
+  test("limit equal to line count is not truncated", () => {
+    expect(Renderer.buildPreviewLines("a\nb\nc", 3)).toEqual({
+      preview: "a\nb\nc",
+      overflow: 0,
+    });
+  });
+});
+
+describe("Renderer.renderBorderedResult", () => {
+  test("wraps expanded output by default", () => {
+    const component = Renderer.renderBorderedResult({
+      result: textResult("0123456789abcdef\nnext"),
+      options: expandedOptions,
+      theme: stubTheme,
+      context: rendererContext,
+      previewLines: 10,
+    });
+
+    expect(component.render(10)).toHaveLength(4);
+  });
+
+  test("expanded output includes all lines even beyond the preview limit", () => {
+    const component = Renderer.renderBorderedResult({
+      result: textResult(
+        [
+          "  src/file.ts:10:before",
+          "> src/file.ts:11:matched",
+          "  src/file.ts:12:after",
+        ].join("\n")
+      ),
+      options: expandedOptions,
+      theme: stubTheme,
+      context: rendererContext,
+      previewLines: 1,
+    });
+
+    expect(component.render(80)).toEqual([
+      " │   src/file.ts:10:before",
+      " │ > src/file.ts:11:matched",
+      " │   src/file.ts:12:after",
+    ]);
+  });
+});
+
+describe("Renderer.renderToolCallTitle", () => {
+  test("leaves single-line titles unbordered", () => {
+    const component = Renderer.renderToolCallTitle({
+      label: "Bash",
+      title: "pwd",
+      theme: stubTheme,
+      context: {
+        lastComponent: undefined,
+        isPartial: false,
+        isError: false,
+      },
+    });
+
+    expect(component.render(80)).toEqual([" ▪ Bash: pwd".padEnd(80, " ")]);
+  });
+
+  test("labelColor overrides the default label color when provided", () => {
+    const overridden = tracingTheme();
+    Renderer.renderToolCallTitle({
+      label: "Subagent",
+      title: "investigate",
+      theme: overridden.theme,
+      context: {
+        lastComponent: undefined,
+        isPartial: false,
+        isError: false,
+      },
+      labelColor: "accent",
+    }).render(80);
+
+    expect(overridden.calls).toContainEqual({
+      color: "accent",
+      text: "Subagent",
+    });
+    expect(overridden.calls).not.toContainEqual({
+      color: "toolTitle",
+      text: "Subagent",
+    });
+
+    const fallback = tracingTheme();
+    Renderer.renderToolCallTitle({
+      label: "Bash",
+      title: "pwd",
+      theme: fallback.theme,
+      context: {
+        lastComponent: undefined,
+        isPartial: false,
+        isError: false,
+      },
+    }).render(80);
+
+    expect(fallback.calls).toContainEqual({ color: "toolTitle", text: "Bash" });
+  });
+
+  test("adds a left border to wrapped title lines", () => {
+    const width = 18;
+    const component = Renderer.renderToolCallTitle({
+      label: "Bash",
+      title: "one two three four five six seven",
+      theme: stubTheme,
+      context: {
+        lastComponent: undefined,
+        isPartial: false,
+        isError: false,
+      },
+    });
+    const lines = component.render(width);
+
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines.slice(1).every((line) => line.startsWith(" │ "))).toBe(true);
+    expect(lines.every((line) => visibleWidth(line) <= width)).toBe(true);
+  });
+});

package/src/shared/Renderer.ts

@@ -0,0 +1,256 @@
+import type {
+  AgentToolResult,
+  Theme,
+  ThemeColor,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Container,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+export type RenderContext = {
+  readonly lastComponent: Component | undefined;
+  readonly isPartial: boolean;
+  readonly isError: boolean;
+};
+
+export type StatefulToolCallTitleContext = RenderContext & {
+  readonly state: unknown;
+};
+
+export type StatefulToolCallTitleState = {
+  titleComponent?: Component;
+};
+
+export type MarkerStatus = "warning" | "error" | "success";
+
+export type PrefixSpec = {
+  readonly prefix: string;
+  readonly width: number;
+};
+
+class ToolTitle implements Component {
+  private text = "";
+  private theme: Theme | undefined;
+
+  public setText(text: string, theme: Theme): void {
+    this.text = text;
+    this.theme = theme;
+  }
+
+  public render(width: number): string[] {
+    if (!this.text || this.text.trim() === "") {
+      return [];
+    }
+
+    const theme = this.theme;
+    const normalized = this.text.replace(/\t/g, "   ");
+    const lines = wrapTextWithAnsi(normalized, Math.max(1, width));
+
+    if (lines.length <= 1 || theme === undefined) {
+      return lines.map((line) => ToolTitle.padLine(line, width));
+    }
+
+    const inner = Math.max(1, width - Renderer.GAPPED_PREFIX.width);
+    const out = [ToolTitle.padLine(lines[0] ?? "", width)];
+
+    for (const logical of lines.slice(1)) {
+      for (const wrapped of wrapTextWithAnsi(logical, inner)) {
+        out.push(
+          ToolTitle.padLine(
+            theme.fg("toolOutput", Renderer.GAPPED_PREFIX.prefix) + wrapped,
+            width
+          )
+        );
+      }
+    }
+
+    return out;
+  }
+
+  public invalidate(): void {}
+
+  private static padLine(line: string, width: number): string {
+    return line + " ".repeat(Math.max(0, width - visibleWidth(line)));
+  }
+}
+
+export class Renderer {
+  public static readonly GAPPED_PREFIX: PrefixSpec = {
+    prefix: " │ ",
+    width: 3,
+  };
+  public static readonly TIGHT_PREFIX: PrefixSpec = {
+    prefix: " │",
+    width: 2,
+  };
+
+  public static markerColorFor(
+    isPartial: boolean,
+    isError: boolean
+  ): MarkerStatus {
+    if (isPartial) {
+      return "warning";
+    }
+    if (isError) {
+      return "error";
+    }
+    return "success";
+  }
+
+  public static extractErrorText(
+    result: {
+      readonly content?: ReadonlyArray<{
+        readonly type: string;
+        readonly text?: string;
+      }>;
+    },
+    fallback: string
+  ): string {
+    const text = (result.content ?? [])
+      .filter((item) => item.type === "text")
+      .map((item) => item.text ?? "")
+      .join("\n")
+      .trim();
+
+    return text || fallback;
+  }
+
+  public static buildPreviewLines(
+    body: string,
+    maxLines: number
+  ): { preview: string; overflow: number } {
+    const lines = body.split("\n");
+    if (lines.length <= maxLines) {
+      return { preview: body, overflow: 0 };
+    }
+    return {
+      preview: lines.slice(0, maxLines).join("\n"),
+      overflow: lines.length - maxLines,
+    };
+  }
+
+  public static renderToolCallTitle(args: {
+    readonly label: string;
+    readonly title: string;
+    readonly theme: Theme;
+    readonly context: RenderContext;
+    readonly labelColor?: ThemeColor;
+  }): Component {
+    const { label, title, theme, context, labelColor } = args;
+    const markerColor = Renderer.markerColorFor(
+      Boolean(context.isPartial),
+      Boolean(context.isError)
+    );
+    const component =
+      context.lastComponent instanceof ToolTitle
+        ? context.lastComponent
+        : new ToolTitle();
+    component.setText(
+      theme.fg(markerColor, " ▪") +
+        " " +
+        theme.fg(labelColor ?? "toolTitle", theme.bold(label)) +
+        theme.fg("toolTitle", ": " + title),
+      theme
+    );
+    return component;
+  }
+
+  public static renderStatefulToolCallTitle(args: {
+    readonly label: string;
+    readonly title: string;
+    readonly theme: Theme;
+    readonly context: StatefulToolCallTitleContext;
+    readonly labelColor?: ThemeColor;
+  }): Component {
+    const state = args.context.state as StatefulToolCallTitleState;
+    const component = Renderer.renderToolCallTitle({
+      ...args,
+      context: {
+        ...args.context,
+        lastComponent: state.titleComponent ?? args.context.lastComponent,
+      },
+    });
+    state.titleComponent = component;
+    return component;
+  }
+
+  public static makePrefixedBlock(args: {
+    readonly text: string;
+    readonly theme: Theme;
+    readonly prefix: PrefixSpec;
+    readonly lineColor?: ThemeColor;
+  }): Component {
+    const { text, theme, prefix, lineColor } = args;
+    return {
+      render(width: number): string[] {
+        const inner = Math.max(1, width - prefix.width);
+        const out: string[] = [];
+        for (const logical of text.split("\n")) {
+          for (const w of wrapTextWithAnsi(logical, inner)) {
+            const body = lineColor ? theme.fg(lineColor, w) : w;
+            out.push(theme.fg("toolOutput", prefix.prefix) + body);
+          }
+        }
+        return out;
+      },
+      invalidate() {},
+    };
+  }
+
+  public static renderBorderedResult(args: {
+    readonly result: AgentToolResult<unknown>;
+    readonly options: ToolRenderResultOptions;
+    readonly theme: Theme;
+    readonly context: RenderContext;
+    readonly previewLines: number;
+  }): Container {
+    const { result, options, theme, context, previewLines } = args;
+    const container =
+      (context.lastComponent as Container | undefined) ?? new Container();
+    container.clear();
+
+    if (options.isPartial) {
+      return container;
+    }
+    if (!context.isError && !options.expanded) {
+      return container;
+    }
+
+    const first = result.content?.[0];
+    const body = first && "text" in first ? (first.text ?? "") : "";
+    if (!body) {
+      return container;
+    }
+
+    const lineColor = context.isError ? "error" : "toolOutput";
+    const block = (text: string): Component =>
+      Renderer.makePrefixedBlock({
+        text,
+        theme,
+        prefix: Renderer.GAPPED_PREFIX,
+        lineColor,
+      });
+
+    if (options.expanded) {
+      container.addChild(block(body));
+    } else {
+      const { preview, overflow } = Renderer.buildPreviewLines(
+        body,
+        previewLines
+      );
+      if (preview) {
+        container.addChild(block(preview));
+      }
+      if (overflow > 0) {
+        container.addChild(block(`… ${overflow} more lines`));
+      }
+    }
+
+    container.invalidate();
+    return container;
+  }
+}