@mcuste/pi-diagram 0.0.0

package/src/display.ts

@@ -0,0 +1,201 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Turns a diagram result into terminal components. Both the image and the text are drawn here
+ * rather than by the host, so neither has to travel back through the model's context. The image is
+ * read from the temp store at display time.
+ */
+
+/** Wide enough for an architecture diagram, short enough to leave the transcript readable. */
+const MAX_WIDTH_CELLS = 80;
+/** Without a bound the library reserves a square, about 40 rows, drawn or not. */
+const MAX_HEIGHT_CELLS = 30;
+const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+
+export interface Component {
+  render(width: number): string[];
+}
+
+export interface DisplayTheme {
+  fg(color: string, text: string): string;
+}
+
+export interface DisplayContext {
+  readonly showImages: boolean;
+  readonly expanded: boolean;
+  /** Per-row scratch space from the host, used to read each image only once. */
+  readonly state: Record<string, unknown>;
+}
+
+interface DisplayImage {
+  readonly path: string;
+  readonly widthPx: number;
+  readonly heightPx: number;
+}
+
+interface TuiModule {
+  readonly getCapabilities: () => { readonly images: "kitty" | "iterm2" | null };
+  readonly Text: new (text?: string, paddingX?: number, paddingY?: number) => Component;
+  readonly Container: new () => Component & { addChild(child: Component): void };
+  readonly Image: new (
+    base64Data: string,
+    mimeType: string,
+    theme: { fallbackColor: (text: string) => string },
+    options?: { maxWidthCells?: number; maxHeightCells?: number; filename?: string },
+    dimensions?: { widthPx: number; heightPx: number },
+  ) => Component;
+}
+
+let tui: TuiModule | undefined;
+
+/**
+ * The library keeps image placement state in module scope, so the host and this package have to
+ * use the same copy. A local checkout has its own, which wins by bare name.
+ */
+export function tuiSpecifier(entry: string | undefined): string {
+  if (entry !== undefined) {
+    try {
+      return pathToFileURL(createRequire(entry).resolve("@earendil-works/pi-tui")).href;
+    } catch {
+      // Not resolvable from the host, so fall back to whatever this package can see.
+    }
+  }
+  return "@earendil-works/pi-tui";
+}
+
+/** Loaded once at registration, since a render cannot wait on an import. */
+export function primeDisplay(): Promise<void> {
+  if (tui !== undefined) {
+    return Promise.resolve();
+  }
+  return import(tuiSpecifier(process.argv[1])).then(
+    (module) => {
+      tui = module as unknown as TuiModule;
+    },
+    () => {
+      // Text rendering needs none of this, so a missing library is not worth reporting.
+    },
+  );
+}
+
+/** Whether the terminal speaks an image protocol, or `undefined` until the library has loaded. */
+export function imagesSupported(): boolean | undefined {
+  return tui === undefined ? undefined : tui.getCapabilities().images !== null;
+}
+
+/** Whether this package can draw a result row at all, or the host has to print the text. */
+export function displayLoaded(): boolean {
+  return tui !== undefined;
+}
+
+/** Throws when the library is missing, which the host takes as a request to draw the row itself. */
+function loadedModule(): TuiModule {
+  if (tui === undefined) {
+    primeDisplay();
+    throw new Error("The TUI library is not loaded.");
+  }
+  return tui;
+}
+
+export interface DiagramCallView {
+  /** What is being drawn: the title, or a line count when there is no title. */
+  readonly subject: string;
+  /** The profile, and the directory when the call also saves files. */
+  readonly note: string;
+}
+
+/** The row while D2 runs. The source would fill the transcript, so it is not shown. */
+export function renderDiagramCall(view: DiagramCallView, theme: DisplayTheme): Component {
+  const module = loadedModule();
+  const text = [
+    theme.fg("toolTitle", "diagram "),
+    theme.fg("accent", view.subject),
+    " ",
+    theme.fg("muted", view.note),
+  ].join("");
+  return new module.Text(text, 0, 0);
+}
+
+export function renderDiagramResult(
+  view: DiagramView,
+  theme: DisplayTheme,
+  context: DisplayContext,
+): Component {
+  const module = loadedModule();
+  const container = new module.Container();
+  const line = (text: string): void => {
+    container.addChild(new module.Text(theme.fg("toolOutput", text), 0, 0));
+  };
+  if (view.title !== undefined) {
+    line(view.title);
+  }
+
+  const image = drawable(module, view.image, context) ? view.image : undefined;
+  if (image === undefined) {
+    line(view.text);
+  } else {
+    try {
+      container.addChild(
+        new module.Image(
+          read(image, context),
+          "image/png",
+          { fallbackColor: (text: string) => theme.fg("toolOutput", text) },
+          {
+            maxWidthCells: MAX_WIDTH_CELLS,
+            maxHeightCells: MAX_HEIGHT_CELLS,
+            filename: image.path,
+          },
+          { widthPx: image.widthPx, heightPx: image.heightPx },
+        ),
+      );
+    } catch {
+      // The picture is gone from the temp store, so show the text instead.
+      line(view.text);
+    }
+  }
+
+  const footer = [...view.notes, ...(context.expanded ? view.details : [])];
+  if (footer.length > 0) {
+    line(footer.join("\n"));
+  }
+  return container;
+}
+
+function drawable(
+  module: TuiModule,
+  image: DisplayImage | undefined,
+  context: DisplayContext,
+): boolean {
+  return image !== undefined && context.showImages && module.getCapabilities().images !== null;
+}
+
+export interface DiagramView {
+  readonly image: DisplayImage | undefined;
+  readonly title: string | undefined;
+  /** Drawn when there is no image, or when the one there is cannot be shown. */
+  readonly text: string;
+  readonly notes: readonly string[];
+  /** Render mode, paths, diagnostics, and source. Shown only in the expanded row. */
+  readonly details: readonly string[];
+}
+
+/** Reads the image once per result row: the host calls the renderer again on every redraw. */
+function read(image: DisplayImage, context: DisplayContext): string {
+  const cached = context.state["diagramImage"];
+  if (typeof cached === "object" && cached !== null) {
+    const { path, encoded } = cached as { path?: unknown; encoded?: unknown };
+    if (path === image.path && typeof encoded === "string") {
+      return encoded;
+    }
+  }
+
+  const bytes = readFileSync(image.path);
+  if (bytes.length === 0 || bytes.length > MAX_IMAGE_BYTES) {
+    throw new Error(`The image at ${image.path} is ${bytes.length} bytes.`);
+  }
+  const encoded = bytes.toString("base64");
+  context.state["diagramImage"] = { path: image.path, encoded };
+  return encoded;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import { type DiagramExtensionApi, registerDiagramTools } from "./tools.js";
+
+export default function piDiagram(pi: DiagramExtensionApi): void {
+  registerDiagramTools(pi);
+}

package/src/normalize.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { DiagramSourceError } from "./d2/diagnostics.js";
+
+/** Byte-level enforcement of the schema's character limit in `tools.ts`. */
+const MAX_SOURCE_BYTES = 20 * 1024;
+const MAX_TITLE_LENGTH = 120;
+
+const TAB = 0x09;
+const LINE_FEED = 0x0a;
+const FIRST_PRINTABLE = 0x20;
+const DELETE = 0x7f;
+const BYTE_ORDER_MARK = 0xfeff;
+
+declare const normalizedSourceBrand: unique symbol;
+declare const safeTitleBrand: unique symbol;
+
+/**
+ * Source in canonical form: no byte-order mark, LF endings, trimmed, no control characters,
+ * within the size cap. Only `normalizeSource` can produce one.
+ */
+export type NormalizedD2Source = string & { readonly [normalizedSourceBrand]: true };
+
+/** A single-line title of bounded length, safe to show beside the diagram. */
+export type SafeTitle = string & { readonly [safeTitleBrand]: true };
+
+export interface NormalizedSource {
+  readonly text: NormalizedD2Source;
+  readonly hash: string;
+  readonly lineCount: number;
+}
+
+interface FoundControl {
+  readonly offset: number;
+  readonly codePoint: number;
+}
+
+/** Characters a terminal would act on rather than print. */
+function isControl(codePoint: number): boolean {
+  if (codePoint === TAB || codePoint === LINE_FEED) {
+    return false;
+  }
+  return codePoint < FIRST_PRINTABLE || codePoint === DELETE;
+}
+
+function findControl(text: string): FoundControl | undefined {
+  let offset = 0;
+  for (const character of text) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (isControl(codePoint)) {
+      return { offset, codePoint };
+    }
+    offset += character.length;
+  }
+  return undefined;
+}
+
+/** Runs before anything inspects or renders, so the scanner and D2 see the same bytes. */
+export function normalizeSource(raw: unknown): NormalizedSource {
+  if (typeof raw !== "string") {
+    throw new DiagramSourceError("Diagram source must be a string.", [
+      { code: "D2_SOURCE", message: `Received ${raw === null ? "null" : typeof raw}.` },
+    ]);
+  }
+
+  const text = stripByteOrderMark(raw).replace(/\r\n?/gu, "\n").trim();
+  if (text.length === 0) {
+    throw new DiagramSourceError("Diagram source is empty.", [
+      { code: "D2_SOURCE", message: "Send D2 source such as `client -> gateway: request`." },
+    ]);
+  }
+
+  const control = findControl(text);
+  if (control) {
+    const label = control.codePoint.toString(16).padStart(4, "0").toUpperCase();
+    throw new DiagramSourceError("Diagram source contains a control character.", [
+      {
+        code: "D2_SOURCE",
+        message: `U+${label} at offset ${control.offset} is not allowed in diagram source.`,
+      },
+    ]);
+  }
+
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes > MAX_SOURCE_BYTES) {
+    throw new DiagramSourceError("Diagram source is too large.", [
+      {
+        code: "D2_TOO_LARGE",
+        message: `${bytes} bytes is above the ${MAX_SOURCE_BYTES} byte limit.`,
+        hint: "Split it into smaller diagrams.",
+      },
+    ]);
+  }
+
+  return {
+    text: text as NormalizedD2Source,
+    hash: createHash("sha256").update(text, "utf8").digest("hex"),
+    lineCount: text.split("\n").length,
+  };
+}
+
+export function parseTitle(raw: unknown): SafeTitle | undefined {
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const printable = Array.from(raw, (character) =>
+    isControl(character.codePointAt(0) ?? 0) ? " " : character,
+  ).join("");
+  const title = printable.replace(/\s+/gu, " ").trim();
+  if (title.length === 0) {
+    return undefined;
+  }
+  const capped =
+    title.length > MAX_TITLE_LENGTH ? `${title.slice(0, MAX_TITLE_LENGTH - 3)}...` : title;
+  return capped as SafeTitle;
+}
+
+function stripByteOrderMark(raw: string): string {
+  return raw.codePointAt(0) === BYTE_ORDER_MARK ? raw.slice(1) : raw;
+}

