From 6cfe4acff7284fc330e3e24ef0f4b0ac878628c4 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 15 Sep 2026 13:34:30 -0500 Subject: [PATCH] fix: preserve README images in npm package (#13488) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Its CLI is published as the paperclipai npm package, with the root README shown on the package page > - The root README uses repository-relative image paths so images render correctly on GitHub > - npm resolves those paths under the package repository directory, which is cli, so the image requests point to missing cli/doc/assets files > - This pull request prepares the generated npm README by converting only image src and srcset asset paths to stable raw GitHub URLs > - The benefit is that the same source README remains correct on GitHub and the published npm README displays its images ## Linked Issues or Issue Description **Where is the issue?** The issue is in the root README image assets and the npm packaging step in scripts/build-npm.sh. The affected public page is https://www.npmjs.com/package/paperclipai. **What's wrong?** The npm build copies README.md into cli/ before publishing. npm resolves relative image paths beneath the package repository directory, so doc/assets/banner.jpg becomes cli/doc/assets/banner.jpg. Those files do not exist, and the images render as broken on npm. **Suggested fix** Keep the root README paths relative for GitHub. Rewrite repository-relative image paths only in the generated npm README copy to absolute raw.githubusercontent.com URLs. ## What Changed - Added a small npm README preparation script that rewrites relative image src and srcset asset paths. - Updated scripts/build-npm.sh to use the preparation step when generating the npm package README. - Added a regression test for src, srcset, immutable refs, absolute URLs, and non-image Markdown links. - Pinned release-build image URLs to the source commit, while preserving tarball builds by passing their known source refs. ## Verification - Passed: node --test scripts/prepare-npm-readme.test.mjs - Passed: bash -n scripts/build-npm.sh scripts/e2e-install-lifecycle.sh scripts/e2e-update-migrations.sh - Passed: focused README and E2E migration harness tests - Passed: git diff origin/master...HEAD --check - Generated README asset URLs were checked against raw GitHub and all seven returned HTTP 200. ## Risks Low risk. The change affects only the temporary README generated for npm packaging. It does not change the GitHub README or runtime code. The generated npm README depends on the public raw GitHub asset URLs remaining available. ## Model Used OpenAI Codex, GPT-5. Tool-enabled repository inspection, code execution, browser verification, and git/GitHub operations were used. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with Fixes: # / Closes: # / Refs: # OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs) - [x] My branch name describes the change (e.g. docs/... or fix/...) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented risks above - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip --- doc/PUBLISHING.md | 4 ++- scripts/build-npm.sh | 14 +++++++-- scripts/e2e-install-lifecycle.sh | 3 +- scripts/e2e-update-migrations.sh | 2 +- scripts/prepare-npm-readme.mjs | 38 +++++++++++++++++++++++ scripts/prepare-npm-readme.test.mjs | 48 +++++++++++++++++++++++++++++ 6 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 scripts/prepare-npm-readme.mjs create mode 100644 scripts/prepare-npm-readme.test.mjs diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.md index 433860153f..26094fdfe0 100644 --- a/doc/PUBLISHING.md +++ b/doc/PUBLISHING.md @@ -41,7 +41,9 @@ This script: 3. bundles the CLI entrypoint with esbuild into `cli/dist/index.js` 4. verifies the bundled entrypoint with `node --check` 5. rewrites `cli/package.json` into a publishable npm manifest and stores the dev copy as `cli/package.dev.json` -6. copies the repo `README.md` into `cli/README.md` for npm metadata +6. copies the repo `README.md` into `cli/README.md` for npm metadata, rewriting + repository-relative image assets to raw GitHub URLs pinned to the source + commit After the release script exits, the dev manifest and temporary files are restored automatically. diff --git a/scripts/build-npm.sh b/scripts/build-npm.sh index 74d801fdfe..937a850212 100755 --- a/scripts/build-npm.sh +++ b/scripts/build-npm.sh @@ -64,8 +64,18 @@ echo " [5/6] Generating publishable package.json..." cp "$CLI_DIR/package.json" "$CLI_DIR/package.dev.json" node "$REPO_ROOT/scripts/generate-npm-package-json.mjs" -# Copy root README so npm shows the repo README on the package page -cp "$REPO_ROOT/README.md" "$CLI_DIR/README.md" +# Copy the root README so npm shows the repo README on the package page, but +# rewrite repository-relative image assets because npm resolves README links +# under the package's `repository.directory` (`cli`), not the repository root. +README_ASSET_REF="${PAPERCLIP_README_ASSET_REF:-}" +if [ -z "$README_ASSET_REF" ]; then + README_ASSET_REF="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || true)" +fi +README_ASSET_REF="${README_ASSET_REF:-master}" +node "$REPO_ROOT/scripts/prepare-npm-readme.mjs" \ + "$REPO_ROOT/README.md" \ + "$CLI_DIR/README.md" \ + "$README_ASSET_REF" # ── Step 6: Summary ─────────────────────────────────────────────────────────── BUNDLE_SIZE=$(wc -c < "$DIST_DIR/index.js" | xargs) diff --git a/scripts/e2e-install-lifecycle.sh b/scripts/e2e-install-lifecycle.sh index 653b4cbc9d..272b74dddd 100755 --- a/scripts/e2e-install-lifecycle.sh +++ b/scripts/e2e-install-lifecycle.sh @@ -68,7 +68,8 @@ if corepack pnpm install --frozen-lockfile > "$HOME/e2e-bootstrap-install.log" 2 else tail -40 "$HOME/e2e-bootstrap-install.log"; fail_ "1b bootstrap pnpm install"; exit 1 fi -if bash scripts/build-npm.sh --skip-checks --skip-typecheck > "$HOME/e2e-bootstrap-build.log" 2>&1; then +if PAPERCLIP_README_ASSET_REF="$E2E_REF" \ + bash scripts/build-npm.sh --skip-checks --skip-typecheck > "$HOME/e2e-bootstrap-build.log" 2>&1; then pass "1c bootstrap build-npm.sh" else tail -40 "$HOME/e2e-bootstrap-build.log"; fail_ "1c bootstrap build-npm.sh"; exit 1 diff --git a/scripts/e2e-update-migrations.sh b/scripts/e2e-update-migrations.sh index e152888e40..b5d57f661a 100755 --- a/scripts/e2e-update-migrations.sh +++ b/scripts/e2e-update-migrations.sh @@ -97,7 +97,7 @@ else | tar -xz --strip-components=1 -C "$BOOT" || { fail_ "1a bootstrap tarball"; exit 1; } ( cd "$BOOT" \ && corepack pnpm install --frozen-lockfile > "$HOME/e2e-upd-bootstrap-install.log" 2>&1 \ - && bash scripts/build-npm.sh --skip-checks --skip-typecheck > "$HOME/e2e-upd-bootstrap-build.log" 2>&1 ) \ + && PAPERCLIP_README_ASSET_REF="$BASE_REF" bash scripts/build-npm.sh --skip-checks --skip-typecheck > "$HOME/e2e-upd-bootstrap-build.log" 2>&1 ) \ || { tail -40 "$HOME"/e2e-upd-bootstrap-*.log; fail_ "1b bootstrap build"; exit 1; } TARBALL="$(cd "$BOOT/cli" && npm pack --silent 2>/dev/null | tail -1)" mkdir -p "$HOME/e2e-upd-bootstrap-cli" diff --git a/scripts/prepare-npm-readme.mjs b/scripts/prepare-npm-readme.mjs new file mode 100644 index 0000000000..fbefd3a15d --- /dev/null +++ b/scripts/prepare-npm-readme.mjs @@ -0,0 +1,38 @@ +import { readFileSync, writeFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +export function prepareNpmReadme(readme, assetRef) { + if (!assetRef) { + throw new Error("an immutable README asset ref is required"); + } + + const assetBaseUrl = + `https://raw.githubusercontent.com/paperclipai/paperclip/${assetRef}/doc/assets/`; + + return readme.replace( + /((?:src|srcset)=["'])([^"']*)(["'])/g, + (_match, prefix, value, suffix) => + `${prefix}${value.replace( + /(^|,\s*)doc\/assets\//g, + `$1${assetBaseUrl}`, + )}${suffix}`, + ); +} + +const isDirectRun = + process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); + +if (isDirectRun) { + const [sourcePath, destinationPath, assetRef] = process.argv.slice(2); + if (!sourcePath || !destinationPath || !assetRef) { + throw new Error( + "usage: prepare-npm-readme.mjs ", + ); + } + + writeFileSync( + destinationPath, + prepareNpmReadme(readFileSync(sourcePath, "utf8"), assetRef), + ); +} diff --git a/scripts/prepare-npm-readme.test.mjs b/scripts/prepare-npm-readme.test.mjs new file mode 100644 index 0000000000..a5d40678e8 --- /dev/null +++ b/scripts/prepare-npm-readme.test.mjs @@ -0,0 +1,48 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import test from "node:test"; + +import { prepareNpmReadme } from "./prepare-npm-readme.mjs"; + +const assetBase = + "https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/"; +const releaseAssetBase = + "https://raw.githubusercontent.com/paperclipai/paperclip/abc123/doc/assets/"; + +test("rewrites repository-relative image sources for npm", () => { + const readme = [ + '', + '', + '[docs](doc/assets/not-an-image.md)', + '', + '', + ].join("\n"); + + assert.equal( + prepareNpmReadme(readme, "master"), + [ + ``, + ``, + "[docs](doc/assets/not-an-image.md)", + '', + '', + ].join("\n"), + ); +}); + +test("prepares the repository README without package-relative image sources", () => { + const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8"); + const npmReadme = prepareNpmReadme(readme, "master"); + + assert.doesNotMatch( + npmReadme, + /(?:src|srcset)=["'](?:doc\/assets\/|[^"']*,\s*doc\/assets\/)/, + ); +}); + +test("supports immutable release refs for generated asset URLs", () => { + assert.equal( + prepareNpmReadme('', "abc123"), + ``, + ); +});