groundwork-method 0.0.1 → 0.11.0

package/src/generators/go-microservice/generator.ts

@@ -0,0 +1,240 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import { execSync } from 'child_process';
+import {
+  promoteEngineerSkill,
+  deployStackDocs,
+  ensureOptionalInfra,
+  readProjectPrefix,
+} from '../shared/scaffold-helpers';
+
+export interface GoMicroserviceGeneratorSchema {
+  name: string;
+  messaging: 'none' | 'kafka' | 'gcp-pubsub';
+  auth: 'none' | 'service' | 'clerk';
+  websockets: boolean;
+}
+
+export default async function (tree: Tree, options: GoMicroserviceGeneratorSchema) {
+  // Derive naming variants
+  const serviceNames = names(options.name);
+  // Using the workspace root, or you might want to place it in `services/`
+  // We'll scaffold it in `services/${serviceNames.fileName}` by default.
+  const projectRoot = `services/${serviceNames.fileName}`;
+
+  // Calculate assignedPort based on docker-compose.yml (if it exists)
+  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);
+    }
+  }
+
+  // Read EJS templates
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    assignedPort,
+    tmpl: '' // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'go-microservice', 'files'),
+    projectRoot,
+    templateOptions
+  );
+
+  deployStackDocs(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'go-microservice', 'docs'));
+
+  // Auto-inject into docker-compose.yml if it exists
+  if (composeDoc) {
+    try {
+      const yaml = require('yaml');
+      if (!composeDoc.get('services')) {
+        // createNode so the result is a YAMLMap with .has/.set — a plain {} is
+        // not, and the base compose no longer ships a services: block.
+        composeDoc.set('services', composeDoc.createNode({}));
+      }
+      const servicesMap = composeDoc.get('services');
+
+      if (!servicesMap.has(serviceNames.fileName)) {
+        // Only wire the infrastructure this service actually uses. Redis backs
+        // the WebSocket hub; the Pub/Sub emulator backs GCP Pub/Sub messaging.
+        // A service using neither should declare neither.
+        const usesRedis = options.websockets;
+        const usesPubSub = options.messaging === 'gcp-pubsub';
+
+        const environment: string[] = [
+          `SERVER_PORT=${assignedPort}`,
+          `DATABASE_URL=postgres://\${DB_USER:-postgres}:\${DB_PASSWORD:-postgres}@db:5432/\${DB_NAME:-${serviceNames.fileName}}?sslmode=disable`,
+          'DB_HOST=db',
+          'DB_PORT=5432',
+          'DB_USER=${DB_USER:-postgres}',
+          'DB_PASSWORD=${DB_PASSWORD:-postgres}',
+          `DB_NAME=\${DB_NAME:-${serviceNames.fileName}}`
+        ];
+        if (usesRedis) {
+          environment.push('REDIS_URL=redis:6379');
+        }
+        if (usesPubSub) {
+          environment.push('PUBSUB_EMULATOR_HOST=pubsub:${PUBSUB_PORT:-8085}');
+        }
+        environment.push(
+          'OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317',
+          'OTEL_EXPORTER_OTLP_PROTOCOL=grpc'
+        );
+
+        const dependsOn: Record<string, { condition: string }> = {
+          db: { condition: 'service_healthy' }
+        };
+        if (usesRedis) {
+          dependsOn.redis = { condition: 'service_healthy' };
+        }
+
+        const newService: Record<string, unknown> = {
+          build: {
+            context: `./${projectRoot}`,
+            dockerfile: 'Dockerfile.dev'
+          },
+          container_name: serviceNames.fileName,
+          restart: 'unless-stopped',
+          ports: [
+            `${assignedPort}:${assignedPort}`
+          ],
+          environment,
+          // The golang:alpine runtime image has no curl, but ships busybox
+          // wget, which probes the health endpoint without an extra binary.
+          healthcheck: {
+            test: [
+              'CMD',
+              'wget',
+              '-q',
+              '--spider',
+              `http://localhost:${assignedPort}/health`
+            ],
+            interval: '10s',
+            timeout: '5s',
+            retries: 5,
+            start_period: '20s'
+          },
+          depends_on: dependsOn,
+          networks: [
+            'groundwork-net'
+          ]
+        };
+
+        servicesMap.set(serviceNames.fileName, newService);
+        // A Go microservice always uses a per-service database and exports
+        // telemetry, so it provisions db + jaeger on demand (they are no longer
+        // in the base compose).
+        ensureOptionalInfra(composeDoc, servicesMap, {
+          usesRedis,
+          usesPubSub,
+          usesDb: true,
+          usesTelemetry: true,
+          projectPrefix: readProjectPrefix(tree),
+        });
+        tree.write('docker-compose.yml', composeDoc.toString());
+      }
+    } catch (e) {
+      console.warn('Failed to update docker-compose.yml:', e);
+    }
+  }
+
+  if (!options.websockets) {
+    tree.delete(`${projectRoot}/internal/websocket`);
+    tree.delete(`${projectRoot}/internal/entrypoints/api/websocket_handler.go`);
+    tree.delete(`${projectRoot}/asyncapi-ws.yaml`);
+  }
+
+  if (options.messaging === 'none') {
+    tree.delete(`${projectRoot}/asyncapi-pubsub.yaml`);
+    tree.delete(`${projectRoot}/internal/core/service/message_queue.go`);
+    tree.delete(`${projectRoot}/internal/core/service/outbox_repository.go`);
+  }
+
+  if (options.messaging !== 'kafka') {
+    tree.delete(`${projectRoot}/internal/kafka/kafka.go`);
+  }
+
+  if (options.messaging !== 'gcp-pubsub') {
+    tree.delete(`${projectRoot}/internal/pubsub/gcp_pubsub.go`);
+  }
+
+  if (options.auth !== 'clerk') {
+    tree.delete(`${projectRoot}/internal/entrypoints/api/middleware_auth.go`);
+    tree.delete(`${projectRoot}/internal/entrypoints/api/auth_middleware_test.go`);
+    tree.delete(`${projectRoot}/internal/entrypoints/api/clerk_webhook.go`);
+    tree.delete(`${projectRoot}/internal/entrypoints/api/clerk_webhook_test.go`);
+    tree.delete(`${projectRoot}/internal/core/domain/user.go`);
+    tree.delete(`${projectRoot}/internal/core/service/user_repository.go`);
+    tree.delete(`${projectRoot}/internal/core/service/user_service.go`);
+    tree.delete(`${projectRoot}/internal/postgres/user_repository.go`);
+  }
+
+  promoteEngineerSkill(tree, 'groundwork-go-engineer');
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'go-microservice', options as unknown as Record<string, unknown>);
+
+  return () => {
+    try {
+      execSync('go mod tidy', { cwd: projectRoot, stdio: 'inherit' });
+    } catch (e) {
+      console.warn(`Failed to run go mod tidy in ${projectRoot}:`, e);
+    }
+  };
+}

