@kodelyth/diffs 2026.5.39 → 2026.5.42

package/src/plugin.ts

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { resolveLivePluginConfigObject } from "klaw/plugin-sdk/plugin-config-runtime";
+import { resolvePreferredKlawTmpDir, type KlawConfig, type KlawPluginApi } from "../api.js";
+import {
+  resolveDiffsPluginDefaults,
+  resolveDiffsPluginSecurity,
+  resolveDiffsPluginViewerBaseUrl,
+} from "./config.js";
+import { createDiffsHttpHandler } from "./http.js";
+import { DIFFS_AGENT_GUIDANCE } from "./prompt-guidance.js";
+import { DiffArtifactStore } from "./store.js";
+import { createDiffsTool } from "./tool.js";
+
+export function registerDiffsPlugin(api: KlawPluginApi): void {
+  const store = new DiffArtifactStore({
+    rootDir: path.join(resolvePreferredKlawTmpDir(), "klaw-diffs"),
+    logger: api.logger,
+  });
+  const resolveCurrentPluginConfig = () =>
+    resolveLivePluginConfigObject(
+      api.runtime.config?.current ? () => api.runtime.config.current() as KlawConfig : undefined,
+      "diffs",
+      api.pluginConfig as Record<string, unknown>,
+    ) ?? {};
+  const resolveCurrentAccessConfig = () => {
+    const currentConfig = (api.runtime.config?.current?.() ?? api.config) as KlawConfig;
+    const pluginConfig = resolveCurrentPluginConfig();
+    return {
+      allowRemoteViewer: resolveDiffsPluginSecurity(pluginConfig).allowRemoteViewer,
+      trustedProxies: currentConfig.gateway?.trustedProxies,
+      allowRealIpFallback: currentConfig.gateway?.allowRealIpFallback === true,
+    };
+  };
+  const initialAccessConfig = resolveCurrentAccessConfig();
+
+  api.registerTool(
+    (ctx) => {
+      const pluginConfig = resolveCurrentPluginConfig();
+      return createDiffsTool({
+        api,
+        store,
+        defaults: resolveDiffsPluginDefaults(pluginConfig),
+        viewerBaseUrl: resolveDiffsPluginViewerBaseUrl(pluginConfig),
+        context: ctx,
+      });
+    },
+    {
+      name: "diffs",
+    },
+  );
+  api.registerHttpRoute({
+    path: "/plugins/diffs",
+    auth: "plugin",
+    match: "prefix",
+    handler: createDiffsHttpHandler({
+      store,
+      logger: api.logger,
+      allowRemoteViewer: initialAccessConfig.allowRemoteViewer,
+      trustedProxies: initialAccessConfig.trustedProxies,
+      allowRealIpFallback: initialAccessConfig.allowRealIpFallback,
+      resolveAccessConfig: resolveCurrentAccessConfig,
+    }),
+  });
+  api.on("before_prompt_build", async () => ({
+    prependSystemContext: DIFFS_AGENT_GUIDANCE,
+  }));
+}

package/src/prompt-guidance.ts

@@ -0,0 +1,7 @@
+export const DIFFS_AGENT_GUIDANCE = [
+  "When you need to show edits as a real diff, prefer the `diffs` tool instead of writing a manual summary.",
+  "It accepts either `before` + `after` text or a unified `patch`.",
+  "`mode=view` returns `details.viewerUrl` for canvas use; `mode=file` returns `details.filePath`; `mode=both` returns both.",
+  "If you need to send the rendered file, use the `message` tool with `path` or `filePath`.",
+  "Include `path` when you know the filename, and omit presentation overrides unless needed.",
+].join("\n");

package/src/render-target.test.ts

