groundwork-method 0.0.1 → 0.10.0

package/src/generators/capabilities/llm/providers/openai/stacks/go/internal/llm/llm.go.template

@@ -0,0 +1,98 @@
+package llm
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"time"
+
+	"<%= moduleName %>/internal/core/service"
+)
+
+// Ensure Client implements the service.TextGenerator interface.
+var _ service.TextGenerator = (*Client)(nil)
+
+// Client calls the OpenAI Chat Completions API (or any
+// OpenAI-compatible endpoint via LLM_BASE_URL) over HTTPS. Minimal net/http
+// adapter (no SDK dependency) — extend or swap for the official SDK behind this
+// same port. Reads LLM_API_KEY / LLM_BASE_URL / LLM_MODEL from env.
+type Client struct {
+	apiKey  string
+	baseURL string
+	model   string
+	http    *http.Client
+}
+
+func NewClient() *Client {
+	base := os.Getenv("LLM_BASE_URL")
+	if base == "" {
+		base = "https://api.openai.com/v1"
+	}
+	model := os.Getenv("LLM_MODEL")
+	if model == "" {
+		model = "gpt-4o"
+	}
+	return &Client{
+		apiKey:  os.Getenv("LLM_API_KEY"),
+		baseURL: base,
+		model:   model,
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+func (a *Client) GenerateText(ctx context.Context, prompt string, maxTokens int) (string, error) {
+	reqBody, err := json.Marshal(map[string]any{
+		"model":      a.model,
+		"max_tokens": maxTokens,
+		"messages":   []map[string]string{{"role": "user", "content": prompt}},
+	})
+	if err != nil {
+		return "", fmt.Errorf("llm: marshal request: %w", err)
+	}
+
+	var lastErr error
+	for attempt := 0; attempt < 3; attempt++ {
+		req, err := http.NewRequestWithContext(ctx, http.MethodPost, a.baseURL+"/chat/completions", bytes.NewReader(reqBody))
+		if err != nil {
+			return "", fmt.Errorf("llm: build request: %w", err)
+		}
+		req.Header.Set("content-type", "application/json")
+		req.Header.Set("authorization", "Bearer "+a.apiKey)
+
+		resp, err := a.http.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("llm: connection error: %w", err)
+			continue // transient — retry
+		}
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		if resp.StatusCode >= 500 || resp.StatusCode == http.StatusTooManyRequests {
+			lastErr = fmt.Errorf("llm: transient provider error (status %d): %s", resp.StatusCode, body)
+			continue
+		}
+		if resp.StatusCode >= 400 {
+			return "", fmt.Errorf("llm: provider request error (status %d): %s", resp.StatusCode, body)
+		}
+
+		var parsed struct {
+			Choices []struct {
+				Message struct {
+					Content string `json:"content"`
+				} `json:"message"`
+			} `json:"choices"`
+		}
+		if err := json.Unmarshal(body, &parsed); err != nil {
+			return "", fmt.Errorf("llm: decode response: %w", err)
+		}
+		if len(parsed.Choices) == 0 || parsed.Choices[0].Message.Content == "" {
+			return "", fmt.Errorf("llm: empty response from provider")
+		}
+		return parsed.Choices[0].Message.Content, nil
+	}
+	return "", fmt.Errorf("llm: exhausted retries: %w", lastErr)
+}

package/src/generators/capabilities/llm/providers/openai/stacks/python/src/__packageName__/adapters/llm.py.template

@@ -0,0 +1,60 @@
+from <%= packageName %>.core.domain.exceptions import TransientInferenceError, PermanentInferenceError, CircuitBreakerOpenError
+from tenacity import retry, wait_exponential_jitter, stop_after_attempt, retry_if_exception_type
+from circuitbreaker import circuit
+from <%= packageName %>.adapters.config import settings
+import openai
+import logging
+
+logger = logging.getLogger(__name__)
+
+def fallback_circuit_breaker(e):
+    logger.error(f"Circuit breaker tripped or open! {e}")
+    raise CircuitBreakerOpenError(f"External LLM API is unavailable. Please try again later.")
+
+class LLMClient:
+    def __init__(self):
+        # Defer building the provider client until the first generate_text call so
+        # the service boots and serves its non-LLM routes even when no API key is
+        # configured — the OpenAI client raises at construction on a missing key,
+        # which would otherwise 500 every route that depends on this service.
+        self._client: openai.AsyncOpenAI | None = None
+        self.model = settings.llm_model
+
+    @property
+    def client(self) -> openai.AsyncOpenAI:
+        if self._client is None:
+            self._client = openai.AsyncOpenAI(
+                api_key=settings.llm_api_key,
+                base_url=settings.llm_base_url,
+            )
+        return self._client
+
+    @circuit(failure_threshold=5, recovery_timeout=30, fallback_function=fallback_circuit_breaker, expected_exception=TransientInferenceError)
+    @retry(
+        wait=wait_exponential_jitter(initial=1, max=30),
+        stop=stop_after_attempt(5),
+        retry=retry_if_exception_type(TransientInferenceError)
+    )
+    async def generate_text(self, prompt: str, max_tokens: int = 100) -> str:
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens
+            )
+
+            # Boundary validation: ensure we got a valid response
+            content = response.choices[0].message.content
+            if not content:
+                raise PermanentInferenceError("Received empty response from LLM provider")
+
+            return content
+
+        except openai.APIConnectionError as e:
+            raise TransientInferenceError(f"Connection error: {e}")
+        except openai.RateLimitError as e:
+            raise TransientInferenceError(f"Rate limited: {e}")
+        except openai.APIStatusError as e:
+            if e.status_code >= 500:
+                raise TransientInferenceError(f"Provider server error: {e}")
+            raise PermanentInferenceError(f"Provider request error: {e}")

