groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,135 @@
+import Link from 'next/link';
+import { source } from '@/app/source';
+
+// A generated, brand-driven landing page (F4): a hero (project name + a one-line
+// tagline) over two audience on-ramps, then section cards derived live from the
+// doc tree. Nothing here is product-specific — the project name, the on-ramp
+// targets, and the sections all come from the workspace and the docs/ folder, so
+// this renders sensibly for any project GroundWork builds. The /docs index (the
+// catch-all route's DocsIndex) remains the fallback link.
+
+const TITLE = '<%= projectName %>';
+const TAGLINE = '<%= tagline %>';
+const WORDMARK = '<%= wordmark %>';
+
+/** Human-friendly label for a top-level docs folder segment. */
+function label(slug: string): string {
+  return slug.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Every page url under /docs, lower-cased once for cheap existence checks. */
+function pageUrls(): Set<string> {
+  return new Set(source.getPages().map((p) => p.url.toLowerCase()));
+}
+
+/** True when any doc exists at exactly `url` or nested beneath it — lets an
+ *  on-ramp target either a leaf doc (product-brief) or a section (getting-started)
+ *  without 404ing on a fresh scaffold where the setup skills have not yet authored
+ *  the doc. */
+function hasRoute(urls: Set<string>, url: string): boolean {
+  const target = url.toLowerCase();
+  for (const u of urls) {
+    if (u === target || u.startsWith(target + '/')) return true;
+  }
+  return false;
+}
+
+/** The two audience on-ramps, in reading order — a fresh-clone developer first,
+ *  a product reader second. Only the ones whose target doc actually exists are
+ *  rendered, so the hero degrades gracefully before setup authors the docs. */
+function onramps(
+  urls: Set<string>,
+): { title: string; blurb: string; url: string }[] {
+  return [
+    {
+      title: 'New here — get it running',
+      blurb: 'Install dependencies, boot the stack, and learn the ./dev workflow.',
+      url: '/docs/getting-started',
+    },
+    {
+      title: 'Understand the product',
+      blurb: 'What the system is, who it serves, and what it does and does not do.',
+      url: '/docs/product-brief',
+    },
+  ].filter((r) => hasRoute(urls, r.url));
+}
+
+/** The top-level sections present under /docs, derived from the page list, plus
+ *  the count of pages each one carries. Top-level docs fall under "Overview". */
+function sections(): { slug: string; title: string; url: string; count: number }[] {
+  const groups = new Map<string, { count: number; firstUrl: string }>();
+  for (const page of source.getPages()) {
+    const segments = page.url.replace(/^\/docs\/?/, '').split('/').filter(Boolean);
+    const section = segments.length > 1 ? segments[0] : 'overview';
+    const g = groups.get(section);
+    if (g) g.count += 1;
+    else groups.set(section, { count: 1, firstUrl: page.url });
+  }
+  return [...groups.entries()].map(([slug, g]) => ({
+    slug,
+    title: slug === 'overview' ? 'Overview' : label(slug),
+    url: slug === 'overview' ? '/docs' : `/docs/${slug}`,
+    count: g.count,
+  }));
+}
+
+export default function HomePage() {
+  const urls = pageUrls();
+  const ramps = onramps(urls);
+  const cards = sections();
+  return (
+    <main className="flex flex-1 flex-col items-center px-4 py-16">
+      <section className="w-full max-w-3xl text-center">
+        {WORDMARK ? (
+          <div
+            aria-hidden
+            className="mb-6 text-4xl font-semibold"
+            style={{ color: 'hsl(var(--fd-primary))' }}
+          >
+            {WORDMARK}
+          </div>
+        ) : null}
+        <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">{TITLE}</h1>
+        <p className="mt-4 text-lg text-fd-muted-foreground">{TAGLINE}</p>
+        <div className="mt-8 flex justify-center gap-3">
+          <Link
+            href="/docs"
+            className="rounded-lg bg-fd-primary px-5 py-2.5 text-sm font-medium text-fd-primary-foreground transition-opacity hover:opacity-90"
+          >
+            Browse the docs
+          </Link>
+        </div>
+      </section>
+
+      {ramps.length ? (
+        <section className="mt-12 grid w-full max-w-4xl grid-cols-1 gap-4 sm:grid-cols-2">
+          {ramps.map((r) => (
+            <Link
+              key={r.url}
+              href={r.url}
+              className="rounded-xl border border-fd-border bg-fd-card p-6 text-left transition-colors hover:border-fd-primary hover:bg-fd-accent"
+            >
+              <div className="text-lg font-semibold text-fd-card-foreground">{r.title}</div>
+              <div className="mt-2 text-sm text-fd-muted-foreground">{r.blurb}</div>
+            </Link>
+          ))}
+        </section>
+      ) : null}
+
+      <section className="mt-10 grid w-full max-w-4xl grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        {cards.map((c) => (
+          <Link
+            key={c.slug}
+            href={c.url}
+            className="rounded-xl border border-fd-border bg-fd-card p-5 text-left transition-colors hover:bg-fd-accent"
+          >
+            <div className="text-base font-semibold text-fd-card-foreground">{c.title}</div>
+            <div className="mt-1 text-sm text-fd-muted-foreground">
+              {c.count} {c.count === 1 ? 'page' : 'pages'}
+            </div>
+          </Link>
+        ))}
+      </section>
+    </main>
+  );
+}

