flowbook 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +11 -1
  2. package/package.json +1 -1
  3. package/README.de.md +0 -219
  4. package/README.es.md +0 -219
  5. package/README.fr.md +0 -219
  6. package/README.ja.md +0 -219
  7. package/README.ko.md +0 -219
  8. package/README.pt-BR.md +0 -219
  9. package/README.ru.md +0 -220
  10. package/README.zh-CN.md +0 -219
package/README.ja.md DELETED
@@ -1,219 +0,0 @@
1
- # Flowbook
2
-
3
- > [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.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)
4
-
5
- フローチャートのための Storybook。コードベースから Mermaid ダイアグラムファイルを自動検出し、カテゴリ別に整理して、ブラウザで閲覧可能なビューアでレンダリングします。
6
-
7
- ![Vite](https://img.shields.io/badge/vite-6.x-646CFF?logo=vite&logoColor=white)
8
- ![React](https://img.shields.io/badge/react-19.x-61DAFB?logo=react&logoColor=white)
9
- ![Mermaid](https://img.shields.io/badge/mermaid-11.x-FF3670?logo=mermaid&logoColor=white)
10
- ![TypeScript](https://img.shields.io/badge/typescript-5.x-3178C6?logo=typescript&logoColor=white)
11
-
12
- ## クイックスタート
13
-
14
- ```bash
15
- # 初期化 — スクリプト + サンプルファイルを追加
16
- npx flowbook@latest init
17
-
18
- # 開発サーバーを起動
19
- npm run flowbook
20
- # → http://localhost:6200
21
-
22
- # 静的サイトをビルド
23
- npm run build-flowbook
24
- # → flowbook-static/
25
- ```
26
-
27
- ## CLI
28
-
29
- ```
30
- flowbook init プロジェクトに Flowbook をセットアップ
31
- flowbook dev [--port 6200] 開発サーバーを起動
32
- flowbook build [--out-dir d] 静的サイトをビルド
33
- ```
34
-
35
- ### `flowbook init`
36
-
37
- - `package.json` に `"flowbook"` と `"build-flowbook"` スクリプトを追加します
38
- - `flows/example.flow.md` をスターターテンプレートとして作成します
39
-
40
- ### `flowbook dev`
41
-
42
- `http://localhost:6200` で HMR 対応の Vite 開発サーバーを起動します。`.flow.md` や `.flowchart.md` ファイルの変更が即座に反映されます。
43
-
44
- ### `flowbook build`
45
-
46
- `flowbook-static/` ディレクトリに静的サイトをビルドします（`--out-dir` で変更可能）。どこにでもデプロイできます。
47
-
48
- ## フローファイルの作成
49
-
50
- プロジェクト内の任意の場所に `.flow.md`（または `.flowchart.md`）ファイルを作成してください：
51
-
52
- ````markdown
53
- ---
54
- title: ログインフロー
55
- category: 認証
56
- tags: [auth, login, oauth]
57
- order: 1
58
- description: OAuth2 を使用したユーザー認証フロー
59
- ---
60
-
61
- ```mermaid
62
- flowchart TD
63
- A[ユーザー] --> B{認証済み?}
64
- B -->|はい| C[ダッシュボード]
65
- B -->|いいえ| D[ログインページ]
66
- ```
67
- ````
68
-
69
- Flowbook がファイルを自動検出し、ビューアに追加します。
70
-
71
- ## フロントマタースキーマ
72
-
73
- | フィールド | 型 | 必須 | 説明 |
74
- |---------------|------------|--------|-------------------------------------|
75
- | `title` | `string` | いいえ | 表示タイトル（デフォルト: ファイル名）|
76
- | `category` | `string` | いいえ | サイドバーのカテゴリ（デフォルト: "Uncategorized"）|
77
- | `tags` | `string[]` | いいえ | フィルタリング可能なタグ |
78
- | `order` | `number` | いいえ | カテゴリ内の並び順（デフォルト: 999）|
79
- | `description` | `string` | いいえ | 詳細ビューに表示される説明 |
80
-
81
- ## ファイル検出
82
-
83
- Flowbook はデフォルトで以下のパターンをスキャンします：
84
-
85
- ```
86
- **/*.flow.md
87
- **/*.flowchart.md
88
- ```
89
-
90
- `node_modules/`、`.git/`、`dist/` は無視します。
91
-
92
- ## AI Agent Skill
93
-
94
- `flowbook init` はサポートされているすべてのコーディングエージェントディレクトリに AI エージェントスキルを自動的にインストールします。
95
- コーディングエージェント（Claude Code、OpenAI Codex、VS Code Copilot、Cursor、Gemini CLI など）がプロンプト内の **"flowbook"** キーワードを検出した場合、以下を実行します：
96
-
97
- 1. コードベース内の論理的なフローを分析（API ルート、認証、状態管理、ビジネスロジックなど）
98
- 2. まだ初期化されていない場合、Flowbook を設定
99
- 3. すべての重要なフローに対して Mermaid ダイアグラム付き `.flow.md` ファイルを生成
100
- 4. ビルドを検証
101
-
102
- ### CLI でスキルをインストール
103
-
104
- [skills.sh](https://skills.sh) を使用してスキルを単独でインストールすることもできます：
105
-
106
- ```bash
107
- npx skills add Epsilondelta-ai/flowbook
108
- ```
109
-
110
- インストール済みのコーディングエージェントを自動検出し、適切なディレクトリにスキルをインストールします。
111
-
112
- ### 互換性のあるエージェント
113
-
114
- | エージェント | スキル位置 |
115
- |-------|---------------|
116
- | Claude Code | `.claude/skills/flowbook/SKILL.md` |
117
- | OpenAI Codex | `.agents/skills/flowbook/SKILL.md` |
118
- | VS Code / GitHub Copilot | `.github/skills/flowbook/SKILL.md` |
119
- | Google Antigravity | `.agent/skills/flowbook/SKILL.md` |
120
- | Gemini CLI | `.gemini/skills/flowbook/SKILL.md` |
121
- | Cursor | `.cursor/skills/flowbook/SKILL.md` |
122
- | Windsurf (Codeium) | `.windsurf/skills/flowbook/SKILL.md` |
123
- | AmpCode | `.amp/skills/flowbook/SKILL.md` |
124
- | OpenCode / oh-my-opencode | `.opencode/skills/flowbook/SKILL.md` |
125
-
126
- <details>
127
- <summary>手動スキルインストール</summary>
128
-
129
- `flowbook init` や `npx skills add` を使用しなかった場合、スキルを手動でコピーしてください：
130
-
131
- ```bash
132
- # 例：Claude Code
133
- mkdir -p .claude/skills/flowbook
134
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .claude/skills/flowbook/
135
-
136
- # 例：Cursor
137
- mkdir -p .cursor/skills/flowbook
138
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .cursor/skills/flowbook/
139
- ```
140
-
141
- 上の互換性テーブルのパスを参考に、適切なディレクトリに置き換えてください。
142
-
143
- </details>
144
- ## 仕組み
145
-
146
- ```
147
- .flow.md ファイル ──→ Vite プラグイン ──→ 仮想モジュール ──→ React ビューア
148
- │ │
149
- ├─ fast-glob スキャン ├─ export default { flows: [...] }
150
- ├─ gray-matter │
151
- │ パース └─ ファイル変更時に HMR
152
- └─ mermaid ブロック
153
- 抽出
154
- ```
155
-
156
- 1. **検出** — `fast-glob` がプロジェクト内の `*.flow.md` / `*.flowchart.md` をスキャン
157
- 2. **パース** — `gray-matter` が YAML フロントマターを抽出；正規表現で `` ```mermaid `` ブロックを抽出
158
- 3. **仮想モジュール** — Vite プラグインがパースしたデータを `virtual:flowbook-data` として提供
159
- 4. **レンダリング** — React アプリが `mermaid.render()` で Mermaid ダイアグラムをレンダリング
160
- 5. **HMR** — ファイル変更時に仮想モジュールを無効化し、リロードをトリガー
161
-
162
- ## プロジェクト構成
163
-
164
- ```
165
- src/
166
- ├── types.ts # 共有型 (FlowEntry, FlowbookData)
167
- ├── node/
168
- │ ├── cli.ts # CLI エントリポイント (init, dev, build)
169
- │ ├── server.ts # プログラマティック Vite サーバー & ビルド
170
- │ ├── init.ts # プロジェクト初期化ロジック
171
- │ ├── discovery.ts # ファイルスキャナー (fast-glob)
172
- │ ├── parser.ts # フロントマター + mermaid 抽出
173
- │ └── plugin.ts # Vite 仮想モジュールプラグイン
174
- └── client/
175
- ├── index.html # エントリ HTML
176
- ├── main.tsx # React エントリ
177
- ├── App.tsx # 検索 + サイドバー + ビューアレイアウト
178
- ├── vite-env.d.ts # 仮想モジュール型宣言
179
- ├── styles/globals.css # Tailwind v4 + カスタムスタイル
180
- └── components/
181
- ├── Header.tsx # ロゴ、検索バー、フロー数
182
- ├── Sidebar.tsx # 折りたたみ可能なカテゴリツリー
183
- ├── MermaidRenderer.tsx # Mermaid ダイアグラムレンダリング
184
- ├── FlowView.tsx # 単一フロー詳細ビュー
185
- └── EmptyState.tsx # 空状態ガイド
186
- ```
187
-
188
- ## 開発（コントリビューション）
189
-
190
- ```bash
191
- git clone https://github.com/Epsilondelta-ai/flowbook.git
192
- cd flowbook
193
- npm install
194
-
195
- # ローカル開発（ルートの vite.config.ts を使用）
196
- npm run dev
197
-
198
- # CLI をビルド
199
- npm run build
200
-
201
- # ローカルで CLI をテスト
202
- node dist/cli.js dev
203
- node dist/cli.js build
204
- ```
205
-
206
- ## 技術スタック
207
-
208
- - **Vite** — HMR 対応開発サーバー
209
- - **React 19** — UI
210
- - **Mermaid 11** — ダイアグラムレンダリング
211
- - **Tailwind CSS v4** — スタイリング
212
- - **gray-matter** — YAML フロントマターパーサー
213
- - **fast-glob** — ファイル検出
214
- - **tsup** — CLI バンドラー
215
- - **TypeScript** — 型安全性
216
-
217
- ## ライセンス
218
-
219
- MIT
package/README.ko.md DELETED
@@ -1,219 +0,0 @@
1
- # Flowbook
2
-
3
- > **[English](./README.md)** | **한국어** | [简体中文](./README.zh-CN.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)
4
-
5
- 플로우차트를 위한 Storybook. 코드베이스에서 Mermaid 다이어그램 파일을 자동으로 발견하고, 카테고리별로 정리하여 브라우저에서 볼 수 있게 렌더링합니다.
6
-
7
- ![Vite](https://img.shields.io/badge/vite-6.x-646CFF?logo=vite&logoColor=white)
8
- ![React](https://img.shields.io/badge/react-19.x-61DAFB?logo=react&logoColor=white)
9
- ![Mermaid](https://img.shields.io/badge/mermaid-11.x-FF3670?logo=mermaid&logoColor=white)
10
- ![TypeScript](https://img.shields.io/badge/typescript-5.x-3178C6?logo=typescript&logoColor=white)
11
-
12
- ## 빠른 시작
13
-
14
- ```bash
15
- # 초기화 — 스크립트 + 예제 파일 추가
16
- npx flowbook@latest init
17
-
18
- # 개발 서버 실행
19
- npm run flowbook
20
- # → http://localhost:6200
21
-
22
- # 정적 사이트 빌드
23
- npm run build-flowbook
24
- # → flowbook-static/
25
- ```
26
-
27
- ## CLI
28
-
29
- ```
30
- flowbook init 프로젝트에 Flowbook 설정
31
- flowbook dev [--port 6200] 개발 서버 실행
32
- flowbook build [--out-dir d] 정적 사이트 빌드
33
- ```
34
-
35
- ### `flowbook init`
36
-
37
- - `package.json`에 `"flowbook"`, `"build-flowbook"` 스크립트를 추가합니다
38
- - `flows/example.flow.md` 예제 템플릿을 생성합니다
39
-
40
- ### `flowbook dev`
41
-
42
- `http://localhost:6200`에서 HMR이 지원되는 Vite 개발 서버를 실행합니다. `.flow.md` 또는 `.flowchart.md` 파일 변경 사항이 즉시 반영됩니다.
43
-
44
- ### `flowbook build`
45
-
46
- `flowbook-static/` 디렉토리에 정적 사이트를 빌드합니다 (`--out-dir`로 변경 가능). 어디서든 배포 가능합니다.
47
-
48
- ## 플로우 파일 작성
49
-
50
- 프로젝트 어디에서나 `.flow.md` (또는 `.flowchart.md`) 파일을 생성하세요:
51
-
52
- ````markdown
53
- ---
54
- title: 로그인 흐름
55
- category: 인증
56
- tags: [auth, login, oauth]
57
- order: 1
58
- description: OAuth2를 사용한 사용자 인증 흐름
59
- ---
60
-
61
- ```mermaid
62
- flowchart TD
63
- A[사용자] --> B{인증됨?}
64
- B -->|예| C[대시보드]
65
- B -->|아니오| D[로그인 페이지]
66
- ```
67
- ````
68
-
69
- Flowbook이 자동으로 파일을 발견하여 뷰어에 추가합니다.
70
-
71
- ## 프론트매터 스키마
72
-
73
- | 필드 | 타입 | 필수 | 설명 |
74
- |---------------|------------|------|-------------------------------------|
75
- | `title` | `string` | 아니오 | 표시 제목 (기본값: 파일명) |
76
- | `category` | `string` | 아니오 | 사이드바 카테고리 (기본값: "Uncategorized") |
77
- | `tags` | `string[]` | 아니오 | 필터링 가능한 태그 |
78
- | `order` | `number` | 아니오 | 카테고리 내 정렬 순서 (기본값: 999) |
79
- | `description` | `string` | 아니오 | 상세 보기에 표시되는 설명 |
80
-
81
- ## 파일 탐색
82
-
83
- Flowbook은 기본적으로 다음 패턴을 스캔합니다:
84
-
85
- ```
86
- **/*.flow.md
87
- **/*.flowchart.md
88
- ```
89
-
90
- `node_modules/`, `.git/`, `dist/`는 무시합니다.
91
-
92
- ## AI Agent Skill
93
-
94
- `flowbook init`은 지원하는 모든 코딩 에이전트 디렉토리에 AI 에이전트 스킬을 자동으로 설치합니다.
95
- 코딩 에이전트(Claude Code, OpenAI Codex, VS Code Copilot, Cursor, Gemini CLI 등)가 프롬프트에서 **"flowbook"** 키워드를 감지하면 다음을 수행합니다:
96
-
97
- 1. 코드베이스에서 논리적 흐름 분석 (API 라우트, 인증, 상태 관리, 비즈니스 로직 등)
98
- 2. 아직 초기화되지 않았으면 Flowbook 설정
99
- 3. 모든 중요한 흐름에 대해 Mermaid 다이어그램이 포함된 `.flow.md` 파일 생성
100
- 4. 빌드 검증
101
-
102
- ### CLI로 스킬 설치
103
-
104
- [skills.sh](https://skills.sh)를 사용하여 스킬을 독립적으로 설치할 수도 있습니다:
105
-
106
- ```bash
107
- npx skills add Epsilondelta-ai/flowbook
108
- ```
109
-
110
- 설치된 코딩 에이전트를 자동 감지하여 올바른 디렉토리에 스킬을 설치합니다.
111
-
112
- ### 호환 에이전트
113
-
114
- | 에이전트 | 스킬 위치 |
115
- |-------|---------------|
116
- | Claude Code | `.claude/skills/flowbook/SKILL.md` |
117
- | OpenAI Codex | `.agents/skills/flowbook/SKILL.md` |
118
- | VS Code / GitHub Copilot | `.github/skills/flowbook/SKILL.md` |
119
- | Google Antigravity | `.agent/skills/flowbook/SKILL.md` |
120
- | Gemini CLI | `.gemini/skills/flowbook/SKILL.md` |
121
- | Cursor | `.cursor/skills/flowbook/SKILL.md` |
122
- | Windsurf (Codeium) | `.windsurf/skills/flowbook/SKILL.md` |
123
- | AmpCode | `.amp/skills/flowbook/SKILL.md` |
124
- | OpenCode / oh-my-opencode | `.opencode/skills/flowbook/SKILL.md` |
125
-
126
- <details>
127
- <summary>수동 스킬 설치</summary>
128
-
129
- `flowbook init`이나 `npx skills add`를 사용하지 않았다면 스킬을 수동으로 복사하세요:
130
-
131
- ```bash
132
- # 예시: Claude Code
133
- mkdir -p .claude/skills/flowbook
134
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .claude/skills/flowbook/
135
-
136
- # 예시: Cursor
137
- mkdir -p .cursor/skills/flowbook
138
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .cursor/skills/flowbook/
139
- ```
140
-
141
- 위 호환 에이전트 테이블의 경로를 참고하여 적절한 디렉토리로 교체하세요.
142
-
143
- </details>
144
- ## 동작 원리
145
-
146
- ```
147
- .flow.md 파일 ──→ Vite 플러그인 ──→ 가상 모듈 ──→ React 뷰어
148
- │ │
149
- ├─ fast-glob 스캔 ├─ export default { flows: [...] }
150
- ├─ gray-matter │
151
- │ 파싱 └─ 파일 변경 시 HMR
152
- └─ mermaid 블록
153
- 추출
154
- ```
155
-
156
- 1. **탐색** — `fast-glob`이 프로젝트에서 `*.flow.md` / `*.flowchart.md`를 스캔
157
- 2. **파싱** — `gray-matter`가 YAML 프론트매터를 추출; 정규식으로 `` ```mermaid `` 블록 추출
158
- 3. **가상 모듈** — Vite 플러그인이 파싱된 데이터를 `virtual:flowbook-data`로 제공
159
- 4. **렌더링** — React 앱이 `mermaid.render()`를 통해 Mermaid 다이어그램 렌더링
160
- 5. **HMR** — 파일 변경 시 가상 모듈을 무효화하여 리로드 트리거
161
-
162
- ## 프로젝트 구조
163
-
164
- ```
165
- src/
166
- ├── types.ts # 공유 타입 (FlowEntry, FlowbookData)
167
- ├── node/
168
- │ ├── cli.ts # CLI 진입점 (init, dev, build)
169
- │ ├── server.ts # 프로그래밍 방식 Vite 서버 & 빌드
170
- │ ├── init.ts # 프로젝트 초기화 로직
171
- │ ├── discovery.ts # 파일 스캐너 (fast-glob)
172
- │ ├── parser.ts # 프론트매터 + mermaid 추출
173
- │ └── plugin.ts # Vite 가상 모듈 플러그인
174
- └── client/
175
- ├── index.html # 진입 HTML
176
- ├── main.tsx # React 진입점
177
- ├── App.tsx # 검색 + 사이드바 + 뷰어 레이아웃
178
- ├── vite-env.d.ts # 가상 모듈 타입 선언
179
- ├── styles/globals.css # Tailwind v4 + 커스텀 스타일
180
- └── components/
181
- ├── Header.tsx # 로고, 검색바, 플로우 개수
182
- ├── Sidebar.tsx # 접을 수 있는 카테고리 트리
183
- ├── MermaidRenderer.tsx # Mermaid 다이어그램 렌더링
184
- ├── FlowView.tsx # 단일 플로우 상세 보기
185
- └── EmptyState.tsx # 빈 상태 안내
186
- ```
187
-
188
- ## 개발 (기여)
189
-
190
- ```bash
191
- git clone https://github.com/Epsilondelta-ai/flowbook.git
192
- cd flowbook
193
- npm install
194
-
195
- # 로컬 개발 (루트 vite.config.ts 사용)
196
- npm run dev
197
-
198
- # CLI 빌드
199
- npm run build
200
-
201
- # 로컬에서 CLI 테스트
202
- node dist/cli.js dev
203
- node dist/cli.js build
204
- ```
205
-
206
- ## 기술 스택
207
-
208
- - **Vite** — HMR 지원 개발 서버
209
- - **React 19** — UI
210
- - **Mermaid 11** — 다이어그램 렌더링
211
- - **Tailwind CSS v4** — 스타일링
212
- - **gray-matter** — YAML 프론트매터 파싱
213
- - **fast-glob** — 파일 탐색
214
- - **tsup** — CLI 번들러
215
- - **TypeScript** — 타입 안전성
216
-
217
- ## 라이선스
218
-
219
- MIT
package/README.pt-BR.md DELETED
@@ -1,219 +0,0 @@
1
- # Flowbook
2
-
3
- > [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [Español](./README.es.md) | **Português (BR)** | [Français](./README.fr.md) | [Русский](./README.ru.md) | [Deutsch](./README.de.md)
4
-
5
- Storybook para fluxogramas. Descobre automaticamente arquivos de diagramas Mermaid no seu código, organiza por categoria e renderiza em um visualizador navegável.
6
-
7
- ![Vite](https://img.shields.io/badge/vite-6.x-646CFF?logo=vite&logoColor=white)
8
- ![React](https://img.shields.io/badge/react-19.x-61DAFB?logo=react&logoColor=white)
9
- ![Mermaid](https://img.shields.io/badge/mermaid-11.x-FF3670?logo=mermaid&logoColor=white)
10
- ![TypeScript](https://img.shields.io/badge/typescript-5.x-3178C6?logo=typescript&logoColor=white)
11
-
12
- ## Início Rápido
13
-
14
- ```bash
15
- # Inicializar — adiciona scripts + arquivo de exemplo
16
- npx flowbook@latest init
17
-
18
- # Iniciar servidor de desenvolvimento
19
- npm run flowbook
20
- # → http://localhost:6200
21
-
22
- # Construir site estático
23
- npm run build-flowbook
24
- # → flowbook-static/
25
- ```
26
-
27
- ## CLI
28
-
29
- ```
30
- flowbook init Configurar Flowbook no seu projeto
31
- flowbook dev [--port 6200] Iniciar o servidor de desenvolvimento
32
- flowbook build [--out-dir d] Construir um site estático
33
- ```
34
-
35
- ### `flowbook init`
36
-
37
- - Adiciona os scripts `"flowbook"` e `"build-flowbook"` ao seu `package.json`
38
- - Cria `flows/example.flow.md` como template inicial
39
-
40
- ### `flowbook dev`
41
-
42
- Inicia um servidor de desenvolvimento Vite em `http://localhost:6200` com HMR. Qualquer alteração em arquivos `.flow.md` ou `.flowchart.md` é refletida instantaneamente.
43
-
44
- ### `flowbook build`
45
-
46
- Constrói um site estático em `flowbook-static/` (configurável via `--out-dir`). Faça deploy em qualquer lugar.
47
-
48
- ## Escrevendo Arquivos de Fluxo
49
-
50
- Crie um arquivo `.flow.md` (ou `.flowchart.md`) em qualquer lugar do seu projeto:
51
-
52
- ````markdown
53
- ---
54
- title: Fluxo de Login
55
- category: Autenticação
56
- tags: [auth, login, oauth]
57
- order: 1
58
- description: Fluxo de autenticação de usuário com OAuth2
59
- ---
60
-
61
- ```mermaid
62
- flowchart TD
63
- A[Usuário] --> B{Autenticado?}
64
- B -->|Sim| C[Dashboard]
65
- B -->|Não| D[Página de Login]
66
- ```
67
- ````
68
-
69
- O Flowbook descobre automaticamente o arquivo e o adiciona ao visualizador.
70
-
71
- ## Schema do Frontmatter
72
-
73
- | Campo | Tipo | Obrigatório | Descrição |
74
- |---------------|------------|-------------|----------------------------------------|
75
- | `title` | `string` | Não | Título exibido (padrão: nome do arquivo) |
76
- | `category` | `string` | Não | Categoria na barra lateral (padrão: "Uncategorized") |
77
- | `tags` | `string[]` | Não | Tags filtráveis |
78
- | `order` | `number` | Não | Ordem dentro da categoria (padrão: 999)|
79
- | `description` | `string` | Não | Descrição na visualização detalhada |
80
-
81
- ## Descoberta de Arquivos
82
-
83
- O Flowbook escaneia estes padrões por padrão:
84
-
85
- ```
86
- **/*.flow.md
87
- **/*.flowchart.md
88
- ```
89
-
90
- Ignora `node_modules/`, `.git/` e `dist/`.
91
-
92
- ## Habilidade de Agente IA
93
-
94
- `flowbook init` instala automaticamente habilidades de agente IA em todos os diretórios de agentes de codificação suportados.
95
- Quando um agente de codificação (Claude Code, OpenAI Codex, VS Code Copilot, Cursor, Gemini CLI, etc.) detecta a palavra-chave **"flowbook"** no seu prompt, ele irá:
96
-
97
- 1. Analisar sua base de código em busca de fluxos lógicos (rotas de API, autenticação, gerenciamento de estado, lógica de negócios, etc.)
98
- 2. Configurar Flowbook se ainda não estiver inicializado
99
- 3. Gerar arquivos `.flow.md` com diagramas Mermaid para cada fluxo significativo
100
- 4. Verificar a compilação
101
-
102
- ### Instalar Habilidade via CLI
103
-
104
- Você também pode instalar a habilidade de forma independente usando [skills.sh](https://skills.sh):
105
-
106
- ```bash
107
- npx skills add Epsilondelta-ai/flowbook
108
- ```
109
-
110
- Detecta automaticamente seus agentes de codificação instalados e instala a habilidade nos diretórios corretos.
111
-
112
- ### Agentes Compatíveis
113
-
114
- | Agente | Local da Habilidade |
115
- |-------|---------------|
116
- | Claude Code | `.claude/skills/flowbook/SKILL.md` |
117
- | OpenAI Codex | `.agents/skills/flowbook/SKILL.md` |
118
- | VS Code / GitHub Copilot | `.github/skills/flowbook/SKILL.md` |
119
- | Google Antigravity | `.agent/skills/flowbook/SKILL.md` |
120
- | Gemini CLI | `.gemini/skills/flowbook/SKILL.md` |
121
- | Cursor | `.cursor/skills/flowbook/SKILL.md` |
122
- | Windsurf (Codeium) | `.windsurf/skills/flowbook/SKILL.md` |
123
- | AmpCode | `.amp/skills/flowbook/SKILL.md` |
124
- | OpenCode / oh-my-opencode | `.opencode/skills/flowbook/SKILL.md` |
125
-
126
- <details>
127
- <summary>Instalação Manual de Habilidade</summary>
128
-
129
- Se você não usou `flowbook init` nem `npx skills add`, copie a habilidade manualmente:
130
-
131
- ```bash
132
- # Exemplo: Claude Code
133
- mkdir -p .claude/skills/flowbook
134
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .claude/skills/flowbook/
135
-
136
- # Exemplo: Cursor
137
- mkdir -p .cursor/skills/flowbook
138
- cp node_modules/flowbook/src/skills/flowbook/SKILL.md .cursor/skills/flowbook/
139
- ```
140
-
141
- Substitua o diretório pelo caminho apropriado da tabela de Agentes Compatíveis.
142
-
143
- </details>
144
- ## Como Funciona
145
-
146
- ```
147
- arquivos .flow.md ──→ Plugin Vite ──→ Módulo Virtual ──→ Visualizador React
148
- │ │
149
- ├─ scan fast-glob ├─ export default { flows: [...] }
150
- ├─ gray-matter │
151
- │ parsing └─ HMR na alteração de arquivo
152
- └─ bloco mermaid
153
- extração
154
- ```
155
-
156
- 1. **Descoberta** — `fast-glob` escaneia o projeto procurando `*.flow.md` / `*.flowchart.md`
157
- 2. **Parsing** — `gray-matter` extrai o frontmatter YAML; regex extrai blocos `` ```mermaid ``
158
- 3. **Módulo Virtual** — Plugin Vite serve os dados parseados como `virtual:flowbook-data`
159
- 4. **Renderização** — App React renderiza diagramas Mermaid via `mermaid.render()`
160
- 5. **HMR** — Alterações de arquivo invalidam o módulo virtual, disparando um reload
161
-
162
- ## Estrutura do Projeto
163
-
164
- ```
165
- src/
166
- ├── types.ts # Tipos compartilhados (FlowEntry, FlowbookData)
167
- ├── node/
168
- │ ├── cli.ts # Ponto de entrada CLI (init, dev, build)
169
- │ ├── server.ts # Servidor Vite programático e build
170
- │ ├── init.ts # Lógica de inicialização do projeto
171
- │ ├── discovery.ts # Scanner de arquivos (fast-glob)
172
- │ ├── parser.ts # Extração de frontmatter + mermaid
173
- │ └── plugin.ts # Plugin de módulo virtual do Vite
174
- └── client/
175
- ├── index.html # HTML de entrada
176
- ├── main.tsx # Entrada React
177
- ├── App.tsx # Layout com busca + barra lateral + visualizador
178
- ├── vite-env.d.ts # Declarações de tipo do módulo virtual
179
- ├── styles/globals.css # Tailwind v4 + estilos customizados
180
- └── components/
181
- ├── Header.tsx # Logo, barra de busca, contagem de fluxos
182
- ├── Sidebar.tsx # Árvore de categorias colapsável
183
- ├── MermaidRenderer.tsx # Renderização de diagramas Mermaid
184
- ├── FlowView.tsx # Visualização detalhada de fluxo individual
185
- └── EmptyState.tsx # Estado vazio com guia
186
- ```
187
-
188
- ## Desenvolvimento (Contribuição)
189
-
190
- ```bash
191
- git clone https://github.com/Epsilondelta-ai/flowbook.git
192
- cd flowbook
193
- npm install
194
-
195
- # Desenvolvimento local (usa o vite.config.ts raiz)
196
- npm run dev
197
-
198
- # Construir CLI
199
- npm run build
200
-
201
- # Testar CLI localmente
202
- node dist/cli.js dev
203
- node dist/cli.js build
204
- ```
205
-
206
- ## Stack Tecnológico
207
-
208
- - **Vite** — Servidor de desenvolvimento com HMR
209
- - **React 19** — UI
210
- - **Mermaid 11** — Renderização de diagramas
211
- - **Tailwind CSS v4** — Estilização
212
- - **gray-matter** — Parsing de frontmatter YAML
213
- - **fast-glob** — Descoberta de arquivos
214
- - **tsup** — Bundler de CLI
215
- - **TypeScript** — Segurança de tipos
216
-
217
- ## Licença
218
-
219
- MIT