fix(plugins): rewrite relative README image URLs to source-host raw URLs

Author: momothemage

src/__tests__/plugins-publish-route.test.tsx

@@ -648,4 +648,114 @@ describe("plugins publish route", () => {
       screen.getByRole("button", { name: "Publish plugin" }).getAttribute("disabled"),
     ).not.toBeNull();
   });
+
+  it("warns when README references relative image paths but no source repo/commit is set", async () => {
+    renderPublishRoute();
+
+    const packageJson = withRelativePath(
+      new File(
+        [makeCodePluginPackageJson({ name: "demo-plugin", version: "1.0.0" })],
+        "package.json",
+        {
+          type: "application/json",
+        },
+      ),
+      "demo-plugin/package.json",
+    );
+    const manifest = withRelativePath(
+      new File(['{"id":"demo.plugin"}'], "openclaw.plugin.json", { type: "application/json" }),
+      "demo-plugin/openclaw.plugin.json",
+    );
+    const readme = withRelativePath(
+      new File(
+        ['# Demo Plugin\n\n![diagram](./images/foo.png)\n\n<img src="./images/bar.png" alt="x"/>'],
+        "README.md",
+        { type: "text/markdown" },
+      ),
+      "demo-plugin/README.md",
+    );
+
+    fireEvent.change(getFileInput(), { target: { files: [packageJson, manifest, readme] } });
+
+    await waitFor(() => {
+      expect(screen.getByText(/Your README references 2 relative image paths/i)).toBeTruthy();
+    });
+    expect(screen.getByText(/ClawHub does not\s+host package binary assets/i)).toBeTruthy();
+    expect(screen.getByText(/\.\/images\/foo\.png/)).toBeTruthy();
+    expect(screen.getByText(/\.\/images\/bar\.png/)).toBeTruthy();
+  });
+
+  it("hides the relative-README-image warning once Source repo and Source commit are filled", async () => {
+    renderPublishRoute();
+
+    const packageJson = withRelativePath(
+      new File(
+        [makeCodePluginPackageJson({ name: "demo-plugin", version: "1.0.0" })],
+        "package.json",
+        {
+          type: "application/json",
+        },
+      ),
+      "demo-plugin/package.json",
+    );
+    const manifest = withRelativePath(
+      new File(['{"id":"demo.plugin"}'], "openclaw.plugin.json", { type: "application/json" }),
+      "demo-plugin/openclaw.plugin.json",
+    );
+    const readme = withRelativePath(
+      new File(["# Demo\n\n![diagram](./images/foo.png)\n"], "README.md", {
+        type: "text/markdown",
+      }),
+      "demo-plugin/README.md",
+    );
+
+    fireEvent.change(getFileInput(), { target: { files: [packageJson, manifest, readme] } });
+
+    await waitFor(() => {
+      expect(screen.getByText(/Your README references a relative image path/i)).toBeTruthy();
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Source repo (owner/repo)"), {
+      target: { value: "openclaw/demo-plugin" },
+    });
+    fireEvent.change(screen.getByPlaceholderText("Source commit"), {
+      target: { value: "abc123" },
+    });
+
+    await waitFor(() => {
+      expect(screen.queryByText(/Your README references/i)).toBeNull();
+    });
+  });
+
+  it("does not warn when README only uses absolute image URLs", async () => {
+    renderPublishRoute();
+
+    const packageJson = withRelativePath(
+      new File(
+        [makeCodePluginPackageJson({ name: "demo-plugin", version: "1.0.0" })],
+        "package.json",
+        {
+          type: "application/json",
+        },
+      ),
+      "demo-plugin/package.json",
+    );
+    const manifest = withRelativePath(
+      new File(['{"id":"demo.plugin"}'], "openclaw.plugin.json", { type: "application/json" }),
+      "demo-plugin/openclaw.plugin.json",
+    );
+    const readme = withRelativePath(
+      new File(["# Demo\n\n![ok](https://example.com/foo.png)\n"], "README.md", {
+        type: "text/markdown",
+      }),
+      "demo-plugin/README.md",
+    );
+
+    fireEvent.change(getFileInput(), { target: { files: [packageJson, manifest, readme] } });
+
+    await waitFor(() => {
+      expect(screen.getByDisplayValue("demo-plugin")).toBeTruthy();
+    });
+    expect(screen.queryByText(/Your README references/i)).toBeNull();
+  });
 });

