@mcuste/pi-diagram 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcuste
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,240 @@
+# pi-diagram
+
+[![CI](https://github.com/mcuste/pi-diagram/actions/workflows/ci.yml/badge.svg)](https://github.com/mcuste/pi-diagram/actions/workflows/ci.yml)
+
+An extension for the [Pi](https://github.com/earendil-works/pi) and
+[Oh My Pi](https://github.com/can1357/oh-my-pi) terminal coding agents. It gives the model one
+`diagram` tool that turns declarative [D2](https://d2lang.com) source into a rendered diagram in the
+transcript, or into documentation artifacts checked into the repository.
+
+If any of those names are new to you:
+
+- **D2** is a declarative diagram language. Text such as `client -> gateway -> api` compiles to a
+  laid-out diagram, and the same language covers containers, sequence diagrams, and SQL tables.
+- **Pi** and **Oh My Pi** are terminal coding agents. An **extension** is an npm package they load
+  at startup to add tools the model can call.
+
+> **Status: images, text, and files work.** In a terminal that supports inline images the diagram
+> itself is shown; everywhere else it is box drawing or plain ASCII. Files land outside the
+> repository unless a destination is named. The design being followed is
+> [docs/terminal_diagram_tool_proposal.md](docs/terminal_diagram_tool_proposal.md).
+
+## Why
+
+Coding agents explain spatial things in prose: "A calls B, B queues C, C writes D, D emits an event
+back to A." The user rebuilds a graph in their head that the agent could have drawn. A fenced
+Mermaid block moves the problem rather than solving it, because a terminal shows the source instead
+of the picture.
+
+This extension gives the model one tool for that. The model writes the meaning: nodes, edges,
+groups, labels, emphasis. The tool owns the appearance: layout engine, theme, spacing, fonts, and
+which representation the current terminal can actually display. Diagrams then look consistent
+across calls, because the model is not styling them one at a time.
+
+## Requirements
+
+- Node.js 22 or newer
+- The D2 CLI, version 0.8.0 or newer, on `PATH` or named by `D2_BIN`
+
+```bash
+brew install d2                          # ships 0.8.1
+go install github.com/d2lang/d2@v0.8.1   # or a pinned build from source
+```
+
+The prebuilt binaries on D2's GitHub releases page stop at 0.7.1, which draws SQL tables as empty
+boxes, so they are below the supported floor.
+
+D2 is an external dependency on purpose. The extension never downloads a renderer during a tool
+call. Without it, the extension still loads and a call explains how to install it.
+
+## Install
+
+Pi:
+
+```bash
+pi install npm:@mcuste/pi-diagram
+```
+
+Oh My Pi:
+
+```bash
+omp plugin install @mcuste/pi-diagram
+```
+
+Or through the Oh My Pi marketplace:
+
+```text
+/marketplace add mcuste/pi-diagram
+/marketplace install pi-diagram@pi-diagram
+```
+
+From a local checkout:
+
+```bash
+pnpm install
+pi install /absolute/path/to/pi-diagram
+omp plugin link /absolute/path/to/pi-diagram
+```
+
+## What the tool does
+
+One tool named `diagram`. Give it D2 source and it draws the diagram in the terminal:
+
+```d2
+edge: Edge { gateway }
+core: Core { api; worker }
+edge.gateway -> core.api
+core.api -> core.worker: enqueue
+```
+
+```text
+┌───────────────────┐
+│       Edge        │
+│                   │
+│    ┌──────────┐   │
+│    │ gateway  │   │
+│    └──────────┘   │
+│          │        │
+└──────────│────────┘
+           │
+ ┌─────────│─────────┐
+ │       Core        │
+ │         ▼         │
+ │     ┌──────┐      │
+ │     │ api  │      │
+ │     └──────┘      │
+ │         │         │
+ │      enqueue      │
+ │         ▼         │
+ │    ┌─────────┐    │
+ │    │ worker  │    │
+ │    └─────────┘    │
+ └───────────────────┘
+```
+
+Containers, sequence diagrams, SQL tables, class shapes, and state flows all work from the same
+language.
+
+| Field | Purpose |
+| --- | --- |
+| `source` | The diagram, in D2 |
+| `title` | Label shown above the diagram |
+| `render` | `auto` and `image` show a picture where the terminal can, `unicode` draws box drawing, `ascii` plain 7-bit, `source` echoes the D2 |
+| `profile` | What the diagram is for. It sets the layout engine, theme, and spacing |
+| `formats` | Files to produce: `source`, `svg`, `png`, `txt`. Written outside the repository |
+| `save` | Also copy them into the repository. `dir` is required |
+
+## What a profile changes
+
+The model says what a diagram is for, and the tool decides how it looks:
+
+| Profile | For | Drawn as |
+| --- | --- | --- |
+| `explain` | A diagram inside an answer | Hand drawn, neutral theme, small margins |
+| `architecture` | System and component views | Neutral theme, more room between rows so edges stay separable |
+| `data` | Schemas, tables, class relationships | Neutral theme, tight spacing: tables are tall already |
+| `docs` | Diagrams checked into a repository | Grey theme that prints in greyscale, page-sized margins |
+| `tree` | A hierarchy: an org chart, a call tree, a file layout | Dagre, which fans children out under their parent |
+| `c4` | Architecture written in the C4 convention | Architecture spacing under the C4 palette |
+| `dependency` | A graph with more nodes than usual | The tightest spacing, cutting the room edges take past nodes |
+
+`explain` is the default and is drawn by hand: an answer in a conversation is a rough model, and a
+crisp diagram claims more precision than it has. Every other profile is crisp.
+
+Every profile also sets a dark theme, so a saved SVG adapts to dark mode.
+
+Only the picture changes. D2 draws text in character cells, so every profile gives the same box
+drawing.
+
+## Images in the terminal
+
+On Kitty, Ghostty, WezTerm, iTerm2, and anything else that speaks a terminal image protocol,
+`auto` shows the drawn diagram. Everywhere else the same call shows box drawing, and text is
+always rendered too, because whether a terminal can display an image is only settled when the
+result reaches the screen.
+
+Nothing needs configuring. The terminal's own capabilities decide, and a terminal without an
+image protocol is never sent one. Note that a multiplexer between the terminal and the agent has
+to forward the protocol: tmux needs `allow-passthrough`, and herdr needs
+`experimental.kitty_graphics`.
+
+The image never enters the model's context. It is written to a private temporary directory and
+read back when the row is displayed.
+
+D2 exports PNG by driving a headless browser it downloads on first use, which this tool will not
+do during a call. Instead the SVG it already produces is rasterized locally by
+[resvg](https://github.com/yisibl/resvg-js), which needs no browser and no network. Labels are
+drawn with the fonts the SVG carries, so the picture matches the boxes D2 measured. Characters
+those fonts do not cover, such as CJK, fall back to the fonts on the machine and say so.
+
+## What the model gets back
+
+In a terminal this extension draws the row, so the model reads one line: `Drew "Request path" as
+an image. It is on the user's screen, so it is not repeated here.` Saved paths and notes come with
+it, so a conversation full of diagrams costs about what a conversation of text costs. Print, RPC,
+and JSON modes have no row to draw, so there the diagram is the result text.
+
+Expanding a row adds the render mode, the profile, the D2 version, the file paths, diagnostics,
+and the source.
+
+## Where files go
+
+Most diagrams explain something in passing and should leave nothing behind. So nothing is written
+unless it is asked for, and the repository is never the default:
+
+| Call | Files | Approval |
+| --- | --- | --- |
+| `{ source }` | none, the diagram is only in the transcript | read |
+| `{ source, formats: ["svg"] }` | an SVG in a private temp directory, path returned | read |
+| `{ source, title, save: { dir: "docs/diagrams" } }` | copied into the repository | write, prompts with the exact files |
+
+`save.dir` has no default. There is no directory convention that holds across repositories, so
+the destination has to be named. Only pass `save` when the user asked to keep the diagram. A
+saved `.d2` is put through `d2 fmt` first, because people edit it later.
+
+A saved pair is editable source plus a viewable rendering:
+
+```text
+docs/diagrams/request-lifecycle.d2
+docs/diagrams/request-lifecycle.svg
+```
+
+Markdown then needs no D2 or Mermaid runtime:
+
+```markdown
+![Request lifecycle](diagrams/request-lifecycle.svg)
+```
+
+For documentation prefer `svg`: it scales, and Markdown renders it anywhere. `png` exists for
+places where SVG support is weak.
+
+Repository paths stay inside the workspace. Absolute paths, `..`, and symlinks pointing outside
+are all refused.
+
+What D2 drew is also kept in a temporary store, so the same diagram drawn again is about ten times
+faster, including in a later session. A new D2 version, or any change to a profile, is a different
+entry. The store holds 64 MB for a week.
+
+Layout engine, theme, padding, and font are deliberately not in the schema. They are policy here,
+and a model given those knobs spends tokens on styling and produces a different look every call.
+
+## What is deliberately missing
+
+- **Model-drawn images.** The model never emits SVG coordinates or ASCII art directly. It writes
+  source, and a renderer lays it out.
+- **Imports and external assets.** Diagram source cannot pull in files, local images, or remote
+  icons. Those turn a rendering request into file and network access.
+- **Interactive editing.** The tool renders; it is not a diagram editor in the terminal.
+- **Every D2 feature.** A safe subset is supported, and anything outside it is reported as an error
+  the model can correct rather than being silently dropped.
+
+## Documentation
+
+- [Safety model](docs/safety.md)
+- [Design proposal](docs/terminal_diagram_tool_proposal.md)
+- [Development and release](docs/development.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE)

package/dist/artifacts.d.ts

@@ -0,0 +1,59 @@
+declare const EXTENSIONS: {
+    readonly source: ".d2";
+    readonly svg: ".svg";
+    readonly png: ".png";
+    readonly txt: ".txt";
+};
+export type ArtifactFormat = keyof typeof EXTENSIONS;
+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;
+}
+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 declare function parseArtifactNames(request: ArtifactAsk, identity: ArtifactIdentity): ArtifactNames;
+/** The workspace-relative paths a repository write would touch, for an approval prompt. */
+export declare function workspacePaths(names: ArtifactNames): readonly string[];
+export declare function parseArtifactTarget(cwd: unknown, names: ArtifactNames): Promise<ArtifactTarget>;
+/**
+ * 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 declare function writeArtifacts(target: ArtifactTarget, contents: ReadonlyMap<ArtifactFormat, string | Uint8Array>): Promise<readonly WrittenArtifact[]>;
+export {};
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AA2BA,QAAA,MAAM,UAAU;aACd,MAAM,EAAE,KAAK;aACb,GAAG,EAAE,MAAM;aACX,GAAG,EAAE,MAAM;aACX,GAAG,EAAE,MAAM;CACH,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,UAAU,CAAC;AAerD,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAC/C,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,gFAAgF;AAChF,KAAK,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEpE,gGAAgG;AAChG,KAAK,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE9E,KAAK,gBAAgB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA8HD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,GACzB,aAAa,CAQf;AAED,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,MAAM,EAAE,CAMtE;AAsDD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,CAAC,CAgCzB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,CAAC,GACzD,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAyCrC"}

package/dist/artifacts.js

@@ -0,0 +1,274 @@
+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",
+};
+/** Editable source plus a viewable rendering. */
+const DEFAULT_FORMATS = ["source", "svg"];
+/** Names Windows treats as devices rather than files, whatever extension follows. */
+const RESERVED_NAMES = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    ...Array.from({ length: 9 }, (_, index) => `com${index + 1}`),
+    ...Array.from({ length: 9 }, (_, index) => `lpt${index + 1}`),
+]);
+function refuse(summary, message, hint) {
+    throw new DiagramSourceError(summary, [
+        { code: "D2_SOURCE", message, ...(hint === undefined ? {} : { hint }) },
+    ]);
+}
+function parseFormats(requested) {
+    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 = [];
+    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) {
+    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) {
+    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) {
+    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, title, fallback) {
+    const chosen = typeof requested === "string" && requested.trim().length > 0 ? requested : title;
+    if (chosen === undefined) {
+        if (fallback !== undefined) {
+            return fallback;
+        }
+        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;
+}
+/** Resolves nothing on disk, so a bad request is refused before any rendering starts. */
+export function parseArtifactNames(request, identity) {
+    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) {
+    if (names.directory === undefined) {
+        return [];
+    }
+    const prefix = names.directory === "." ? "" : `${names.directory}/`;
+    return names.formats.map((format) => `${prefix}${names.basename}${EXTENSIONS[format]}`);
+}
+function contains(root, candidate) {
+    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, target) {
+    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.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;
+/**
+ * `mkdtemp` creates the directory owner-only, so diagrams that quote repository content are not
+ * readable by other users of a shared machine.
+ */
+function sessionDirectory() {
+    sessionStore ??= mkdtemp(join(tmpdir(), "pi-diagram-store-"));
+    return sessionStore;
+}
+export async function parseArtifactTarget(cwd, names) {
+    if (names.directory === undefined) {
+        const directory = await sessionDirectory();
+        return { location: "temp", directory: directory, 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;
+    try {
+        realRoot = await realpath(root);
+    }
+    catch (error) {
+        refuse("The workspace directory cannot be read.", `${root} could not be resolved: ${error.message}.`);
+    }
+    const directory = resolve(realRoot, names.directory);
+    await assertInsideWorkspace(realRoot, directory);
+    return {
+        location: "workspace",
+        directory: directory,
+        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, contents) {
+    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 = [];
+    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" } : {}),
+                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) {
+    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.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+async function evictOldest(directory) {
+    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 });
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,43 @@
+export interface CacheKeyParts {
+    readonly source: string;
+    readonly language: "d2";
+    /** Which renderer ran. Two builds can report the same version from different paths. */
+    readonly binary: string;
+    /** So no output is served after a D2 upgrade. */
+    readonly version: string;
+    /**
+     * Carries the engine, theme, and spacing a profile chose, so a policy change cannot serve a
+     * picture drawn under the old one.
+     */
+    readonly argv: readonly string[];
+}
+export interface RenderCache {
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+}
+export declare function cacheKey(parts: CacheKeyParts): string;
+/** Length-prefixed, so no two field lists can read as one another. */
+export declare function cacheKeyOf(fields: readonly string[]): string;
+/** Keeps nothing. For tests, and for callers that want every render to run. */
+export declare const noCache: RenderCache;
+export interface FileCacheOptions {
+    readonly directory?: string;
+    readonly maxBytes?: number;
+    readonly maxAgeMs?: number;
+}
+/**
+ * Entries on disk, outside the project, shared between sessions. Every operation is best-effort: a
+ * cache that cannot be read or written must not fail a diagram.
+ */
+export declare class FileCache implements RenderCache {
+    private readonly directory;
+    private readonly maxBytes;
+    private readonly maxAgeMs;
+    constructor(options?: FileCacheOptions);
+    read(key: string): Promise<string | undefined>;
+    write(key: string, value: string): Promise<void>;
+    /** Drops entries past the age limit, then the least recently used until the size fits. */
+    private prune;
+    private pathFor;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC/C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAErD;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM5D;AAED,+EAA+E;AAC/E,eAAO,MAAM,OAAO,EAAE,WAGrB,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,qBAAa,SAAU,YAAW,WAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,OAAO,GAAE,gBAAqB,EAIzC;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAWnD;IAEK,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrD;IAED,0FAA0F;YAC5E,KAAK;IAkCnB,OAAO,CAAC,OAAO;CAGhB"}