package/src/generators/go-microservice/schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "go-microservice",
+  "title": "Go Microservice",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the microservice",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the service?"
+    },
+    "messaging": {
+      "type": "string",
+      "enum": ["none", "kafka", "gcp-pubsub"],
+      "default": "none",
+      "description": "Include the Transactional Outbox pattern and message broker configuration",
+      "x-prompt": {
+        "message": "Which message broker do you want to use for the outbox pattern?",
+        "type": "list",
+        "items": [
+          { "value": "none", "label": "None" },
+          { "value": "kafka", "label": "Kafka" },
+          { "value": "gcp-pubsub", "label": "Google Cloud Pub/Sub" }
+        ]
+      }
+    },
+    "auth": {
+      "type": "string",
+      "enum": ["none", "service", "clerk"],
+      "default": "none",
+      "description": "The level of authentication boilerplate to include",
+      "x-prompt": {
+        "message": "Which authentication boilerplate should we include?",
+        "type": "list",
+        "items": [
+          {
+            "value": "none",
+            "label": "None"
+          },
+          {
+            "value": "service",
+            "label": "Service-to-Service Auth Only"
+          },
+          {
+            "value": "clerk",
+            "label": "Full Clerk User & Service Auth"
+          }
+        ]
+      }
+    },
+    "websockets": {
+      "type": "boolean",
+      "description": "Include WebSocket Hub, Session Manager, and AsyncAPI v3 generation",
+      "default": false,
+      "x-prompt": "Do you want to enable WebSockets?"
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/nextjs-app/docs/principles/stack/typescript/frontend.md

@@ -0,0 +1,65 @@
+---
+title: Frontend
+description: React 19, Server Components, SWR, Tailwind, and the design language of a Next.js application.
+status: active
+last_reviewed: 2026-05-26
+---
+# Frontend
+
+## TL;DR
+
+The frontend is Next.js 16 with React 19 Server Components, SWR for client-side data, and Tailwind for styling. We render on the server by default, hydrate the minimum needed for interactivity, and keep data-fetching at the leaves. The design language is consistent, calm, and accessible first.
+
+## Why this matters
+
+Frontend engineering in 2026 is no longer a "client-side" discipline. Most pixels are rendered on the server before they reach the browser, and the browser's job is to stay responsive to the user's input rather than to fetch data on their behalf. Getting this split right — what runs on the server, what runs on the client, what streams in between — is the single biggest determinant of how fast and how reliable the app feels. It is also where most frontend bugs live.
+
+## Our principles
+
+### 1. Server components are the default
+
+Every component starts as a Server Component. We add `"use client"` only when we need state, events, or browser-only APIs. The economic argument is simple: every client component costs download, parse, hydrate, and memory on every user's device. Server components cost none of that. The ratio of server-to-client components is tracked and kept high.
+
+### 2. Data fetches at the leaves, not the root
+
+Data fetching happens in the component that actually renders the data, not in a page-level fetcher that passes everything down through props. This lets Suspense boundaries stream exactly as deep as they need to, and it keeps prop-drilling in check. The exception is when two leaves need the same data — then we fetch once in a common ancestor and share via React's built-in request deduplication.
+
+### 3. SWR for client-interactive state
+
+For state that must respond to user interaction in real time — live views, session state, optimistic updates — we use SWR. One cache, one invalidation story, one mental model. We do not mix query libraries in the same app.
+
+### 4. Styling is Tailwind utilities, composed
+
+We style with Tailwind utility classes. When a composition of utilities gets long or is repeated, we extract a component — not a custom CSS class. Component extraction keeps the `className` strings honest; new CSS classes are where design systems go to die of untracked one-offs.
+
+### 5. The design system is a library, not a guideline
+
+Buttons, inputs, modals, tooltips — every primitive is a typed, reviewed component in the shared component library. Ad-hoc styling of a button in a feature folder is a smell; the fix is to add the variant to the library, not to reimplement it.
+
+### 6. Accessibility is a baseline, not a feature
+
+Every interactive component supports keyboard navigation, is screen-reader labelled, and meets WCAG 2.2 AA contrast at minimum. Accessibility failures block merges the same way type errors do. The golden path for every new UI begins with "can I get to it, use it, and understand it with just the keyboard and a screen reader?"
+
+### 7. Client state is recoverable
+
+We do not store state in React that cannot be rebuilt from the server or the URL. Refreshing the page is the end-to-end test of this: if the user loses context after a refresh, we are holding state we should not. The URL is a first-class state container; so are Server Components.
+
+### 8. Performance budgets are enforced in CI
+
+Largest Contentful Paint, Interaction-to-Next-Paint, JS bundle size — all tracked in CI with budgets. A PR that regresses a budget requires an explicit waiver. Performance is never negotiated after the fact; it is designed in.
+
+## Anti-patterns we reject
+
+- **`useEffect` for data fetching.** `useEffect` is an escape hatch for non-React systems; it is not a data-fetching primitive. Use Server Components or SWR.
+- **Context for everything.** React Context is a tool for genuinely app-wide concerns (theme, auth, locale). Using it to avoid prop-drilling on three levels is overreach.
+- **CSS Modules alongside Tailwind.** One styling system. Not three.
+- **Ad-hoc design primitives.** Every new button variant is a tax on the design system. If it needs a variant, add it to the library.
+- **State that cannot survive refresh.** Modals that disappear on refresh lose user context; counters that reset on refresh are not counters.
+- **"Fix it in a later PR" accessibility.** The later PR will not happen. Ship accessible or ship later.
+
+## Further reading
+
+- *React documentation* ([react.dev](https://react.dev)) — the canonical source for the Server Component mental model.
+- *Patterns.dev*, Lydia Hallie & Addy Osmani — a clean survey of modern frontend patterns.
+- *Inclusive Components*, Heydon Pickering — the pattern language of accessible component design.
+- *Refactoring UI*, Schoger & Wathan — the design vocabulary that informs how we compose Tailwind.

package/src/generators/nextjs-app/files/.dockerignore.template

@@ -0,0 +1,7 @@
+Dockerfile
+.dockerignore
+node_modules
+npm-debug.log
+README.md
+.next
+.git

package/src/generators/nextjs-app/files/.env.example.template

@@ -0,0 +1,24 @@
+# Environment Configuration
+# Copy this file to .env.local and fill in the values
+<% if (apiProxy) { %>
+# Server-side only: URL of the backend API (no trailing slash).
+# Drives the HTTP proxy (/api/proxy) and runtime config (/api/config).
+API_URL=http://localhost:4000
+<% } %>
+<% if (auth === 'clerk') { %>
+# Clerk Auth (REQUIRED — get from https://dashboard.clerk.com → API Keys)
+# Use pk_test_ / sk_test_ keys for local dev
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+CLERK_SECRET_KEY=sk_test_...
+
+# Clerk Routing
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
+NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
+<% } %>
+# OpenTelemetry
+OTEL_SERVICE_NAME=<%= fileName %>
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+# Browser-reachable OTLP HTTP endpoint for client-side spans (NOT the in-container host).
+NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

package/src/generators/nextjs-app/files/.gitignore.template

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env*.local
+.DS_Store
+coverage/

package/src/generators/nextjs-app/files/Dockerfile

@@ -0,0 +1,53 @@
+# ── Base ─────────────────────────────────────────────────────────────────────
+FROM node:22-alpine AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+# ── Dependencies ─────────────────────────────────────────────────────────────
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml ./
+# --trust-lockfile skips re-running pnpm's supply-chain release-age verification
+# against each entry: the lockfile was just produced by this project's own
+# `pnpm install` and is the trusted build input, so the check only blocks the
+# image on transiently too-new deps (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION).
+RUN pnpm install --frozen-lockfile --ignore-scripts --trust-lockfile
+
+# ── Build ────────────────────────────────────────────────────────────────────
+FROM base AS builder
+WORKDIR /app
+<% if (auth === 'clerk') { %>
+ARG NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+ENV NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=$NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+<% } %>
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN pnpm run build
+
+# ── Runtime ──────────────────────────────────────────────────────────────────
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Copy standalone output (requires output: 'standalone' in next.config.mjs)
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE <%= assignedPort %>
+ENV PORT=<%= assignedPort %>
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

package/src/generators/nextjs-app/files/app/(auth)/sign-in/__sign-in__/page.tsx.template

@@ -0,0 +1,9 @@
+import { SignIn } from "@clerk/nextjs";
+
+export default function SignInPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <SignIn />
+    </div>
+  );
+}

package/src/generators/nextjs-app/files/app/(auth)/sign-up/__sign-up__/page.tsx.template

@@ -0,0 +1,9 @@
+import { SignUp } from "@clerk/nextjs";
+
+export default function SignUpPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <SignUp />
+    </div>
+  );
+}

