@mcuste/pi-diagram 0.0.0

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@mcuste/pi-diagram",
+  "version": "0.0.0",
+  "description": "Terminal-native diagram rendering as one safe, model-callable tool for the Pi and Oh My Pi coding agents",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "oh-my-pi",
+    "omp",
+    "extension",
+    "diagram",
+    "d2",
+    "architecture-diagram",
+    "sequence-diagram",
+    "svg",
+    "ascii"
+  ],
+  "license": "MIT",
+  "author": "mcuste",
+  "homepage": "https://github.com/mcuste/pi-diagram#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcuste/pi-diagram.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcuste/pi-diagram/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "typebox": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.9",
+    "@earendil-works/pi-tui": "^0.84.2",
+    "@types/node": "^26.2.0",
+    "knip": "6.32.2",
+    "publint": "0.3.23",
+    "typebox": "^1.3.15",
+    "typescript": "^7.0.2"
+  },
+  "knip": {
+    "entry": [
+      "test/**/*.test.mjs",
+      "test/**/*.e2e.mjs",
+      "scripts/*.mjs"
+    ],
+    "project": [
+      "src/**/*.ts",
+      "test/**/*.mjs",
+      "scripts/*.mjs"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "pnpm quality && pnpm package:check && pnpm test && pnpm test:integration && pnpm deadcode && pnpm security",
+    "deadcode": "knip",
+    "fix": "biome check --write .",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "package:check": "pnpm build && publint",
+    "preview": "pnpm build && node scripts/preview.mjs",
+    "quality": "biome check .",
+    "release": "node scripts/release.mjs",
+    "security": "pnpm audit --audit-level high",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "test:integration": "pnpm build && node --test test/*.e2e.mjs"
+  }
+}

package/src/artifacts.ts

