feat: Bun is the package manager, in the docs and in this repo

[dmitriyzhuk]

What

Bun is the package manager — in the documentation corpus this server ships, and in this repo's own tooling.

Companion PRs (same change, other repos):

• docs site — docs(standards): Bun everywhere — commands, prerequisites, and a page of its own docs#3
• starter kit — feat: Bun everywhere — scripts, hooks, docs, and a Docker build that boots nest-nuxt-starter-kit#5

Why

Every setup document here told the reader — and every agent that reads them — to run npm install, npm run dev, npx prisma. The starter kit those documents describe already builds with Bun. So an agent that followed the docs produced a project with two lockfiles and a CI that installs something different from what the developer ran.

The corpus

npm install → bun install, npm install -D → bun add -d, npm run → bun run, npx → bunx, and the two pnpm lines that had crept in. 16 documents.

New: docs/02-standards/bun.md — the rule stated once, with the command map, the lockfile policy, and the gotchas below. It is indexed like any other standard, so search finds it on "package manager", "bun install", "lockfile".

Hand-written rather than replaced, because a blind swap would have been wrong:

• nest new --package-manager npm has no Bun value → --skip-install, then bun install.
• The Dockerfile examples now use oven/bun-free builders (see below) and CMD ["bun", "run", "start"].
• "scoped npm packages" stayed factual as "scoped packages" — the registry is still npm.

This repo

• Dockerfile — installs and builds with Bun; bun.lock replaces package-lock.json.
• package.json — "dev": "bun run start:dev".
• README and the landing page — bun install, bun run dev.

Two things that cost time here, now written down

Build in a Node image with the Bun binary copied in, never in oven/bun. That image ships a shim named node, so nest build runs under Bun, and Nest's tsconfig-paths hook stops rewriting #mcp to a relative path. The image builds without a warning and the server dies on boot:

Error: Cannot find module '#mcp'
Require stack:
- /app/dist/slices/knowledge/knowledge.tool.js

Same source, same lockfile, same command — require("#mcp") inside oven/bun, require("../mcp") with a real Node under the build. (bunx also needs an explicit symlink: it is a symlink to the same binary in the oven image.)

Migrate the lockfile, don't regenerate it. bun install run while package-lock.json is still present carries the resolved versions across. Deleting it first re-resolved every range, pulled a newer zod/MCP SDK, and broke the build on three type errors.

Verified

• bun install, bun run build — clean.
• docker build — clean.
• Image booted: /health → 200 {"status":"ok"}, Nest started, GitHub docs indexed (44 documents).

Not done

get-started returns an empty document today: the gateway looks for a quickstart doc whose path or name contains "rules", and 00-quickstart/get-started.md matches neither (it only carries a rules tag). Pre-existing, untouched here — but it means the corpus's front door is blank, so the Bun rule is stated in the standards doc and repeated in every setup page instead.

🤖 Generated with Claude Code