package/src/generators/capabilities/llm/stacks/go/internal/core/service/llm.go.template

@@ -0,0 +1,12 @@
+package service
+
+import "context"
+
+// TextGenerator is the interface the core depends on for large-language-model
+// text generation. It is declared here, in the consuming service package, so
+// the dependency arrow points inward: concrete adapters live in internal/llm
+// and are swappable at scaffold time (anthropic | openai | local | none)
+// without touching this interface or its callers.
+type TextGenerator interface {
+	GenerateText(ctx context.Context, prompt string, maxTokens int) (string, error)
+}

package/src/generators/capabilities/llm/stacks/go/internal/llm/llm_test.go.template

@@ -0,0 +1,33 @@
+package llm
+
+import (
+	"context"
+	"testing"
+
+	"<%= moduleName %>/internal/core/service"
+)
+
+// Compile-time conformance: the adapter satisfies the service.TextGenerator
+// interface. If the interface and adapter drift, this test file fails to build —
+// the contract is enforced at compile time, the strongest place to put it.
+var _ service.TextGenerator = (*Client)(nil)
+
+func TestClientConformsToInterface(t *testing.T) {
+	var _ service.TextGenerator = (*Client)(nil)
+}
+<% if (provider === 'none') { %>
+// Bet: the bare adapter has no implementation yet. While the stub returns an
+// error this test Skips, so a freshly scaffolded service stays green. The moment
+// you implement GenerateText it runs for real and asserts the contract — your
+// cue that the bet is delivered and this Skip can come out. The interface is the
+// spec, the adapter is the bet.
+func TestClientGeneratesText(t *testing.T) {
+	out, err := NewClient().GenerateText(context.Background(), "ping", 8)
+	if err != nil {
+		t.Skipf("bet: LLM adapter not implemented yet: %v", err)
+	}
+	if out == "" {
+		t.Fatal("expected non-empty text from the LLM client")
+	}
+}
+<% } %>

package/src/generators/capabilities/llm/stacks/python/src/__packageName__/core/llm.py.template

@@ -0,0 +1,15 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TextGenerator(Protocol):
+    """Port: large-language-model text generation.
+
+    This interface is the stable contract the domain depends on. Concrete
+    adapters live in src/<%= packageName %>/adapters/llm.py and are swappable at scaffold time
+    (anthropic | openai | local | none) without touching this port or its
+    callers — that is the whole point of the ports/adapters boundary.
+    """
+
+    async def generate_text(self, prompt: str, max_tokens: int = 100) -> str:
+        ...

package/src/generators/capabilities/llm/stacks/python/tests/contracts/test_llm.py.template