@@ -0,0 +1,418 @@
+import { randomUUID } from "node:crypto";
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { DiagramSourceError } from "./d2/diagnostics.js";
+
+/**
+ * Writes diagram artifacts. Files land in a private temporary directory unless a call names a
+ * repository destination, because most diagrams explain something in passing and have no
+ * business being committed.
+ */
+
+const MAX_BASENAME_LENGTH = 60;
+const MAX_DIRECTORY_LENGTH = 255;
+/** Keeps a long session from filling the temp directory with diagrams nobody opened. */
+const MAX_TEMP_FILES = 64;
+
+const EXTENSIONS = {
+  source: ".d2",
+  svg: ".svg",
+  png: ".png",
+  txt: ".txt",
+} as const;
+
+export type ArtifactFormat = keyof typeof EXTENSIONS;
+
+/** Editable source plus a viewable rendering. */
+const DEFAULT_FORMATS: readonly ArtifactFormat[] = ["source", "svg"];
+
+/** Names Windows treats as devices rather than files, whatever extension follows. */
+const RESERVED_NAMES: ReadonlySet<string> = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  ...Array.from({ length: 9 }, (_, index) => `com${index + 1}`),
+  ...Array.from({ length: 9 }, (_, index) => `lpt${index + 1}`),
+]);
+
+declare const safeBasenameBrand: unique symbol;
+declare const artifactDirectoryBrand: unique symbol;
+
+/** A file name stem with no path separators, extension, or reserved meaning. */
+type SafeBasename = string & { readonly [safeBasenameBrand]: true };
+
+/** An absolute directory that is either the session temp store or inside the workspace root. */
+type ArtifactDirectory = string & { readonly [artifactDirectoryBrand]: true };
+
+type ArtifactLocation = "temp" | "workspace";
+
+export interface ArtifactNames {
+  /** Workspace-relative destination, or `undefined` to keep the files out of the repository. */
+  readonly directory: string | undefined;
+  readonly basename: SafeBasename;
+  readonly formats: readonly ArtifactFormat[];
+}
+
+export interface ArtifactTarget {
+  readonly location: ArtifactLocation;
+  readonly directory: ArtifactDirectory;
+  readonly names: ArtifactNames;
+  readonly root: string;
+}
+
+export interface WrittenArtifact {
+  readonly format: ArtifactFormat;
+  readonly location: ArtifactLocation;
+  /** Workspace-relative for a repository file, absolute for a temporary one. */
+  readonly path: string;
+}
+
+function refuse(summary: string, message: string, hint?: string): never {
+  throw new DiagramSourceError(summary, [
+    { code: "D2_SOURCE", message, ...(hint === undefined ? {} : { hint }) },
+  ]);
+}
+
+function parseFormats(requested: unknown): readonly ArtifactFormat[] {
+  if (requested === undefined) {
+    return DEFAULT_FORMATS;
+  }
+  if (!Array.isArray(requested) || requested.length === 0) {
+    refuse(
+      "Diagram save formats are not usable.",
+      `Expected a non-empty list, got ${typeof requested}.`,
+    );
+  }
+
+  const formats: ArtifactFormat[] = [];
+  for (const format of requested) {
+    if (!Object.hasOwn(EXTENSIONS, format)) {
+      refuse(
+        "Diagram save formats are not usable.",
+        `${JSON.stringify(format)} is not a format.`,
+        `Use ${Object.keys(EXTENSIONS).join(", ")}.`,
+      );
+    }
+    if (!formats.includes(format)) {
+      formats.push(format);
+    }
+  }
+  return formats;
+}
+
+/** A repository destination has to be named. There is no directory convention worth assuming. */
+function parseDirectory(requested: unknown): string {
+  if (typeof requested !== "string" || requested.trim().length === 0) {
+    refuse(
+      "Saving a diagram needs a directory.",
+      requested === undefined
+        ? "`save.dir` was not given."
+        : `Expected a path, got ${typeof requested}.`,
+      "Name the directory to write into, such as docs/diagrams.",
+    );
+  }
+
+  const directory = requested.trim().replaceAll("\\", "/");
+  if (directory.length > MAX_DIRECTORY_LENGTH) {
+    refuse(
+      "Diagram save directory is not usable.",
+      `It is longer than ${MAX_DIRECTORY_LENGTH} characters.`,
+    );
+  }
+  if (isAbsolute(requested) || directory.startsWith("/")) {
+    refuse(
+      "Diagram save directory is not usable.",
+      `${JSON.stringify(requested)} is an absolute path.`,
+      "Give a path relative to the workspace, such as docs/diagrams.",
+    );
+  }
+  const segments = directory.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+  if (segments.includes("..")) {
+    refuse(
+      "Diagram save directory is not usable.",
+      `${JSON.stringify(requested)} climbs out of the workspace.`,
+      "Give a path inside the workspace.",
+    );
+  }
+  return segments.length === 0 ? "." : segments.join("/");
+}
+
+function parseSave(requested: unknown): { readonly directory: string; readonly basename: unknown } {
+  if (typeof requested !== "object" || requested === null || Array.isArray(requested)) {
+    refuse("Diagram save options are not usable.", `Expected an object, got ${typeof requested}.`);
+  }
+  return {
+    directory: parseDirectory(Reflect.get(requested, "dir")),
+    basename: Reflect.get(requested, "basename"),
+  };
+}
+
+function slugify(value: string): string {
+  return value
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+/u, "")
+    .slice(0, MAX_BASENAME_LENGTH)
+    .replace(/-+$/u, "");
+}
+
+/**
+ * A repository file needs a name someone chose, so regenerating the diagram lands on the same
+ * path. A temporary file falls back to the source hash, so an ad-hoc diagram needs no title.
+ */
+function parseBasename(
+  requested: unknown,
+  title: string | undefined,
+  fallback: string | undefined,
+): SafeBasename {
+  const chosen = typeof requested === "string" && requested.trim().length > 0 ? requested : title;
+  if (chosen === undefined) {
+    if (fallback !== undefined) {
+      return fallback as SafeBasename;
+    }
+    refuse(
+      "A diagram saved into the repository needs a name.",
+      "Neither `save.basename` nor `title` was given.",
+      "Add a title so the file keeps the same name when the diagram is regenerated.",
+    );
+  }
+
+  const basename = slugify(chosen);
+  if (basename.length === 0) {
+    refuse(
+      "A saved diagram needs a usable name.",
+      `${JSON.stringify(chosen)} has no letters or digits to build a file name from.`,
+    );
+  }
+  if (RESERVED_NAMES.has(basename)) {
+    refuse("A saved diagram needs a different name.", `${basename} is a reserved device name.`);
+  }
+  return basename as SafeBasename;
+}
+
+export interface ArtifactIdentity {
+  readonly title: string | undefined;
+  /** Hash of the normalized source, used to name a temporary file with no title. */
+  readonly hash: string;
+}
+
+export interface ArtifactAsk {
+  /** Which artifacts to produce. They land in the temp store either way. */
+  readonly formats?: unknown;
+  /** Present only when the caller also wants them in the repository. */
+  readonly save?: unknown;
+}
+
+/** Resolves nothing on disk, so a bad request is refused before any rendering starts. */
+export function parseArtifactNames(
+  request: ArtifactAsk,
+  identity: ArtifactIdentity,
+): ArtifactNames {
+  const save = request.save === undefined ? undefined : parseSave(request.save);
+  const fallback = save === undefined ? `diagram-${identity.hash.slice(0, 12)}` : undefined;
+  return {
+    directory: save?.directory,
+    basename: parseBasename(save?.basename, identity.title, fallback),
+    formats: parseFormats(request.formats),
+  };
+}
+
+/** The workspace-relative paths a repository write would touch, for an approval prompt. */
+export function workspacePaths(names: ArtifactNames): readonly string[] {
+  if (names.directory === undefined) {
+    return [];
+  }
+  const prefix = names.directory === "." ? "" : `${names.directory}/`;
+  return names.formats.map((format) => `${prefix}${names.basename}${EXTENSIONS[format]}`);
+}
+
+function contains(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+
+/**
+ * Checks the deepest existing ancestor, before any directory is created: a `docs` symlink
+ * pointing outside would otherwise have `mkdir` build the rest of the path beyond it.
+ */
+async function assertInsideWorkspace(realRoot: string, target: string): Promise<void> {
+  if (!contains(realRoot, target)) {
+    refuse(
+      "Diagram save directory is outside the workspace.",
+      `${target} is not inside ${realRoot}.`,
+    );
+  }
+
+  let probe = target;
+  for (;;) {
+    try {
+      const real = await realpath(probe);
+      if (!contains(realRoot, real)) {
+        refuse(
+          "Diagram save directory leaves the workspace.",
+          `${probe} resolves to ${real}, outside ${realRoot}.`,
+          "A symbolic link on that path points outside the workspace.",
+        );
+      }
+      return;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw error;
+      }
+      const parent = dirname(probe);
+      if (parent === probe) {
+        refuse("Diagram save directory is not usable.", `No part of ${target} exists.`);
+      }
+      probe = parent;
+    }
+  }
+}
+
+let sessionStore: Promise<string> | undefined;
+
+/**
+ * `mkdtemp` creates the directory owner-only, so diagrams that quote repository content are not
+ * readable by other users of a shared machine.
+ */
+function sessionDirectory(): Promise<string> {
+  sessionStore ??= mkdtemp(join(tmpdir(), "pi-diagram-store-"));
+  return sessionStore;
+}
+
+export async function parseArtifactTarget(
+  cwd: unknown,
+  names: ArtifactNames,
+): Promise<ArtifactTarget> {
+  if (names.directory === undefined) {
+    const directory = await sessionDirectory();
+    return { location: "temp", directory: directory as ArtifactDirectory, names, root: directory };
+  }
+
+  if (typeof cwd !== "string" || cwd.length === 0 || !isAbsolute(cwd)) {
+    refuse(
+      "Diagrams cannot be saved into a repository without a workspace directory.",
+      `The host gave ${JSON.stringify(cwd)}.`,
+    );
+  }
+
+  const root = resolve(cwd);
+  let realRoot: string;
+  try {
+    realRoot = await realpath(root);
+  } catch (error) {
+    refuse(
+      "The workspace directory cannot be read.",
+      `${root} could not be resolved: ${(error as Error).message}.`,
+    );
+  }
+
+  const directory = resolve(realRoot, names.directory);
+  await assertInsideWorkspace(realRoot, directory);
+  return {
+    location: "workspace",
+    directory: directory as ArtifactDirectory,
+    names,
+    root: realRoot,
+  };
+}
+
+/**
+ * Writes each artifact through a temporary file and a rename, so a reader never sees a half
+ * written diagram and a failed render leaves the previous version in place.
+ */
+export async function writeArtifacts(
+  target: ArtifactTarget,
+  contents: ReadonlyMap<ArtifactFormat, string | Uint8Array>,
+): Promise<readonly WrittenArtifact[]> {
+  await mkdir(target.directory, { recursive: true });
+  if (target.location === "workspace") {
+    // The directory exists now, so this catches a link created between the check and the write.
+    await assertInsideWorkspace(target.root, target.directory);
+  }
+
+  const written: WrittenArtifact[] = [];
+  for (const format of target.names.formats) {
+    const content = contents.get(format);
+    if (content === undefined) {
+      continue;
+    }
+
+    const destination = join(target.directory, `${target.names.basename}${EXTENSIONS[format]}`);
+    await assertWritable(destination);
+    const temporary = join(target.directory, `.${target.names.basename}.${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, content, {
+        ...(typeof content === "string" ? { encoding: "utf8" as const } : {}),
+        mode: 0o644,
+      });
+      await rename(temporary, destination);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+    written.push({
+      format,
+      location: target.location,
+      path:
+        target.location === "workspace"
+          ? relative(target.root, destination).split(sep).join("/")
+          : destination,
+    });
+  }
+
+  if (target.location === "temp") {
+    await evictOldest(target.directory);
+  }
+  return written;
+}
+
+/** Regenerating a diagram replaces its own files, but never anything that is not a plain file. */
+async function assertWritable(destination: string): Promise<void> {
+  try {
+    const existing = await lstat(destination);
+    if (!existing.isFile()) {
+      refuse(
+        "That diagram path cannot be written.",
+        `${destination} already exists and is not a regular file.`,
+      );
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function evictOldest(directory: string): Promise<void> {
+  const names = await readdir(directory);
+  if (names.length <= MAX_TEMP_FILES) {
+    return;
+  }
+
+  const aged = await Promise.all(
+    names.map(async (name) => {
+      const path = join(directory, name);
+      try {
+        return { path, at: (await stat(path)).mtimeMs };
+      } catch {
+        return { path, at: Number.POSITIVE_INFINITY };
+      }
+    }),
+  );
+  aged.sort((left, right) => left.at - right.at);
+  for (const { path } of aged.slice(0, aged.length - MAX_TEMP_FILES)) {
+    await rm(path, { force: true, recursive: true });
+  }
+}

package/src/d2/diagnostics.ts

@@ -0,0 +1,114 @@
+/**
+ * One vocabulary for every refusal, including D2's own errors, so a policy rejection and a
+ * syntax error read the same way and the model has one thing to correct.
+ */
+
+const MAX_DIAGNOSTICS = 10;
+const MAX_MESSAGE_LENGTH = 200;
+
+export type DiagnosticCode =
+  | "D2_SOURCE"
+  | "D2_TOO_LARGE"
+  | "D2_TIMEOUT"
+  | "D2_IMPORT"
+  | "D2_ICON"
+  | "D2_LINK"
+  | "D2_IMAGE_SHAPE"
+  | "D2_UNKNOWN_SHAPE"
+  | "D2_BLOCK_STRING"
+  | "D2_CONFIG"
+  | "D2_UNTERMINATED"
+  | "D2_SYNTAX"
+  | "D2_RENDER";
+
+export interface Diagnostic {
+  readonly code: DiagnosticCode;
+  readonly message: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly hint?: string;
+}
+
+/** A refusal the model can fix by editing its source. What it cannot fix gets another type. */
+export class DiagramSourceError extends Error {
+  readonly diagnostics: readonly Diagnostic[];
+
+  constructor(summary: string, diagnostics: readonly Diagnostic[]) {
+    const capped = diagnostics.slice(0, MAX_DIAGNOSTICS);
+    super(capped.length > 0 ? `${summary}\n${formatDiagnostics(capped)}` : summary);
+    this.name = "DiagramSourceError";
+    this.diagnostics = capped;
+  }
+}
+
+function formatDiagnostics(diagnostics: readonly Diagnostic[]): string {
+  return diagnostics.map(formatDiagnostic).join("\n");
+}
+
+/** One line, indented, the way it reads inside a refusal message. */
+export function formatDiagnostic(diagnostic: Diagnostic): string {
+  const at =
+    diagnostic.line === undefined
+      ? ""
+      : diagnostic.column === undefined
+        ? `line ${diagnostic.line}: `
+        : `line ${diagnostic.line}, column ${diagnostic.column}: `;
+  const hint = diagnostic.hint === undefined ? "" : ` ${diagnostic.hint}`;
+  return `  ${at}${diagnostic.message}${hint} [${diagnostic.code}]`;
+}
+
+/** Prefixes D2 adds that do not help the model fix its source. */
+const NOISE_PREFIXES = [/^err:\s*/u, /^failed to compile [^:]*:\s*/u, /^github\.com\/\S+:\s*/u];
+
+const LOCATION = /(\d+):(\d+):\s*(.+)$/u;
+
+/**
+ * `secretPaths` are absolute paths from the isolated render directory. D2 puts them in render
+ * errors, and they must not reach the model or the transcript.
+ */
+export function parseD2Diagnostics(
+  stderr: string,
+  code: DiagnosticCode,
+  secretPaths: readonly string[],
+): readonly Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  for (const rawLine of stderr.split("\n")) {
+    if (diagnostics.length >= MAX_DIAGNOSTICS) {
+      break;
+    }
+    const scrubbed = scrub(rawLine, secretPaths);
+    if (scrubbed.length === 0) {
+      continue;
+    }
+    const location = LOCATION.exec(scrubbed);
+    if (location) {
+      const [, line, column, message] = location;
+      diagnostics.push({
+        code,
+        message: cap(message ?? scrubbed),
+        line: Number(line),
+        column: Number(column),
+      });
+      continue;
+    }
+    diagnostics.push({ code, message: cap(scrubbed) });
+  }
+  return diagnostics;
+}
+
+function scrub(line: string, secretPaths: readonly string[]): string {
+  let text = line.trim();
+  for (const prefix of NOISE_PREFIXES) {
+    text = text.replace(prefix, "").trim();
+  }
+  for (const secret of secretPaths) {
+    // Strip the directory before the file name so `<dir>/input.d2:2:6:` leaves `2:6:`.
+    text = text.split(`${secret}/`).join("").split(secret).join("");
+  }
+  return text.replace(/^input\.d2:/u, "").trim();
+}
+
+function cap(message: string): string {
+  const text = message.trim();
+  return text.length > MAX_MESSAGE_LENGTH ? `${text.slice(0, MAX_MESSAGE_LENGTH - 1)}...` : text;
+}