@@ -0,0 +1,132 @@
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { preloadFileDiffMock, preloadMultiFileDiffMock } = vi.hoisted(() => ({
+  preloadFileDiffMock: vi.fn(async ({ fileDiff }: { fileDiff: unknown }) => ({
+    prerenderedHTML: "<div>mock diff</div>",
+    fileDiff,
+  })),
+  preloadMultiFileDiffMock: vi.fn(
+    async ({ oldFile, newFile }: { oldFile: unknown; newFile: unknown }) => ({
+      prerenderedHTML: "<div>mock diff</div>",
+      oldFile,
+      newFile,
+    }),
+  ),
+}));
+
+vi.mock("@pierre/diffs/ssr", () => ({
+  preloadFileDiff: preloadFileDiffMock,
+  preloadMultiFileDiff: preloadMultiFileDiffMock,
+}));
+
+afterAll(() => {
+  vi.doUnmock("@pierre/diffs/ssr");
+  vi.resetModules();
+});
+
+import { DEFAULT_DIFFS_TOOL_DEFAULTS, resolveDiffImageRenderOptions } from "./config.js";
+import { renderDiffDocument } from "./render.js";
+import { parseViewerPayloadJson } from "./viewer-payload.js";
+
+function createRenderOptions() {
+  return {
+    presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+    image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+    expandUnchanged: false,
+  };
+}
+
+describe("renderDiffDocument render targets", () => {
+  beforeEach(() => {
+    preloadFileDiffMock.mockClear();
+    preloadMultiFileDiffMock.mockClear();
+  });
+
+  it("renders only the viewer variant for before/after viewer mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "one\n",
+        after: "two\n",
+      },
+      createRenderOptions(),
+      "viewer",
+    );
+
+    expect(rendered.html).toContain("mock diff");
+    expect(rendered.imageHtml).toBeUndefined();
+    expect(preloadMultiFileDiffMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders both variants for before/after both mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "one\n",
+        after: "two\n",
+      },
+      createRenderOptions(),
+      "both",
+    );
+
+    expect(rendered.html).toContain("mock diff");
+    expect(rendered.imageHtml).toContain("mock diff");
+    expect(preloadMultiFileDiffMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("renders only the image variant for patch image mode", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch: [
+          "diff --git a/a.ts b/a.ts",
+          "--- a/a.ts",
+          "+++ b/a.ts",
+          "@@ -1 +1 @@",
+          "-a",
+          "+b",
+        ].join("\n"),
+      },
+      createRenderOptions(),
+      "image",
+    );
+
+    expect(rendered.html).toBeUndefined();
+    expect(rendered.imageHtml).toContain("mock diff");
+    expect(preloadFileDiffMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes stale patch payload languages before serializing viewer output", async () => {
+    preloadFileDiffMock.mockResolvedValueOnce({
+      prerenderedHTML: "<div>mock diff</div>",
+      fileDiff: {
+        name: "a.ts",
+        lang: "not-a-real-language",
+      },
+    });
+
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch: [
+          "diff --git a/a.ts b/a.ts",
+          "--- a/a.ts",
+          "+++ b/a.ts",
+          "@@ -1 +1 @@",
+          "-a",
+          "+b",
+        ].join("\n"),
+      },
+      createRenderOptions(),
+      "viewer",
+    );
+
+    const payloads = [
+      ...(rendered.html ?? "").matchAll(/data-klaw-diff-payload>(.*?)<\/script>/g),
+    ].map((match) => parseViewerPayloadJson(match[1] ?? ""));
+
+    expect(payloads).toHaveLength(1);
+    expect(payloads[0]?.langs).toEqual(["text"]);
+    expect(payloads[0]?.fileDiff?.lang).toBe("text");
+  });
+});

package/src/render.test.ts