@@ -0,0 +1,37 @@
+"""Contract test for the LLM capability port.
+
+Generated by the `llm` capability. Asserts the chosen adapter satisfies the
+TextGenerator port so a provider swap can never silently break the boundary.
+"""
+import pytest
+
+from <%= packageName %>.core.llm import TextGenerator
+from <%= packageName %>.adapters.llm import LLMClient
+
+
+def test_adapter_conforms_to_text_generator_port():
+    """Structural conformance: the adapter implements the port's method surface.
+
+    Uses issubclass against the runtime_checkable Protocol so it never has to
+    construct the adapter (no network, no API key, no provider SDK call).
+    """
+    assert issubclass(LLMClient, TextGenerator)
+<% if (provider === 'none') { %>
+
+@pytest.mark.asyncio
+@pytest.mark.xfail(
+    strict=True,
+    reason="bet: implement the LLM adapter, then remove this marker",
+)
+async def test_unimplemented_adapter_generates_text():
+    """RED bet — the bare adapter has no implementation yet.
+
+    Marked xfail(strict) so a freshly scaffolded service stays green while the
+    bet is open. The moment you implement LLMClient.generate_text this test
+    XPASSes and the suite goes red: your cue to remove this marker and own the
+    behavioural contract. This is GroundWork's design-locked-in-tests loop —
+    the port is the spec, the adapter is the bet.
+    """
+    result = await LLMClient().generate_text("ping", max_tokens=8)
+    assert isinstance(result, str) and result
+<% } %>

package/src/generators/cli-app/files/README.md.template

@@ -0,0 +1,76 @@
+# <%= name %>
+
+A command-line tool scaffolded by GroundWork. It is built on the **composable spine**
+every GroundWork CLI shares — structured `--json` output, exit-code discipline, colour
+that degrades to plain text, and a non-TTY fallback so it never blocks in CI or pipes —
+and it is themed from your design system's **brand tokens**, so it looks like a sibling of
+this project's `./dev` control plane.
+
+## Develop
+
+```bash
+npm install
+npm run build      # bundle to dist/cli.js
+npm run typecheck  # tsc --noEmit
+npm test           # node:test — compiles src/ to dist-test/ and runs *.test.ts
+node dist/cli.js --help
+node dist/cli.js hello you
+node dist/cli.js hello you --json
+```
+
+## Structure
+
+```
+src/
+├── cli.ts            # entry: arg parsing, dispatch, --json, exit codes
+├── registry.ts       # the command registry (single source of truth)
+├── registry.test.ts  # keeps the registry honest as commands accrete
+├── brand.json        # brand tokens projected from the design system
+├── theme/            # the shared render layer (colour resolution, output hierarchy)
+│   ├── tokens.ts
+│   ├── color.ts
+│   └── render.ts
+<% if (core) { %>├── core/
+│   ├── client.ts       # the core-access seam — the ONLY place this CLI talks to the workspace gateway
+│   └── client.test.ts  # seam proven without a network (fetch injected)
+<% } %>└── commands/
+    └── hello.ts      # a sample command — replace with your own
+```
+
+`src/brand.json` is projected from `.groundwork/config/brand-tokens.json` at scaffold time.
+Re-run the design system to evolve the brand; update `brand.json` to match.
+
+<% if (core) { %>## Workspace core mode
+
+This CLI fronts the workspace's services. All gateway traffic flows through the
+**core-access seam** (`src/core/client.ts`) — commands consume its typed functions and
+never carry transport detail themselves.
+
+```bash
+node dist/cli.js status            # the wiring proof: probes the core's /health
+node dist/cli.js status --json     # {"baseUrl": ..., "reachable": ..., "status": ...}
+API_BASE_URL=http://staging:4000 node dist/cli.js status
+```
+
+- **Base URL** — defaults to `http://localhost:4000` (the workspace gateway); override
+  with the `API_BASE_URL` environment variable.
+- **Auth** — unauthenticated by default. Wire your identity provider in
+  `coreAuthHeaders` (a service token becomes a `Bearer` header); `/health` stays public.
+- **Exit codes** — `status` exits 0 when the core is reachable, 1 when it is not, so
+  scripts and the system-test harness gate on it without parsing output.
+- **Growing the contract** — add one thin function per promoted-contract operation to
+  `src/core/client.ts`; when the contract outgrows hand-rolled functions, switch to a
+  generated client and keep this module as the seam.
+
+<% } else { %>## Standalone
+
+This CLI was scaffolded **standalone** — it fronts no workspace services and carries no
+core client. If it later grows into a frontend for the workspace's services, re-run the
+generator with `--core=true` (or copy the `src/core/` seam from a core-wired sibling)
+to add the core-access seam and the `status` wiring-proof command.
+
+<% } %>## Add a command
+
+1. Create `src/commands/<name>.ts` exporting `async function <name>(ctx): Promise<number>`.
+2. Register it in `src/registry.ts`.
+3. It gets `--json`, exit-code handling, and themed output for free.

