spec-snake 0.0.1-beta.0

package/README.ja.md

@@ -0,0 +1,333 @@
+# Spec Snake Beta
+
+AI を活用した設計ドキュメントジェネレーター
+
+- Config Base
+  - TypeScript の設定ファイルでシナリオ、フォーム、プロンプトを定義
+- Multi Step Form
+  - ステップ形式のフォームで必要な情報を段階的に収集
+- AI Generation
+  - Claude Agent SDK を使用し、収集した情報から高品質なドキュメントを生成
+- MCP Integration
+  - Figma などの外部ツールと連携して、より詳細なドキュメントを生成可能
+
+## コンセプト
+
+下記の 3 つの概念を基本としてドキュメントを管理します。
+
+- Scenario
+  - ドキュメントの種類を表す単位。技術設計書、実装方針など、目的ごとにシナリオを定義する
+- Step
+  - シナリオ内のフォーム入力ステップ。複数のステップで情報を段階的に収集する
+- Document
+  - 生成されるマークダウン形式のドキュメント。フォーム入力と AI によって生成される
+
+## インストール
+
+```bash
+pnpm add @cut0/spec-snake
+```
+
+**Note**: GitHub Packages で公開されている
+
+## 環境
+
+- **Node.js**: 18 以上
+- **Claude Code**: [Claude Code](https://claude.ai/code) がインストールされている必要があります。
+
+## CLI コマンド
+
+### `init` - 設定ファイルの初期化
+
+新しい設定ファイルを作成します。
+
+```bash
+npx spec-snake-beta init
+```
+
+オプション:
+
+| オプション | エイリアス | デフォルト             | 説明                 |
+| ---------- | ---------- | ---------------------- | -------------------- |
+| `--output` | `-o`       | `spec-snake.config.ts` | 出力ファイルパス     |
+| `--force`  | `-f`       | `false`                | 既存ファイルを上書き |
+
+例:
+
+```bash
+# デフォルトのファイル名で作成
+npx spec-snake-beta init
+
+# カスタムファイル名で作成
+npx spec-snake-beta init -o my-config.ts
+
+# 既存ファイルを上書き
+npx spec-snake-beta init -f
+```
+
+### `start` - サーバーの起動
+
+設定ファイルを読み込み、Web UI サーバーを起動します。
+
+```bash
+npx spec-snake-beta start
+```
+
+オプション:
+
+| オプション | エイリアス | デフォルト             | 説明                 |
+| ---------- | ---------- | ---------------------- | -------------------- |
+| `--config` | `-c`       | `spec-snake.config.ts` | 設定ファイルのパス   |
+| `--port`   | `-p`       | `3000`                 | サーバーのポート番号 |
+| `--host`   | -          | `localhost`            | バインドするホスト   |
+
+例:
+
+```bash
+# デフォルト設定で起動
+npx spec-snake-beta start
+
+# カスタム設定ファイルとポートで起動
+npx spec-snake-beta start -c my-config.ts -p 8080
+
+# すべてのインターフェースでリッスン
+npx spec-snake-beta start --host 0.0.0.0
+```
+
+## 設定ファイル
+
+### 設定ファイルの例
+
+設定ファイル例は [`examples/`](./examples/) ディレクトリを参照してください。
+
+- [`examples/spec-snake.ts`](./examples/spec-snake-ja.ts) - 基本的な設定例
+
+また、設定可能な項目は [src/types.ts](./src/types.ts) を参照してください。
+
+### 設定構造
+
+```typescript
+import { defineConfig, defineScenario } from '@cut0/spec-snake';
+
+export default defineConfig({
+  scenarios: [
+    defineScenario({
+      id: 'design-doc',
+      name: '設計ドキュメント',
+      steps: [
+        {
+          slug: 'overview',
+          title: '概要',
+          description: 'プロジェクトの概要',
+          section: {
+            type: 'single',
+            name: 'overview',
+            fields: [
+              { id: 'title', type: 'input', label: 'タイトル', description: '' },
+            ],
+          },
+        },
+      ],
+      prompt: '...',
+      outputDir: 'docs',
+      overrides: {
+        filename: ({ formData, timestamp }) =>
+          `${formData.overview?.title ?? 'untitled'}-${timestamp}.md`,
+      },
+    }),
+  ],
+  permissions: {
+    allowSave: true,
+  },
+});
+```
+
+### 型定義
+
+**`Config`** - ルート設定オブジェクト
+
+| プロパティ    | 型            | 必須 | 説明                     |
+| ------------- | ------------- | ---- | ------------------------ |
+| `scenarios`   | `Scenario[]`  | Yes  | 利用可能なシナリオの配列 |
+| `permissions` | `Permissions` | Yes  | グローバル権限設定       |
+
+**`Permissions`** - 権限設定
+
+| プロパティ  | 型        | 説明                           |
+| ----------- | --------- | ------------------------------ |
+| `allowSave` | `boolean` | ドキュメントの保存を許可するか |
+
+**`Scenario`** - シナリオ定義。各シナリオは 1 つのドキュメントタイプを表す
+
+| プロパティ   | 型                   | 必須 | 説明                                    |
+| ------------ | -------------------- | ---- | --------------------------------------- |
+| `id`         | `string`             | Yes  | URL で使用される一意の識別子            |
+| `name`       | `string`             | Yes  | 表示名                                  |
+| `steps`      | `Step[]`             | Yes  | フォームウィザードのステップ            |
+| `prompt`     | `string \| Function` | Yes  | Claude に送信するプロンプトテンプレート |
+| `outputDir`  | `string`             | No   | ドキュメントの保存先ディレクトリ        |
+| `aiSettings` | `AiSettings`         | No   | Claude Agent SDK の設定                 |
+| `hooks`      | `ScenarioHooks`      | No   | ライフサイクルフック                    |
+| `overrides`  | `ScenarioOverrides`  | No   | デフォルト動作のオーバーライド          |
+
+**`Step`** - マルチステップフォームの各ステップ
+
+| プロパティ    | 型        | 必須 | 説明                                 |
+| ------------- | --------- | ---- | ------------------------------------ |
+| `slug`        | `string`  | Yes  | URL フレンドリーな識別子             |
+| `title`       | `string`  | Yes  | ステップヘッダーに表示されるタイトル |
+| `description` | `string`  | Yes  | タイトル下に表示される説明文         |
+| `section`     | `Section` | Yes  | ステップのフィールドを含むセクション |
+
+### `Section` - セクションは 2 種類
+
+SingleSection - 1 回だけ入力するフィールドのグループ
+
+```typescript
+{
+  type: 'single',
+  name: 'overview',
+  fields: [...]
+}
+```
+
+ArraySection - 複数のエントリを追加できるフィールドのグループ
+
+```typescript
+{
+  type: 'array',
+  name: 'requirements',
+  fields: [...],
+  minFieldCount: 1  // 最小エントリ数（オプション）
+}
+```
+
+### フィールドタイプ
+
+#### InputField - テキスト入力
+
+```typescript
+{
+  type: 'input',
+  id: 'title',
+  label: 'タイトル',
+  description: 'フィールドの説明',
+  placeholder: 'プレースホルダー',
+  required: true,
+  inputType: 'text' | 'date' | 'url',
+  suggestions: ['候補1', '候補2']
+}
+```
+
+#### TextareaField - 複数行テキスト
+
+```typescript
+{
+  type: 'textarea',
+  id: 'description',
+  label: '説明',
+  description: 'フィールドの説明',
+  rows: 4
+}
+```
+
+#### SelectField - ドロップダウン選択
+
+```typescript
+{
+  type: 'select',
+  id: 'priority',
+  label: '優先度',
+  description: 'フィールドの説明',
+  options: [
+    { value: 'high', label: '高' },
+    { value: 'medium', label: '中' },
+    { value: 'low', label: '低' }
+  ]
+}
+```
+
+#### CheckboxField - チェックボックス
+
+```typescript
+{
+  type: 'checkbox',
+  id: 'agree',
+  label: '同意する',
+  description: 'フィールドの説明'
+}
+```
+
+### `AiSettings` - Claude Agent SDK の設定オプション
+
+| プロパティ                        | 型                                | 説明                                                      |
+| --------------------------------- | --------------------------------- | --------------------------------------------------------- |
+| `model`                           | `string`                          | 使用するモデル（例: `claude-sonnet-4-5-20250929`）        |
+| `fallbackModel`                   | `string`                          | フォールバックモデル                                      |
+| `maxTurns`                        | `number`                          | 最大ターン数                                              |
+| `maxBudgetUsd`                    | `number`                          | USD での予算上限                                          |
+| `tools`                           | `object`                          | ツール設定（`{ type: 'preset', preset: 'claude_code' }`） |
+| `allowedTools`                    | `string[]`                        | 許可するツール                                            |
+| `disallowedTools`                 | `string[]`                        | 禁止するツール                                            |
+| `permissionMode`                  | `PermissionMode`                  | 権限モード                                                |
+| `allowDangerouslySkipPermissions` | `boolean`                         | 権限チェックをスキップ                                    |
+| `mcpServers`                      | `Record<string, McpServerConfig>` | MCP サーバー設定                                          |
+
+#### 利用可能なツール
+
+- ファイル操作: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`
+- コマンド実行: `Bash`
+- Web: `WebSearch`, `WebFetch`
+- エージェント: `Task`, `TodoWrite`
+- コード補完: `LSP`
+- MCP ツール: `mcp__<server>__<tool>` 形式
+
+### `scenario.hooks` - ライフサイクルフック
+
+```typescript
+{
+  // プレビュー生成後に呼ばれる
+  onPreview: async ({ formData, content }) => {
+    console.log('Preview generated');
+  },
+  // ドキュメント保存後に呼ばれる
+  onSave: async ({ content, filename, outputPath, formData }) => {
+    console.log(`Saved to ${outputPath}`);
+  }
+}
+```
+
+### `scenario.overrides` - デフォルト動作のオーバーライド
+
+```typescript
+{
+  // 静的ファイル名
+  filename: 'design-doc.md',
+  // または動的ファイル名
+  filename: ({ formData, timestamp }) =>
+    `${formData.project_name}-${timestamp}.md`
+}
+```
+
+### プロンプトテンプレート
+
+プロンプト内で `{{INPUT_JSON}}` を使用すると、フォームデータが JSON 形式で挿入されます。
+
+```typescript
+const prompt = `以下の入力に基づいて設計ドキュメントを生成してください。
+
+{{INPUT_JSON}}
+
+マークダウン形式で出力してください。`;
+```
+
+プロンプトは関数としても定義可能です。
+
+```typescript
+const prompt = ({ formData }) =>
+  `${formData.doc_type} ドキュメントを生成: {{INPUT_JSON}}`;
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,335 @@
+# Spec Snake Beta
+
+AI-powered design document generator
+
+[日本語版](./README.ja.md)
+
+- Config Base
+  - Define scenarios, forms, and prompts in TypeScript config files
+- Multi Step Form
+  - Collect required information step by step through wizard-style forms
+- AI Generation
+  - Generate high-quality documents from collected information using Claude Agent SDK
+- MCP Integration
+  - Connect with external tools like Figma to generate more detailed documents
+
+## Concept
+
+Documents are managed based on three core concepts:
+
+- Scenario
+  - A unit representing the type of document. Define scenarios for each purpose such as technical design docs, implementation plans, etc.
+- Step
+  - Form input steps within a scenario. Collect information progressively through multiple steps
+- Document
+  - The generated markdown document. Created from form input and AI
+
+## Installation
+
+```bash
+pnpm add @cut0/spec-snake
+```
+
+**Note**: Published on GitHub Packages
+
+## Requirements
+
+- **Node.js**: 18 or higher
+- **Claude Code**: [Claude Code](https://claude.ai/code) must be installed
+
+## CLI Commands
+
+### `init` - Initialize config file
+
+Creates a new config file.
+
+```bash
+npx spec-snake-beta init
+```
+
+Options:
+
+| Option     | Alias | Default                | Description              |
+| ---------- | ----- | ---------------------- | ------------------------ |
+| `--output` | `-o`  | `spec-snake.config.ts` | Output file path         |
+| `--force`  | `-f`  | `false`                | Overwrite existing files |
+
+Examples:
+
+```bash
+# Create with default filename
+npx spec-snake-beta init
+
+# Create with custom filename
+npx spec-snake-beta init -o my-config.ts
+
+# Overwrite existing file
+npx spec-snake-beta init -f
+```
+
+### `start` - Start the server
+
+Loads the config file and starts the Web UI server.
+
+```bash
+npx spec-snake-beta start
+```
+
+Options:
+
+| Option     | Alias | Default                | Description      |
+| ---------- | ----- | ---------------------- | ---------------- |
+| `--config` | `-c`  | `spec-snake.config.ts` | Config file path |
+| `--port`   | `-p`  | `3000`                 | Server port      |
+| `--host`   | -     | `localhost`            | Host to bind     |
+
+Examples:
+
+```bash
+# Start with default settings
+npx spec-snake-beta start
+
+# Start with custom config and port
+npx spec-snake-beta start -c my-config.ts -p 8080
+
+# Listen on all interfaces
+npx spec-snake-beta start --host 0.0.0.0
+```
+
+## Config File
+
+### Config Examples
+
+See the [`examples/`](./examples/) directory for config file examples.
+
+- [`examples/spec-snake.ts`](./examples/spec-snake-ja.ts) - Basic config example
+
+Also refer to [src/types.ts](./src/types.ts) for configurable options.
+
+### Config Structure
+
+```typescript
+import { defineConfig, defineScenario } from '@cut0/spec-snake';
+
+export default defineConfig({
+  scenarios: [
+    defineScenario({
+      id: 'design-doc',
+      name: 'Design Document',
+      steps: [
+        {
+          slug: 'overview',
+          title: 'Overview',
+          description: 'Project overview',
+          section: {
+            type: 'single',
+            name: 'overview',
+            fields: [
+              { id: 'title', type: 'input', label: 'Title', description: '' },
+            ],
+          },
+        },
+      ],
+      prompt: '...',
+      outputDir: 'docs',
+      overrides: {
+        filename: ({ formData, timestamp }) =>
+          `${formData.overview?.title ?? 'untitled'}-${timestamp}.md`,
+      },
+    }),
+  ],
+  permissions: {
+    allowSave: true,
+  },
+});
+```
+
+### Type Definitions
+
+**`Config`** - Root config object
+
+| Property      | Type          | Required | Description              |
+| ------------- | ------------- | -------- | ------------------------ |
+| `scenarios`   | `Scenario[]`  | Yes      | Array of scenarios       |
+| `permissions` | `Permissions` | Yes      | Global permission config |
+
+**`Permissions`** - Permission settings
+
+| Property    | Type      | Description                    |
+| ----------- | --------- | ------------------------------ |
+| `allowSave` | `boolean` | Whether to allow saving docs   |
+
+**`Scenario`** - Scenario definition. Each scenario represents one document type
+
+| Property     | Type                 | Required | Description                          |
+| ------------ | -------------------- | -------- | ------------------------------------ |
+| `id`         | `string`             | Yes      | Unique identifier used in URL        |
+| `name`       | `string`             | Yes      | Display name                         |
+| `steps`      | `Step[]`             | Yes      | Form wizard steps                    |
+| `prompt`     | `string \| Function` | Yes      | Prompt template sent to Claude       |
+| `outputDir`  | `string`             | No       | Directory for saving documents       |
+| `aiSettings` | `AiSettings`         | No       | Claude Agent SDK settings            |
+| `hooks`      | `ScenarioHooks`      | No       | Lifecycle hooks                      |
+| `overrides`  | `ScenarioOverrides`  | No       | Override default behaviors           |
+
+**`Step`** - Each step in the multi-step form
+
+| Property      | Type      | Required | Description                        |
+| ------------- | --------- | -------- | ---------------------------------- |
+| `slug`        | `string`  | Yes      | URL-friendly identifier            |
+| `title`       | `string`  | Yes      | Title displayed in step header     |
+| `description` | `string`  | Yes      | Description shown below title      |
+| `section`     | `Section` | Yes      | Section containing step fields     |
+
+### `Section` - Two types available
+
+SingleSection - A group of fields entered once
+
+```typescript
+{
+  type: 'single',
+  name: 'overview',
+  fields: [...]
+}
+```
+
+ArraySection - A group of fields that can have multiple entries
+
+```typescript
+{
+  type: 'array',
+  name: 'requirements',
+  fields: [...],
+  minFieldCount: 1  // Minimum entries (optional)
+}
+```
+
+### Field Types
+
+#### InputField - Text input
+
+```typescript
+{
+  type: 'input',
+  id: 'title',
+  label: 'Title',
+  description: 'Field description',
+  placeholder: 'Placeholder',
+  required: true,
+  inputType: 'text' | 'date' | 'url',
+  suggestions: ['Option 1', 'Option 2']
+}
+```
+
+#### TextareaField - Multi-line text
+
+```typescript
+{
+  type: 'textarea',
+  id: 'description',
+  label: 'Description',
+  description: 'Field description',
+  rows: 4
+}
+```
+
+#### SelectField - Dropdown select
+
+```typescript
+{
+  type: 'select',
+  id: 'priority',
+  label: 'Priority',
+  description: 'Field description',
+  options: [
+    { value: 'high', label: 'High' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'low', label: 'Low' }
+  ]
+}
+```
+
+#### CheckboxField - Checkbox
+
+```typescript
+{
+  type: 'checkbox',
+  id: 'agree',
+  label: 'I agree',
+  description: 'Field description'
+}
+```
+
+### `AiSettings` - Claude Agent SDK settings
+
+| Property                          | Type                              | Description                                               |
+| --------------------------------- | --------------------------------- | --------------------------------------------------------- |
+| `model`                           | `string`                          | Model to use (e.g., `claude-sonnet-4-5-20250929`)         |
+| `fallbackModel`                   | `string`                          | Fallback model                                            |
+| `maxTurns`                        | `number`                          | Maximum turns                                             |
+| `maxBudgetUsd`                    | `number`                          | Budget limit in USD                                       |
+| `tools`                           | `object`                          | Tool settings (`{ type: 'preset', preset: 'claude_code' }`) |
+| `allowedTools`                    | `string[]`                        | Allowed tools                                             |
+| `disallowedTools`                 | `string[]`                        | Disallowed tools                                          |
+| `permissionMode`                  | `PermissionMode`                  | Permission mode                                           |
+| `allowDangerouslySkipPermissions` | `boolean`                         | Skip permission checks                                    |
+| `mcpServers`                      | `Record<string, McpServerConfig>` | MCP server config                                         |
+
+#### Available Tools
+
+- File operations: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `NotebookEdit`
+- Command execution: `Bash`
+- Web: `WebSearch`, `WebFetch`
+- Agents: `Task`, `TodoWrite`
+- Code completion: `LSP`
+- MCP tools: `mcp__<server>__<tool>` format
+
+### `scenario.hooks` - Lifecycle hooks
+
+```typescript
+{
+  // Called after preview generation
+  onPreview: async ({ formData, content }) => {
+    console.log('Preview generated');
+  },
+  // Called after document save
+  onSave: async ({ content, filename, outputPath, formData }) => {
+    console.log(`Saved to ${outputPath}`);
+  }
+}
+```
+
+### `scenario.overrides` - Override default behaviors
+
+```typescript
+{
+  // Static filename
+  filename: 'design-doc.md',
+  // Or dynamic filename
+  filename: ({ formData, timestamp }) =>
+    `${formData.project_name}-${timestamp}.md`
+}
+```
+
+### Prompt Template
+
+Use `{{INPUT_JSON}}` in prompts to insert form data as JSON.
+
+```typescript
+const prompt = `Generate a design document based on the following input.
+
+{{INPUT_JSON}}
+
+Output in markdown format.`;
+```
+
+Prompts can also be defined as functions.
+
+```typescript
+const prompt = ({ formData }) =>
+  `Generate ${formData.doc_type} document: {{INPUT_JSON}}`;
+```
+
+## License
+
+MIT