fix(FR-2906): invoke docs-toolkit CLI by node path so build_docs survives pnpm v11 bin-link gap

[yomybaby]

Resolves #7440(FR-2906)

Problem

The build_docs job in .github/workflows/package.yml has been failing during release builds, e.g. v26.4.8-rc.4: https://github.com/lablup/backend.ai-webui/actions/runs/25917622880/job/76178117083

$ pnpm run build:toolkit && docs-toolkit pdf --lang all
$ pnpm --filter backend.ai-docs-toolkit build
$ tsc
sh: 1: docs-toolkit: not found

No PDFs are produced, so Stage PDFs for upload and Upload PDF release assets are skipped and the job exits 1.

Root cause

backend.ai-docs-toolkit ships its CLI as a package bin pointing at ./dist/cli.js, which only exists after tsc runs. On a fresh checkout under pnpm v11 (since #7307 / #7345):

1. pnpm install --frozen-lockfile cannot create the node_modules/.bin/docs-toolkit symlink because the target file does not yet exist. pnpm v11 logs a [WARN] Failed to create bin … ENOENT and skips it (older pnpm versions silently created a dangling symlink, which is what the previous "build then re-install" workaround relied on).
2. The workflow then runs pnpm --filter backend.ai-docs-toolkit run build which produces dist/cli.js.
3. The workflow re-runs pnpm install --frozen-lockfile hoping the bin symlink will be retried — but pnpm v11 sees node_modules as Already up to date and does not retry bin linking. Even pnpm install --force is a no-op once the lockfile and node_modules agree.

The bin symlink stays missing for the rest of the job, and docs-toolkit pdf --lang all (and every other pdf:*, preview*, build:web*, serve:web*, agents* script in backend.ai-webui-docs / backend.ai-docs-toolkit-example) fails with spawn ENOENT.

Fix

Invoke the toolkit by direct file path instead of relying on the bin symlink. Each of these scripts already runs pnpm run build:toolkit first, so packages/backend.ai-docs-toolkit/dist/cli.js is guaranteed to exist by the time we call it:

- "pdf:all": "pnpm run build:toolkit && docs-toolkit pdf --lang all"
+ "pdf:all": "pnpm run build:toolkit && node ../backend.ai-docs-toolkit/dist/cli.js pdf --lang all"

This works regardless of whether pnpm managed to wire the bin link, so the same scripts behave identically on local dev and in CI under any pnpm version.

agents / agents:force previously assumed the toolkit was already built; they now also pnpm run build:toolkit first, matching every other entry.

The CI step Build docs-toolkit and link CLI (added as a workaround) is now obsolete — pnpm run build:toolkit inside each script handles the build, and there is no symlink to wire — so it is removed.

Files

• packages/backend.ai-webui-docs/package.json — replace every docs-toolkit … invocation with node ../backend.ai-docs-toolkit/dist/cli.js …. Add the missing pnpm run build:toolkit && prefix to agents / agents:force.
• packages/backend.ai-docs-toolkit-example/package.json — same replacement.
• .github/workflows/package.yml — drop the now-redundant Build docs-toolkit and link CLI step.

Verification

Reproduced the exact CI scenario locally — fresh checkout, no dist/, on pnpm v11.1.1:

rm -rf node_modules packages/*/node_modules packages/backend.ai-docs-toolkit/dist
pnpm install --frozen-lockfile
# WARN: Failed to create bin at .../docs-toolkit. ENOENT  ← unchanged, harmless now
pnpm --filter backend.ai-webui-docs run pdf:en

Before this PR: sh: 1: docs-toolkit: not found, exit 1.

After this PR:

[en] Done: …/dist/Backend.AI_WebUI_User_Guide_v26.5.0-alpha.0+b82b5521f_en.pdf (22.9 MB, 57.2s)
PDF generation complete!

The [WARN] Failed to create bin … message from pnpm install still appears but is now cosmetic — nothing depends on the bin symlink anymore.

Test plan

• CI build_docs job goes green on this PR (PDF artifacts uploaded).
• Next release build (workflow_dispatch or release tag) attaches *.pdf assets.

[yomybaby]

• fix(FR-2906): invoke docs-toolkit CLI by node path so build_docs survives pnpm v11 bin-link gap #7441 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• flow:merge-queue - adds this PR to the back of the merge queue
• flow:hotfix - for urgent changes, fast-track this PR to the front of the merge queue

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has required the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Copilot]

Pull request overview

This PR fixes the docs PDF build failure caused by pnpm v11 not creating the docs-toolkit bin link before dist/cli.js exists. It makes docs package scripts invoke the built CLI directly via node, avoiding reliance on workspace bin linking.

Changes:

• Replaced docs-toolkit ... script calls with direct node ../backend.ai-docs-toolkit/dist/cli.js ... invocations.
• Added toolkit build steps before agents scripts for consistency.
• Removed the obsolete CI workaround step that attempted to rebuild and relink the CLI.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
packages/backend.ai-webui-docs/package.json	Updates docs scripts to invoke the toolkit CLI by direct built file path.
packages/backend.ai-docs-toolkit-example/package.json	Applies the same direct CLI invocation pattern to example package scripts.
.github/workflows/package.yml	Removes the redundant docs-toolkit build/reinstall workaround from the release docs job.

[yomybaby]

✅ Verified on real CI via workflow_dispatch on this branch — run 25944698130:

Job	Result
build_docs	✅ success (was failing on v26.4.8-rc.4)
build_web	✅ success
build_desktop	✅ success
build_mac	✅ success

webui-docs-pdfs artifact uploaded (82 MB), confirming all four language PDFs (en/ko/ja/th) were generated and staged.