Add generated stack runtime matrix and CI verification

Author: Ali-dev11

.github/workflows/ci.yml

@@ -6,12 +6,51 @@ on:
 
 jobs:
   validate:
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: [20, 22]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: ${{ matrix.node-version }}
           cache: npm
       - run: npm ci
       - run: npm run check
+
+  generated-runtime-matrix:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        scenario:
+          - landing-react-vite
+          - frontend-nextjs
+          - frontend-astro
+          - frontend-vue-vite
+          - frontend-nuxt
+          - frontend-svelte
+          - frontend-solidjs
+          - backend-express
+          - backend-fastify
+          - backend-hono
+          - backend-koa-javascript
+          - backend-nestjs
+          - fullstack-nextjs
+          - fullstack-react-api
+          - microfrontend-workspace
+          - chrome-extension-react
+          - chrome-extension-vanilla-ts
+          - cli-tool
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: node dist/bin/runtime-matrix.js --scenario ${{ matrix.scenario }}

CHANGELOG.md

@@ -6,6 +6,25 @@ The format follows Keep a Changelog and the version numbers follow Semantic Vers
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-26
+
+### Added
+
+- Added a generated-project runtime matrix runner that scaffolds representative stacks, installs dependencies, builds them, and verifies real runtime surfaces or production artifacts.
+- Added a GitHub Actions matrix job for generated stack verification alongside the existing repository validation job.
+- Added regression coverage that enforces runtime-matrix coverage across every primary project intent and every backend framework surface.
+
+### Changed
+
+- Raised generated frontend and extension project engine declarations to match the current Vite-family toolchain requirements.
+- Documented the local runtime-matrix workflow in contributor docs and development docs.
+
+### Fixed
+
+- Added Node compatibility warnings when users choose a custom Node version that is too old for the selected frontend-oriented scaffold.
+- Added Node type definitions to generated TypeScript configs so backend, fullstack, and CLI projects build cleanly when they reference `process`.
+- Tightened the runtime verifier so CLI JSON checks execute the built binary directly instead of parsing npm wrapper output.
+
 ## [0.2.3] - 2026-03-25
 
 ### Added

CONTRIBUTING.md

@@ -28,8 +28,11 @@ npm run check
 ```bash
 npm run check
 npm run smoke
+npm run runtime:matrix -- --scenario backend-hono --scenario cli-tool
 ```
 
+For generated frontend, extension, and fullstack runtime scenarios, use Node `20.19.0+` or `22.12.0+` so the current Vite-family toolchain can install and build cleanly.
+
 ## Pull Request Expectations
 
 - explain what changed and why

README.md

@@ -45,6 +45,7 @@ npm run test
 npm run build
 npm run check
 npm run smoke
+npm run runtime:matrix -- --scenario backend-hono --scenario cli-tool
 ```
 
 ## Documentation

docs/development.md

@@ -8,6 +8,7 @@ title: Development
 
 - Node.js 20+
 - npm 10+ recommended
+- Use Node `20.19.0+` or `22.12.0+` when running generated frontend or extension runtime scenarios locally.
 
 ## Local Setup
 
@@ -24,11 +25,13 @@ npm run build
 npm run test
 npm run lint
 npm run smoke
+npm run runtime:matrix -- --scenario backend-hono --scenario cli-tool
 ```
 
 ## Workflow
 
 1. Make changes in `src/`.
 2. Run `npm run check`.
 3. Use `npm run smoke` for an end-to-end non-interactive scaffold.
-4. Update docs when command behavior or generated output changes.
+4. Use `npm run runtime:matrix` to verify generated installs, builds, and runtime surfaces for representative stacks.
+5. Update docs when command behavior or generated output changes.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@ali-dev11/devforge",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Production-focused AI-native project scaffolding CLI for JavaScript and TypeScript teams.",
   "license": "MIT",
   "author": "Ali-dev11",
@@ -50,6 +50,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --import tsx --test test/**/*.test.ts",
     "check": "npm run lint && npm run typecheck && npm run test && npm run build",
+    "runtime:matrix": "npm run build && node dist/bin/runtime-matrix.js",
     "release:check": "npm run check && npm pack --dry-run --ignore-scripts --cache /tmp/devforge-npm-cache",
     "release:patch": "npm version patch",
     "release:minor": "npm version minor",

package.json

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runRuntimeMatrix } from "../runtime-matrix.js";
+
+runRuntimeMatrix().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

src/bin/runtime-matrix.ts

@@ -11,6 +11,10 @@ import type {
   ProjectPlan,
   RuleCategory,
 } from "../types.js";
+import {
+  isNodeVersionSupportedForPlan,
+  minimumSupportedNodeVersionHint,
+} from "../utils/node-compat.js";
 import { dedupe } from "../utils/strings.js";
 
 function supportsShadcn(framework: FrontendFramework): boolean {
@@ -169,6 +173,18 @@ export function normalizeProjectPlan(
     plan.ai.tools = ["codex"];
   }
 
+  if (
+    plan.nodeStrategy === "custom" &&
+    plan.customNodeVersion &&
+    !isNodeVersionSupportedForPlan(plan, plan.customNodeVersion)
+  ) {
+    warnings.push(
+      `Selected Node.js ${plan.customNodeVersion} is below the recommended minimum for this stack (${minimumSupportedNodeVersionHint(
+        plan,
+      )}). Upgrade Node or choose LTS/latest to avoid install and build failures.`,
+    );
+  }
+
   if (!plan.testing.enabled) {
     plan.testing.runner = "none";
     plan.testing.environment = "none";

src/engines/decision.ts

@@ -6,5 +6,13 @@ export { detectEnvironment } from "./engines/environment.js";
 export { generateProject } from "./engines/generator.js";
 export { runInstallers } from "./engines/installer.js";
 export { buildDefaultPlan, collectProjectPlan } from "./engines/prompts.js";
+export {
+  expectedBackendFrameworkCoverage,
+  expectedIntentCoverage,
+  getRuntimeScenario,
+  runRuntimeMatrix,
+  runtimeScenarioCoverage,
+  runtimeScenarios,
+} from "./runtime-matrix.js";
 export { buildProjectFiles } from "./templates.js";
 export type * from "./types.js";