@opengroundplan/core 0.1.1

package/templates/bases/nestjs-api/files/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "{{ solutionName | kebab }}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{ solutionName | title }} REST API",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "engines": {
+    "node": ">={{ nodeVersion }}"
+  },
+  "scripts": {
+    "build": "nest build",
+    "dev": "nest start --watch",
+    "start": "node dist/main.js",
+    "start:debug": "nest start --debug --watch",
+    "lint": "eslint .",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.1.28",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.1.28",
+    "@nestjs/platform-express": "^11.1.28",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@nestjs/cli": "^11.0.24",
+    "@nestjs/schematics": "^11.1.0",
+    "@types/node": "^24.9.0",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.5",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.64.0"
+  }
+}

package/templates/bases/nestjs-api/files/src/app.module.ts

@@ -0,0 +1,16 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+
+import { appConfig } from './config/app.config';
+import { validateEnv } from './config/env.validation';
+import { HealthModule } from './health/health.module';
+import { {{ solutionName | pascal }}Module } from './modules/{{ solutionName | kebab }}/{{ solutionName | kebab }}.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, cache: true, load: [appConfig], validate: validateEnv }),
+    HealthModule,
+    {{ solutionName | pascal }}Module,
+  ],
+})
+export class AppModule {}

package/templates/bases/nestjs-api/files/src/config/app.config.ts

@@ -0,0 +1,30 @@
+import { registerAs } from '@nestjs/config';
+import type { ConfigType } from '@nestjs/config';
+
+export const APP_CONFIG_NAMESPACE = 'app';
+
+/** The single default table. Nothing outside this file may read process.env or inline a tunable. */
+const defaults = {
+  nodeEnv: 'development',
+  host: '0.0.0.0',
+  port: {{ httpPort }},
+  apiPrefix: '{{ apiPrefix }}',
+  corsOrigin: '*',
+  serviceName: '{{ solutionName | kebab }}',
+};
+
+export const appConfig = registerAs(APP_CONFIG_NAMESPACE, () => ({
+  nodeEnv: process.env.NODE_ENV ?? defaults.nodeEnv,
+  host: process.env.HOST ?? defaults.host,
+  port: toInt(process.env.PORT, defaults.port),
+  apiPrefix: process.env.API_PREFIX ?? defaults.apiPrefix,
+  corsOrigin: process.env.CORS_ORIGIN ?? defaults.corsOrigin,
+  serviceName: process.env.SERVICE_NAME ?? defaults.serviceName,
+}));
+
+export type AppConfig = ConfigType<typeof appConfig>;
+
+function toInt(raw: string | undefined, fallback: number): number {
+  const parsed = Number.parseInt(raw ?? '', 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}

package/templates/bases/nestjs-api/files/src/config/env.validation.ts

@@ -0,0 +1,15 @@
+const PORT_MIN = 1;
+const PORT_MAX = 65535;
+
+/** Runs before the DI container boots — a bad PORT should crash here, not on first request. */
+export function validateEnv(raw: Record<string, string>): Record<string, string> {
+  if (raw.PORT !== undefined) {
+    const port = Number(raw.PORT);
+    if (!Number.isInteger(port) || port < PORT_MIN || port > PORT_MAX) {
+      throw new Error(
+        `PORT must be an integer between ${PORT_MIN} and ${PORT_MAX}, received "${raw.PORT}"`,
+      );
+    }
+  }
+  return raw;
+}

package/templates/bases/nestjs-api/files/src/health/health.controller.ts

@@ -0,0 +1,19 @@
+import { Controller, Get, Inject } from '@nestjs/common';
+
+import { appConfig, type AppConfig } from '../config/app.config';
+
+@Controller('health')
+export class HealthController {
+  constructor(@Inject(appConfig.KEY) private readonly config: AppConfig) {}
+
+  @Get()
+  check() {
+    return {
+      status: 'ok',
+      service: this.config.serviceName,
+      env: this.config.nodeEnv,
+      uptimeSeconds: Math.round(process.uptime()),
+      timestamp: new Date().toISOString(),
+    };
+  }
+}

package/templates/bases/nestjs-api/files/src/health/health.module.ts

@@ -0,0 +1,6 @@
+import { Module } from '@nestjs/common';
+
+import { HealthController } from './health.controller';
+
+@Module({ controllers: [HealthController] })
+export class HealthModule {}

package/templates/bases/nestjs-api/files/src/main.ts

@@ -0,0 +1,25 @@
+import 'reflect-metadata';
+
+import { ValidationPipe } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+import { appConfig, type AppConfig } from './config/app.config';
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule);
+  const config = app.get<AppConfig>(appConfig.KEY);
+
+  app.setGlobalPrefix(config.apiPrefix);
+  app.enableCors({ origin: config.corsOrigin });
+  app.enableShutdownHooks();
+
+  // Strip unknown keys and reject them, so DTOs are the only contract a client can hit.
+  app.useGlobalPipes(
+    new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }),
+  );
+
+  await app.listen(config.port, config.host);
+}
+
+void bootstrap();

