fix(showcase/shell-docs): Dockerfile hygiene (ARG scope, npm ci, .dockerignore, direct next binary)

- Re-declare COMMIT_SHA and BRANCH ARGs in the runner stage so ENV
  interpolation resolves (ARGs do not cross stages in multi-stage builds).
- Declare NEXT_PUBLIC_BASE_URL as a build-time ARG/ENV so CI can pass it
  via --build-arg for the production `next build` (next.config.ts requires it).
- Copy lockfile for shell-docs and switch to `npm ci` for reproducible installs.
  scripts/ has no committed lockfile yet, so keep `npm install` there.
- Add .dockerignore so local .next/, node_modules/, .git, logs, and .env*
  are not slurped into the build context.
- Invoke next via node_modules/.bin/next (both build and CMD) instead of
  npx to avoid runtime network-fallback risk.
- Document the required build context at the top of the Dockerfile.
- Note the libc6-compat discussion: the slim base is Debian (glibc), so
  no compat shim is required; note how to enable it if we ever move to
  node:20-alpine.

Author: jpr5

showcase/shell-docs/.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+.next
+.git
+dist
+build
+coverage
+*.log
+.env
+.env.local
+.env.*.local
+.DS_Store

showcase/shell-docs/Dockerfile

@@ -1,14 +1,30 @@
+# Build from repo root: docker build -f showcase/shell-docs/Dockerfile .
+# The build context MUST be the repository root; this Dockerfile copies from
+# showcase/scripts, showcase/shared, showcase/packages, and showcase/shell-docs.
+
 FROM node:20-slim AS builder
 ARG COMMIT_SHA=unknown
 ARG BRANCH=unknown
+# NEXT_PUBLIC_BASE_URL is required at `next build` time (see next.config.ts).
+# Pass it via: docker build --build-arg NEXT_PUBLIC_BASE_URL=https://...
+ARG NEXT_PUBLIC_BASE_URL
+ENV NEXT_PUBLIC_BASE_URL=${NEXT_PUBLIC_BASE_URL}
 WORKDIR /app
 
-# Copy only what shell-docs + scripts need
-COPY showcase/scripts/package.json ./scripts/package.json
-COPY showcase/shell-docs/package.json ./shell-docs/package.json
+# NOTE on SWC native bindings: Next.js recommends installing `libc6-compat`
+# on Alpine-based images so @next/swc-* native binaries load. We use
+# `node:20-slim` (Debian bookworm), which ships with glibc, so no compat
+# shim is required. If we ever switch to `node:20-alpine`, add:
+#   RUN apk add --no-cache libc6-compat
+
+# Copy manifests + lockfiles first for cached, reproducible installs.
+# showcase/scripts/ does not currently ship a lockfile; use `npm install`
+# there and `npm ci` for shell-docs, which does.
+COPY showcase/scripts/package.json ./scripts/
+COPY showcase/shell-docs/package.json showcase/shell-docs/package-lock.json ./shell-docs/
 
-# Install deps for both (standalone, no workspace)
-RUN cd scripts && npm install --silent && cd ../shell-docs && npm install --silent
+RUN cd scripts && npm install --silent \
+    && cd ../shell-docs && npm ci --silent
 
 # Copy source
 COPY showcase/shared/ ./shared/
@@ -24,9 +40,13 @@ ENV NEXT_PUBLIC_BRANCH=${BRANCH}
 RUN cd scripts && node node_modules/tsx/dist/cli.mjs generate-registry.ts \
     && node node_modules/tsx/dist/cli.mjs bundle-demo-content.ts \
     && node node_modules/tsx/dist/cli.mjs generate-search-index.ts \
-    && cd ../shell-docs && npx next build
+    && cd ../shell-docs && node_modules/.bin/next build
 
 FROM node:20-slim AS runner
+# Re-declare build args in this stage so ENV interpolation below resolves.
+# ARGs do not cross stages in multi-stage builds.
+ARG COMMIT_SHA=unknown
+ARG BRANCH=unknown
 WORKDIR /app
 ENV NODE_ENV=production
 ENV PORT=10000
@@ -40,4 +60,5 @@ COPY --from=builder /app/shell-docs/public ./public
 COPY --from=builder /app/shell-docs/src/content ./src/content
 
 EXPOSE 10000
-CMD ["npx", "next", "start", "-p", "10000"]
+# Invoke next directly (no npx) to avoid runtime network fallback
+CMD ["node_modules/.bin/next", "start", "-p", "10000"]