Merge pull request #26 from rogerchappel/agent/oss-1363-pin-next-toolchain

fix(next-app): pin reproducible dependency graph

Author: rogerchappel

README.md

@@ -73,6 +73,12 @@ StackForge is local-first and review-friendly:
 
 Generated repositories include `scripts/validate.sh` as the default local verification path. It runs the repo's normal local package checks when they exist, including `release:check`, and only runs `agent-qc ready` when `agent-qc` is installed, so `agent-qc` stays optional.
 
+The `next-app` scaffold ships an npm lockfile and an exact, reviewed Next.js
+toolchain. Use `npm ci` for a reproducible install and `npm run audit` to check
+the production dependency graph for high or critical advisories. The scaffold
+temporarily overrides Next.js's bundled `postcss` and `sharp` versions because
+the upstream range otherwise resolves releases with active advisories.
+
 `oss-cli` projects also include ReleaseBox by default: `releasebox.config.json`, reviewed/tag-gated GitHub release workflows, and package smoke scripts. The generated release path creates GitHub Releases with attached tarballs while leaving npm and Homebrew publishing disabled until explicitly enabled.
 
 ## Local planning docs

scripts/smoke-init.sh

@@ -173,10 +173,33 @@ test -f py-api/src/py_api/main.py
 node "$repo_root/dist/index.js" init next-app web-app > next.json
 test -f web-app/src/app/page.tsx
 test -f web-app/eslint.config.mjs
+test -f web-app/package-lock.json
+node -e '
+  const pkg = require("./web-app/package.json");
+  const expected = {
+    dependencies: { next: "16.2.12", react: "19.1.9", "react-dom": "19.1.9" },
+    devDependencies: {
+      "@types/node": "22.20.1",
+      "@types/react": "19.1.17",
+      "@types/react-dom": "19.1.11",
+      eslint: "9.39.5",
+      "eslint-config-next": "16.2.12",
+      typescript: "5.9.3"
+    },
+    overrides: { postcss: "8.5.23", sharp: "0.35.3" }
+  };
+  for (const [field, values] of Object.entries(expected)) {
+    if (JSON.stringify(pkg[field]) !== JSON.stringify(values)) {
+      throw new Error(`unexpected next-app ${field}`);
+    }
+  }
+'
 (
   cd web-app
-  npm install
+  npm ci --ignore-scripts
   npm run lint
+  npm run build
+  npm run audit
   bash scripts/validate.sh
 )
 

src/index.ts

@@ -80,6 +80,7 @@ const templateScaffolds: Record<TemplateKey, TemplateScaffold> = {
       { source: 'templates/repo-docs/README.md', destination: 'docs/README.md' },
       { source: 'templates/repo-validate/validate.sh', destination: 'scripts/validate.sh' },
       { destination: 'package.json', content: nextPackageJsonTemplate() },
+      { source: 'templates/next-app/package-lock.json', destination: 'package-lock.json', render: true },
       { destination: 'eslint.config.mjs', content: nextEslintConfigTemplate() },
       { destination: 'src/app/page.tsx', content: "export default function Home() {\n  return <main>{{PROJECT_NAME}}</main>;\n}\n" },
       { destination: 'src/app/layout.tsx', content: "export default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    <html lang=\"en\">\n      <body>{children}</body>\n    </html>\n  );\n}\n" }
@@ -519,19 +520,25 @@ function nextPackageJsonTemplate(): string {
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "audit": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "next": "latest",
-    "react": "latest",
-    "react-dom": "latest"
+    "next": "16.2.12",
+    "react": "19.1.9",
+    "react-dom": "19.1.9"
   },
   "devDependencies": {
-    "@types/node": "latest",
-    "@types/react": "latest",
-    "eslint": "latest",
-    "eslint-config-next": "latest",
-    "typescript": "latest"
+    "@types/node": "22.20.1",
+    "@types/react": "19.1.17",
+    "@types/react-dom": "19.1.11",
+    "eslint": "9.39.5",
+    "eslint-config-next": "16.2.12",
+    "typescript": "5.9.3"
+  },
+  "overrides": {
+    "postcss": "8.5.23",
+    "sharp": "0.35.3"
   }
 }
 `;