package/templates/bases/nestjs-api/files/src/modules/__solutionName.kebab__/__solutionName.kebab__.controller.ts

@@ -0,0 +1,14 @@
+import { Controller, Get, Query } from '@nestjs/common';
+
+import { GreetQueryDto } from './dto/greet-query.dto';
+import { {{ solutionName | pascal }}Service } from './{{ solutionName | kebab }}.service';
+
+@Controller('{{ solutionName | kebab }}')
+export class {{ solutionName | pascal }}Controller {
+  constructor(private readonly service: {{ solutionName | pascal }}Service) {}
+
+  @Get('greet')
+  greet(@Query() query: GreetQueryDto) {
+    return this.service.greet(query.name);
+  }
+}

package/templates/bases/nestjs-api/files/src/modules/__solutionName.kebab__/__solutionName.kebab__.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common';
+
+import { {{ solutionName | pascal }}Controller } from './{{ solutionName | kebab }}.controller';
+import { {{ solutionName | pascal }}Service } from './{{ solutionName | kebab }}.service';
+
+@Module({
+  controllers: [{{ solutionName | pascal }}Controller],
+  providers: [{{ solutionName | pascal }}Service],
+  exports: [{{ solutionName | pascal }}Service],
+})
+export class {{ solutionName | pascal }}Module {}

package/templates/bases/nestjs-api/files/src/modules/__solutionName.kebab__/__solutionName.kebab__.service.ts

@@ -0,0 +1,12 @@
+import { Inject, Injectable } from '@nestjs/common';
+
+import { appConfig, type AppConfig } from '../../config/app.config';
+
+@Injectable()
+export class {{ solutionName | pascal }}Service {
+  constructor(@Inject(appConfig.KEY) private readonly config: AppConfig) {}
+
+  greet(name = 'world'): { message: string; service: string } {
+    return { message: `Hello, ${name}!`, service: this.config.serviceName };
+  }
+}

package/templates/bases/nestjs-api/files/src/modules/__solutionName.kebab__/dto/greet-query.dto.ts

@@ -0,0 +1,10 @@
+import { IsOptional, IsString, Length } from 'class-validator';
+
+const NAME_MAX_LENGTH = 64;
+
+export class GreetQueryDto {
+  @IsOptional()
+  @IsString()
+  @Length(1, NAME_MAX_LENGTH)
+  name?: string;
+}

package/templates/bases/nestjs-api/files/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "dist", "eslint.config.mjs"]
+}

package/templates/bases/nestjs-api/files/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "module": "node18",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "moduleResolution": "node16",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": false,
+    "sourceMap": true,
+    "incremental": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/bases/nextjs-app/blueprint.yaml

@@ -0,0 +1,80 @@
+id: nextjs-app
+kind: base
+name: Next.js App Router
+description: >-
+  Next.js 16 App Router skeleton — React 19, TypeScript strict, Tailwind CSS v4,
+  flat ESLint. Ships a config module, one page, and a health endpoint. No CI,
+  Docker, auth, database, or testing — those compose on top as layers.
+stack: typescript
+
+tags:
+  - nextjs
+  - react
+  - typescript
+  - tailwind
+  - app-router
+  - fullstack
+  - frontend
+
+provides:
+  - web-app
+  - http-server
+  - node-runtime
+
+# Frontend/fullstack layouts only. Hexagonal, onion, and microservices govern a
+# service boundary this base does not own; the AI architectures need a different base.
+supportsArchitectures:
+  - monolith
+  - vertical-slice
+  - feature-sliced-design
+  - nextjs-colocation
+  - bff
+  - mvc-mvvm
+  # The Next app becomes the shell. Try multi-zones first — see the overlay's doc.
+  - micro-frontends
+
+variables:
+  - name: appDescription
+    prompt: One-line description of the app (used in metadata and the README)
+    type: string
+    default: A Next.js application.
+    required: false
+
+  - name: defaultPort
+    prompt: Port the dev and production servers listen on
+    type: number
+    default: 3000
+    required: false
+
+  - name: packageManager
+    prompt: Package manager
+    type: select
+    choices:
+      - value: pnpm
+        label: pnpm
+      - value: npm
+        label: npm
+      - value: yarn
+        label: Yarn
+      - value: bun
+        label: Bun
+    default: pnpm
+    required: true
+
+files:
+  - from: files/**/*
+    to: .
+
+postApply:
+  - run: pnpm install
+    when: packageManager == 'pnpm'
+    optional: true
+  - run: npm install
+    when: packageManager == 'npm'
+    optional: true
+  - run: yarn install
+    when: packageManager == 'yarn'
+    optional: true
+  - run: bun install
+    when: packageManager == 'bun'
+    optional: true