package/src/generators/cli-app/files/build.mjs.template

@@ -0,0 +1,15 @@
+// Bundles the CLI into a single executable at dist/cli.js.
+import { build } from 'esbuild';
+
+await build({
+  entryPoints: ['src/cli.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  format: 'cjs',
+  outfile: 'dist/cli.js',
+  banner: { js: '#!/usr/bin/env node' },
+  loader: { '.json': 'json' },
+  legalComments: 'none',
+  logLevel: 'info',
+});

package/src/generators/cli-app/files/package.json.template

@@ -0,0 +1,21 @@
+{
+  "name": "<%= binName %>",
+  "version": "0.1.0",
+  "private": true,
+  "type": "commonjs",
+  "bin": {
+    "<%= binName %>": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\"",
+    "dev": "node build.mjs && node dist/cli.js",
+    "start": "node dist/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/generators/cli-app/files/src/cli.ts.template

@@ -0,0 +1,67 @@
+/*
+ * <%= name %> — command-line entry point.
+ *
+ * Built on the composable spine every GroundWork CLI shares: structured `--json`
+ * output, exit-code discipline (0/1/2, 130 on interrupt), colour that degrades, and a
+ * non-TTY fallback so the tool never blocks in CI or pipes. The render layer in
+ * src/theme/ is themed from your design system's brand tokens (src/brand.json), so this
+ * CLI and the project's ./dev control plane look like kin.
+ */
+import brand from './brand.json';
+import { COMMANDS, findCommand, CommandGroup } from './registry';
+import { makeRenderer, Renderer } from './theme/render';
+
+function showHelp(r: Renderer): void {
+  r.logo('<%= name %>');
+  const groups: CommandGroup[] = ['CORE', 'META'];
+  for (const g of groups) {
+    const cmds = COMMANDS.filter((c) => c.group === g);
+    if (cmds.length === 0) continue;
+    r.category(g);
+    for (const c of cmds) r.cmd(c.name, c.summary);
+  }
+  process.stderr.write('\n');
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2);
+  let json = false;
+  let help = false;
+  const rest: string[] = [];
+  for (const a of argv) {
+    if (a === '--json') json = true;
+    else if (a === '-h' || a === '--help') help = true;
+    else if (a === '--version' || a === '-V') {
+      process.stdout.write('<%= binName %> 0.1.0\n');
+      return 0;
+    } else rest.push(a);
+  }
+
+  const r = makeRenderer(brand);
+  const command = rest[0];
+  const args = rest.slice(1);
+
+  if (!command || command === 'help' || help) {
+    showHelp(r);
+    return 0;
+  }
+  const def = findCommand(command);
+  if (!def) {
+    r.error(`Unknown command: ${command}`);
+    showHelp(r);
+    return 2;
+  }
+  return def.handler({ r, json, args });
+}
+
+process.on('SIGINT', () => {
+  process.stderr.write('\n\x1b[?25h');
+  process.exit(130);
+});
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    makeRenderer(brand).error(err?.message ?? String(err));
+    process.exit(1);
+  });

package/src/generators/cli-app/files/src/commands/hello.ts.template

@@ -0,0 +1,17 @@
+import type { Ctx } from '../registry';
+
+/** A sample command. It demonstrates the spine: themed human output by default, clean
+ *  JSON on stdout under --json. Replace it with your own commands. */
+export async function hello(ctx: Ctx): Promise<number> {
+  const who = ctx.args[0] ?? 'world';
+
+  if (ctx.json) {
+    process.stdout.write(JSON.stringify({ greeting: `Hello, ${who}!` }) + '\n');
+    return 0;
+  }
+
+  ctx.r.logo();
+  ctx.r.success(`Hello, ${who}!`);
+  ctx.r.info('Edit src/commands/ and register new commands in src/registry.ts.');
+  return 0;
+}

