groundwork-method 0.0.1 → 0.11.0

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'));
+  });
+<% } %>});

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

@@ -0,0 +1,31 @@
+import type { Renderer } from './theme/render';
+import { hello } from './commands/hello';
+<% if (core) { %>import { status } from './commands/status';
+<% } %><% if (repl) { %>import { repl } from './commands/repl';
+<% } %>
+export interface Ctx {
+  r: Renderer;
+  json: boolean;
+  args: string[];
+}
+
+export type CommandGroup = 'CORE' | 'META';
+
+export interface CommandDef {
+  name: string;
+  group: CommandGroup;
+  summary: string;
+  handler: (ctx: Ctx) => Promise<number>;
+}
+
+/** The command registry — the single source of truth for dispatch and help. Add a row
+ *  here and the command is wired into both. */
+export const COMMANDS: CommandDef[] = [
+  { name: 'hello', group: 'CORE', summary: 'Print a themed greeting (supports --json)', handler: hello },
+<% if (core) { %>  { name: 'status', group: 'CORE', summary: 'Probe the workspace core (exit 0 reachable, 1 not)', handler: status },
+<% } %><% if (repl) { %>  { name: 'repl', group: 'CORE', summary: 'Start an interactive session', handler: repl },
+<% } %>];
+
+export function findCommand(name: string): CommandDef | undefined {
+  return COMMANDS.find((c) => c.name === name);
+}

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

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2021"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

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

@@ -0,0 +1,11 @@
+{
+  "//": "Test build: compiles src/ (including *.test.ts) to CommonJS in dist-test/ so node --test runs it directly. The shipped bundle still comes from build.mjs.",
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "rootDir": "src",
+    "outDir": "dist-test",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}

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