package/templates/bases/nextjs-app/files/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env.local. Every key here is optional — src/config/env.ts holds the defaults.
+
+# Exposed to the browser (NEXT_PUBLIC_* is inlined at build time — never put secrets here).
+NEXT_PUBLIC_APP_NAME="{{ solutionName | title }}"
+NEXT_PUBLIC_APP_URL="http://localhost:{{ defaultPort }}"
+
+# Server only.
+APP_ENV=development
+LOG_LEVEL=info
+HEALTH_CACHE_SECONDS=0

package/templates/bases/nextjs-app/files/README.md

@@ -0,0 +1,48 @@
+# {{ solutionName | title }}
+
+{{ appDescription }}
+
+Next.js 16 (App Router) · React 19 · TypeScript strict · Tailwind CSS v4.
+
+## Getting started
+
+```bash
+cp .env.example .env.local
+{{ packageManager }} install
+{{ packageManager }} run dev
+```
+
+Open <http://localhost:{{ defaultPort }}>.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `{{ packageManager }} run dev` | Dev server with Turbopack on port {{ defaultPort }} |
+| `{{ packageManager }} run build` | Production build |
+| `{{ packageManager }} run start` | Serve the production build |
+| `{{ packageManager }} run lint` | ESLint (flat config) |
+| `{{ packageManager }} run typecheck` | `next typegen` (route types + `next-env.d.ts`) then `tsc --noEmit` |
+
+## Layout
+
+```
+src/
+├── app/                 routes, layouts, and route handlers
+│   ├── api/health/      liveness probe → GET /api/health
+│   ├── globals.css      Tailwind entry + design tokens
+│   ├── layout.tsx       root layout and metadata
+│   └── page.tsx         /
+└── config/env.ts        the only module that reads process.env
+```
+
+`@/*` resolves to `src/*`.
+
+## Configuration
+
+`src/config/env.ts` is the single source of runtime configuration: it reads the
+environment and falls back to one typed default table. Add new settings there
+rather than reaching for `process.env` from a component or route handler.
+
+`NEXT_PUBLIC_*` values are inlined into the client bundle at build time — keep
+secrets out of them.

package/templates/bases/nextjs-app/files/eslint.config.mjs

@@ -0,0 +1,12 @@
+import { defineConfig, globalIgnores } from 'eslint/config';
+import nextVitals from 'eslint-config-next/core-web-vitals';
+import nextTs from 'eslint-config-next/typescript';
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    // Agent infrastructure, deliberately outside any tsconfig.
+    '.agent/**',
+'.next/**', 'out/**', 'build/**', 'next-env.d.ts']),
+]);

package/templates/bases/nextjs-app/files/gitignore

@@ -0,0 +1,32 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# next.js
+/.next/
+/out/
+/build
+
+# env — the example is the documented contract and is committed
+.env*
+!.env.example
+
+# misc
+.DS_Store
+*.pem
+npm-debug.log*
+yarn-debug.log*
+.pnpm-debug.log*
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# vercel
+.vercel

package/templates/bases/nextjs-app/files/next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // Fail the build on type errors instead of silently shipping them.
+  typescript: { ignoreBuildErrors: false },
+};
+
+export default nextConfig;

package/templates/bases/nextjs-app/files/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{{ solutionName | kebab }}",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "dev": "next dev --turbopack --port {{ defaultPort }}",
+    "build": "next build",
+    "start": "next start --port {{ defaultPort }}",
+    "lint": "eslint .",
+    "typecheck": "next typegen && tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "16.2.10",
+    "react": "19.2.7",
+    "react-dom": "19.2.7"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/node": "26.1.1",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "eslint": "9.39.5",
+    "eslint-config-next": "16.2.10",
+    "tailwindcss": "4.3.3",
+    "typescript": "6.0.3"
+  }
+}