package/src/generators/cli-app/files/src/commands/status.ts.template

@@ -0,0 +1,23 @@
+import type { Ctx } from '../registry';
+import { coreBaseUrl, fetchCoreHealth } from '../core/client';
+
+/** Probe the workspace core this CLI fronts — the surface's wiring proof.
+ *  Exit-code discipline carries the verdict: 0 reachable, 1 unreachable, so
+ *  scripts and the system-test harness gate on it without parsing output. */
+export async function status(ctx: Ctx): Promise<number> {
+  const baseUrl = coreBaseUrl();
+  const health = await fetchCoreHealth(baseUrl);
+
+  if (ctx.json) {
+    process.stdout.write(JSON.stringify({ baseUrl, ...health }) + '\n');
+    return health.reachable ? 0 : 1;
+  }
+
+  if (health.reachable) {
+    ctx.r.success(`Workspace core reachable at ${baseUrl} — status ${health.status}`);
+    return 0;
+  }
+  ctx.r.error(`Workspace core unreachable at ${baseUrl} (${health.status})`);
+  ctx.r.info('Set API_BASE_URL to point at your workspace gateway.');
+  return 1;
+}

package/src/generators/cli-app/files/src/core/client.test.ts.template

@@ -0,0 +1,80 @@
+// The core-access seam is proven without a network: fetch is injected, so
+// every reachability outcome (ok, non-200, thrown) is a deterministic case.
+// Runs on node:test — the CLI's test layer adds no dependencies, like the
+// CLI itself.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  DEFAULT_CORE_BASE_URL,
+  coreAuthHeaders,
+  coreBaseUrl,
+  fetchCoreHealth,
+} from './client';
+
+function fetchReturning(status: number, body: unknown): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    })) as typeof fetch;
+}
+
+describe('coreBaseUrl', () => {
+  it('defaults to the workspace gateway', () => {
+    assert.equal(coreBaseUrl({}), DEFAULT_CORE_BASE_URL);
+  });
+
+  it('honours API_BASE_URL from the environment', () => {
+    assert.equal(coreBaseUrl({ API_BASE_URL: 'http://10.0.0.5:4000' }), 'http://10.0.0.5:4000');
+  });
+
+  it('treats a blank API_BASE_URL as unset', () => {
+    assert.equal(coreBaseUrl({ API_BASE_URL: '  ' }), DEFAULT_CORE_BASE_URL);
+  });
+});
+
+describe('coreAuthHeaders', () => {
+  it('is unauthenticated by default', () => {
+    assert.deepEqual(coreAuthHeaders(), {});
+  });
+
+  it('carries a supplied token as a Bearer header', () => {
+    assert.deepEqual(coreAuthHeaders('jwt-123'), { Authorization: 'Bearer jwt-123' });
+  });
+});
+
+describe('fetchCoreHealth', () => {
+  it('maps a healthy core to reachable + its reported status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(200, { status: 'ok', checks: { db: 'ok' } }),
+    );
+    assert.deepEqual(health, { reachable: true, status: 'ok' });
+  });
+
+  it('requests the /health route of the configured base URL', async () => {
+    let requested: string | undefined;
+    const probe = (async (input: Parameters<typeof fetch>[0]) => {
+      requested = String(input);
+      return new Response('{"status":"ok"}', { status: 200 });
+    }) as typeof fetch;
+    await fetchCoreHealth('http://core.test:4000', probe);
+    assert.equal(requested, 'http://core.test:4000/health');
+  });
+
+  it('maps a non-200 to unreachable with the code as the status', async () => {
+    const health = await fetchCoreHealth(
+      'http://core.test',
+      fetchReturning(503, { error: 'overloaded' }),
+    );
+    assert.deepEqual(health, { reachable: false, status: 'http 503' });
+  });
+
+  it('maps a network failure to a value, never a throw', async () => {
+    const down = (async () => {
+      throw new Error('ECONNREFUSED');
+    }) as typeof fetch;
+    const health = await fetchCoreHealth('http://core.test', down);
+    assert.deepEqual(health, { reachable: false, status: 'unreachable' });
+  });
+});

