pim-agent 0.0.1 → 0.9.0

package/packages/core/src/shared/Updater.ts

@@ -0,0 +1,193 @@
+import { rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+import { Git } from "./Git";
+import { PimVersion } from "./PimVersion";
+import { Proc } from "./Proc";
+import { Supervisor, type Install } from "./Supervisor";
+
+const STAGING = "staging";
+
+// Relative to `packages/web`: the vite root `web:build` cds into.
+const STAGING_OUT_DIR = `dist/${STAGING}`;
+
+type ClientDirs = {
+  readonly staging: string;
+  readonly client: string;
+  readonly previous: string;
+};
+
+/** A spawned command, or filesystem work — never both. */
+export type UpdateStep =
+  | {
+      readonly label: string;
+      readonly command: ReadonlyArray<string>;
+      readonly cwd: string | undefined;
+    }
+  | { readonly label: string; readonly act: () => Promise<void> };
+
+/** Work the plan declined to do; `blocking` means the run did less than asked. */
+export type UpdateSkip = {
+  readonly label: string;
+  readonly reason: string;
+  readonly blocking: boolean;
+};
+
+export type UpdatePlan = {
+  readonly steps: ReadonlyArray<UpdateStep>;
+  readonly skipped: ReadonlyArray<UpdateSkip>;
+};
+
+export type UpdateFacts = {
+  readonly at: Install;
+  readonly packageName: string;
+  /** A dev checkout with no uncommitted changes; irrelevant to a prod install. */
+  readonly cleanTree: boolean;
+  /** The newest published release, or undefined when the registry was silent. */
+  readonly latest: string | undefined;
+};
+
+export type UpdateOutcome = {
+  readonly ok: boolean;
+  readonly from: string;
+  /** Re-read from disk after the steps ran, never the version that was asked for. */
+  readonly to: string;
+  readonly skipped: ReadonlyArray<UpdateSkip>;
+  readonly error: string | undefined;
+};
+
+export type UpdateOptions = {
+  readonly onStep?: (label: string) => void | Promise<void>;
+};
+
+function clientDirs(packageRoot: string): ClientDirs {
+  const dist = join(packageRoot, "packages", "web", "dist");
+  return {
+    staging: join(dist, STAGING),
+    client: join(dist, "client"),
+    previous: join(dist, "previous"),
+  };
+}
+
+// `vite build` empties its outDir: build to staging and swap, or a failed build deletes the live bundle.
+async function swapClient(packageRoot: string): Promise<void> {
+  const dirs = clientDirs(packageRoot);
+  await rm(dirs.previous, { recursive: true, force: true });
+  await rename(dirs.client, dirs.previous).catch((err: unknown) => {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
+  });
+  await rename(dirs.staging, dirs.client);
+}
+
+function plan(facts: UpdateFacts): UpdatePlan {
+  const steps: UpdateStep[] = [];
+  const skipped: UpdateSkip[] = [];
+  const { at, packageName, cleanTree, latest } = facts;
+
+  if (at.kind === "dev") {
+    if (cleanTree) {
+      steps.push({
+        label: "git pull",
+        command: ["git", "pull", "--ff-only"],
+        cwd: at.packageRoot,
+      });
+    } else {
+      skipped.push({
+        label: "git pull",
+        reason: "the working tree has uncommitted changes",
+        blocking: false,
+      });
+    }
+    steps.push({
+      label: "bun install",
+      command: ["bun", "install"],
+      cwd: at.packageRoot,
+    });
+    steps.push({
+      label: "build the web client",
+      command: ["bun", "run", "web:build", "--", "--outDir", STAGING_OUT_DIR],
+      cwd: at.packageRoot,
+    });
+    steps.push({
+      label: "swap in the new web client",
+      act: () => swapClient(at.packageRoot),
+    });
+    return { steps, skipped };
+  }
+
+  if (latest === undefined) {
+    skipped.push({
+      label: "install",
+      reason: "the npm registry could not be reached",
+      blocking: true,
+    });
+  } else {
+    // Install the exact version, never `@latest`: a tag cannot be reported truthfully.
+    steps.push({
+      label: `install ${packageName}@${latest}`,
+      command: ["bun", "install", "-g", `${packageName}@${latest}`],
+      // No cwd: a global install must not adopt the tree it is replacing.
+      cwd: undefined,
+    });
+  }
+  return { steps, skipped };
+}
+
+async function gather(): Promise<UpdateFacts> {
+  const at = await Supervisor.detectInstall();
+  const [packageName, cleanTree, latest] = await Promise.all([
+    PimVersion.name(),
+    at.kind === "dev"
+      ? Git.fetchStatus(at.packageRoot).then((git) => git.dirtyCount === 0)
+      : Promise.resolve(true),
+    at.kind === "prod" ? PimVersion.latest() : Promise.resolve(undefined),
+  ]);
+  return { at, packageName, cleanTree, latest };
+}
+
+/** Never restarts or exits: the caller owns that. */
+async function run(options: UpdateOptions = {}): Promise<UpdateOutcome> {
+  const from = await PimVersion.current();
+  const { steps, skipped } = plan(await gather());
+  for (const step of steps) {
+    await options.onStep?.(step.label);
+    try {
+      if ("command" in step) {
+        await runOrThrow(step.command, step.cwd);
+      } else {
+        await step.act();
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        from,
+        to: await PimVersion.current(),
+        skipped,
+        error: `${step.label}: ${(err as Error).message}`,
+      };
+    }
+  }
+  return {
+    ok: true,
+    from,
+    to: await PimVersion.current(),
+    skipped,
+    error: undefined,
+  };
+}
+
+async function runOrThrow(
+  cmd: ReadonlyArray<string>,
+  cwd: string | undefined
+): Promise<void> {
+  const { code, stderr } = await Proc.run(cmd, { cwd, stdout: "inherit" });
+  if (code !== 0) {
+    throw new Error(
+      `exit ${code}: ${stderr.trim().split("\n").slice(-5).join("\n") || "(no stderr)"}`
+    );
+  }
+}
+
+export const Updater = { plan, run };

package/packages/core/src/view/AnsiPainter.ts

@@ -0,0 +1,227 @@
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { DiffRenderer } from "../shared/DiffRenderer";
+import { Renderer } from "../shared/Renderer";
+import { type BlockFrame, Painting, type PainterMap } from "./Painting";
+import type {
+  BlockOf,
+  NoticeSeverity,
+  Span,
+  Tone,
+  ViewBlock,
+} from "./ViewBlock";
+
+export type { BlockFrame } from "./Painting";
+
+export type PaintedGroup =
+  | {
+      readonly frame: Exclude<BlockFrame, "embed">;
+      readonly lines: readonly string[];
+    }
+  | { readonly frame: "embed"; readonly markdown: string };
+
+function paint(blocks: readonly ViewBlock[], theme: Theme): string[] {
+  return blocks.flatMap((block) => paintBlock(block, theme));
+}
+
+function paintTitle(
+  blocks: readonly ViewBlock[],
+  theme: Theme
+): { readonly text: string; readonly markdown: boolean } {
+  const only = blocks.length === 1 ? blocks[0] : undefined;
+  if (only?.kind === "markdown") {
+    return { text: only.text, markdown: true };
+  }
+  return {
+    text: paint(blocks, theme).join(" "),
+    markdown: false,
+  };
+}
+
+function themeColorFor(tone: Tone | undefined): ThemeColor | undefined {
+  return tone === undefined || tone === "default"
+    ? undefined
+    : TONE_COLORS[tone];
+}
+
+function paintBody(blocks: readonly ViewBlock[], theme: Theme): PaintedGroup[] {
+  return Painting.groupByFrame(
+    blocks,
+    FRAMES,
+    (frame) => frame !== "embed"
+  ).map((group): PaintedGroup => {
+    const [first] = group.blocks;
+    if (first?.kind === "markdown") {
+      return { frame: "embed", markdown: first.text };
+    }
+    return {
+      frame: group.frame as Exclude<BlockFrame, "embed">,
+      lines: group.blocks.flatMap((block) => paintBlock(block, theme)),
+    };
+  });
+}
+
+const TONE_COLORS = {
+  muted: "muted",
+  dim: "dim",
+  error: "error",
+  warning: "warning",
+  accent: "accent",
+  added: "toolDiffAdded",
+  removed: "toolDiffRemoved",
+  title: "toolTitle",
+} as const satisfies Record<Exclude<Tone, "default">, ThemeColor>;
+
+const NOTICE_COLORS = {
+  info: "muted",
+  warn: "warning",
+  error: "error",
+} as const satisfies Record<NoticeSeverity, ThemeColor>;
+
+function paintBlock(block: ViewBlock, theme: Theme): readonly string[] {
+  return Painting.dispatch(PAINTERS, block, theme);
+}
+
+function paintText(block: BlockOf<"text">, theme: Theme): readonly string[] {
+  const lines = block.text.split("\n");
+  const tone = block.tone ?? "default";
+
+  if (tone === "default") {
+    return lines;
+  }
+
+  return lines.map((line) => theme.fg(TONE_COLORS[tone], line));
+}
+
+function spansText(spans: readonly Span[], theme: Theme): string {
+  return spans
+    .filter((span) => span.text !== "")
+    .map((span) => {
+      let text =
+        span.strike === true ? theme.strikethrough(span.text) : span.text;
+      if (span.strong === true) {
+        text = theme.bold(text);
+      }
+      const tone = span.tone ?? "default";
+      return tone === "default" ? text : theme.fg(TONE_COLORS[tone], text);
+    })
+    .join("");
+}
+
+function paintSpans(block: BlockOf<"spans">, theme: Theme): readonly string[] {
+  return [spansText(block.spans, theme)];
+}
+
+function paintSection(
+  block: BlockOf<"section">,
+  theme: Theme
+): readonly string[] {
+  return [
+    "",
+    Renderer.toolTitleText({
+      label: block.label,
+      title: paint(block.content, theme).join(" "),
+      theme,
+      markerColor: "success",
+    }),
+  ];
+}
+
+function paintCode(block: BlockOf<"code">, theme: Theme): readonly string[] {
+  const lines = block.text.split("\n");
+  const start = block.startLine;
+
+  if (start === undefined) {
+    return lines;
+  }
+
+  const width = Painting.lineNumberWidth(start, lines.length);
+  return lines.map(
+    (line, index) =>
+      theme.fg("muted", `${String(start + index).padStart(width)} `) + line
+  );
+}
+
+function paintDiff(block: BlockOf<"diff">, theme: Theme): readonly string[] {
+  return DiffRenderer.renderLines({
+    toolDiff: { path: block.path, hunks: block.hunks },
+    theme,
+  });
+}
+
+function paintFile(block: BlockOf<"file">, theme: Theme): readonly string[] {
+  const { range, truncated } = Painting.fileSuffix(block);
+  const suffix = `${range}${truncated}`;
+  return [suffix === "" ? block.path : block.path + theme.fg("muted", suffix)];
+}
+
+function paintList(block: BlockOf<"list">, theme: Theme): readonly string[] {
+  return Painting.hangingList(
+    block.items,
+    block.ordered === true,
+    (item) => paintBlock(item, theme),
+    (marker) => theme.fg("muted", marker)
+  );
+}
+
+function paintKv(block: BlockOf<"kv">, theme: Theme): readonly string[] {
+  const width = Math.max(0, ...block.pairs.map(([key]) => key.length + 1));
+  return block.pairs.map(
+    ([key, value]) => theme.fg("muted", `${key}:`.padEnd(width + 1)) + value
+  );
+}
+
+function paintLink(block: BlockOf<"link">, theme: Theme): readonly string[] {
+  const label = Painting.linkLabel(block);
+  if (label === block.href) {
+    return [theme.fg("mdLinkUrl", block.href)];
+  }
+  return [`${theme.fg("mdLink", label)} ${theme.fg("mdLinkUrl", block.href)}`];
+}
+
+function paintAttachment(
+  block: BlockOf<"attachment">,
+  theme: Theme
+): readonly string[] {
+  return [`${theme.fg("muted", "sent")} ${block.name}`];
+}
+
+function paintImage(block: BlockOf<"image">, theme: Theme): readonly string[] {
+  return [theme.fg("muted", Painting.imageSummary(block))];
+}
+
+function paintMarkdown(block: BlockOf<"markdown">): readonly string[] {
+  return block.text.split("\n");
+}
+
+function paintNotice(
+  block: BlockOf<"notice">,
+  theme: Theme
+): readonly string[] {
+  const color = NOTICE_COLORS[block.severity];
+  return block.text.split("\n").map((line) => theme.fg(color, line));
+}
+
+const PAINTERS: PainterMap<readonly string[], [Theme]> = {
+  text: paintText,
+  markdown: paintMarkdown,
+  spans: paintSpans,
+  section: paintSection,
+  code: paintCode,
+  diff: paintDiff,
+  file: paintFile,
+  list: paintList,
+  kv: paintKv,
+  link: paintLink,
+  attachment: paintAttachment,
+  image: paintImage,
+  notice: paintNotice,
+};
+
+const FRAMES = {
+  ...Painting.FRAMES,
+  code: "flow",
+  diff: "tight",
+} as const satisfies Record<ViewBlock["kind"], BlockFrame>;
+
+/** Paints a `ViewBlock` tree to ANSI lines. */
+export const AnsiPainter = { paint, paintTitle, themeColorFor, paintBody };

package/packages/core/src/view/BodyRenderer.ts

@@ -0,0 +1,102 @@
+import type {
+  Theme,
+  ThemeColor,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, Container } from "@earendil-works/pi-tui";
+import {
+  type PrefixSpec,
+  type RenderContext,
+  Renderer,
+} from "../shared/Renderer";
+import { AnsiPainter, type BlockFrame, type PaintedGroup } from "./AnsiPainter";
+import type { ViewBlock } from "./ViewBlock";
+
+type FrameBuilder = (group: PaintedGroup, theme: Theme) => Component[];
+
+type FrameBuilders = Record<BlockFrame, FrameBuilder>;
+
+function render(args: {
+  readonly summary?: readonly ViewBlock[];
+  readonly body?: readonly ViewBlock[];
+  readonly options: ToolRenderResultOptions;
+  readonly theme: Theme;
+  readonly context: RenderContext;
+}): Container {
+  const { summary, body, options, theme, context } = args;
+  const container =
+    (context.lastComponent as Container | undefined) ?? new Container();
+  container.clear();
+
+  let drew = draw(container, summary ?? [], SUMMARY_BUILDERS, theme);
+  if (!options.isPartial && options.expanded) {
+    drew = draw(container, body ?? [], FRAME_BUILDERS, theme) || drew;
+  }
+
+  if (drew) {
+    container.invalidate();
+  }
+  return container;
+}
+
+function draw(
+  container: Container,
+  blocks: readonly ViewBlock[],
+  builders: FrameBuilders,
+  theme: Theme
+): boolean {
+  let drew = false;
+  for (const group of AnsiPainter.paintBody(blocks, theme)) {
+    for (const child of builders[group.frame](group, theme)) {
+      container.addChild(child);
+      drew = true;
+    }
+  }
+  return drew;
+}
+
+function gutter(prefix: PrefixSpec, lineColor?: ThemeColor): FrameBuilder {
+  return (group, theme) => {
+    if (group.frame === "embed") {
+      return [
+        Renderer.makeMarkdownBlock({
+          text: group.markdown,
+          theme,
+          prefix,
+          lineColor,
+        }),
+      ];
+    }
+    const lines = group.lines;
+    return lines.length === 0 || (lines.length === 1 && lines[0] === "")
+      ? []
+      : [Renderer.makePrefixedBlock({ lines, theme, prefix, lineColor })];
+  };
+}
+
+function blankLine(): Component {
+  return { render: () => [""], invalidate() {} };
+}
+
+function headings(group: PaintedGroup, theme: Theme): Component[] {
+  const lines =
+    group.frame === "embed" ? group.markdown.split("\n") : group.lines;
+  return lines.map((line) =>
+    line === "" ? blankLine() : Renderer.makeTitleBlock({ text: line, theme })
+  );
+}
+
+const FRAME_BUILDERS: FrameBuilders = {
+  flow: gutter(Renderer.GAPPED_PREFIX, "toolOutput"),
+  embed: gutter(Renderer.GAPPED_PREFIX),
+  tight: gutter(Renderer.TIGHT_PREFIX),
+  heading: headings,
+};
+
+const SUMMARY_BUILDERS: FrameBuilders = {
+  ...FRAME_BUILDERS,
+  flow: gutter(Renderer.GAPPED_PREFIX),
+};
+
+/** Turns painted body lines into the pi-tui components that frame them. */
+export const BodyRenderer = { render };

package/packages/core/src/view/DiffBlocks.ts

@@ -0,0 +1,52 @@
+import type { ToolDiff } from "../shared/DiffLines";
+import { DiffView } from "../shared/DiffView";
+import { Paths } from "../shared/Paths";
+import type { Span, ToolView, ViewBlock } from "./ViewBlock";
+
+function statSpans(diff: ToolDiff | undefined): readonly Span[] {
+  const { added, removed } = DiffView.countStats(diff);
+  const spans: Span[] = [];
+
+  if (added > 0) {
+    spans.push({ text: `+${added}`, tone: "added" });
+  }
+  if (removed > 0) {
+    if (spans.length > 0) {
+      spans.push({ text: "/" });
+    }
+    spans.push({ text: `-${removed}`, tone: "removed" });
+  }
+
+  return spans;
+}
+
+function stats(diff: ToolDiff | undefined): readonly ViewBlock[] {
+  const spans = statSpans(diff);
+  return spans.length === 0 ? [] : [{ kind: "spans", spans }];
+}
+
+function body(diff: ToolDiff | undefined): readonly ViewBlock[] {
+  return diff === undefined
+    ? []
+    : [{ kind: "diff", path: diff.path, hunks: diff.hunks }];
+}
+
+function fileView(args: {
+  readonly label: string;
+  readonly path: string | undefined;
+  readonly cwd: string;
+  readonly diff: ToolDiff | undefined;
+}): ToolView {
+  return {
+    label: args.label,
+    icon: "edit",
+    title: [
+      { kind: "file", path: Paths.titleOr(args.path, args.cwd) },
+      ...stats(args.diff),
+    ],
+    body: body(args.diff),
+  };
+}
+
+/** View-model fragments shared by every tool that reports a file diff. */
+export const DiffBlocks = { statSpans, stats, body, fileView };

package/packages/core/src/view/DiffLayout.ts

@@ -0,0 +1,69 @@
+import type { ToolDiffHunk } from "../shared/DiffLines";
+
+const TAB = "   ";
+
+function detab(text: string): string {
+  return text.replace(/\t/g, TAB);
+}
+
+// Highlight each side as one block, never line by line, or multi-line strings and comments mis-tokenise.
+function mapSides<T>(
+  hunk: ToolDiffHunk,
+  highlight: (block: string) => readonly T[]
+): readonly (T | undefined)[] {
+  const oldIndices: (number | undefined)[] = [];
+  const newIndices: (number | undefined)[] = [];
+  const oldBlock: string[] = [];
+  const newBlock: string[] = [];
+
+  for (const line of hunk.lines) {
+    // A context line must hold a slot in both blocks to keep tokeniser state aligned.
+    if (line.kind !== "added") {
+      oldIndices.push(oldBlock.length);
+      oldBlock.push(line.text);
+    } else {
+      oldIndices.push(undefined);
+    }
+
+    if (line.kind !== "removed") {
+      newIndices.push(newBlock.length);
+      newBlock.push(line.text);
+    } else {
+      newIndices.push(undefined);
+    }
+  }
+
+  const oldLines = oldBlock.length === 0 ? [] : highlight(oldBlock.join("\n"));
+  const newLines = newBlock.length === 0 ? [] : highlight(newBlock.join("\n"));
+
+  return hunk.lines.map((line, index) => {
+    const side = line.kind === "removed" ? oldLines : newLines;
+    const at = line.kind === "removed" ? oldIndices[index] : newIndices[index];
+    return at === undefined ? undefined : side[at];
+  });
+}
+
+function gutterWidth(hunks: readonly ToolDiffHunk[]): number {
+  let max = 0;
+
+  for (const hunk of hunks) {
+    max = Math.max(max, hunk.oldStart + hunk.oldLines - 1);
+    max = Math.max(max, hunk.newStart + hunk.newLines - 1);
+  }
+
+  return Math.max(1, String(max).length);
+}
+
+function lineNumber(line: ToolDiffHunk["lines"][number]): number | undefined {
+  if (line.kind === "added") {
+    return line.newLine;
+  }
+
+  if (line.kind === "removed") {
+    return line.oldLine;
+  }
+
+  return line.newLine ?? line.oldLine;
+}
+
+export const DiffLayout = { detab, mapSides, gutterWidth, lineNumber };