package/src/process.ts

@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+
+const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+
+export interface CommandResult {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface RunCommandOptions {
+  readonly cwd: string;
+  readonly signal?: AbortSignal | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly maxOutputBytes?: number | undefined;
+}
+
+export type CommandRunner = (
+  command: string,
+  args: readonly string[],
+  options: RunCommandOptions,
+) => Promise<CommandResult>;
+
+/** The command never started, which is what a missing D2 install looks like. */
+export class CommandInvocationError extends Error {
+  readonly command: string;
+  readonly code: string | undefined;
+
+  constructor(command: string, message: string, code: string | undefined, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CommandInvocationError";
+    this.command = command;
+    this.code = code;
+  }
+}
+
+export class CommandCancelledError extends Error {
+  constructor(command: string) {
+    super(`${command} was cancelled.`);
+    this.name = "CommandCancelledError";
+  }
+}
+
+export class CommandTimeoutError extends Error {
+  readonly command: string;
+  readonly timeoutMs: number;
+
+  constructor(command: string, timeoutMs: number) {
+    super(`${command} did not finish within ${timeoutMs} ms and was stopped.`);
+    this.name = "CommandTimeoutError";
+    this.command = command;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/** A `maxBuffer` kill is a size limit, not a broken executable, so it is not a spawn failure. */
+export class CommandOutputLimitError extends Error {
+  readonly command: string;
+  readonly maxOutputBytes: number;
+
+  constructor(command: string, maxOutputBytes: number, options?: ErrorOptions) {
+    super(`${command} produced more than ${maxOutputBytes} bytes of output and was stopped.`, {
+      ...options,
+    });
+    this.name = "CommandOutputLimitError";
+    this.command = command;
+    this.maxOutputBytes = maxOutputBytes;
+  }
+}
+
+export const runCommand: CommandRunner = (command, args, options) => {
+  if (options.signal?.aborted) {
+    return Promise.reject(new CommandCancelledError(command));
+  }
+
+  const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const timeoutMs = options.timeoutMs ?? 0;
+  const { promise, resolve, reject } = Promise.withResolvers<CommandResult>();
+  execFile(
+    command,
+    [...args],
+    {
+      cwd: options.cwd,
+      encoding: "utf8",
+      maxBuffer: maxOutputBytes,
+      signal: options.signal,
+      timeout: timeoutMs,
+      env: options.env,
+      windowsHide: true,
+    },
+    (error, stdout, stderr) => {
+      if (options.signal?.aborted || error?.name === "AbortError") {
+        reject(new CommandCancelledError(command));
+        return;
+      }
+
+      if (error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+        reject(new CommandOutputLimitError(command, maxOutputBytes, { cause: error }));
+        return;
+      }
+
+      // `timeout` kills the child with a signal, which arrives without a numeric exit code.
+      if (timeoutMs > 0 && error?.signal && typeof error.code !== "number") {
+        reject(new CommandTimeoutError(command, timeoutMs));
+        return;
+      }
+
+      if (error && typeof error.code !== "number") {
+        const detail = error.message.trim();
+        reject(
+          new CommandInvocationError(
+            command,
+            `Unable to execute ${command}: ${detail}`,
+            typeof error.code === "string" ? error.code : undefined,
+            { cause: error },
+          ),
+        );
+        return;
+      }
+
+      resolve({
+        command,
+        args: [...args],
+        exitCode: typeof error?.code === "number" ? error.code : 0,
+        stdout,
+        stderr,
+      });
+    },
+  );
+  return promise;
+};