package/src/generators/docs-site/files/app/source.ts

@@ -0,0 +1,8 @@
+import { docs, meta } from '@/.source';
+import { createMDXSource } from 'fumadocs-mdx';
+import { loader } from 'fumadocs-core/source';
+
+export const source = loader({
+  baseUrl: '/docs',
+  source: createMDXSource(docs, meta),
+});

package/src/generators/docs-site/files/components/mermaid.tsx

@@ -0,0 +1,67 @@
+'use client';
+
+import { useEffect, useId, useState } from 'react';
+
+// Client-side renderer for a single ```mermaid block. The remark transform in
+// source.config.ts rewrites each fenced mermaid block into `<Mermaid chart="…" />`, and the
+// docs page passes this component into the MDX components map. Rendering happens in the
+// browser via mermaid's own renderer — `next build` never needs a headless browser, so the
+// site stays plain-Markdown and Playwright-free. Re-renders on light/dark toggle (Fumadocs
+// flips the `dark` class on <html>).
+export function Mermaid({ chart }: { chart: string }) {
+  const [svg, setSvg] = useState('');
+  const rawId = useId();
+  const id = 'mmd-' + rawId.replace(/[^a-zA-Z0-9]/g, '');
+
+  useEffect(() => {
+    let active = true;
+
+    const render = async () => {
+      const mermaid = (await import('mermaid')).default;
+      if (!active) return;
+      const isDark = document.documentElement.classList.contains('dark');
+      mermaid.initialize({
+        startOnLoad: false,
+        theme: isDark ? 'dark' : 'default',
+        securityLevel: 'strict',
+      });
+      try {
+        const { svg } = await mermaid.render(id, chart);
+        if (active) setSvg(svg);
+      } catch {
+        // A malformed diagram should never crash the page.
+        if (active) setSvg('');
+      }
+    };
+
+    void render();
+
+    const observer = new MutationObserver(() => void render());
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class'],
+    });
+
+    return () => {
+      active = false;
+      observer.disconnect();
+    };
+  }, [chart, id]);
+
+  if (!svg) {
+    // Pre-render / pre-hydration fallback: show the source so the diagram is never blank.
+    return (
+      <pre className="mermaid-fallback">
+        <code>{chart}</code>
+      </pre>
+    );
+  }
+
+  return (
+    <div
+      className="my-4 flex justify-center"
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/src/generators/docs-site/files/next.config.mjs

@@ -0,0 +1,10 @@
+import { createMDX } from 'fumadocs-mdx/next';
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+};
+
+export default withMDX(config);

package/src/generators/docs-site/files/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "<%= fileName %>",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "postinstall": "fumadocs-mdx"
+  },
+  "dependencies": {
+    "fumadocs-core": "14.7.7",
+    "fumadocs-mdx": "11.10.1",
+    "fumadocs-ui": "14.7.7",
+    "lucide-react": "^0.460.0",
+    "mermaid": "^11.4.0",
+    "next": "15.1.8",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "22.9.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
+    "typescript": "5.6.3"
+  }
+}