src/components/MarkdownPreview.test.tsx

@@ -64,6 +64,54 @@ describe("MarkdownPreview — raw HTML passthrough", () => {
     );
   });
 
+  it("leaves relative <img src> alone when no assetBaseUrl is provided", () => {
+    const { container } = render(
+      <MarkdownPreview highlight={false}>{`![diagram](./images/foo.png)`}</MarkdownPreview>,
+    );
+    const img = container.querySelector("img");
+    // Falls back to the legacy pass-through behavior — relative path stays as-is.
+    expect(img?.getAttribute("src")).toBe("./images/foo.png");
+  });
+
+  it("resolves relative ![](./path) images against assetBaseUrl and proxies them", () => {
+    const { container } = render(
+      <MarkdownPreview
+        highlight={false}
+        assetBaseUrl="https://raw.githubusercontent.com/owner/repo/abc123/sub/"
+      >{`![diagram](./images/foo.png)`}</MarkdownPreview>,
+    );
+    const img = container.querySelector("img");
+    expect(img?.getAttribute("src")).toBe(
+      "/_vercel/image?url=https%3A%2F%2Fraw.githubusercontent.com%2Fowner%2Frepo%2Fabc123%2Fsub%2Fimages%2Ffoo.png&w=1024&q=75",
+    );
+  });
+
+  it("resolves relative <img src> in raw HTML against assetBaseUrl", () => {
+    const { container } = render(
+      <MarkdownPreview
+        highlight={false}
+        assetBaseUrl="https://raw.githubusercontent.com/owner/repo/abc123/"
+      >{`<img src="images/foo.png" alt="d"/>`}</MarkdownPreview>,
+    );
+    const img = container.querySelector("img");
+    expect(img?.getAttribute("src")).toBe(
+      "/_vercel/image?url=https%3A%2F%2Fraw.githubusercontent.com%2Fowner%2Frepo%2Fabc123%2Fimages%2Ffoo.png&w=1024&q=75",
+    );
+  });
+
+  it("does not rewrite root-absolute paths even when assetBaseUrl is set", () => {
+    const { container } = render(
+      <MarkdownPreview
+        highlight={false}
+        assetBaseUrl="https://raw.githubusercontent.com/owner/repo/abc123/"
+      >{`![x](/foo.png)`}</MarkdownPreview>,
+    );
+    const img = container.querySelector("img");
+    // Root-absolute paths are intentionally left alone — they typically point
+    // at the ClawHub site itself, not at a package asset.
+    expect(img?.getAttribute("src")).toBe("/foo.png");
+  });
+
   it("renders <br/> as a real line break", () => {
     const container = renderMarkdown(`line one<br/>line two`);
     expect(container.querySelector("br")).not.toBeNull();

src/components/MarkdownPreview.tsx

@@ -14,6 +14,15 @@ interface MarkdownPreviewProps {
   /** Enable Shiki syntax highlighting for fenced code blocks. Default: true. */
   highlight?: boolean;
   urlTransform?: UrlTransform;
+  /**
+   * Base URL used to resolve relative <img src> values inside the README
+   * (e.g. `./images/foo.png`). When set, relative sources are resolved
+   * against this base and then routed through the standard image proxy.
+   * Typical value: a `raw.githubusercontent.com/<repo>/<commit>/<dir>/` URL
+   * derived from the package release's `verification.sourceRepo` +
+   * `verification.sourceCommit`. Must end with `/`.
+   */
+  assetBaseUrl?: string;
 }
 
 const schema = {
@@ -32,7 +41,9 @@ const schema = {
 // sees user-authored HTML; shiki's trusted styled output flows through after.
 // rehypeProxyImages rewrites after sanitize so we rewrite only already-safe
 // <img src="..."> nodes (sanitize strips event handlers, javascript: URLs).
-const baseRehype: PluggableList = [rehypeRaw, [rehypeSanitize, schema], rehypeProxyImages];
+function buildBaseRehype(assetBaseUrl: string | undefined): PluggableList {
+  return [rehypeRaw, [rehypeSanitize, schema], [rehypeProxyImages, { assetBaseUrl }]];
+}
 
 const SHIKI_THEME = "github-dark";
 const SHIKI_LANGS = [
@@ -77,6 +88,7 @@ export function MarkdownPreview({
   className,
   highlight = true,
   urlTransform,
+  assetBaseUrl,
 }: MarkdownPreviewProps) {
   const [highlighter, setHighlighter] = useState<unknown>(null);
 
@@ -97,11 +109,12 @@ export function MarkdownPreview({
   }, [highlight]);
 
   const rehypePlugins = useMemo<PluggableList>(() => {
+    const baseRehype = buildBaseRehype(assetBaseUrl);
     if (highlight && highlighter) {
       return [...baseRehype, [rehypeShikiFromHighlighter, highlighter, { theme: SHIKI_THEME }]];
     }
     return baseRehype;
-  }, [highlight, highlighter]);
+  }, [highlight, highlighter, assetBaseUrl]);
 
   return (
     <div className={cn("markdown", className)}>

src/lib/detectRelativeReadmeAssets.test.ts

@@ -0,0 +1,75 @@
+/* @vitest-environment node */
+
+import { describe, expect, it } from "vitest";
+import { detectRelativeReadmeAssets } from "./detectRelativeReadmeAssets";
+
+describe("detectRelativeReadmeAssets", () => {
+  it("returns nothing for empty input", () => {
+    expect(detectRelativeReadmeAssets("")).toEqual({ samples: [], total: 0 });
+  });
+
+  it("flags a relative markdown image reference", () => {
+    const report = detectRelativeReadmeAssets("![diagram](./images/foo.png)");
+    expect(report.samples).toEqual(["./images/foo.png"]);
+    expect(report.total).toBe(1);
+  });
+
+  it("flags relative <img src> references in raw HTML", () => {
+    const report = detectRelativeReadmeAssets(
+      `<img src="images/foo.png" alt="x"/><img src='./bar.svg'/>`,
+    );
+    expect(report.samples).toEqual(["images/foo.png", "./bar.svg"]);
+    expect(report.total).toBe(2);
+  });
+
+  it("flags root-absolute paths because they break on the plugin detail page", () => {
+    const report = detectRelativeReadmeAssets("![logo](/static/logo.png)");
+    expect(report.samples).toEqual(["/static/logo.png"]);
+  });
+
+  it("ignores absolute http(s) URLs", () => {
+    const report = detectRelativeReadmeAssets(
+      '![ok](https://example.com/foo.png)\n<img src="http://example.com/x.png"/>',
+    );
+    expect(report).toEqual({ samples: [], total: 0 });
+  });
+
+  it("ignores protocol-relative URLs, data:, mailto:, tel:, and fragment hrefs", () => {
+    const report = detectRelativeReadmeAssets(
+      [
+        "![a](//cdn.example.com/x.png)",
+        "![b](data:image/png;base64,abc)",
+        "![c](#anchor)",
+        '<img src="mailto:x@y"/>',
+      ].join("\n"),
+    );
+    expect(report).toEqual({ samples: [], total: 0 });
+  });
+
+  it("deduplicates samples but counts each occurrence in total", () => {
+    const report = detectRelativeReadmeAssets(
+      '![a](./x.png)\n![a](./x.png)\n<img src="./x.png"/>\n![b](./y.png)',
+    );
+    expect(report.samples).toEqual(["./x.png", "./y.png"]);
+    expect(report.total).toBe(4);
+  });
+
+  it("caps samples at 5 distinct paths but keeps counting in total", () => {
+    const lines = Array.from({ length: 10 }, (_, idx) => `![n](./img-${idx}.png)`);
+    const report = detectRelativeReadmeAssets(lines.join("\n"));
+    expect(report.samples.length).toBe(5);
+    expect(report.samples).toEqual([
+      "./img-0.png",
+      "./img-1.png",
+      "./img-2.png",
+      "./img-3.png",
+      "./img-4.png",
+    ]);
+    expect(report.total).toBe(10);
+  });
+
+  it("handles markdown image references with a title segment", () => {
+    const report = detectRelativeReadmeAssets(`![alt](./images/foo.png "title text")`);
+    expect(report.samples).toEqual(["./images/foo.png"]);
+  });
+});

src/lib/detectRelativeReadmeAssets.ts

@@ -0,0 +1,77 @@
+/**
+ * Scans README markdown text for relative image references — both Markdown
+ * `![alt](./path)` syntax and raw HTML `<img src="./path">` tags — and returns
+ * the unique set of relative paths it finds (capped to keep UI warnings short).
+ *
+ * Why: ClawHub does not host package binary assets. When a publisher uploads
+ * a zip/tgz whose README references local images via relative paths, those
+ * images render fine inside the package but 404 on the plugin detail page
+ * unless the release also carries Source repo + Source commit (which lets us
+ * resolve them to a stable raw.githubusercontent.com URL). We use this scanner
+ * to surface a non-blocking warning on the publish form so authors can either
+ * fill in source metadata or rewrite their README to absolute URLs before
+ * shipping.
+ *
+ * Definition of "relative" here is intentionally narrow: anything that is not
+ * an absolute http(s) URL, a protocol-relative URL, a data:/mailto:/tel: URI,
+ * or a fragment. Root-absolute paths like `/foo.png` are also flagged because
+ * on the plugin detail page the browser resolves them against clawhub.ai
+ * itself, which is just as broken as `./foo.png`.
+ */
+
+const MARKDOWN_IMAGE = /!\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+const HTML_IMG_SRC = /<img\b[^>]*?\bsrc\s*=\s*(?:"([^"]+)"|'([^']+)')[^>]*?>/gi;
+
+const ABSOLUTE_URL = /^[a-z][a-z0-9+\-.]*:/i;
+const PROTOCOL_RELATIVE = /^\/\//;
+
+const MAX_REPORTED = 5;
+
+function isRelativeAsset(rawSrc: string): boolean {
+  const src = rawSrc.trim();
+  if (!src) return false;
+  if (src.startsWith("#")) return false;
+  if (PROTOCOL_RELATIVE.test(src)) return false;
+  if (ABSOLUTE_URL.test(src)) return false;
+  return true;
+}
+
+export interface RelativeReadmeAssetReport {
+  /** Up to MAX_REPORTED unique paths, in the order encountered. */
+  samples: string[];
+  /** Total number of relative references detected (may exceed samples.length). */
+  total: number;
+}
+
+export function detectRelativeReadmeAssets(readmeText: string): RelativeReadmeAssetReport {
+  if (!readmeText) return { samples: [], total: 0 };
+
+  const seen = new Set<string>();
+  const samples: string[] = [];
+  let total = 0;
+
+  const record = (src: string | undefined) => {
+    if (!src) return;
+    if (!isRelativeAsset(src)) return;
+    total += 1;
+    if (seen.has(src)) return;
+    seen.add(src);
+    if (samples.length < MAX_REPORTED) samples.push(src);
+  };
+
+  MARKDOWN_IMAGE.lastIndex = 0;
+  for (
+    let match = MARKDOWN_IMAGE.exec(readmeText);
+    match;
+    match = MARKDOWN_IMAGE.exec(readmeText)
+  ) {
+    record(match[1]);
+  }
+
+  HTML_IMG_SRC.lastIndex = 0;
+  for (let match = HTML_IMG_SRC.exec(readmeText); match; match = HTML_IMG_SRC.exec(readmeText)) {
+    record(match[1] ?? match[2]);
+  }
+
+  return { samples, total };
+}