package/src/generators/nextjs-app/files/app/api/config/route.ts.template

@@ -0,0 +1,39 @@
+import { NextResponse } from "next/server";
+
+/**
+ * Exposes runtime configuration to the client.
+ *
+ * This is how the browser discovers the WebSocket URL without any
+ * NEXT_PUBLIC_ build-time variables. The single API_URL env var
+ * drives both the HTTP proxy and this config endpoint.
+ *
+ * API_URL is validated before transforming http(s) → ws(s). A malformed
+ * value fails loud with a 500 rather than emitting a broken WebSocket URL.
+ */
+export function GET() {
+    const apiUrl = process.env.API_URL ?? "http://localhost:4000";
+
+    let parsed: URL;
+    try {
+        parsed = new URL(apiUrl);
+    } catch {
+        return NextResponse.json(
+            { detail: "API_URL is not a valid URL" },
+            { status: 500 }
+        );
+    }
+
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return NextResponse.json(
+            { detail: "API_URL must use http or https" },
+            { status: 500 }
+        );
+    }
+
+    // http → ws, https → wss (anchored to the protocol, not a blind replace).
+    const wsProtocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+    parsed.protocol = wsProtocol;
+    const wsUrl = `${parsed.origin}/ws`;
+
+    return NextResponse.json({ wsUrl });
+}