package/src/generators/docs-site/files/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+# pnpm 10+ gates dependency build scripts by default and exits non-zero
+# (ERR_PNPM_IGNORED_BUILDS) when it skips them — which also makes `pnpm dev` and
+# `pnpm build` fail their pre-run dependency check. The skipped scripts here are
+# first-party Next.js build deps (esbuild, sharp) whose native binaries this app
+# legitimately wants, so allow dependency builds to run — the same behaviour npm
+# and yarn give by default. (These settings moved out of .npmrc in pnpm 10.)
+dangerouslyAllowAllBuilds: true

package/src/generators/docs-site/files/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/src/generators/docs-site/files/source.config.ts

@@ -0,0 +1,77 @@
+import { defineDocs, defineConfig, frontmatterSchema } from 'fumadocs-mdx/config';
+import { z } from 'zod';
+
+// GroundWork docs carry `title` + `description` frontmatter (required by the
+// groundwork-writer skill); the site renders them as the page heading and subtitle.
+// `title` is relaxed to optional only as a fallback: when a doc omits it, the schema
+// derives the title from the document's first `# H1`, so the site still serves any
+// doc (bets, hand-written pages) with a real title in the sidebar and on the page.
+//
+// Note: the schema function runs before remark, so we read the raw `source`. The
+// first `# ` line is the title; a `#` inside an opening code fence is not a case
+// GroundWork docs hit.
+export const { docs, meta } = defineDocs({
+  // Direct compile-time access to the pristine root docs directory.
+  dir: '../../docs',
+  docs: {
+    schema: (ctx) =>
+      frontmatterSchema
+        .extend({ title: z.string().optional() })
+        .transform(
+          (data): { title: string; description?: string; icon?: string; full?: boolean } => {
+            const fm = data as {
+              title?: string;
+              description?: string;
+              icon?: string;
+              full?: boolean;
+            };
+            const match = ctx.source.match(/^\s{0,3}#\s+(.+?)\s*#*\s*$/m);
+            return {
+              title: fm.title ?? (match ? match[1].trim() : 'Untitled'),
+              description: fm.description,
+              icon: fm.icon,
+              full: fm.full,
+            };
+          }
+        ),
+  },
+});
+
+// Render fenced ```mermaid blocks CLIENT-SIDE, with zero build-time dependency on a
+// headless browser. A small remark transform rewrites each `code` node with lang `mermaid`
+// into a `<Mermaid chart="…" />` MDX element (resolved from the components map in the docs
+// page); the `Mermaid` client component renders it in the browser. We deliberately avoid
+// `rehype-mermaid` — it transitively imports `mermaid-isomorphic` → `playwright`, so merely
+// importing it makes `next build`/codegen require Playwright even when no diagram renders at
+// build. The content stays plain Markdown: GitHub renders the same fenced block natively,
+// agents cold-read it, and this site renders it client-side — one source, three readers, no
+// MDX components in the content itself.
+function remarkMermaid() {
+  return (tree: { children?: unknown[] }) => {
+    const walk = (node: { children?: unknown[] }) => {
+      if (!node || !Array.isArray(node.children)) return;
+      node.children = node.children.map((child) => {
+        const c = child as { type?: string; lang?: string; value?: string };
+        if (c.type === 'code' && c.lang === 'mermaid') {
+          return {
+            type: 'mdxJsxFlowElement',
+            name: 'Mermaid',
+            attributes: [
+              { type: 'mdxJsxAttribute', name: 'chart', value: c.value ?? '' },
+            ],
+            children: [],
+          };
+        }
+        return child;
+      });
+      for (const child of node.children) walk(child as { children?: unknown[] });
+    };
+    walk(tree);
+  };
+}
+
+export default defineConfig({
+  mdxOptions: {
+    remarkPlugins: (v) => [remarkMermaid, ...v],
+  },
+});

package/src/generators/docs-site/files/tailwind.config.js

@@ -0,0 +1,10 @@
+import { createPreset } from 'fumadocs-ui/tailwind-plugin';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './app/**/*.{ts,tsx}',
+    './node_modules/fumadocs-ui/dist/**/*.js',
+  ],
+  presets: [createPreset()],
+};

package/src/generators/docs-site/files/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}