@shanyucoder/flowgrid 0.1.0

package/engines/docs/vitepress/theme/custom.css

@@ -0,0 +1,418 @@
+/* Full-width layout — default theme caps doc column at 688px / layout at 1440px */
+:root {
+  --vp-layout-max-width: 100%;
+}
+
+.VPDoc .container {
+  max-width: 100% !important;
+}
+
+.VPDoc.has-aside .content-container,
+.VPDoc .content-container {
+  max-width: none !important;
+}
+
+.VPDoc .content {
+  max-width: none !important;
+}
+
+/* Keep all document text readable on wide layouts. */
+.VPDoc .vp-doc,
+.VPDoc .vp-doc p,
+.VPDoc .vp-doc li,
+.VPDoc .vp-doc table,
+.VPDoc .vp-doc blockquote,
+.VPDoc .vp-doc .custom-block {
+  font-size: 20px;
+}
+
+.VPDoc .vp-doc p,
+.VPDoc .vp-doc li {
+  line-height: 1.75;
+}
+
+.VPDoc .vp-doc code {
+  font-size: 0.9em;
+}
+
+.VPDoc .vp-doc h1 {
+  font-size: 38px;
+}
+
+.VPDoc .vp-doc h2 {
+  font-size: 30px;
+}
+
+.VPDoc .vp-doc h3 {
+  font-size: 24px;
+}
+
+/* Intro two-column cards — palette matches start-here-layers.png (teal/mint + coral) */
+.vp-doc .intro-grid {
+  display: flex;
+  gap: 20px;
+  align-items: stretch;
+  margin: 20px 0 8px;
+}
+
+.vp-doc .intro-card {
+  padding: 20px 28px;
+  border-radius: 32px;
+  border: 1px solid rgb(58 154 140 / 25%);
+  box-shadow:
+    0 8px 24px rgb(31 104 94 / 10%),
+    inset 0 1px 0 rgb(255 255 255 / 45%);
+}
+
+.vp-doc .intro-card--main {
+  flex: 0 0 65%;
+  background: linear-gradient(135deg, rgb(224 244 240 / 90%), rgb(198 233 226 / 75%));
+}
+
+.vp-doc .intro-card--side {
+  flex: 1;
+  background: linear-gradient(135deg, rgb(253 236 230 / 90%), rgb(250 219 209 / 70%));
+  border-color: rgb(240 138 118 / 30%);
+  box-shadow:
+    0 8px 24px rgb(196 92 71 / 10%),
+    inset 0 1px 0 rgb(255 255 255 / 45%);
+}
+
+.vp-doc .intro-card h3 {
+  margin: 0 0 10px;
+  border: none;
+  padding-top: 0;
+}
+
+.vp-doc .intro-card--main h3 {
+  color: #1f685e;
+}
+
+.vp-doc .intro-card--side h3 {
+  color: #b4543d;
+}
+
+.vp-doc .intro-card ul,
+.vp-doc .intro-card ol {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.vp-doc .intro-card li {
+  margin: 8px 0;
+}
+
+@media (max-width: 960px) {
+  .vp-doc .intro-grid {
+    flex-direction: column;
+  }
+
+  .vp-doc .intro-card--main {
+    flex-basis: auto;
+  }
+}
+
+.dark .vp-doc .intro-card--main {
+  background: linear-gradient(135deg, rgb(31 74 68 / 70%), rgb(23 55 51 / 60%));
+  border-color: rgb(94 190 173 / 30%);
+}
+
+.dark .vp-doc .intro-card--side {
+  background: linear-gradient(135deg, rgb(84 46 38 / 70%), rgb(64 35 29 / 60%));
+  border-color: rgb(240 138 118 / 30%);
+}
+
+.dark .vp-doc .intro-card--main h3 {
+  color: #7fd6c6;
+}
+
+.dark .vp-doc .intro-card--side h3 {
+  color: #f0a08a;
+}
+
+/* Hero image centered at natural size */
+.vp-doc .intro-hero {
+  display: flex;
+  justify-content: center;
+}
+
+/* Plain two-column layout (no card background) */
+.vp-doc .duo-grid {
+  display: flex;
+  gap: 28px;
+  align-items: flex-start;
+}
+
+.vp-doc .duo-col {
+  flex: 1 1 50%;
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .vp-doc .duo-grid {
+    flex-direction: column;
+  }
+}
+
+/* Business tree uses only its content width; the overview diagram gets remaining space. */
+.vp-doc .tree-overview-grid {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: 28px;
+  align-items: start;
+}
+
+.vp-doc .tree-overview-grid__tree {
+  width: fit-content;
+  max-width: 100%;
+}
+
+.vp-doc .tree-overview-grid__tree div[class*='language-'] {
+  margin: 0;
+}
+
+.vp-doc .tree-overview-grid__diagram {
+  min-width: 0;
+}
+
+@media (max-width: 1100px) {
+  .vp-doc .tree-overview-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .vp-doc .tree-overview-grid__tree {
+    width: 100%;
+  }
+}
+
+/* Five project-operation phases: illustrated cards with floating step pills. */
+.vp-doc .phase-card {
+  display: flex;
+  gap: 30px;
+  align-items: center;
+  margin: 30px 0;
+  padding: 26px;
+  overflow: hidden;
+  border: 1px solid rgb(148 163 184 / 26%);
+  border-radius: 38px;
+  box-shadow:
+    0 14px 36px rgb(15 23 42 / 9%),
+    inset 0 1px 0 rgb(255 255 255 / 55%);
+}
+
+.vp-doc .phase-card--reverse {
+  flex-direction: row-reverse;
+}
+
+.vp-doc .phase-card--lead {
+  background: linear-gradient(135deg, #e8f2ff 0%, #f4f8ff 52%, #dcecff 100%);
+}
+
+.vp-doc .phase-card--member {
+  background: linear-gradient(135deg, #e3f7f1 0%, #f2fbf8 52%, #d5f2e9 100%);
+}
+
+.vp-doc .phase-card--test {
+  background: linear-gradient(135deg, #fff4d6 0%, #fffbef 52%, #fee9b5 100%);
+}
+
+.vp-doc .phase-card--dev {
+  background: linear-gradient(135deg, #eee9ff 0%, #f8f6ff 52%, #e2d9ff 100%);
+}
+
+.vp-doc .phase-card--ship {
+  background: linear-gradient(135deg, #e9eef4 0%, #f7f9fb 52%, #dce4ec 100%);
+}
+
+.vp-doc .phase-card__visual {
+  flex: 0 0 34%;
+  min-width: 0;
+}
+
+.vp-doc .phase-card__visual img {
+  display: block;
+  width: 100%;
+  margin: 0;
+  border-radius: 26px;
+  box-shadow: 0 10px 24px rgb(15 23 42 / 10%);
+}
+
+.vp-doc .phase-card__body {
+  flex: 1 1 66%;
+  min-width: 0;
+}
+
+.vp-doc .phase-card__body h3 {
+  margin-top: 0;
+  padding-top: 0;
+  border-top: 0;
+}
+
+.vp-doc .phase-pills {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 11px;
+  margin: 18px 0;
+}
+
+.vp-doc .phase-pills span {
+  display: inline-flex;
+  align-items: center;
+  min-height: 42px;
+  padding: 8px 17px;
+  border: 1px solid rgb(100 116 139 / 24%);
+  border-radius: 999px;
+  background: rgb(255 255 255 / 72%);
+  box-shadow:
+    0 5px 14px rgb(15 23 42 / 8%),
+    inset 0 1px 0 rgb(255 255 255 / 80%);
+  font-size: 17px;
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+.vp-doc .phase-pills .phase-pill-more {
+  min-width: 48px;
+  justify-content: center;
+  font-size: 24px;
+}
+
+.dark .vp-doc .phase-card {
+  border-color: rgb(148 163 184 / 25%);
+  box-shadow: 0 14px 36px rgb(0 0 0 / 28%);
+}
+
+.dark .vp-doc .phase-card--lead {
+  background: linear-gradient(135deg, #172b46, #1c2637);
+}
+
+.dark .vp-doc .phase-card--member {
+  background: linear-gradient(135deg, #153a33, #1c2f2c);
+}
+
+.dark .vp-doc .phase-card--test {
+  background: linear-gradient(135deg, #493817, #302b21);
+}
+
+.dark .vp-doc .phase-card--dev {
+  background: linear-gradient(135deg, #302454, #292437);
+}
+
+.dark .vp-doc .phase-card--ship {
+  background: linear-gradient(135deg, #293441, #252b32);
+}
+
+.dark .vp-doc .phase-pills span {
+  border-color: rgb(203 213 225 / 20%);
+  background: rgb(15 23 42 / 48%);
+}
+
+@media (max-width: 1000px) {
+  .vp-doc .phase-card,
+  .vp-doc .phase-card--reverse {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .vp-doc .phase-card__visual {
+    flex-basis: auto;
+  }
+
+  .vp-doc .phase-card__visual img {
+    max-height: 420px;
+    object-fit: cover;
+  }
+}
+
+/* Optional-scope note used by onboarding pages. */
+.vp-doc .base-note {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  margin: 18px 0 24px;
+  padding: 12px 18px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 999px;
+  background:
+    linear-gradient(135deg, var(--vp-c-bg-soft), var(--vp-c-bg-alt));
+  box-shadow:
+    0 6px 18px rgb(0 0 0 / 8%),
+    inset 0 1px 0 rgb(255 255 255 / 35%);
+  line-height: 1.65;
+}
+
+.vp-doc .base-note-mark {
+  flex: 0 0 auto;
+  font-weight: 700;
+  color: var(--vp-c-brand-1);
+}
+
+.vp-doc .base-note em {
+  font-size: 19px;
+}
+
+/* Mermaid labels must keep the size mermaid measured with (page 20px cascade clips nodes).
+   Node boxes are sized at render time using themeVariables.fontSize (18px, see config.ts);
+   any page rule bumping label text afterwards overflows the boxes. Pin every label element. */
+.VPDoc .vp-doc .mermaid,
+.VPDoc .vp-doc .vitepress-mermaid-renderer,
+.VPDoc .vp-doc .mermaid foreignObject div,
+.VPDoc .vp-doc .mermaid foreignObject span,
+.VPDoc .vp-doc .mermaid foreignObject p,
+.VPDoc .vp-doc .mermaid .nodeLabel,
+.VPDoc .vp-doc .mermaid .nodeLabel p,
+.VPDoc .vp-doc .mermaid .edgeLabel,
+.VPDoc .vp-doc .mermaid .edgeLabel p,
+.VPDoc .vp-doc .mermaid .cluster-label,
+.VPDoc .vp-doc .mermaid .cluster-label p {
+  font-size: 18px !important;
+  line-height: 1.4 !important;
+}
+
+/* Mermaid — fill content column (don’t leave half-width empty) */
+.vp-doc .mermaid,
+.vp-doc div[class*='mermaid'],
+.vp-doc .vitepress-mermaid-renderer,
+.vp-doc .mermaid-diagram,
+.vp-doc [class*='MermaidDiagram'] {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.vp-doc .mermaid svg,
+.vp-doc .vitepress-mermaid-renderer svg,
+.vp-doc .mermaid-diagram svg,
+.vp-doc pre.mermaid svg {
+  display: block;
+  width: 100% !important;
+  max-width: 100%;
+  height: auto !important;
+  margin-inline: auto;
+}
+
+/* Viewport around zoomable diagrams — use content width */
+.vp-doc .vitepress-mermaid-renderer .diagram-container,
+.vp-doc .vitepress-mermaid-renderer .mermaid-container {
+  width: 100%;
+  min-height: 280px;
+}
+
+/* Per-toolkit illustration in the install catalog */
+.vp-doc .toolkit-illus {
+  display: block;
+  width: 100%;
+  max-width: 460px;
+  margin: 14px 0 18px;
+  border-radius: 16px;
+  border: 1px solid rgb(58 154 140 / 22%);
+  box-shadow:
+    0 10px 26px rgb(31 104 94 / 12%),
+    inset 0 1px 0 rgb(255 255 255 / 45%);
+}
+
+.dark .vp-doc .toolkit-illus {
+  border-color: rgb(94 190 173 / 28%);
+  box-shadow: 0 10px 26px rgb(0 0 0 / 35%);
+}

package/engines/docs/vitepress/theme/index.ts

@@ -0,0 +1,46 @@
+import { h, nextTick, watch } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+import { createMermaidRenderer } from 'vitepress-mermaid-renderer'
+import 'vitepress-mermaid-renderer/css'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    const { isDark } = useData()
+
+    const initMermaid = () => {
+      createMermaidRenderer({
+        theme: isDark.value ? 'dark' : 'default',
+        // Expand diagram to content width (default compact SVG was ~½ column)
+        flowchart: {
+          useMaxWidth: true,
+          htmlLabels: true,
+          padding: 16,
+          nodeSpacing: 50,
+          rankSpacing: 60,
+        },
+        sequence: {
+          useMaxWidth: true,
+          diagramMarginX: 40,
+          diagramMarginY: 20,
+          actorMargin: 50,
+          boxMargin: 12,
+        },
+        themeVariables: {
+          fontSize: '18px',
+        },
+      })
+    }
+
+    nextTick(() => initMermaid())
+    watch(
+      () => isDark.value,
+      () => initMermaid(),
+    )
+
+    return h(DefaultTheme.Layout)
+  },
+} satisfies Theme

package/engines/openapi/build-openapi-ui.mjs

@@ -0,0 +1,72 @@
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(join(process.cwd(), 'package.json'))
+const swaggerUiDist = require('swagger-ui-dist')
+
+const repoRoot = process.cwd()
+const sourceDir = swaggerUiDist.getAbsoluteFSPath()
+const targetDir = join(repoRoot, 'docs/public/api-ui')
+const openApiFile = join(repoRoot, 'docs/public/openapi/openapi.yaml')
+
+if (!existsSync(openApiFile)) {
+  throw new Error(
+    'Missing docs/public/openapi/openapi.yaml. Run `pnpm openapi:bundle` before `pnpm openapi:build`.'
+  )
+}
+
+await mkdir(targetDir, { recursive: true })
+
+const assets = [
+  'swagger-ui.css',
+  'swagger-ui-bundle.js',
+  'swagger-ui-standalone-preset.js',
+  'favicon-16x16.png',
+  'favicon-32x32.png'
+]
+
+for (const asset of assets) {
+  await copyFile(join(sourceDir, asset), join(targetDir, asset))
+}
+
+await writeFile(
+  join(targetDir, 'index.html'),
+  `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>OpenAPI Explorer</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="./swagger-ui.css" />
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="./swagger-ui-bundle.js"></script>
+    <script src="./swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: '/openapi/openapi.yaml',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: 'StandaloneLayout'
+      })
+    </script>
+  </body>
+</html>
+`,
+  'utf8'
+)
+
+console.log('openapi:build-ui: OpenAPI UI built at docs/public/api-ui/index.html')

package/engines/openapi/build-swagger-ui.mjs

@@ -0,0 +1,72 @@
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const swaggerUiDist = require('swagger-ui-dist')
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../..')
+const sourceDir = swaggerUiDist.getAbsoluteFSPath()
+const targetDir = join(repoRoot, 'docs/public/swagger')
+const openApiFile = join(repoRoot, 'docs/public/openapi/openapi.yaml')
+
+if (!existsSync(openApiFile)) {
+  throw new Error(
+    'Missing docs/public/openapi/openapi.yaml. Run `pnpm openapi:bundle` before `pnpm swagger:build`.'
+  )
+}
+
+await mkdir(targetDir, { recursive: true })
+
+const assets = [
+  'swagger-ui.css',
+  'swagger-ui-bundle.js',
+  'swagger-ui-standalone-preset.js',
+  'favicon-16x16.png',
+  'favicon-32x32.png'
+]
+
+for (const asset of assets) {
+  await copyFile(join(sourceDir, asset), join(targetDir, asset))
+}
+
+await writeFile(
+  join(targetDir, 'index.html'),
+  `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>API Swagger UI</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="stylesheet" href="./swagger-ui.css" />
+    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="./swagger-ui-bundle.js"></script>
+    <script src="./swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        url: '/openapi/openapi.yaml',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: 'StandaloneLayout'
+      })
+    </script>
+  </body>
+</html>
+`,
+  'utf8'
+)
+
+console.log('swagger:build: Swagger UI built at docs/public/swagger/index.html')

package/engines/openapi/check-backend-spec.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parse } from 'yaml'
+
+import { listBackendSpecs } from './gen-openapi.mjs'
+import { checkBackendSpec } from './lib/check-backend-spec.mjs'
+
+async function resolveSpecFiles(specArg, cwd) {
+  if (!specArg) {
+    const surfaces = path.join(cwd, 'surfaces')
+    return await listBackendSpecs(surfaces)
+  }
+  const abs = path.resolve(cwd, specArg)
+  const st = existsSync(abs) ? await stat(abs) : null
+  if (!st) throw new Error(`Not found: ${abs}`)
+  if (st.isDirectory()) return await listBackendSpecs(abs)
+  if (path.basename(abs) !== '01-backend-spec.yaml') {
+    throw new Error(`Expected 01-backend-spec.yaml, got ${abs}`)
+  }
+  return [abs]
+}
+
+export async function checkBackendSpecFiles(options, cwd = process.cwd()) {
+  const files = await resolveSpecFiles(options.spec, cwd)
+  if (!files.length) throw new Error('No 01-backend-spec.yaml found. Pass --spec <path>.')
+  let failed = 0
+  for (const specPath of files) {
+    const spec = parse(await readFile(specPath, 'utf8')) ?? {}
+    const result = checkBackendSpec(spec, specPath)
+    const rel = path.relative(cwd, specPath)
+    if (result.ok) {
+      console.log(`ok: ${rel}`)
+    } else {
+      failed++
+      console.error(`fail: ${rel}`)
+      for (const e of result.errors) console.error(`  ✗ ${e}`)
+    }
+    for (const w of result.warnings) console.warn(`  warn: ${w}`)
+  }
+  if (failed) throw new Error(`api:check failed for ${failed} spec(s)`)
+  return files
+}
+
+function parseArgs(argv) {
+  const options = { spec: null }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--spec') options.spec = argv[++i]
+    else if (!arg.startsWith('-') && !options.spec) options.spec = arg
+  }
+  return options
+}
+
+async function main() {
+  await checkBackendSpecFiles(parseArgs(process.argv.slice(2)), process.cwd())
+}
+
+if (path.resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message ?? error)
+    process.exit(1)
+  })
+}