@actagent/diffs 2026.6.2

package/src/url.ts

@@ -0,0 +1,61 @@
+// Diffs plugin module implements url behavior.
+import type { ACTAgentConfig } from "../api.js";
+
+const DEFAULT_GATEWAY_PORT = 18789;
+type ViewerBaseUrlFieldName = "baseUrl" | "viewerBaseUrl";
+
+export function buildViewerUrl(params: {
+  config: ACTAgentConfig;
+  viewerPath: string;
+  baseUrl?: string;
+}): string {
+  const baseUrl = params.baseUrl?.trim() || resolveGatewayBaseUrl(params.config);
+  const normalizedBase = normalizeViewerBaseUrl(baseUrl);
+  const viewerPath = params.viewerPath.startsWith("/")
+    ? params.viewerPath
+    : `/${params.viewerPath}`;
+  const parsedBase = new URL(normalizedBase);
+  const basePath = parsedBase.pathname === "/" ? "" : parsedBase.pathname.replace(/\/+$/, "");
+  parsedBase.pathname = `${basePath}${viewerPath}`;
+  parsedBase.search = "";
+  parsedBase.hash = "";
+  return parsedBase.toString();
+}
+
+export function normalizeViewerBaseUrl(
+  raw: string,
+  fieldName: ViewerBaseUrlFieldName = "baseUrl",
+): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`Invalid ${fieldName}: ${raw}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${fieldName} must use http or https: ${raw}`);
+  }
+  if (parsed.search || parsed.hash) {
+    throw new Error(`${fieldName} must not include query/hash: ${raw}`);
+  }
+  parsed.search = "";
+  parsed.hash = "";
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  const withoutTrailingSlash = parsed.toString().replace(/\/+$/, "");
+  return withoutTrailingSlash;
+}
+
+function resolveGatewayBaseUrl(config: ACTAgentConfig): string {
+  const scheme = config.gateway?.tls?.enabled ? "https" : "http";
+  const port =
+    typeof config.gateway?.port === "number" ? config.gateway.port : DEFAULT_GATEWAY_PORT;
+  const customHost = config.gateway?.customBindHost?.trim();
+
+  if (config.gateway?.bind === "custom" && customHost) {
+    return `${scheme}://${customHost}:${port}`;
+  }
+
+  // Viewer links are used by local canvas/clients; default to loopback to avoid
+  // container/bridge interfaces that are often unreachable from the caller.
+  return `${scheme}://127.0.0.1:${port}`;
+}

package/src/viewer-assets.ts