package/src/generators/nextjs-app/files/app/api/healthz/route.test.ts

@@ -0,0 +1,15 @@
+// @vitest-environment node
+import { describe, it, expect } from "vitest";
+import { GET } from "./route";
+
+describe("GET /api/healthz", () => {
+  it("returns 200 with a healthy status and timestamp", async () => {
+    const res = await GET();
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe("healthy");
+    expect(typeof body.timestamp).toBe("string");
+    // timestamp must be a valid ISO date.
+    expect(Number.isNaN(Date.parse(body.timestamp))).toBe(false);
+  });
+});

package/src/generators/nextjs-app/files/app/api/healthz/route.ts

@@ -0,0 +1,5 @@
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  return NextResponse.json({ status: 'healthy', timestamp: new Date().toISOString() });
+}

package/src/generators/nextjs-app/files/app/api/proxy/__path__/route.test.ts.template

@@ -0,0 +1,55 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { NextRequest } from "next/server";
+import { GET } from "./route";
+
+function makeRequest(path: string): NextRequest {
+  return new NextRequest(new Request(`http://localhost/api/proxy/${path}`));
+}
+
+function makeParams(path: string[]) {
+  return { params: Promise.resolve({ path }) };
+}
+
+describe("api proxy error handling", () => {
+  const realFetch = global.fetch;
+
+  beforeEach(() => {
+    process.env.API_URL = "http://upstream.test";
+  });
+
+  afterEach(() => {
+    global.fetch = realFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("forwards an upstream 502 as a 502", async () => {
+    global.fetch = vi.fn(async () =>
+      new Response("bad gateway", { status: 502, statusText: "Bad Gateway" })
+    ) as unknown as typeof fetch;
+
+    const res = await GET(makeRequest("entities"), makeParams(["entities"]));
+    expect(res.status).toBe(502);
+  });
+
+  it("maps an upstream fetch failure (e.g. timeout/abort) to a 502", async () => {
+    global.fetch = vi.fn(async () => {
+      // Simulate an AbortController timeout / network failure: fetch rejects.
+      throw new DOMException("The operation was aborted.", "AbortError");
+    }) as unknown as typeof fetch;
+
+    const res = await GET(makeRequest("entities"), makeParams(["entities"]));
+    expect(res.status).toBe(502);
+    const body = await res.json();
+    expect(body.detail).toBe("Backend service unavailable");
+  });
+
+  it("passes through a successful upstream status", async () => {
+    global.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), { status: 200 })
+    ) as unknown as typeof fetch;
+
+    const res = await GET(makeRequest("entities"), makeParams(["entities"]));
+    expect(res.status).toBe(200);
+  });
+});