Install typedoc just-in-time for API docs (end Dependabot churn, keep the docs)

[amcaplan]

What & why

typedoc is a doc-only devDependency in @shopify/cli-kit that drives recurring Dependabot churn — 35 version bumps over the last 24 months. Its only consumer is the cli-kit API-docs generator (packages/cli-kit/scripts/build-api-docs.js).

An earlier version of this PR removed typedoc and the API-docs generation, on the assumption the generated docs were unused. That was incorrect. The cli-kit API reference at https://shopify.github.io/cli/api/cli-kit/ is:

• Generated at GitHub Pages deploy time — docs/api is gitignored and never committed; the "Build TSDoc docs" step in pages.yml regenerates it on every deploy.
• Continuously redeployed — pages.yml fires on pushes to docs/** and packages/cli-kit/package.json (e.g. every release's changeset version bump); recent runs are all green.
• Live and search-indexed — deep pages such as shopifyFetch and isDevelopment are crawlable. Dropping generation would have silently 404'd them on the next Pages run.

The fix

Keep the API-docs pipeline, but take typedoc out of tracked dependencies and install it just-in-time in the Pages job:

• typedoc is no longer in cli-kit/package.json or pnpm-lock.yaml → Dependabot can't see it → no more churn, which was the original goal.
• The Pages job runs pnpm --filter @shopify/cli-kit add --save-dev typedoc right before building the docs. Left unpinned so docs track the latest typedoc and stay compatible with the repo's TypeScript automatically. Nothing it installs is committed.

Also in this PR

• Dropped the open-api-docs target (the local "build + open in browser" convenience) and its open knip entry — nothing invokes it, and it only ever worked with typedoc installed locally.
• Linked the API reference from docs/README.md so it's discoverable from the docs site rather than orphaned (previously reachable only by direct URL — it isn't linked from anywhere in the repo).

Validation (local, on this branch)

• Ran the exact Pages sequence — pnpm --filter @shopify/cli-kit add --save-dev typedoc && pnpm build-api-docs — with both pinned 0.28.17 and unpinned (resolves 0.28.19): docs generate successfully (795 files incl. index.html) against the repo's TypeScript 5.9.3; the programmatic typedoc API is intact.
• pnpm knip → exit 0 (typedoc added to cli-kit ignoreDependencies, since the script uses it but it's deliberately not a listed dependency).

Trade-off

Local pnpm build-api-docs now requires a one-time pnpm --filter @shopify/cli-kit add --save-dev typedoc first (CI does this automatically). Accepted, since it removes the dependency from Dependabot's view while keeping the docs.

Changeset

None — devDependency/CI/docs-only, invisible to consumers of the published package.

[Copilot]

Pull request overview

This PR removes typedoc from tracked @shopify/cli-kit devDependencies to avoid recurring Dependabot churn, while preserving the generated cli-kit API reference by installing typedoc just-in-time during the GitHub Pages deployment workflow.

Changes:

• Removed typedoc (and its lockfile entries) from the repo’s tracked dependencies for @shopify/cli-kit.
• Updated the Pages workflow to install typedoc during the deploy job before generating the API docs.
• Removed the unused open-api-docs target and added a discoverable link to the published API reference in docs/README.md.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Drops typedoc and updates lockfile content accordingly (currently includes broad structural churn).
packages/cli-kit/project.json	Removes the open-api-docs Nx target.
packages/cli-kit/package.json	Removes the open-api-docs script and the typedoc devDependency.
package.json	Updates Knip config to ignore typedoc for cli-kit since it’s intentionally untracked.
docs/README.md	Adds a link to the published cli-kit API reference.
.github/workflows/pages.yml	Installs typedoc during Pages build before running build-api-docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.