package/src/generators/cli-app/files/src/core/client.ts.template

@@ -0,0 +1,64 @@
+// The core-access seam: the ONLY place this CLI talks to the workspace
+// gateway. Commands consume these functions and never carry transport
+// detail themselves — the terminal twin of the desktop scaffold's
+// main-process core client and the mobile scaffold's thin dio client.
+//
+// Contract-client stance (O8): hand-rolled and deliberately thin — one
+// function per promoted-contract operation, typed results beside them.
+// When the promoted openapi.yaml grows past a handful of operations, switch
+// to a generated TypeScript client and keep this module as the seam the
+// commands consume — nothing above it changes.
+
+/** The workspace core's health as commands render it. An unreachable core
+ *  is a value, not an exception: a CLI fronting a down service reports it
+ *  through output and exit code, never a stack trace. */
+export type CoreHealth = {
+  reachable: boolean;
+  status: string;
+};
+
+export const DEFAULT_CORE_BASE_URL = 'http://localhost:4000';
+
+/** Where the workspace core lives. The system-test harness (and any
+ *  deployed environment) overrides via the API_BASE_URL environment
+ *  variable. Standalone use never reaches this module — the seam only
+ *  exists when the CLI fronts workspace services. */
+export function coreBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env['API_BASE_URL']?.trim();
+  return configured ? configured : DEFAULT_CORE_BASE_URL;
+}
+
+/** The auth seam: headers attached to every core request. Unauthenticated
+ *  by default — wire your identity provider here (e.g. a service token from
+ *  the environment becomes `Authorization: Bearer <token>`); the core's
+ *  /health route stays public. */
+export function coreAuthHeaders(token?: string): Record<string, string> {
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+/** Probe the gateway's health endpoint — the wiring proof the `status`
+ *  command renders. `/health` is what GroundWork's Go and Python cores
+ *  serve; a Next.js BFF would be `/api/healthz` — adjust to your gateway.
+ *  Failures map to a value, never a throw: an unreachable core is a state
+ *  the command reports (exit 1), not an exception that kills the process. */
+export async function fetchCoreHealth(
+  baseUrl: string = coreBaseUrl(),
+  fetchImpl: typeof fetch = fetch,
+): Promise<CoreHealth> {
+  try {
+    const response = await fetchImpl(new URL('/health', baseUrl), {
+      headers: { Accept: 'application/json', ...coreAuthHeaders() },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (!response.ok) {
+      return { reachable: false, status: `http ${response.status}` };
+    }
+    const body = (await response.json()) as { status?: unknown };
+    return {
+      reachable: true,
+      status: typeof body.status === 'string' ? body.status : 'ok',
+    };
+  } catch {
+    return { reachable: false, status: 'unreachable' };
+  }
+}

package/src/generators/cli-app/files/src/registry.test.ts.template

@@ -0,0 +1,35 @@
+// The registry is the single source of truth for dispatch and help — these
+// tests keep it honest as commands accrete. Runs on node:test (zero deps).
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { COMMANDS, findCommand } from './registry';
+
+describe('command registry', () => {
+  it('registers at least one command', () => {
+    assert.ok(COMMANDS.length > 0);
+  });
+
+  it('has no duplicate command names', () => {
+    const names = COMMANDS.map((c) => c.name);
+    assert.equal(new Set(names).size, names.length);
+  });
+
+  it('gives every command a group and a summary (help renders from these)', () => {
+    for (const c of COMMANDS) {
+      assert.ok(c.summary.length > 0, `command ${c.name} has no summary`);
+      assert.ok(['CORE', 'META'].includes(c.group), `command ${c.name} has an unknown group`);
+    }
+  });
+
+  it('resolves a registered command', () => {
+    assert.ok(findCommand('hello'));
+  });
+
+  it('returns undefined for an unknown command (cli.ts exits 2 on this)', () => {
+    assert.equal(findCommand('no-such-command'), undefined);
+  });
+<% if (core) { %>
+  it('registers the core status probe — the wiring proof to the workspace core', () => {
+    assert.ok(findCommand('status'));
+  });
+<% } %>});