@@ -0,0 +1,219 @@
+import {
+  disposeHighlighter,
+  RegisteredCustomThemes,
+  ResolvedThemes,
+  ResolvingThemes,
+} from "@pierre/diffs";
+import { afterEach, describe, expect, it } from "vitest";
+import { DEFAULT_DIFFS_TOOL_DEFAULTS, resolveDiffImageRenderOptions } from "./config.js";
+import { renderDiffDocument } from "./render.js";
+import { parseViewerPayloadJson } from "./viewer-payload.js";
+
+describe("renderDiffDocument", () => {
+  afterEach(async () => {
+    await disposeHighlighter();
+  });
+
+  it("renders before/after input into a complete viewer document", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "const value = 1;\n",
+        after: "const value = 2;\n",
+        path: "src/example.ts",
+      },
+      {
+        presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+        image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+        expandUnchanged: false,
+      },
+    );
+
+    expect(rendered.title).toBe("src/example.ts");
+    expect(rendered.fileCount).toBe(1);
+    expect(rendered.html).toContain("data-klaw-diff-root");
+    expect(rendered.html).toContain("src/example.ts");
+    expect(rendered.html).toContain("../../assets/viewer.js");
+    expect(rendered.imageHtml).toContain("../../assets/viewer.js");
+    expect(rendered.imageHtml).toContain("max-width: 960px;");
+    expect(rendered.imageHtml).toContain("--diffs-font-size: 16px;");
+    expect(rendered.html).toContain("min-height: 100vh;");
+    expect(rendered.html).toContain('"diffIndicators":"bars"');
+    expect(rendered.html).toContain('"disableLineNumbers":false');
+    expect(rendered.html).toContain("--diffs-line-height: 24px;");
+    expect(rendered.html).toContain("--diffs-font-size: 15px;");
+    expect(rendered.html).not.toContain("fonts.googleapis.com");
+  });
+
+  it("resolves viewer assets under an optional base path", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "const value = 1;\n",
+        after: "const value = 2;\n",
+      },
+      {
+        presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+        image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+        expandUnchanged: false,
+      },
+    );
+
+    const html = rendered.html ?? "";
+    const loaderSrc = html.match(/<script type="module" src="([^"]+)"><\/script>/)?.[1];
+    expect(loaderSrc).toBe("../../assets/viewer.js");
+    expect(
+      new URL(loaderSrc ?? "", "https://example.com/klaw/plugins/diffs/view/id/token").pathname,
+    ).toBe("/klaw/plugins/diffs/assets/viewer.js");
+  });
+
+  it("downgrades invalid language hints to plain text", async () => {
+    const rendered = await renderDiffDocument(
+      {
+        kind: "before_after",
+        before: "const value = 1;\n",
+        after: "const value = 2;\n",
+        lang: "not-a-real-language",
+      },
+      {
+        presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+        image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+        expandUnchanged: false,
+      },
+    );
+
+    const html = rendered.html ?? "";
+
+    expect(rendered.title).toBe("Text diff");
+    expect(html).toContain("diff.txt");
+    expect(html).not.toContain("not-a-real-language");
+
+    const payloads = [...html.matchAll(/data-klaw-diff-payload>(.*?)<\/script>/g)].map((match) =>
+      parseViewerPayloadJson(match[1] ?? ""),
+    );
+    expect(payloads).toHaveLength(1);
+    expect(payloads[0]?.langs).toEqual(["text"]);
+    expect(payloads[0]?.oldFile?.lang).toBeUndefined();
+    expect(payloads[0]?.newFile?.lang).toBeUndefined();
+  });
+
+  it("renders multi-file patch input", async () => {
+    const patch = [
+      "diff --git a/a.ts b/a.ts",
+      "--- a/a.ts",
+      "+++ b/a.ts",
+      "@@ -1 +1 @@",
+      "-const a = 1;",
+      "+const a = 2;",
+      "diff --git a/b.ts b/b.ts",
+      "--- a/b.ts",
+      "+++ b/b.ts",
+      "@@ -1 +1 @@",
+      "-const b = 1;",
+      "+const b = 2;",
+    ].join("\n");
+
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch,
+        title: "Workspace patch",
+      },
+      {
+        presentation: {
+          ...DEFAULT_DIFFS_TOOL_DEFAULTS,
+          layout: "split",
+          theme: "dark",
+        },
+        image: resolveDiffImageRenderOptions({
+          defaults: DEFAULT_DIFFS_TOOL_DEFAULTS,
+          fileQuality: "hq",
+          fileMaxWidth: 1180,
+        }),
+        expandUnchanged: true,
+      },
+    );
+
+    expect(rendered.title).toBe("Workspace patch");
+    expect(rendered.fileCount).toBe(2);
+    expect(rendered.html).toContain("Workspace patch");
+    expect(rendered.imageHtml).toContain("max-width: 1180px;");
+  });
+
+  it("re-registers pierre theme loaders before rendering", async () => {
+    await disposeHighlighter();
+
+    const originalLightLoader = RegisteredCustomThemes.get("pierre-light");
+    const originalDarkLoader = RegisteredCustomThemes.get("pierre-dark");
+    const brokenLoader = async () => {
+      throw new Error("broken pierre theme loader");
+    };
+
+    RegisteredCustomThemes.set("pierre-light", brokenLoader);
+    RegisteredCustomThemes.set("pierre-dark", brokenLoader);
+    ResolvedThemes.delete("pierre-light");
+    ResolvedThemes.delete("pierre-dark");
+    ResolvingThemes.delete("pierre-light");
+    ResolvingThemes.delete("pierre-dark");
+
+    try {
+      const rendered = await renderDiffDocument(
+        {
+          kind: "before_after",
+          before: "const value = 1;\n",
+          after: "const value = 2;\n",
+          path: "src/example.ts",
+        },
+        {
+          presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+          image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+          expandUnchanged: false,
+        },
+      );
+
+      expect(rendered.fileCount).toBe(1);
+      expect(rendered.html).toContain("src/example.ts");
+      expect(RegisteredCustomThemes.get("pierre-light")).not.toBe(brokenLoader);
+      expect(RegisteredCustomThemes.get("pierre-dark")).not.toBe(brokenLoader);
+    } finally {
+      if (originalLightLoader) {
+        RegisteredCustomThemes.set("pierre-light", originalLightLoader);
+      } else {
+        RegisteredCustomThemes.delete("pierre-light");
+      }
+      if (originalDarkLoader) {
+        RegisteredCustomThemes.set("pierre-dark", originalDarkLoader);
+      } else {
+        RegisteredCustomThemes.delete("pierre-dark");
+      }
+      await disposeHighlighter();
+    }
+  });
+
+  it("rejects patches that exceed file-count limits", async () => {
+    const patch = Array.from({ length: 129 }, (_, i) => {
+      return [
+        `diff --git a/f${i}.ts b/f${i}.ts`,
+        `--- a/f${i}.ts`,
+        `+++ b/f${i}.ts`,
+        "@@ -1 +1 @@",
+        "-const x = 1;",
+        "+const x = 2;",
+      ].join("\n");
+    }).join("\n");
+
+    await expect(
+      renderDiffDocument(
+        {
+          kind: "patch",
+          patch,
+        },
+        {
+          presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+          image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+          expandUnchanged: false,
+        },
+      ),
+    ).rejects.toThrow("too many files");
+  });
+});