groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,102 @@
+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 a self-hosted, OpenAI-compatible endpoint (Ollama,
+// vLLM, llama.cpp, LM Studio) over HTTP. Minimal net/http adapter, no SDK
+// dependency. Reads LLM_BASE_URL (the server you run) / LLM_MODEL / LLM_API_KEY
+// from env; local servers usually ignore the key.
+type Client struct {
+	apiKey  string
+	baseURL string
+	model   string
+	http    *http.Client
+}
+
+func NewClient() *Client {
+	base := os.Getenv("LLM_BASE_URL")
+	if base == "" {
+		base = "http://localhost:11434/v1"
+	}
+	model := os.Getenv("LLM_MODEL")
+	if model == "" {
+		model = "llama3.1"
+	}
+	apiKey := os.Getenv("LLM_API_KEY")
+	if apiKey == "" {
+		apiKey = "not-needed"
+	}
+	return &Client{
+		apiKey:  apiKey,
+		baseURL: base,
+		model:   model,
+		http:    &http.Client{Timeout: 120 * 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 (is the local model server up at %s?): %w", a.baseURL, 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 endpoint error (status %d): %s", resp.StatusCode, body)
+			continue
+		}
+		if resp.StatusCode >= 400 {
+			return "", fmt.Errorf("llm: endpoint 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 local endpoint")
+		}
+		return parsed.Choices[0].Message.Content, nil
+	}
+	return "", fmt.Errorf("llm: exhausted retries: %w", lastErr)
+}

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

@@ -0,0 +1,53 @@
+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"Local LLM endpoint is unavailable. Is the model server running at LLM_BASE_URL?")
+
+class LLMClient:
+    """OpenAI-compatible adapter for a self-hosted endpoint (Ollama, vLLM,
+    llama.cpp, LM Studio). Talks to settings.llm_base_url; the API key is usually
+    irrelevant for local servers, so it defaults to a placeholder."""
+
+    def __init__(self):
+        self.client = openai.AsyncOpenAI(
+            api_key=settings.llm_api_key or "not-needed",
+            base_url=settings.llm_base_url,
+        )
+        self.model = settings.llm_model
+
+    @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
+            )
+
+            content = response.choices[0].message.content
+            if not content:
+                raise PermanentInferenceError("Received empty response from local LLM endpoint")
+
+            return content
+
+        except openai.APIConnectionError as e:
+            raise TransientInferenceError(f"Connection error (is the local model server up?): {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"Local endpoint server error: {e}")
+            raise PermanentInferenceError(f"Local endpoint request error: {e}")

package/src/generators/capabilities/llm/providers/openai/footprint.json

@@ -0,0 +1,13 @@
+{
+  "kind": "env",
+  "summary": "OpenAI (or any OpenAI-compatible endpoint) over HTTPS. API key in env; no infrastructure.",
+  "env": [
+    { "name": "LLM_API_KEY", "required": true, "default": "" },
+    { "name": "LLM_BASE_URL", "required": false, "default": "" },
+    { "name": "LLM_MODEL", "required": false, "default": "gpt-4o" }
+  ],
+  "stacks": {
+    "python": { "dependencies": ["openai>=1.14.0"] },
+    "go": { "dependencies": [] }
+  }
+}

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;
+}