groundwork-method 0.0.1 → 0.11.0

package/src/generators/nextjs-app/generator.ts

@@ -0,0 +1,307 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import {
+  promoteEngineerSkill,
+  deployStackDocs,
+  ensureOptionalInfra,
+  readProjectPrefix,
+} from '../shared/scaffold-helpers';
+import {
+  SHADCN_VARS,
+  ResolvedVisual,
+  resolveVisual,
+} from '../shared/brand-tokens';
+
+export interface NextjsAppGeneratorSchema {
+  name: string;
+  auth: 'none' | 'clerk';
+  apiProxy: boolean;
+  websockets: boolean;
+}
+
+/** Render app/brand.css from the resolved visual tokens. globals.css imports
+ *  this file and owns the structure (token mappings + surface utilities); this
+ *  file is pure values and is regenerated, never hand-edited. */
+function renderBrandCss(v: ResolvedVisual): string {
+  const out: string[] = [];
+  out.push('/* GENERATED by the GroundWork nextjs-app generator from');
+  out.push(' * .groundwork/config/brand-tokens.json — do not hand-edit this file.');
+  out.push(' * Re-run the design system to evolve the brand, then regenerate.');
+  out.push(' * app/globals.css imports this file and maps these values into Tailwind');
+  out.push(' * token utilities and surface classes; components consume those, never');
+  out.push(` * these variables directly. Projection source: ${v.source}. */`);
+  out.push('');
+  out.push(':root {');
+  out.push(`  --radius: ${v.radius};`);
+  for (const name of Object.keys(SHADCN_VARS)) {
+    out.push(`  --${name}: ${v.shadcn[name].light};`);
+  }
+  out.push('');
+  out.push('  /* Atmosphere — blur radii, elevation stacks, hero gradient. */');
+  out.push(`  --gw-blur-subtle: ${v.blur.subtle};`);
+  out.push(`  --gw-blur-standard: ${v.blur.standard};`);
+  out.push(`  --gw-blur-heavy: ${v.blur.heavy};`);
+  out.push(`  --gw-shadow-low: ${v.shadow.low.light};`);
+  out.push(`  --gw-shadow-mid: ${v.shadow.mid.light};`);
+  out.push(`  --gw-shadow-high: ${v.shadow.high.light};`);
+  out.push(`  --gw-gradient-hero: ${v.gradientHero.light};`);
+  out.push('');
+  out.push('  /* Surface treatments — tint + border per named treatment. */');
+  for (const name of ['glass', 'elevated', 'hero'] as const) {
+    out.push(`  --gw-surface-${name}-tint: ${v.surfaces[name].tint.light};`);
+    out.push(`  --gw-surface-${name}-border: ${v.surfaces[name].border.light};`);
+  }
+  out.push('');
+  out.push('  /* Typography roles — size, line-height, weight, tracking. */');
+  for (const [role, r] of Object.entries(v.typeRoles)) {
+    out.push(`  --gw-text-${role}-size: ${r.size};`);
+    out.push(`  --gw-text-${role}-line: ${r.line};`);
+    out.push(`  --gw-text-${role}-weight: ${r.weight};`);
+    out.push(`  --gw-text-${role}-tracking: ${r.tracking};`);
+  }
+  out.push('');
+  out.push('  /* Motion interaction profiles — duration, easing, transform. */');
+  for (const [ctx, m] of Object.entries(v.motion)) {
+    out.push(`  --gw-motion-${ctx}-duration: ${m.duration};`);
+    out.push(`  --gw-motion-${ctx}-ease: ${m.ease};`);
+    out.push(`  --gw-motion-${ctx}-transform: ${m.transform};`);
+  }
+  out.push('}');
+  out.push('');
+  out.push('.dark {');
+  for (const name of Object.keys(SHADCN_VARS)) {
+    out.push(`  --${name}: ${v.shadcn[name].dark};`);
+  }
+  out.push('');
+  out.push('  /* Atmosphere — dark-theme variants. */');
+  out.push(`  --gw-shadow-low: ${v.shadow.low.dark};`);
+  out.push(`  --gw-shadow-mid: ${v.shadow.mid.dark};`);
+  out.push(`  --gw-shadow-high: ${v.shadow.high.dark};`);
+  out.push(`  --gw-gradient-hero: ${v.gradientHero.dark};`);
+  for (const name of ['glass', 'elevated', 'hero'] as const) {
+    out.push(`  --gw-surface-${name}-tint: ${v.surfaces[name].tint.dark};`);
+    out.push(`  --gw-surface-${name}-border: ${v.surfaces[name].border.dark};`);
+  }
+  out.push('}');
+  out.push('');
+  return out.join('\n');
+}
+
+export default async function (tree: Tree, options: NextjsAppGeneratorSchema) {
+  const serviceNames = names(options.name);
+  const projectRoot = `services/${serviceNames.fileName}`;
+
+  // Calculate assignedPort from docker-compose.yml (base 4000, sequential)
+  let assignedPort = 4000;
+  let composeDoc: any = null;
+  if (tree.exists('docker-compose.yml')) {
+    try {
+      const yaml = require('yaml');
+      const composeContent = tree.read('docker-compose.yml', 'utf-8');
+      composeDoc = yaml.parseDocument(composeContent);
+
+      const usedPorts = new Set<number>();
+
+      // Collect ports from docker-compose.yml
+      const servicesMap = composeDoc.get('services');
+      if (servicesMap && servicesMap.items) {
+        for (const item of servicesMap.items) {
+          const service = item.value;
+          if (service && service.get) {
+            const ports = service.get('ports');
+            if (ports && ports.items) {
+              for (const pItem of ports.items) {
+                const portStr = String(pItem.value || pItem);
+                const match = portStr.match(/^(\d+):/);
+                if (match) {
+                  usedPorts.add(parseInt(match[1], 10));
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Also collect ports from .env files of natively-run services (not in docker-compose)
+      if (tree.exists('services')) {
+        for (const svcName of tree.children('services') ?? []) {
+          const envPath = `services/${svcName}/.env`;
+          if (tree.exists(envPath)) {
+            const envContent = tree.read(envPath, 'utf-8') ?? '';
+            for (const line of envContent.split('\n')) {
+              const m = line.match(/^(?:PORT|SERVER_PORT)=(\d+)/);
+              if (m) usedPorts.add(parseInt(m[1], 10));
+            }
+          }
+        }
+      }
+
+      while (usedPorts.has(assignedPort)) {
+        assignedPort++;
+      }
+    } catch (e) {
+      console.warn('Failed to parse docker-compose.yml for port calculation:', e);
+    }
+  }
+
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    assignedPort,
+    tmpl: '' // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'nextjs-app', 'files'),
+    projectRoot,
+    templateOptions
+  );
+
+  deployStackDocs(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'nextjs-app', 'docs'));
+
+  // Nx's generateFiles treats __var__ as template substitution, which
+  // conflicts with Next.js dynamic route segments like [...path] and
+  // [[...sign-in]]. We use placeholder dir names and rename post-generation.
+  const renames: [string, string][] = [
+    [`${projectRoot}/app/api/proxy/__path__`, `${projectRoot}/app/api/proxy/[...path]`],
+    [`${projectRoot}/app/(auth)/sign-in/__sign-in__`, `${projectRoot}/app/(auth)/sign-in/[[...sign-in]]`],
+    [`${projectRoot}/app/(auth)/sign-up/__sign-up__`, `${projectRoot}/app/(auth)/sign-up/[[...sign-up]]`],
+  ];
+
+  for (const [oldDir, newDir] of renames) {
+    // Find all files under the old directory and move them
+    const children = tree.children(oldDir);
+    if (children && children.length > 0) {
+      for (const child of children) {
+        const content = tree.read(`${oldDir}/${child}`);
+        if (content) {
+          tree.write(`${newDir}/${child}`, content);
+          tree.delete(`${oldDir}/${child}`);
+        }
+      }
+    }
+  }
+
+  // Project brand-tokens.json's visual block into app/brand.css — the per-app
+  // palette + atmosphere layer (elevation, blur, gradients, surface treatments,
+  // type-role micro, motion profiles). Parity with electron-app/flutter-app:
+  // globals.css imports this file and owns the structure, this file owns the
+  // values, and no engineer skill carries a fixed aesthetic catalogue.
+  tree.write(
+    `${projectRoot}/app/brand.css`,
+    renderBrandCss(resolveVisual(tree)),
+  );
+
+  // Auto-inject into docker-compose.yml if it exists
+  if (composeDoc) {
+    try {
+      if (!composeDoc.get('services')) {
+        // createNode so the result is a YAMLMap with .has/.set (a plain {} is not).
+        composeDoc.set('services', composeDoc.createNode({}));
+      }
+      const servicesMap = composeDoc.get('services');
+      if (!servicesMap.has(serviceNames.fileName)) {
+        const envVars = [
+          `PORT=${assignedPort}`,
+          `OTEL_SERVICE_NAME=${serviceNames.fileName}`,
+          'OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318',
+        ];
+
+        if (options.apiProxy) {
+          envVars.push('API_URL=http://core:4000');
+        }
+
+        if (options.auth === 'clerk') {
+          envVars.push('NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=${CLERK_PUBLISHABLE_KEY}');
+          envVars.push('CLERK_SECRET_KEY=${CLERK_SECRET_KEY}');
+        }
+
+        const newService: Record<string, unknown> = {
+          build: {
+            context: `./${projectRoot}`,
+            dockerfile: 'Dockerfile'
+          },
+          container_name: serviceNames.fileName,
+          restart: 'unless-stopped',
+          ports: [
+            `${assignedPort}:${assignedPort}`
+          ],
+          environment: envVars,
+          // The node:alpine runtime image has no curl, but ships busybox wget,
+          // which probes the health route without an extra binary.
+          healthcheck: {
+            test: [
+              'CMD',
+              'wget',
+              '-q',
+              '--spider',
+              `http://localhost:${assignedPort}/api/healthz`
+            ],
+            interval: '10s',
+            timeout: '5s',
+            retries: 5,
+            start_period: '20s'
+          },
+          networks: [
+            'groundwork-net'
+          ]
+        };
+
+        servicesMap.set(serviceNames.fileName, newService);
+        // A Next.js app exports OTLP telemetry but uses no database, so it
+        // provisions jaeger only (no longer in the base compose).
+        ensureOptionalInfra(composeDoc, servicesMap, {
+          usesRedis: false,
+          usesPubSub: false,
+          usesTelemetry: true,
+          projectPrefix: readProjectPrefix(tree),
+        });
+        tree.write('docker-compose.yml', composeDoc.toString());
+      }
+    } catch (e) {
+      console.warn('Failed to update docker-compose.yml:', e);
+    }
+  }
+
+  // Conditionally remove auth files
+  if (options.auth !== 'clerk') {
+    tree.delete(`${projectRoot}/app/(auth)`);
+    tree.delete(`${projectRoot}/proxy.ts`);
+    tree.delete(`${projectRoot}/proxy.test.ts`);
+    tree.delete(`${projectRoot}/components/providers/production.tsx`);
+  }
+
+  // Conditionally remove API proxy files
+  if (!options.apiProxy) {
+    tree.delete(`${projectRoot}/app/api/proxy`);
+    tree.delete(`${projectRoot}/lib/api`);
+    tree.delete(`${projectRoot}/lib/config.ts`);
+  }
+
+  // Conditionally remove websocket files
+  if (!options.websockets) {
+    tree.delete(`${projectRoot}/app/api/config`);
+  }
+
+  promoteEngineerSkill(tree, 'groundwork-nextjs-engineer');
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'nextjs-app', options as unknown as Record<string, unknown>);
+
+  return () => {
+    const { execSync } = require('child_process');
+    try {
+      execSync('pnpm install', { cwd: projectRoot, stdio: 'inherit' });
+    } catch (e) {
+      console.warn(`Failed to run pnpm install in ${projectRoot}. Run it manually.`);
+    }
+  };
+}

package/src/generators/nextjs-app/schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "nextjs-app",
+  "title": "Next.js App",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the Next.js application",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the app?"
+    },
+    "auth": {
+      "type": "string",
+      "enum": ["none", "clerk"],
+      "default": "none",
+      "description": "Authentication provider to include",
+      "x-prompt": {
+        "message": "Which authentication provider should we include?",
+        "type": "list",
+        "items": [
+          { "value": "none", "label": "None" },
+          { "value": "clerk", "label": "Clerk (User Auth + Middleware)" }
+        ]
+      }
+    },
+    "apiProxy": {
+      "type": "boolean",
+      "description": "Include a server-side reverse proxy to a backend API service",
+      "default": false,
+      "x-prompt": "Do you want to include an API reverse proxy to a backend service?"
+    },
+    "websockets": {
+      "type": "boolean",
+      "description": "Include a WebSocket provider with runtime config discovery",
+      "default": false,
+      "x-prompt": "Do you want to enable WebSocket support?"
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/python-microservice/docs/principles/stack/python/async.md

@@ -0,0 +1,168 @@
+---
+title: Async Patterns
+description: Structured concurrency, FastAPI async, background tasks, and the application lifecycle for Python microservices.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# Async Patterns
+
+## TL;DR
+
+A Python microservice built on FastAPI is async-first. Every route handler, service method, and provider call is `async def`. The event loop must never block. CPU-bound and blocking operations run off the event loop via `asyncio.to_thread`. Concurrent work uses `asyncio.TaskGroup` — never bare `create_task`.
+
+---
+
+## Why Async
+
+An async-first service design is suited to these characteristics:
+
+1. **Streaming connections** — WebSocket connections remain open for the duration of a session. A synchronous server blocks the entire process on each open connection.
+2. **Concurrent inference** — Multiple independent operations run in parallel. Async makes this composition natural and explicit.
+3. **Pub/Sub consumption** — Background message processing runs alongside live HTTP traffic without requiring threads.
+
+A synchronous model can handle all of this, but requires explicit thread management, shared state coordination, and careful GIL reasoning. Async eliminates that complexity at one cost: the event loop must never block.
+
+---
+
+## The One Rule: Never Block the Event Loop
+
+Any synchronous call longer than a few milliseconds inside an `async def` function stalls every other coroutine in the process. The symptoms look like random, unrelated timeouts across the service.
+
+Blocking calls — file I/O, model loading, `time.sleep`, synchronous SDK methods — must run in a thread:
+
+```python
+import asyncio
+
+result = await asyncio.to_thread(load_and_run_model, audio_path)
+```
+
+`asyncio.to_thread` runs the callable in the default thread pool executor and returns a coroutine. The event loop stays responsive while the blocking work executes.
+
+If you are unsure whether a call blocks, check for it in OpenTelemetry traces. A span that is unexpectedly long without any child spans is a sign the event loop was blocked inside it.
+
+---
+
+## Structured Concurrency with TaskGroup
+
+When multiple coroutines should run concurrently, use `asyncio.TaskGroup`. It is the only primitive that guarantees all tasks complete — or are cancelled — before control returns to the caller.
+
+```python
+async def process_meeting(meeting_id: str) -> MeetingResult:
+    async with asyncio.TaskGroup() as tg:
+        transcription_task = tg.create_task(transcribe(meeting_id))
+        speaker_task = tg.create_task(identify_speakers(meeting_id))
+
+    return MeetingResult(
+        transcript=transcription_task.result(),
+        speakers=speaker_task.result(),
+    )
+```
+
+If either task raises, `TaskGroup` cancels the sibling and re-raises the exception — no orphaned tasks, no leaked resources, no silent failures.
+
+**Never use bare `asyncio.create_task` for fire-and-forget work.** The event loop holds only a weak reference to tasks created this way. If the calling coroutine exits before the task completes, it is garbage collected mid-execution. This is a source of silent data loss that is extremely difficult to reproduce.
+
+```python
+# Wrong — task may be silently dropped
+asyncio.create_task(publish_event(event))
+
+# Correct — task lifetime is bound to the TaskGroup scope
+async with asyncio.TaskGroup() as tg:
+    tg.create_task(publish_event(event))
+```
+
+---
+
+## Route Handlers
+
+All route handlers are `async def`. FastAPI runs them directly in the event loop. Synchronous `def` handlers are threaded by FastAPI's default executor — this makes the async/sync boundary invisible and is a source of subtle performance issues.
+
+```python
+from fastapi import APIRouter
+
+router = APIRouter()
+
+@router.post("/transcribe")
+async def transcribe_endpoint(request: TranscribeRequest) -> TranscribeResponse:
+    result = await transcription_service.transcribe(request.audio_url)
+    return TranscribeResponse.from_domain(result)
+```
+
+---
+
+## Background Tasks
+
+For work that should happen after a response is returned — publishing a Pub/Sub event, triggering downstream processing — use FastAPI's `BackgroundTasks`:
+
+```python
+from fastapi import BackgroundTasks
+
+@router.post("/transcribe")
+async def transcribe_endpoint(
+    request: TranscribeRequest,
+    background_tasks: BackgroundTasks,
+) -> TranscribeResponse:
+    result = await transcription_service.transcribe(request.audio_url)
+    background_tasks.add_task(publish_completed_event, result.id)
+    return TranscribeResponse.from_domain(result)
+```
+
+FastAPI runs background tasks after the response is sent but before the connection closes. They are bound to the request lifecycle and will complete before the server exits during graceful shutdown.
+
+---
+
+## Application Lifespan
+
+Initialise shared resources — database connection pools, model clients, Pub/Sub subscriptions — in the FastAPI `lifespan` context manager. This ensures resources are available before the first request and are released cleanly on shutdown.
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    db_pool = await create_db_pool()
+    pubsub_client = await create_pubsub_client()
+
+    app.state.db = db_pool
+    app.state.pubsub = pubsub_client
+
+    yield
+
+    await db_pool.close()
+    await pubsub_client.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Never initialise database pools or SDK clients at module level. Module-level initialisation runs at import time, before environment variables are loaded, and cannot be awaited.
+
+---
+
+## Toolchain
+
+`uv` manages all Python tooling — dependencies, virtual environments, and script execution:
+
+```bash
+uv run pytest          # Run tests
+uv add httpx           # Add a dependency
+uv sync                # Sync from lockfile
+uv run python -m your_service  # Run the service
+```
+
+The lockfile (`uv.lock`) is committed. Every developer and CI run resolves identical dependency trees. There is no `pip`, `poetry`, or `pipenv` in this service.
+
+---
+
+## Anti-Patterns
+
+**Blocking the event loop.** Any synchronous call over ~1ms inside `async def` degrades the entire service. Use `asyncio.to_thread` for blocking operations.
+
+**Bare `asyncio.create_task`.** Creates an untracked task that can be silently dropped. Use `TaskGroup`.
+
+**Synchronous `def` route handlers.** FastAPI threads them silently. Write `async def` so the boundary is explicit.
+
+**Module-level async initialisation.** Calling `asyncio.run()` at import time or using `asyncio.get_event_loop()` creates a new event loop that conflicts with FastAPI's loop. Initialise in `lifespan`.
+
+**`asyncio.sleep` as a retry delay.** Sleeping inline blocks the coroutine's task slot. Use `tenacity` with async backoff (see [Resilience](resilience.md)).