package/templates/bases/nextjs-app/files/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/templates/bases/nextjs-app/files/src/app/api/health/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from 'next/server';
+import { config } from '@/config/env';
+
+// Liveness probes must reflect the current process, never a cached render.
+export const dynamic = 'force-dynamic';
+
+export function GET() {
+  const body = {
+    status: 'ok',
+    app: config.app.name,
+    env: config.app.env,
+    uptimeSeconds: Math.round(process.uptime()),
+    checkedAt: new Date().toISOString(),
+  };
+
+  return NextResponse.json(body, {
+    headers: {
+      'Cache-Control': `public, max-age=${config.health.cacheSeconds}`,
+    },
+  });
+}

package/templates/bases/nextjs-app/files/src/app/globals.css

@@ -0,0 +1,45 @@
+@import "tailwindcss";
+
+/* Palette lives in plain custom properties: @theme cannot be nested in a media query. */
+:root {
+  --surface: oklch(99% 0.004 260);
+  --ink: oklch(22% 0.02 260);
+  --muted: oklch(52% 0.02 260);
+  --line: oklch(90% 0.008 260);
+  --accent: oklch(58% 0.17 264);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --surface: oklch(17% 0.015 260);
+    --ink: oklch(95% 0.006 260);
+    --muted: oklch(66% 0.02 260);
+    --line: oklch(28% 0.015 260);
+    --accent: oklch(72% 0.15 264);
+  }
+}
+
+/* `inline` so utilities resolve to the overridable vars above, not a frozen copy. */
+@theme inline {
+  --color-surface: var(--surface);
+  --color-ink: var(--ink);
+  --color-muted: var(--muted);
+  --color-line: var(--line);
+  --color-accent: var(--accent);
+}
+
+@theme {
+  --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --font-mono: ui-monospace, "SF Mono", "Cascadia Code", Menlo, monospace;
+}
+
+html {
+  color-scheme: light dark;
+}
+
+body {
+  background: var(--surface);
+  color: var(--ink);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+}

package/templates/bases/nextjs-app/files/src/app/layout.tsx

@@ -0,0 +1,28 @@
+import type { Metadata, Viewport } from 'next';
+import { config } from '@/config/env';
+import './globals.css';
+
+export const metadata: Metadata = {
+  metadataBase: new URL(config.app.url),
+  title: {
+    default: config.app.name,
+    template: `%s · ${config.app.name}`,
+  },
+  description: config.app.description,
+};
+
+export const viewport: Viewport = {
+  // Hex mirrors of --surface in globals.css; a meta tag cannot read a CSS variable.
+  themeColor: [
+    { media: '(prefers-color-scheme: light)', color: '#fafcff' },
+    { media: '(prefers-color-scheme: dark)', color: '#0c1016' },
+  ],
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="min-h-dvh">{children}</body>
+    </html>
+  );
+}

package/templates/bases/nextjs-app/files/src/app/page.tsx

@@ -0,0 +1,39 @@
+import { config } from '@/config/env';
+
+const links = [
+  { label: 'Health endpoint', href: '/api/health', hint: 'JSON liveness probe' },
+  { label: 'Next.js docs', href: 'https://nextjs.org/docs', hint: 'App Router reference' },
+];
+
+export default function HomePage() {
+  return (
+    <main className="mx-auto flex min-h-dvh max-w-2xl flex-col justify-center gap-10 px-6 py-20">
+      <header className="flex flex-col gap-3">
+        <span className="w-fit rounded-full border border-line px-3 py-1 font-mono text-xs tracking-widest text-muted uppercase">
+          {config.app.env}
+        </span>
+        <h1 className="text-4xl font-semibold tracking-tight text-balance sm:text-5xl">
+          {config.app.name}
+        </h1>
+        <p className="text-lg text-muted text-pretty">{config.app.description}</p>
+      </header>
+
+      <nav className="flex flex-col divide-y divide-line border-y border-line">
+        {links.map((link) => (
+          <a
+            key={link.href}
+            href={link.href}
+            className="group flex items-baseline justify-between gap-4 py-4 transition-colors hover:text-accent"
+          >
+            <span className="font-medium">{link.label}</span>
+            <span className="text-sm text-muted">{link.hint}</span>
+          </a>
+        ))}
+      </nav>
+
+      <p className="font-mono text-xs text-muted">
+        Edit <code>src/app/page.tsx</code> to get started.
+      </p>
+    </main>
+  );
+}