@@ -0,0 +1,190 @@
+// Diffs plugin module implements viewer assets behavior.
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export const VIEWER_ASSET_PREFIX = "/plugins/diffs/assets/";
+export const VIEWER_LOADER_PATH = `${VIEWER_ASSET_PREFIX}viewer.js`;
+export const VIEWER_RUNTIME_PATH = `${VIEWER_ASSET_PREFIX}viewer-runtime.js`;
+export const LANGUAGE_PACK_VIEWER_ASSET_PREFIX = "/plugins/diffs-language-pack/assets/";
+export const LANGUAGE_PACK_VIEWER_LOADER_PATH = `${LANGUAGE_PACK_VIEWER_ASSET_PREFIX}viewer.js`;
+export const LANGUAGE_PACK_VIEWER_RUNTIME_PATH = `${LANGUAGE_PACK_VIEWER_ASSET_PREFIX}viewer-runtime.js`;
+const VIEWER_RUNTIME_RELATIVE_IMPORT_PATH = "./viewer-runtime.js";
+const VIEWER_RUNTIME_CANDIDATE_RELATIVE_PATHS = [
+  "./assets/viewer-runtime.js",
+  "../assets/viewer-runtime.js",
+] as const;
+const LANGUAGE_PACK_RUNTIME_CANDIDATE_RELATIVE_PATHS = [
+  "../../diffs-language-pack/assets/viewer-runtime.js",
+  "../diffs-language-pack/assets/viewer-runtime.js",
+] as const;
+
+type ServedViewerAsset = {
+  body: string | Buffer;
+  contentType: string;
+};
+
+type RuntimeAssetCache = {
+  mtimeMs: number;
+  runtimeBody: Buffer;
+  loaderBody: string;
+};
+
+let runtimeAssetCache: RuntimeAssetCache | null = null;
+let languagePackRuntimeAssetCache: RuntimeAssetCache | null = null;
+
+type ViewerRuntimeFileUrlParams = {
+  baseUrl?: string | URL;
+  stat?: (path: string) => Promise<unknown>;
+};
+
+function isMissingFileError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+export async function resolveViewerRuntimeFileUrl(
+  params: ViewerRuntimeFileUrlParams = {},
+): Promise<URL> {
+  const baseUrl = params.baseUrl ?? import.meta.url;
+  const stat = params.stat ?? ((path: string) => fs.stat(path));
+  let missingFileError: NodeJS.ErrnoException | null = null;
+
+  for (const relativePath of VIEWER_RUNTIME_CANDIDATE_RELATIVE_PATHS) {
+    const candidateUrl = new URL(relativePath, baseUrl);
+    try {
+      await stat(fileURLToPath(candidateUrl));
+      return candidateUrl;
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        missingFileError = error;
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  if (missingFileError) {
+    throw missingFileError;
+  }
+
+  throw new Error("viewer runtime asset candidates were not checked");
+}
+
+export async function getServedViewerAsset(pathname: string): Promise<ServedViewerAsset | null> {
+  if (pathname !== VIEWER_LOADER_PATH && pathname !== VIEWER_RUNTIME_PATH) {
+    return null;
+  }
+
+  const assets = await loadViewerAssets();
+  if (pathname === VIEWER_LOADER_PATH) {
+    return {
+      body: assets.loaderBody,
+      contentType: "text/javascript; charset=utf-8",
+    };
+  }
+
+  if (pathname === VIEWER_RUNTIME_PATH) {
+    return {
+      body: assets.runtimeBody,
+      contentType: "text/javascript; charset=utf-8",
+    };
+  }
+
+  return null;
+}
+
+export async function getServedLanguagePackViewerAsset(
+  pathname: string,
+): Promise<ServedViewerAsset | null> {
+  if (
+    pathname !== LANGUAGE_PACK_VIEWER_LOADER_PATH &&
+    pathname !== LANGUAGE_PACK_VIEWER_RUNTIME_PATH
+  ) {
+    return null;
+  }
+
+  let assets: RuntimeAssetCache;
+  try {
+    const runtimeUrl = await resolveRuntimeFileUrl(LANGUAGE_PACK_RUNTIME_CANDIDATE_RELATIVE_PATHS);
+    assets = await loadRuntimeAssets({
+      runtimeUrl,
+      cache: languagePackRuntimeAssetCache,
+      updateCache: (cache) => {
+        languagePackRuntimeAssetCache = cache;
+      },
+    });
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+    throw error;
+  }
+  if (pathname === LANGUAGE_PACK_VIEWER_LOADER_PATH) {
+    return {
+      body: assets.loaderBody,
+      contentType: "text/javascript; charset=utf-8",
+    };
+  }
+
+  return {
+    body: assets.runtimeBody,
+    contentType: "text/javascript; charset=utf-8",
+  };
+}
+
+async function loadViewerAssets(): Promise<RuntimeAssetCache> {
+  const runtimeUrl = await resolveViewerRuntimeFileUrl();
+  return loadRuntimeAssets({
+    runtimeUrl,
+    cache: runtimeAssetCache,
+    updateCache: (cache) => {
+      runtimeAssetCache = cache;
+    },
+  });
+}
+
+async function loadRuntimeAssets(params: {
+  cache: RuntimeAssetCache | null;
+  runtimeUrl: URL;
+  updateCache(cache: RuntimeAssetCache): void;
+}): Promise<RuntimeAssetCache> {
+  const runtimePath = fileURLToPath(params.runtimeUrl);
+  const runtimeStat = await fs.stat(runtimePath);
+  if (params.cache && params.cache.mtimeMs === runtimeStat.mtimeMs) {
+    return params.cache;
+  }
+
+  const runtimeBody = await fs.readFile(runtimePath);
+  const hash = crypto.createHash("sha1").update(runtimeBody).digest("hex").slice(0, 12);
+  const cache = {
+    mtimeMs: runtimeStat.mtimeMs,
+    runtimeBody,
+    loaderBody: `import "${VIEWER_RUNTIME_RELATIVE_IMPORT_PATH}?v=${hash}";\n`,
+  };
+  params.updateCache(cache);
+  return cache;
+}
+
+async function resolveRuntimeFileUrl(relativePaths: readonly string[]): Promise<URL> {
+  let missingFileError: NodeJS.ErrnoException | null = null;
+
+  for (const relativePath of relativePaths) {
+    const candidateUrl = new URL(relativePath, import.meta.url);
+    try {
+      await fs.stat(fileURLToPath(candidateUrl));
+      return candidateUrl;
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        missingFileError = error;
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  if (missingFileError) {
+    throw missingFileError;
+  }
+
+  throw new Error("viewer runtime asset candidates were not checked");
+}

package/src/viewer-client.test.ts

@@ -0,0 +1,175 @@
+/* @vitest-environment jsdom */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const disableAutoStartKey = Symbol.for("actagent.diffs.disableAutoStart");
+(globalThis as typeof globalThis & Record<symbol, unknown>)[disableAutoStartKey] = true;
+
+const VIEWER_CLIENT_SRC = readFileSync(
+  path.join(process.cwd(), "extensions/diffs/src/viewer-client.ts"),
+  "utf8",
+);
+
+const XSS_PATTERNS = ["onerror", "<script", "onclick", "javascript:", "onload"];
+
+const {
+  fileDiffHydrateMock,
+  fileDiffRerenderMock,
+  fileDiffSetOptionsMock,
+  preloadHighlighterMock,
+} = vi.hoisted(() => ({
+  fileDiffHydrateMock: vi.fn(),
+  fileDiffRerenderMock: vi.fn(),
+  fileDiffSetOptionsMock: vi.fn(),
+  preloadHighlighterMock: vi.fn(async () => undefined),
+}));
+
+vi.mock("@pierre/diffs", () => ({
+  FileDiff: class {
+    hydrate(params: unknown) {
+      return fileDiffHydrateMock(params);
+    }
+    rerender() {
+      return fileDiffRerenderMock();
+    }
+    setOptions(params: unknown) {
+      return fileDiffSetOptionsMock(params);
+    }
+  },
+  preloadHighlighter: preloadHighlighterMock,
+}));
+
+const viewerPayload = JSON.stringify({
+  prerenderedHTML: "<div>diff</div>",
+  options: {
+    theme: { light: "pierre-light", dark: "pierre-dark" },
+    diffStyle: "unified",
+    diffIndicators: "bars",
+    disableLineNumbers: false,
+    expandUnchanged: false,
+    themeType: "dark",
+    backgroundEnabled: true,
+    overflow: "wrap",
+    unsafeCSS: "",
+  },
+  langs: ["text"],
+  oldFile: { fileName: "a.ts", lang: "text", content: "old" },
+  newFile: { fileName: "a.ts", lang: "text", content: "new" },
+});
+
+function renderCard(): void {
+  document.body.insertAdjacentHTML(
+    "beforeend",
+    `<section class="oc-diff-card">
+      <div data-actagent-diff-host></div>
+      <script type="application/json" data-actagent-diff-payload>${viewerPayload}</script>
+    </section>`,
+  );
+}
+
+describe("createToolbarButton icon safety", () => {
+  it("toolbarIconSvg map exists and has exactly 8 icon names", () => {
+    const requiredNames = [
+      "split",
+      "unified",
+      "wrap-on",
+      "wrap-off",
+      "background-on",
+      "background-off",
+      "theme-dark",
+      "theme-light",
+    ] as const;
+    for (const name of requiredNames) {
+      expect(
+        VIEWER_CLIENT_SRC.includes(name + ":") || VIEWER_CLIENT_SRC.includes(`"${name}"`),
+        `icon "${name}" should exist in toolbarIconSvg`,
+      ).toBe(true);
+    }
+  });
+
+  it("no iconMarkup: string parameter exists", () => {
+    expect(VIEWER_CLIENT_SRC.includes("iconMarkup: string")).toBe(false);
+  });
+
+  it("innerHTML reads only from toolbarIconSvg lookup", () => {
+    expect(VIEWER_CLIENT_SRC.includes("button.innerHTML = toolbarIconSvg[params.icon]")).toBe(true);
+  });
+
+  it("SVG strings in toolbarIconSvg contain no XSS patterns", () => {
+    for (const pattern of XSS_PATTERNS) {
+      expect(
+        VIEWER_CLIENT_SRC.includes(pattern),
+        `source must not contain "${pattern}"`,
+      ).toBe(false);
+    }
+  });
+
+  it("old icon functions are removed", () => {
+    const removedFunctions = [
+      "function splitIcon(",
+      "function unifiedIcon(",
+      "function wrapIcon(",
+      "function backgroundIcon(",
+      "function themeIcon(",
+    ];
+    for (const fn of removedFunctions) {
+      expect(VIEWER_CLIENT_SRC.includes(fn), `"${fn}" should be removed`).toBe(false);
+    }
+  });
+});
+
+describe("hydrateViewer", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    delete document.documentElement.dataset.actagentDiffsError;
+    delete document.documentElement.dataset.actagentDiffsReady;
+    vi.clearAllMocks();
+  });
+
+  it("continues hydrating later cards when one card throws", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    renderCard();
+    renderCard();
+    fileDiffHydrateMock.mockImplementationOnce(() => {
+      throw new Error("broken card");
+    });
+    const { controllers, hydrateViewer } = await import("./viewer-client.js");
+    controllers.splice(0);
+
+    await hydrateViewer();
+
+    expect(fileDiffHydrateMock).toHaveBeenCalledTimes(2);
+    expect(controllers).toHaveLength(1);
+    expect(warn).toHaveBeenCalledWith(
+      "Skipping diff card that failed to hydrate",
+      expect.any(Error),
+    );
+    expect(document.documentElement.dataset.actagentDiffsError).toBeUndefined();
+    warn.mockRestore();
+  });
+
+  it("does not retain controllers when initial state application throws", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    renderCard();
+    renderCard();
+    fileDiffSetOptionsMock.mockImplementationOnce(() => {
+      throw new Error("broken options");
+    });
+    const { controllers, hydrateViewer } = await import("./viewer-client.js");
+    controllers.splice(0);
+
+    await hydrateViewer();
+
+    expect(fileDiffHydrateMock).toHaveBeenCalledTimes(2);
+    expect(fileDiffSetOptionsMock).toHaveBeenCalledTimes(2);
+    expect(controllers).toHaveLength(1);
+    expect(warn).toHaveBeenCalledWith(
+      "Skipping diff card that failed to hydrate",
+      expect.any(Error),
+    );
+    expect(document.documentElement.dataset.actagentDiffsError).toBeUndefined();
+    warn.mockRestore();
+  });
+});