flowbook 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,170 @@
+# Flowbook
+
+> [English](./README.md) | [한국어](./README.ko.md) | **简体中文** | [日本語](./README.ja.md) | [Español](./README.es.md) | [Português (BR)](./README.pt-BR.md) | [Français](./README.fr.md) | [Русский](./README.ru.md) | [Deutsch](./README.de.md)
+
+流程图的 Storybook。自动发现代码库中的 Mermaid 图表文件，按类别组织，并在可浏览的查看器中渲染。
+
+![Vite](https://img.shields.io/badge/vite-6.x-646CFF?logo=vite&logoColor=white)
+![React](https://img.shields.io/badge/react-19.x-61DAFB?logo=react&logoColor=white)
+![Mermaid](https://img.shields.io/badge/mermaid-11.x-FF3670?logo=mermaid&logoColor=white)
+![TypeScript](https://img.shields.io/badge/typescript-5.x-3178C6?logo=typescript&logoColor=white)
+
+## 快速开始
+
+```bash
+# 安装
+npm install -D flowbook
+
+# 初始化 — 添加脚本 + 示例文件
+npx flowbook init
+
+# 启动开发服务器
+npm run flowbook
+# → http://localhost:6200
+
+# 构建静态站点
+npm run build-flowbook
+# → flowbook-static/
+```
+
+## CLI
+
+```
+flowbook init                在项目中设置 Flowbook
+flowbook dev  [--port 6200]  启动开发服务器
+flowbook build [--out-dir d] 构建静态站点
+```
+
+### `flowbook init`
+
+- 在 `package.json` 中添加 `"flowbook"` 和 `"build-flowbook"` 脚本
+- 创建 `flows/example.flow.md` 作为入门模板
+
+### `flowbook dev`
+
+在 `http://localhost:6200` 启动支持 HMR 的 Vite 开发服务器。任何 `.flow.md` 或 `.flowchart.md` 文件的更改都会即时生效。
+
+### `flowbook build`
+
+将静态站点构建到 `flowbook-static/` 目录（可通过 `--out-dir` 配置）。可部署到任何地方。
+
+## 编写流程文件
+
+在项目中任意位置创建 `.flow.md`（或 `.flowchart.md`）文件：
+
+````markdown
+---
+title: 登录流程
+category: 认证
+tags: [auth, login, oauth]
+order: 1
+description: 使用 OAuth2 的用户认证流程
+---
+
+```mermaid
+flowchart TD
+    A[用户] --> B{已认证?}
+    B -->|是| C[仪表盘]
+    B -->|否| D[登录页面]
+```
+````
+
+Flowbook 会自动发现文件并将其添加到查看器中。
+
+## Frontmatter 模式
+
+| 字段          | 类型       | 必填 | 说明                                |
+|---------------|------------|------|-------------------------------------|
+| `title`       | `string`   | 否   | 显示标题（默认为文件名）            |
+| `category`    | `string`   | 否   | 侧边栏分类（默认为 "Uncategorized"）|
+| `tags`        | `string[]` | 否   | 可筛选的标签                        |
+| `order`       | `number`   | 否   | 分类内排序（默认：999）             |
+| `description` | `string`   | 否   | 详情视图中显示的描述                |
+
+## 文件发现
+
+Flowbook 默认扫描以下模式：
+
+```
+**/*.flow.md
+**/*.flowchart.md
+```
+
+忽略 `node_modules/`、`.git/` 和 `dist/`。
+
+## 工作原理
+
+```
+.flow.md 文件 ──→ Vite 插件 ──→ 虚拟模块 ──→ React 查看器
+                    │                   │
+                    ├─ fast-glob 扫描   ├─ export default { flows: [...] }
+                    ├─ gray-matter      │
+                    │  解析             └─ 文件更改时 HMR
+                    └─ mermaid 块
+                       提取
+```
+
+1. **发现** — `fast-glob` 扫描项目中的 `*.flow.md` / `*.flowchart.md`
+2. **解析** — `gray-matter` 提取 YAML frontmatter；正则表达式提取 `` ```mermaid `` 块
+3. **虚拟模块** — Vite 插件将解析后的数据作为 `virtual:flowbook-data` 提供
+4. **渲染** — React 应用通过 `mermaid.render()` 渲染 Mermaid 图表
+5. **HMR** — 文件更改时使虚拟模块失效，触发重新加载
+
+## 项目结构
+
+```
+src/
+├── types.ts                    # 共享类型 (FlowEntry, FlowbookData)
+├── node/
+│   ├── cli.ts                  # CLI 入口 (init, dev, build)
+│   ├── server.ts               # 编程式 Vite 服务器与构建
+│   ├── init.ts                 # 项目初始化逻辑
+│   ├── discovery.ts            # 文件扫描器 (fast-glob)
+│   ├── parser.ts               # Frontmatter + mermaid 提取
+│   └── plugin.ts               # Vite 虚拟模块插件
+└── client/
+    ├── index.html              # 入口 HTML
+    ├── main.tsx                # React 入口
+    ├── App.tsx                 # 搜索 + 侧边栏 + 查看器布局
+    ├── vite-env.d.ts           # 虚拟模块类型声明
+    ├── styles/globals.css      # Tailwind v4 + 自定义样式
+    └── components/
+        ├── Header.tsx          # Logo、搜索栏、流程计数
+        ├── Sidebar.tsx         # 可折叠分类树
+        ├── MermaidRenderer.tsx # Mermaid 图表渲染
+        ├── FlowView.tsx        # 单个流程详情视图
+        └── EmptyState.tsx      # 空状态引导
+```
+
+## 开发（贡献）
+
+```bash
+git clone https://github.com/Epsilondelta-ai/flowbook.git
+cd flowbook
+npm install
+
+# 本地开发（使用根目录 vite.config.ts）
+npm run dev
+
+# 构建 CLI
+npm run build
+
+# 本地测试 CLI
+node dist/cli.js dev
+node dist/cli.js build
+```
+
+## 技术栈
+
+- **Vite** — 支持 HMR 的开发服务器
+- **React 19** — 用户界面
+- **Mermaid 11** — 图表渲染
+- **Tailwind CSS v4** — 样式
+- **gray-matter** — YAML frontmatter 解析
+- **fast-glob** — 文件发现
+- **tsup** — CLI 打包工具
+- **TypeScript** — 类型安全
+
+## 许可证
+
+MIT

package/dist/cli.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+// src/node/init.ts
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { resolve } from "path";
+var EXAMPLE_FLOW = `---
+title: Example Flow
+category: Getting Started
+tags: [example]
+order: 1
+description: An example flowchart to get you started
+---
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action A]
+    B -->|No| D[Action B]
+    C --> E[End]
+    D --> E
+\`\`\`
+`;
+async function initFlowbook() {
+  const cwd = process.cwd();
+  const pkgPath = resolve(cwd, "package.json");
+  if (!existsSync(pkgPath)) {
+    console.error("  No package.json found. Run 'npm init' first.");
+    process.exit(1);
+  }
+  const raw = readFileSync(pkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  pkg.scripts = pkg.scripts ?? {};
+  let scriptsAdded = false;
+  if (!pkg.scripts.flowbook) {
+    pkg.scripts.flowbook = "flowbook dev";
+    scriptsAdded = true;
+  }
+  if (!pkg.scripts["build-flowbook"]) {
+    pkg.scripts["build-flowbook"] = "flowbook build";
+    scriptsAdded = true;
+  }
+  if (scriptsAdded) {
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log('  \u2713 Added "flowbook" and "build-flowbook" scripts to package.json');
+  } else {
+    console.log("  \u2713 Scripts already exist in package.json");
+  }
+  const flowsDir = resolve(cwd, "flows");
+  const examplePath = resolve(flowsDir, "example.flow.md");
+  if (!existsSync(examplePath)) {
+    mkdirSync(flowsDir, { recursive: true });
+    writeFileSync(examplePath, EXAMPLE_FLOW);
+    console.log("  \u2713 Created flows/example.flow.md");
+  } else {
+    console.log("  \u2713 Example flow already exists");
+  }
+  console.log("");
+  console.log("  Next steps:");
+  console.log("    npm run flowbook       Start the dev server");
+  console.log("    npm run build-flowbook  Build static site");
+  console.log("");
+}
+
+// src/node/server.ts
+import { createServer, build } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+// src/node/discovery.ts
+import fg from "fast-glob";
+async function discoverFlowFiles(options) {
+  const patterns = options.include ?? ["**/*.flow.md", "**/*.flowchart.md"];
+  const ignore = options.ignore ?? [
+    "node_modules/**",
+    ".git/**",
+    "dist/**"
+  ];
+  const cwd = options.cwd ?? process.cwd();
+  return fg(patterns, { cwd, ignore, absolute: true });
+}
+
+// src/node/parser.ts
+import matter from "gray-matter";
+import { readFileSync as readFileSync2 } from "fs";
+import { relative } from "path";
+var MERMAID_BLOCK_RE = /```mermaid\n([\s\S]*?)```/g;
+function parseFlowFile(filePath, cwd) {
+  const raw = readFileSync2(filePath, "utf-8");
+  const { data, content } = matter(raw);
+  const mermaidBlocks = [];
+  let match;
+  while ((match = MERMAID_BLOCK_RE.exec(content)) !== null) {
+    mermaidBlocks.push(match[1].trim());
+  }
+  MERMAID_BLOCK_RE.lastIndex = 0;
+  const relPath = relative(cwd, filePath);
+  const id = relPath.replace(/[/\\]/g, "-").replace(/\.flow(chart)?\.md$/, "");
+  const fileName = relPath.replace(/\.flow(chart)?\.md$/, "").split("/").pop();
+  return {
+    id,
+    title: typeof data.title === "string" ? data.title : fileName ?? "Untitled",
+    category: typeof data.category === "string" ? data.category : "Uncategorized",
+    tags: Array.isArray(data.tags) ? data.tags : [],
+    description: typeof data.description === "string" ? data.description : "",
+    order: typeof data.order === "number" ? data.order : 999,
+    filePath: relPath,
+    mermaidBlocks
+  };
+}
+
+// src/node/plugin.ts
+var VIRTUAL_MODULE_ID = "virtual:flowbook-data";
+var RESOLVED_ID = "\0" + VIRTUAL_MODULE_ID;
+function flowbookPlugin(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  async function loadFlows() {
+    const files = await discoverFlowFiles({ ...options, cwd });
+    const flows = files.map((f) => parseFlowFile(f, cwd));
+    flows.sort((a, b) => {
+      if (a.category !== b.category)
+        return a.category.localeCompare(b.category);
+      return a.order - b.order;
+    });
+    return { flows };
+  }
+  return {
+    name: "flowbook",
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) return RESOLVED_ID;
+    },
+    async load(id) {
+      if (id === RESOLVED_ID) {
+        const data = await loadFlows();
+        return `export default ${JSON.stringify(data)}`;
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file.endsWith(".flow.md") || file.endsWith(".flowchart.md")) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({ type: "full-reload" });
+        }
+      }
+    },
+    configureServer(server) {
+      if (cwd !== process.cwd()) {
+        server.watcher.add(cwd);
+      }
+    }
+  };
+}
+
+// src/node/server.ts
+import { resolve as resolve2, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getClientDir() {
+  return resolve2(__dirname, "..", "src", "client");
+}
+function createConfig(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const clientDir = getClientDir();
+  return {
+    configFile: false,
+    root: clientDir,
+    plugins: [
+      react(),
+      tailwindcss(),
+      flowbookPlugin({
+        include: ["**/*.flow.md", "**/*.flowchart.md"],
+        ignore: ["node_modules/**", ".git/**", "dist/**"],
+        cwd
+      })
+    ],
+    server: {
+      port: options.port ?? 6200
+    },
+    build: {
+      outDir: resolve2(cwd, options.outDir ?? "flowbook-static"),
+      emptyOutDir: true
+    }
+  };
+}
+async function startDevServer(options) {
+  const config = createConfig({ port: options.port });
+  const server = await createServer(config);
+  await server.listen();
+  server.printUrls();
+}
+async function buildStatic(options) {
+  const config = createConfig({ outDir: options.outDir });
+  await build(config);
+  console.log(`
+  Static site built to ${options.outDir ?? "flowbook-static"}/
+`);
+}
+
+// src/node/cli.ts
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  switch (command) {
+    case "init":
+      await initFlowbook();
+      break;
+    case "dev": {
+      const port = Number(getFlag(args, "--port", "6200"));
+      await startDevServer({ port });
+      break;
+    }
+    case "build": {
+      const outDir = String(getFlag(args, "--out-dir", "flowbook-static"));
+      await buildStatic({ outDir });
+      break;
+    }
+    default:
+      printUsage();
+      break;
+  }
+}
+function getFlag(args, flag, fallback) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return fallback;
+  return args[idx + 1];
+}
+function printUsage() {
+  console.log(`
+  flowbook \u2014 Storybook for flowcharts
+
+  Usage:
+    flowbook init                Set up Flowbook in your project
+    flowbook dev  [--port 6200]  Start the dev server
+    flowbook build [--out-dir d] Build a static site
+
+  Options:
+    --port <number>    Dev server port (default: 6200)
+    --out-dir <path>   Build output directory (default: flowbook-static)
+`);
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "flowbook",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "flowbook": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsup",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "fast-glob": "^3.3.0",
+    "gray-matter": "^4.0.3",
+    "mermaid": "^11.4.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0",
+    "vite": "^6.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/client/App.tsx

@@ -0,0 +1,52 @@
+import { useState, useMemo } from "react";
+import data from "virtual:flowbook-data";
+import { Sidebar } from "./components/Sidebar";
+import { FlowView } from "./components/FlowView";
+import { Header } from "./components/Header";
+import { EmptyState } from "./components/EmptyState";
+
+export function App() {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [searchQuery, setSearchQuery] = useState("");
+
+  const filteredFlows = useMemo(() => {
+    if (!searchQuery) return data.flows;
+    const q = searchQuery.toLowerCase();
+    return data.flows.filter(
+      (f) =>
+        f.title.toLowerCase().includes(q) ||
+        f.category.toLowerCase().includes(q) ||
+        f.tags.some((t) => t.toLowerCase().includes(q)) ||
+        f.description.toLowerCase().includes(q),
+    );
+  }, [searchQuery]);
+
+  const selectedFlow = useMemo(
+    () => data.flows.find((f) => f.id === selectedId) ?? null,
+    [selectedId],
+  );
+
+  return (
+    <div className="h-screen flex flex-col bg-zinc-950 text-zinc-100">
+      <Header
+        searchQuery={searchQuery}
+        onSearchChange={setSearchQuery}
+        flowCount={data.flows.length}
+      />
+      <div className="flex flex-1 overflow-hidden">
+        <Sidebar
+          flows={filteredFlows}
+          selectedId={selectedId}
+          onSelect={setSelectedId}
+        />
+        <main className="flex-1 overflow-auto">
+          {selectedFlow ? (
+            <FlowView flow={selectedFlow} />
+          ) : (
+            <EmptyState flowCount={data.flows.length} />
+          )}
+        </main>
+      </div>
+    </div>
+  );
+}

package/src/client/components/EmptyState.tsx

@@ -0,0 +1,57 @@
+interface EmptyStateProps {
+  flowCount: number;
+}
+
+export function EmptyState({ flowCount }: EmptyStateProps) {
+  return (
+    <div className="flex items-center justify-center h-full">
+      <div className="text-center max-w-lg px-4">
+        <svg
+          className="w-16 h-16 text-zinc-800 mx-auto mb-6"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <rect x="3" y="3" width="7" height="7" rx="1" />
+          <rect x="14" y="3" width="7" height="7" rx="1" />
+          <rect x="8" y="14" width="7" height="7" rx="1" />
+          <path d="M6.5 10v1.5a1 1 0 0 0 1 1h9a1 1 0 0 0 1-1V10" />
+          <path d="M11.5 12.5V14" />
+        </svg>
+        <h2 className="text-xl font-semibold text-zinc-400 mb-2">
+          {flowCount > 0 ? "Select a flow" : "No flows found"}
+        </h2>
+        <p className="text-zinc-600 text-sm leading-relaxed">
+          {flowCount > 0
+            ? "Choose a flow from the sidebar to view its diagram."
+            : "Create .flow.md or .flowchart.md files with mermaid diagrams to get started."}
+        </p>
+        {flowCount === 0 && (
+          <div className="mt-8 bg-zinc-900 border border-zinc-800 rounded-xl p-5 text-left">
+            <p className="text-xs text-zinc-500 mb-3 font-medium">
+              Example: <code>auth/login.flow.md</code>
+            </p>
+            <pre className="text-xs text-zinc-400 font-mono leading-relaxed whitespace-pre overflow-x-auto">
+              {`---
+title: Login Flow
+category: Authentication
+tags: [auth, login]
+description: User login process
+---
+
+\`\`\`mermaid
+flowchart TD
+    A[User] --> B{Authenticated?}
+    B -->|Yes| C[Dashboard]
+    B -->|No| D[Login Page]
+\`\`\``}
+            </pre>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/client/components/FlowView.tsx

@@ -0,0 +1,62 @@
+import type { FlowEntry } from "../../types";
+import { MermaidRenderer } from "./MermaidRenderer";
+
+interface FlowViewProps {
+  flow: FlowEntry;
+}
+
+export function FlowView({ flow }: FlowViewProps) {
+  return (
+    <div className="p-8 max-w-5xl mx-auto">
+      {/* Header */}
+      <div className="mb-8">
+        <div className="flex items-center gap-2 mb-3 flex-wrap">
+          <span className="text-xs font-medium text-violet-300 bg-violet-500/10 border border-violet-500/20 px-2.5 py-0.5 rounded-full">
+            {flow.category}
+          </span>
+          {flow.tags.map((tag) => (
+            <span
+              key={tag}
+              className="text-xs text-zinc-400 bg-zinc-800/80 px-2 py-0.5 rounded-full"
+            >
+              {tag}
+            </span>
+          ))}
+        </div>
+        <h2 className="text-2xl font-bold text-zinc-50 tracking-tight">
+          {flow.title}
+        </h2>
+        {flow.description && (
+          <p className="mt-2 text-zinc-400 leading-relaxed">
+            {flow.description}
+          </p>
+        )}
+        <p className="mt-2 text-xs text-zinc-600 font-mono">{flow.filePath}</p>
+      </div>
+
+      {/* Diagrams */}
+      <div className="space-y-6">
+        {flow.mermaidBlocks.map((block, i) => (
+          <div
+            key={i}
+            className="bg-zinc-900/50 border border-zinc-800 rounded-xl p-6 backdrop-blur-sm"
+          >
+            <MermaidRenderer code={block} />
+          </div>
+        ))}
+
+        {flow.mermaidBlocks.length === 0 && (
+          <div className="bg-zinc-900/50 border border-zinc-800 rounded-xl p-12 text-center">
+            <p className="text-zinc-500">
+              No mermaid diagrams found in this file.
+            </p>
+            <p className="text-zinc-600 text-sm mt-1">
+              Add a <code className="text-violet-400">```mermaid</code> code
+              block to see it rendered here.
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/client/components/Header.tsx

@@ -0,0 +1,48 @@
+interface HeaderProps {
+  searchQuery: string;
+  onSearchChange: (query: string) => void;
+  flowCount: number;
+}
+
+export function Header({
+  searchQuery,
+  onSearchChange,
+  flowCount,
+}: HeaderProps) {
+  return (
+    <header className="h-14 border-b border-zinc-800 flex items-center px-4 gap-4 shrink-0 bg-zinc-950">
+      <div className="flex items-center gap-2.5">
+        <svg
+          className="w-6 h-6 text-violet-400"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <rect x="3" y="3" width="7" height="7" rx="1" />
+          <rect x="14" y="3" width="7" height="7" rx="1" />
+          <rect x="8" y="14" width="7" height="7" rx="1" />
+          <path d="M6.5 10v1.5a1 1 0 0 0 1 1h9a1 1 0 0 0 1-1V10" />
+          <path d="M11.5 12.5V14" />
+        </svg>
+        <h1 className="text-lg font-semibold tracking-tight text-zinc-100">
+          Flowbook
+        </h1>
+        <span className="text-xs text-zinc-500 bg-zinc-800/80 px-2 py-0.5 rounded-full font-medium">
+          {flowCount}
+        </span>
+      </div>
+      <div className="flex-1 max-w-md">
+        <input
+          type="text"
+          placeholder="Search flows…"
+          value={searchQuery}
+          onChange={(e) => onSearchChange(e.target.value)}
+          className="w-full bg-zinc-900 border border-zinc-800 rounded-lg px-3 py-1.5 text-sm placeholder-zinc-500 focus:outline-none focus:border-violet-500/60 focus:ring-1 focus:ring-violet-500/20 transition-all"
+        />
+      </div>
+    </header>
+  );
+}