@@ -0,0 +1,138 @@
+import { formatFiles, generateFiles, Tree } from '@nx/devkit';
+import * as path from 'path';
+import * as fs from 'fs';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import { registerRunner } from '../shared/scaffold-helpers';
+
+export interface CliAppGeneratorSchema {
+  name: string;
+  repl?: boolean;
+  /** Wire the CLI to the workspace core (core-access seam + `status` wiring
+   *  proof). Omit for a standalone tool that fronts no services. */
+  core?: boolean;
+}
+
+const BRAND_TOKENS_PATH = '.groundwork/config/brand-tokens.json';
+
+/** The shared CLI render layer lives with the ./dev CLI source and is the single
+ *  source of truth. The product gets an owned copy so it can evolve independently. */
+const THEME_SRC = path.join(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'src',
+  'generators',
+  'workspace-dev-cli',
+  'cli-src',
+  'src',
+);
+
+function kebab(s: string): string {
+  return s
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** Project the design system's brand tokens (identity + terminal) for the product, or
+ *  a minimal Tier-1 identity derived from the name when no tokens exist. */
+function buildBrand(tree: Tree, name: string): Record<string, unknown> {
+  if (tree.exists(BRAND_TOKENS_PATH)) {
+    try {
+      const raw = JSON.parse(tree.read(BRAND_TOKENS_PATH, 'utf-8') || '{}');
+      return { identity: raw.identity, terminal: raw.terminal };
+    } catch {
+      /* malformed — fall through */
+    }
+  }
+  return {
+    identity: { appName: name, wordmark: '◢◤', primary: '#5fafff', accent: '#d7afff', voice: 'clear, modern' },
+  };
+}
+
+function copyShared(tree: Tree, fromRel: string, toRel: string): void {
+  const content = fs.readFileSync(path.join(THEME_SRC, fromRel), 'utf-8');
+  tree.write(toRel, content);
+}
+
+export default async function (tree: Tree, options: CliAppGeneratorSchema) {
+  const name = options.name;
+  const binName = kebab(name) || 'cli';
+  const repl = Boolean(options.repl);
+  const core = Boolean(options.core);
+  const projectRoot = path.join('services', binName);
+
+  const filesDir = path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'cli-app', 'files');
+  generateFiles(tree, filesDir, projectRoot, {
+    name,
+    binName,
+    repl,
+    core,
+    tmpl: '',
+  });
+
+  // Standalone mode: the CLI is the whole product and fronts no services, so
+  // it carries no core-access seam. Core mode (--core) keeps these files —
+  // the same seam shape electron-app (src/main/core-client.ts) and
+  // flutter-app (lib/data/services/api_client.dart) ship unconditionally;
+  // here it is opt-in because a standalone CLI genuinely has no core.
+  if (!core) {
+    tree.delete(path.join(projectRoot, 'src/core/client.ts'));
+    tree.delete(path.join(projectRoot, 'src/core/client.test.ts'));
+    tree.delete(path.join(projectRoot, 'src/commands/status.ts'));
+  }
+
+  // Copy the shared render layer as owned product source.
+  copyShared(tree, 'theme/tokens.ts', path.join(projectRoot, 'src/theme/tokens.ts'));
+  copyShared(tree, 'theme/color.ts', path.join(projectRoot, 'src/theme/color.ts'));
+  copyShared(tree, 'theme/render.ts', path.join(projectRoot, 'src/theme/render.ts'));
+
+  // Project brand tokens into the product (baked into the build via import).
+  tree.write(path.join(projectRoot, 'src/brand.json'), JSON.stringify(buildBrand(tree, name), null, 2) + '\n');
+
+  // Interactive layer: reuse the same prompt utilities the ./dev wizard uses.
+  if (repl) {
+    copyShared(tree, 'util/prompt.ts', path.join(projectRoot, 'src/util/prompt.ts'));
+    tree.write(
+      path.join(projectRoot, 'src/commands/repl.ts'),
+      `import type { Ctx } from '../registry';
+import { isInteractive, textPrompt } from '../util/prompt';
+
+/** A minimal interactive session on top of the composable spine. Extend it into a
+ *  full REPL — slash commands, streaming, autocomplete — per your design system. */
+export async function repl(ctx: Ctx): Promise<number> {
+  if (!isInteractive()) {
+    ctx.r.error('repl requires an interactive terminal.');
+    return 2;
+  }
+  ctx.r.logo('interactive session');
+  ctx.r.info("Type a name to greet, or 'exit' to quit.");
+  for (;;) {
+    const line = await textPrompt(ctx.r.painter, '>');
+    if (line === 'exit' || line === 'quit') break;
+    if (line) ctx.r.success(\`Hello, \${line}!\`);
+  }
+  return 0;
+}
+`,
+    );
+  }
+
+  // A CLI is invoked ad hoc, not a long-running service — register it as a
+  // runner so `./dev status` reports it and `./dev` knows how to run it, but
+  // autostart is false so it is never launched by `./dev start`.
+  registerRunner(tree, {
+    name: binName,
+    kind: 'surface',
+    cmd: 'npm run dev',
+    cwd: projectRoot,
+    autostart: false,
+  });
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'cli-app', options as unknown as Record<string, unknown>);
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "CliApp",
+  "title": "CLI App",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The CLI product name (used for the binary, package name, and branding fallback).",
+      "x-prompt": "What is the CLI called?"
+    },
+    "repl": {
+      "type": "boolean",
+      "description": "Scaffold the interactive REPL layer on top of the composable spine.",
+      "default": false
+    },
+    "core": {
+      "type": "boolean",
+      "description": "Wire the CLI to the workspace core: scaffolds the core-access seam (src/core/client.ts, API_BASE_URL-configurable, Bearer auth seam) and a `status` wiring-proof command. Omit for a standalone tool that fronts no services.",
+      "default": false
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/docs-site/files/.gitignore.ejs

@@ -0,0 +1,40 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# fumadocs generated source map (regenerated by `fumadocs-mdx` / next build)
+/.source/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/src/generators/docs-site/files/app/docs/__slug__/page.tsx

@@ -0,0 +1,101 @@
+import { source } from '@/app/source';
+import { DocsPage, DocsBody, DocsDescription, DocsTitle } from 'fumadocs-ui/page';
+import { notFound } from 'next/navigation';
+import Link from 'next/link';
+import type { ComponentProps, FC } from 'react';
+import { Mermaid } from '@/components/mermaid';
+
+// MDX components injected into every rendered doc. `Mermaid` resolves the
+// `<Mermaid chart="…" />` nodes the remark transform (source.config.ts) emits for fenced
+// ```mermaid blocks.
+const mdxComponents = { Mermaid };
+
+// The custom title-from-H1 schema (source.config.ts) is a transform, which stops
+// createMDXSource from threading the full page-data type through — the inferred
+// type degrades to the base PageData (title only). The other fields (description,
+// full, and the compiled-MDX runtime fields body + toc) are present at runtime;
+// this view restores their types. toc's type is borrowed from DocsPage's own prop.
+type DocData = {
+  title: string;
+  description?: string;
+  full?: boolean;
+  body: FC;
+  toc: ComponentProps<typeof DocsPage>['toc'];
+};
+
+// The pristine root docs/ tree ships without an index.md (source.config.ts reads
+// it untouched), so the `/docs` root — the empty slug — has no backing page. The
+// home route redirects here, so 404ing it would make the whole site look broken
+// on first load. Instead, render a generated overview that links into every
+// section, derived live from the page list and grouped by the first folder
+// segment under /docs (top-level docs fall under "Overview").
+function DocsIndex() {
+  const groups = new Map<string, { title: string; url: string }[]>();
+  for (const page of source.getPages()) {
+    const segments = page.url.replace(/^\/docs\/?/, '').split('/');
+    const section = segments.length > 1 ? segments[0] : 'Overview';
+    const list = groups.get(section) ?? [];
+    list.push({ title: page.data.title, url: page.url });
+    groups.set(section, list);
+  }
+
+  return (
+    <DocsPage>
+      <DocsTitle><%= navTitle %></DocsTitle>
+      <DocsDescription>Project documentation, organized by section.</DocsDescription>
+      <DocsBody>
+        {[...groups.entries()].map(([section, pages]) => (
+          <section key={section}>
+            <h2 style={{ textTransform: 'capitalize' }}>{section.replace(/-/g, ' ')}</h2>
+            <ul>
+              {pages.map((p) => (
+                <li key={p.url}>
+                  <Link href={p.url}>{p.title}</Link>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export default async function Page(props: { params: Promise<{ slug?: string[] }> }) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) {
+    // Empty slug is the `/docs` root — render the generated overview, not a 404.
+    if (!params.slug || params.slug.length === 0) return <DocsIndex />;
+    notFound();
+  }
+
+  const data = page.data as typeof page.data & DocData;
+  const MDX = data.body;
+
+  return (
+    <DocsPage toc={data.toc} full={data.full}>
+      <DocsTitle>{data.title}</DocsTitle>
+      <DocsDescription>{data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={mdxComponents} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: { params: Promise<{ slug?: string[] }> }) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) return {};
+
+  const data = page.data as typeof page.data & DocData;
+  return {
+    title: data.title,
+    description: data.description,
+  };
+}

package/src/generators/docs-site/files/app/docs/layout.tsx

@@ -0,0 +1,14 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { ReactNode } from 'react';
+import { source } from '@/app/source';
+
+// Sidebar order is declarative now: docs/meta.json seeds the canonical top-level
+// ordering and sinks the principles tree to the bottom (collapsed), so the old
+// imperative betsFirst() sort is gone. Order is owned by the content tree, not code.
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} nav={{ title: '<%= navTitle %>' }}>
+      {children}
+    </DocsLayout>
+  );
+}

package/src/generators/docs-site/files/app/docs.css

@@ -0,0 +1,43 @@
+/* GENERATED by the GroundWork docs-site generator.
+ * Typography discipline for the docs prose (F2): a bounded reading measure, a
+ * comfortable line-height, and an explicit h1-h4 scale — the readability layer
+ * the stock Fumadocs starter leaves at defaults. Imported by app/layout.tsx
+ * only for branded sites; the unbranded fallback keeps the stock appearance.
+ *
+ * Scoped to the rendered doc body (`.prose`, Fumadocs' content container) so it
+ * shapes reference prose without touching the nav, sidebar, or landing chrome. */
+
+.prose {
+  /* ~68ch measure keeps long lines readable; the stock starter runs full-width. */
+  max-width: 68ch;
+  line-height: 1.6;
+}
+
+/* Full-bleed pages (`full: true` frontmatter) opt out of the measure cap. */
+.prose:where(.full) {
+  max-width: none;
+}
+
+/* Explicit type scale: a clear hierarchy from h1 to h4, with tightened
+ * line-height and tracking on headings so they read as structure, not body. */
+.prose h1 {
+  font-size: 2.25rem;
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+}
+
+.prose h2 {
+  font-size: 1.5rem;
+  line-height: 1.25;
+  letter-spacing: -0.01em;
+}
+
+.prose h3 {
+  font-size: 1.25rem;
+  line-height: 1.3;
+}
+
+.prose h4 {
+  font-size: 1.05rem;
+  line-height: 1.4;
+}

package/src/generators/docs-site/files/app/layout.tsx

@@ -0,0 +1,24 @@
+import { RootProvider } from 'fumadocs-ui/provider';
+import 'fumadocs-ui/style.css';
+<% if (branded) { %>import './brand.css';
+import './docs.css';
+<% } %><% if (bodyFont) { %>import { <%= bodyFont.replace(/[^A-Za-z0-9]/g, '_') %> } from 'next/font/google';
+<% } else { %>import { Inter } from 'next/font/google';
+<% } %>import type { ReactNode } from 'react';
+
+<% if (bodyFont) { %>const brandFont = <%= bodyFont.replace(/[^A-Za-z0-9]/g, '_') %>({
+  subsets: ['latin'],
+});
+<% } else { %>const inter = Inter({
+  subsets: ['latin'],
+});
+<% } %>
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className={<% if (bodyFont) { %>brandFont.className<% } else { %>inter.className<% } %>} suppressHydrationWarning>
+      <body className="flex flex-col min-h-screen">
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}