@mind-fold/open-flow 0.1.0

package/dist/configurators/workflow.js

@@ -0,0 +1,739 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export async function createWorkflowStructure(cwd) {
+    const workflowDir = path.join(cwd, 'workflow');
+    // Create directories
+    const dirs = [
+        'workflow',
+        'workflow/scripts',
+        'workflow/agent-progress',
+        'workflow/structure',
+        'workflow/structure/frontend',
+        'workflow/structure/backend',
+    ];
+    for (const dir of dirs) {
+        fs.mkdirSync(path.join(cwd, dir), { recursive: true });
+    }
+    // Create scripts
+    await createScripts(cwd);
+    // Create agent-progress index
+    await createAgentProgressIndex(cwd);
+    // Create structure templates
+    await createStructureTemplates(cwd);
+    // Create feature.json
+    await createFeatureJson(cwd);
+    // Create flow.md
+    await createFlowMd(cwd);
+    // Create .gitignore for workflow
+    await createWorkflowGitignore(cwd);
+}
+async function createScripts(cwd) {
+    const initDeveloperScript = `#!/bin/bash
+
+# Initialize developer identity for open-flow
+# Usage: ./workflow/scripts/init-developer.sh <developer-name>
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+WORKFLOW_DIR="$(dirname "$SCRIPT_DIR")"
+
+if [ -z "$1" ]; then
+    echo "Usage: $0 <developer-name>"
+    echo "Example: $0 john-doe"
+    exit 1
+fi
+
+DEVELOPER_NAME="$1"
+DEVELOPER_FILE="$WORKFLOW_DIR/.developer"
+PROGRESS_DIR="$WORKFLOW_DIR/agent-progress/$DEVELOPER_NAME"
+
+# Check if already initialized
+if [ -f "$DEVELOPER_FILE" ]; then
+    CURRENT=$(cat "$DEVELOPER_FILE" | grep "name:" | cut -d' ' -f2)
+    echo "Already initialized as: $CURRENT"
+    read -p "Override with $DEVELOPER_NAME? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 0
+    fi
+fi
+
+# Create developer identity file
+cat > "$DEVELOPER_FILE" << EOF
+# Developer Identity (gitignored)
+# Created by open-flow
+
+name: $DEVELOPER_NAME
+created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+EOF
+
+# Create progress directory
+mkdir -p "$PROGRESS_DIR"
+
+# Create personal index
+cat > "$PROGRESS_DIR/index.md" << EOF
+# Agent Progress - $DEVELOPER_NAME
+
+> Personal progress tracking for $DEVELOPER_NAME
+
+## Current Status
+
+- **Active File**: \\\`progress-1.md\\\`
+- **Total Sessions**: 0
+- **Last Active**: $(date +%Y-%m-%d)
+
+## Active Documents
+
+| File | Lines | Status |
+|------|-------|--------|
+| \\\`progress-1.md\\\` | ~0 | Active |
+
+## Session History (Recent)
+
+| Session | Date | Title | Commit |
+|---------|------|-------|--------|
+| - | - | - | - |
+
+---
+
+## Notes
+
+- Each progress file has max 2000 lines
+- When exceeded, create new file and archive old one
+- Update this index when creating new files
+EOF
+
+# Create initial progress file
+cat > "$PROGRESS_DIR/progress-1.md" << EOF
+# Progress Record - $DEVELOPER_NAME
+
+> Session-by-session work log
+
+---
+
+## Session 1 - $(date +%Y-%m-%d)
+
+### Summary
+Initial setup
+
+### Main Changes
+- Initialized developer identity
+
+### Git Commits
+- N/A (initial setup)
+
+### Next Steps
+- Start first development task
+
+---
+EOF
+
+echo "✅ Developer identity initialized: $DEVELOPER_NAME"
+echo "   Progress directory: $PROGRESS_DIR"
+`;
+    const getDeveloperScript = `#!/bin/bash
+
+# Get current developer identity
+# Usage: ./workflow/scripts/get-developer.sh
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+WORKFLOW_DIR="$(dirname "$SCRIPT_DIR")"
+DEVELOPER_FILE="$WORKFLOW_DIR/.developer"
+
+if [ ! -f "$DEVELOPER_FILE" ]; then
+    echo "Not initialized. Run: ./workflow/scripts/init-developer.sh <your-name>" >&2
+    exit 1
+fi
+
+cat "$DEVELOPER_FILE" | grep "name:" | cut -d' ' -f2
+`;
+    fs.writeFileSync(path.join(cwd, 'workflow/scripts/init-developer.sh'), initDeveloperScript);
+    fs.writeFileSync(path.join(cwd, 'workflow/scripts/get-developer.sh'), getDeveloperScript);
+    // Make scripts executable
+    fs.chmodSync(path.join(cwd, 'workflow/scripts/init-developer.sh'), '755');
+    fs.chmodSync(path.join(cwd, 'workflow/scripts/get-developer.sh'), '755');
+}
+async function createAgentProgressIndex(cwd) {
+    const content = `# Agent Progress
+
+> Multi-developer progress tracking system
+
+## Overview
+
+Each developer (human or AI agent) has their own progress directory under \`agent-progress/\`.
+
+## Structure
+
+\`\`\`
+agent-progress/
+├── index.md              # This file
+└── {developer}/          # Per-developer directory
+    ├── index.md          # Personal index
+    └── progress-N.md     # Progress files (sequential: 1, 2, 3...)
+\`\`\`
+
+## Active Developers
+
+| Developer | Active File | Last Active |
+|-----------|-------------|-------------|
+| - | - | - |
+
+## Session Template
+
+When recording a session, use this format:
+
+\`\`\`markdown
+## Session N - YYYY-MM-DD
+
+### Summary
+One-line description of what was done
+
+### Main Changes
+- File1: Description of changes
+- File2: Description of changes
+
+### Git Commits
+- \`abc1234\` - commit message
+
+### Testing
+- [x] pnpm lint passed
+- [x] pnpm type-check passed
+- [x] Manual testing passed
+
+### Related Features
+- feature-id from feature.json
+
+### Next Steps
+- What to do next
+
+---
+\`\`\`
+
+## Rules
+
+1. **Max 2000 lines per progress file** - Create new file when exceeded
+2. **Include commit hashes** - For traceability
+3. **Update personal index** - After each session
+4. **Sequential numbering** - progress-1.md, progress-2.md, etc.
+`;
+    fs.writeFileSync(path.join(cwd, 'workflow/agent-progress/index.md'), content);
+}
+async function createStructureTemplates(cwd) {
+    // Frontend index.md
+    const frontendIndex = `# Frontend Development Guidelines Index
+
+> **Full documentation**: See \`./doc.md\` for detailed guidelines
+
+This index helps you quickly locate the guidelines you need based on your task type.
+
+## Quick Navigation
+
+| Task | Section | Line Range |
+|------|---------|------------|
+| **New feature module** | Directory Structure | L5-30 |
+| **Write Query Hook** | Hook Guidelines > Query | L50-100 |
+| **Write Mutation Hook** | Hook Guidelines > Mutation | L100-150 |
+| **API calls** | API Guidelines | L150-250 |
+| **State management** | State Guidelines | L250-350 |
+| **Write component** | Component Guidelines | L350-500 |
+| **Performance optimization** | Performance Guidelines | L500-600 |
+| **Code quality check** | Quality Guidelines | L600-700 |
+
+## Core Rules
+
+| Rule | Location |
+|------|----------|
+| Import types from backend | L50-60 |
+| Use semantic HTML | L400-420 |
+| Use Next.js Image | L420-440 |
+| No non-null assertions | L600-620 |
+
+## Reference Files
+
+| Feature | Reference File |
+|---------|----------------|
+| Query Hook | (add your example file path) |
+| Mutation Hook | (add your example file path) |
+| Component | (add your example file path) |
+
+---
+
+Fill in the line numbers and reference files based on your project's doc.md content.
+`;
+    const frontendDoc = `# Frontend Development Guidelines
+
+> Complete guidelines for frontend development
+
+---
+
+## 1. Directory Structure (L5-30)
+
+\`\`\`
+modules/
+├── {feature}/
+│   ├── components/     # UI components
+│   ├── hooks/          # Custom hooks
+│   ├── context/        # React context
+│   └── types.ts        # Type definitions
+\`\`\`
+
+---
+
+## 2. Type Safety (L30-50)
+
+### Import Types from Backend
+
+Always import types from the API package instead of redefining them:
+
+\`\`\`typescript
+// ✅ Good
+import type { User } from '@/packages/api';
+
+// ❌ Bad - don't redefine
+interface User {
+  id: string;
+  name: string;
+}
+\`\`\`
+
+---
+
+## 3. Hook Guidelines (L50-150)
+
+### Query Hook (L50-100)
+
+\`\`\`typescript
+// Template for query hooks
+export function useExample() {
+  return useQuery({
+    queryKey: ['example'],
+    queryFn: async () => {
+      // API call
+    },
+  });
+}
+\`\`\`
+
+### Mutation Hook (L100-150)
+
+\`\`\`typescript
+// Template for mutation hooks
+export function useUpdateExample() {
+  const queryClient = useQueryClient();
+  
+  return useMutation({
+    mutationFn: async (data) => {
+      // API call
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['example'] });
+    },
+  });
+}
+\`\`\`
+
+---
+
+## 4. API Guidelines (L150-250)
+
+(Add your project-specific API guidelines here)
+
+---
+
+## 5. State Management (L250-350)
+
+(Add your project-specific state management guidelines here)
+
+---
+
+## 6. Component Guidelines (L350-500)
+
+### Semantic HTML
+
+Use proper HTML elements:
+
+\`\`\`tsx
+// ✅ Good
+<button onClick={handleClick}>Click me</button>
+
+// ❌ Bad
+<div role="button" onClick={handleClick}>Click me</div>
+\`\`\`
+
+### Image Optimization
+
+Use Next.js Image component:
+
+\`\`\`tsx
+// ✅ Good
+import Image from 'next/image';
+<Image src="/logo.png" alt="Logo" width={100} height={100} />
+
+// ❌ Bad
+<img src="/logo.png" alt="Logo" />
+\`\`\`
+
+---
+
+## 7. Performance Guidelines (L500-600)
+
+(Add your project-specific performance guidelines here)
+
+---
+
+## 8. Quality Guidelines (L600-700)
+
+### Before Every Commit
+
+- [ ] \`pnpm lint\` - 0 errors
+- [ ] \`pnpm type-check\` - No type errors
+- [ ] Manual testing passes
+
+### Forbidden Patterns
+
+- No non-null assertions (\`!\`)
+- No \`any\` type
+- No unused imports/variables
+
+---
+
+**Note**: Update line numbers in index.md when you modify this document.
+`;
+    // Backend index.md
+    const backendIndex = `# Backend Development Guidelines Index
+
+> **Full documentation**: See \`./doc.md\` for detailed guidelines
+
+This index helps you quickly locate the guidelines you need based on your task type.
+
+## Quick Navigation
+
+| Task | Section | Line Range |
+|------|---------|------------|
+| **New API module** | Directory Structure | L5-30 |
+| **Type safety** | Type Safety | L30-100 |
+| **Database operations** | Database Guidelines | L100-200 |
+| **Error handling** | Error Handling | L200-250 |
+| **Logging** | Logging Guidelines | L250-300 |
+| **AI/Prompt** | AI Guidelines | L300-400 |
+| **Code quality** | Quality Guidelines | L400-500 |
+
+## Core Rules
+
+| Rule | Location |
+|------|----------|
+| No non-null assertions | L40-60 |
+| All inputs/outputs need Zod Schema | L60-80 |
+| Use structured logging | L250-270 |
+| No await in loops | L120-140 |
+
+## Reference Files
+
+| Feature | Reference File |
+|---------|----------------|
+| API Route | (add your example file path) |
+| Database Query | (add your example file path) |
+
+---
+
+Fill in the line numbers and reference files based on your project's doc.md content.
+`;
+    const backendDoc = `# Backend Development Guidelines
+
+> Complete guidelines for backend development
+
+---
+
+## 1. Directory Structure (L5-30)
+
+\`\`\`
+packages/api/modules/
+├── {module}/
+│   ├── router.ts        # Route definitions
+│   ├── procedures/      # Business logic
+│   ├── types.ts         # Type definitions
+│   └── api/             # API documentation
+│       └── *.md
+\`\`\`
+
+---
+
+## 2. Type Safety (L30-100)
+
+### No Non-Null Assertions (L40-60)
+
+\`\`\`typescript
+// ✅ Good - use local variable
+const user = await getUser(id);
+if (!user) {
+  throw new Error('User not found');
+}
+const userName = user.name; // Safe access
+
+// ❌ Bad - non-null assertion
+const userName = user!.name;
+\`\`\`
+
+### Zod Schema (L60-80)
+
+\`\`\`typescript
+// All inputs and outputs need Zod schemas
+const inputSchema = z.object({
+  id: z.string(),
+});
+
+const outputSchema = z.object({
+  success: z.boolean(),
+  data: z.object({...}),
+});
+\`\`\`
+
+---
+
+## 3. Database Guidelines (L100-200)
+
+### No Await in Loops (L120-140)
+
+\`\`\`typescript
+// ✅ Good - parallel execution
+const results = await Promise.all(
+  ids.map(id => db.query.users.findFirst({ where: eq(users.id, id) }))
+);
+
+// ❌ Bad - sequential execution
+for (const id of ids) {
+  await db.query.users.findFirst({ where: eq(users.id, id) });
+}
+\`\`\`
+
+### Batch Operations (L140-160)
+
+\`\`\`typescript
+// Use batch insert with conflict handling
+await db.insert(users).values(data).onConflictDoUpdate({
+  target: users.id,
+  set: { updatedAt: new Date() },
+});
+\`\`\`
+
+---
+
+## 4. Error Handling (L200-250)
+
+(Add your project-specific error handling guidelines here)
+
+---
+
+## 5. Logging Guidelines (L250-300)
+
+### Use Structured Logging
+
+\`\`\`typescript
+// ✅ Good
+logger.info('User created', { userId: user.id, email: user.email });
+
+// ❌ Bad
+console.log('User created: ' + user.id);
+\`\`\`
+
+---
+
+## 6. AI Guidelines (L300-400)
+
+(Add your project-specific AI/prompt guidelines here)
+
+---
+
+## 7. Quality Guidelines (L400-500)
+
+### Before Every Commit
+
+- [ ] \`pnpm lint\` - 0 errors
+- [ ] \`pnpm type-check\` - No type errors
+- [ ] API documentation updated
+
+### Forbidden Patterns
+
+- No non-null assertions (\`!\`)
+- No \`console.log\` (use logger)
+- No await in loops
+
+---
+
+**Note**: Update line numbers in index.md when you modify this document.
+`;
+    fs.writeFileSync(path.join(cwd, 'workflow/structure/frontend/index.md'), frontendIndex);
+    fs.writeFileSync(path.join(cwd, 'workflow/structure/frontend/doc.md'), frontendDoc);
+    fs.writeFileSync(path.join(cwd, 'workflow/structure/backend/index.md'), backendIndex);
+    fs.writeFileSync(path.join(cwd, 'workflow/structure/backend/doc.md'), backendDoc);
+}
+async function createFeatureJson(cwd) {
+    const content = {
+        project: 'My Project',
+        lastUpdated: new Date().toISOString().split('T')[0],
+        version: '1.0.0',
+        categories: {
+            example: {
+                name: 'Example Category',
+                features: [
+                    {
+                        id: 'example-001',
+                        name: 'Example Feature',
+                        description: 'An example feature to demonstrate the structure',
+                        status: 'planned',
+                        priority: 'medium',
+                    },
+                ],
+            },
+        },
+        statistics: {
+            totalFeatures: 1,
+            completed: 0,
+            inProgress: 0,
+            planned: 1,
+            blocked: 0,
+            completionRate: '0%',
+        },
+        notes: [
+            'Feature ID format: category-XXX (e.g., auth-001, ui-002)',
+            'Status: completed | in-progress | planned | blocked',
+            'Priority: high | medium | low',
+            'When completed, add completedAt (YYYY-MM-DD) and commit (hash)',
+            'When blocked, add blockedReason field',
+            'Update statistics after changing feature status',
+        ],
+    };
+    fs.writeFileSync(path.join(cwd, 'workflow/feature.json'), JSON.stringify(content, null, 2));
+}
+async function createFlowMd(cwd) {
+    const content = `# Development Workflow
+
+> Based on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+---
+
+## Core Principles
+
+1. **Read Before Write** - Understand context before starting
+2. **Follow Standards** - Read \`workflow/structure/\` guidelines before coding
+3. **Incremental Development** - Complete one feature at a time
+4. **Record Promptly** - Update tracking files after completion
+5. **Document Limits** - Max 2000 lines per agent-progress document
+
+---
+
+## Session Start Process
+
+### Step 1: Read Work Context
+
+\`\`\`bash
+# 0. Check your developer identity
+./workflow/scripts/get-developer.sh
+
+# 1. Check recent work progress (your own directory)
+DEVELOPER=$(./workflow/scripts/get-developer.sh)
+cat workflow/agent-progress/$DEVELOPER/index.md
+
+# 2. Check feature status
+cat workflow/feature.json
+
+# 3. Check Git history
+git status
+git log --oneline -20
+\`\`\`
+
+### Step 2: Read Development Guidelines
+
+Based on your task (frontend/backend), read the corresponding guidelines:
+
+\`\`\`bash
+# Frontend
+cat workflow/structure/frontend/index.md
+
+# Backend
+cat workflow/structure/backend/index.md
+\`\`\`
+
+### Step 3: Select Feature to Develop
+
+Based on \`workflow/feature.json\`:
+- Prioritize \`in-progress\` status features
+- Then select \`planned\` with \`priority: high\`
+- Only select one feature at a time
+
+---
+
+## Development Process
+
+\`\`\`
+1. Update feature.json
+   └─> Change selected feature status to "in-progress"
+
+2. Write code according to guidelines
+   └─> Follow workflow/structure/ guidelines
+
+3. Self-test
+   └─> pnpm lint (must pass)
+   └─> pnpm type-check (must pass)
+   └─> Manual feature testing
+
+4. Commit code (human responsibility)
+   └─> git add <files>
+   └─> git commit -m "type(scope): description"
+
+5. Update tracking files
+   └─> agent-progress: Record session work
+   └─> feature.json: Update feature status
+\`\`\`
+
+---
+
+## Session End
+
+### Checklist
+
+1. ✅ All code committed
+2. ✅ \`workflow/agent-progress/{developer}/progress-N.md\` updated
+3. ✅ \`workflow/feature.json\` status updated
+4. ✅ No lint/type-check errors
+
+---
+
+## Best Practices
+
+### DO
+- Read guidelines before coding
+- Update agent-progress after each session
+- Include commit hashes in progress records
+- Run lint and type-check before finishing
+
+### DON'T
+- Skip reading guidelines (CRITICAL VIOLATION)
+- Let agent-progress exceed 2000 lines
+- Commit code with lint/type-check errors
+- Execute \`git commit\` as AI - human reviews and commits
+
+---
+
+## Common Commands
+
+\`\`\`bash
+# Development
+pnpm dev              # Start dev server
+pnpm build            # Production build
+pnpm lint             # Lint check
+pnpm type-check       # Type check
+
+# Git
+git log --oneline -20         # Recent commits
+git status                    # Working directory status
+\`\`\`
+`;
+    fs.writeFileSync(path.join(cwd, 'workflow/flow.md'), content);
+}
+async function createWorkflowGitignore(cwd) {
+    const content = `# Developer identity (local only)
+.developer
+`;
+    fs.writeFileSync(path.join(cwd, 'workflow/.gitignore'), content);
+}
+//# sourceMappingURL=workflow.js.map