@jahanxu/trellis 0.4.1

package/dist/templates/trellis/scripts/create_bootstrap.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""
+Create Bootstrap Task for First-Time Setup.
+
+Creates a guided task to help users fill in project guidelines
+after initializing Trellis for the first time.
+
+Usage:
+    python3 create_bootstrap.py [project-type]
+
+Arguments:
+    project-type: frontend | backend | fullstack (default: fullstack)
+
+Prerequisites:
+    - .trellis/.developer must exist (run init_developer.py first)
+
+Creates:
+    .trellis/tasks/00-bootstrap-guidelines/
+        - task.json    # Task metadata
+        - prd.md       # Task description and guidance
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.paths import (
+    DIR_WORKFLOW,
+    DIR_SCRIPTS,
+    DIR_TASKS,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+    set_current_task,
+)
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+TASK_NAME = "00-bootstrap-guidelines"
+
+
+# =============================================================================
+# PRD Content
+# =============================================================================
+
+def write_prd_header() -> str:
+    """Write PRD header section."""
+    return """# Bootstrap: Fill Project Development Guidelines
+
+## Purpose
+
+Welcome to Trellis! This is your first task.
+
+AI agents use `.trellis/spec/` to understand YOUR project's coding conventions.
+**Empty templates = AI writes generic code that doesn't match your project style.**
+
+Filling these guidelines is a one-time setup that pays off for every future AI session.
+
+---
+
+## Your Task
+
+Fill in the guideline files based on your **existing codebase**.
+"""
+
+
+def write_prd_backend_section() -> str:
+    """Write PRD backend section."""
+    return """
+
+### Backend Guidelines
+
+| File | What to Document |
+|------|------------------|
+| `.trellis/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.trellis/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.trellis/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.trellis/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.trellis/spec/backend/quality-guidelines.md` | Code review standards, testing requirements |
+"""
+
+
+def write_prd_frontend_section() -> str:
+    """Write PRD frontend section."""
+    return """
+
+### Frontend Guidelines
+
+| File | What to Document |
+|------|------------------|
+| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
+| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
+| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+"""
+
+
+def write_prd_footer() -> str:
+    """Write PRD footer section."""
+    return """
+
+### Thinking Guides (Optional)
+
+The `.trellis/spec/guides/` directory contains thinking guides that are already
+filled with general best practices. You can customize them for your project if needed.
+
+---
+
+## How to Fill Guidelines
+
+### Principle: Document Reality, Not Ideals
+
+Write what your codebase **actually does**, not what you wish it did.
+AI needs to match existing patterns, not introduce new ones.
+
+### Steps
+
+1. **Look at existing code** - Find 2-3 examples of each pattern
+2. **Document the pattern** - Describe what you see
+3. **Include file paths** - Reference real files as examples
+4. **List anti-patterns** - What does your team avoid?
+
+---
+
+## Tips for Using AI
+
+Ask AI to help analyze your codebase:
+
+- "Look at my codebase and document the patterns you see"
+- "Analyze my code structure and summarize the conventions"
+- "Find error handling patterns and document them"
+
+The AI will read your code and help you document it.
+
+---
+
+## Completion Checklist
+
+- [ ] Guidelines filled for your project type
+- [ ] At least 2-3 real code examples in each guideline
+- [ ] Anti-patterns documented
+
+When done:
+
+```bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+```
+
+---
+
+## Why This Matters
+
+After completing this task:
+
+1. AI will write code that matches your project style
+2. Relevant `/trellis:before-*-dev` commands will inject real context
+3. `/trellis:check-*` commands will validate against your actual standards
+4. Future developers (human or AI) will onboard faster
+"""
+
+
+def write_prd(task_dir: Path, project_type: str) -> None:
+    """Write prd.md file."""
+    content = write_prd_header()
+
+    if project_type == "frontend":
+        content += write_prd_frontend_section()
+    elif project_type == "backend":
+        content += write_prd_backend_section()
+    else:  # fullstack
+        content += write_prd_backend_section()
+        content += write_prd_frontend_section()
+
+    content += write_prd_footer()
+
+    prd_file = task_dir / "prd.md"
+    prd_file.write_text(content, encoding="utf-8")
+
+
+# =============================================================================
+# Task JSON
+# =============================================================================
+
+def write_task_json(task_dir: Path, developer: str, project_type: str) -> None:
+    """Write task.json file."""
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    # Generate subtasks and related files based on project type
+    if project_type == "frontend":
+        subtasks = [
+            {"name": "Fill frontend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/frontend/"]
+    elif project_type == "backend":
+        subtasks = [
+            {"name": "Fill backend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/backend/"]
+    else:  # fullstack
+        subtasks = [
+            {"name": "Fill backend guidelines", "status": "pending"},
+            {"name": "Fill frontend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".trellis/spec/backend/", ".trellis/spec/frontend/"]
+
+    task_data = {
+        "id": TASK_NAME,
+        "name": "Bootstrap Guidelines",
+        "description": "Fill in project development guidelines for AI agents",
+        "status": "in_progress",
+        "dev_type": "docs",
+        "priority": "P1",
+        "creator": developer,
+        "assignee": developer,
+        "createdAt": today,
+        "completedAt": None,
+        "commit": None,
+        "subtasks": subtasks,
+        "relatedFiles": related_files,
+        "notes": f"First-time setup task created by trellis init ({project_type} project)",
+    }
+
+    task_json = task_dir / "task.json"
+    task_json.write_text(json.dumps(task_data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+def main() -> int:
+    """Main entry point."""
+    # Parse project type argument
+    project_type = "fullstack"
+    if len(sys.argv) > 1:
+        project_type = sys.argv[1]
+
+    # Validate project type
+    if project_type not in ("frontend", "backend", "fullstack"):
+        print(f"Unknown project type: {project_type}, defaulting to fullstack")
+        project_type = "fullstack"
+
+    repo_root = get_repo_root()
+    developer = get_developer(repo_root)
+
+    # Check developer initialized
+    if not developer:
+        print("Error: Developer not initialized")
+        print(f"Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <your-name>")
+        return 1
+
+    tasks_dir = get_tasks_dir(repo_root)
+    task_dir = tasks_dir / TASK_NAME
+    relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{TASK_NAME}"
+
+    # Check if already exists
+    if task_dir.exists():
+        print(f"Bootstrap task already exists: {relative_path}")
+        return 0
+
+    # Create task directory
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write files
+    write_task_json(task_dir, developer, project_type)
+    write_prd(task_dir, project_type)
+
+    # Set as current task
+    set_current_task(relative_path, repo_root)
+
+    # Silent output - init command handles user-facing messages
+    # Only output the task path for programmatic use
+    print(relative_path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/templates/trellis/scripts/get_context.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""
+Get Session Context for AI Agent.
+
+Usage:
+    python3 get_context.py           Output context in text format
+    python3 get_context.py --json    Output context in JSON format
+"""
+
+from __future__ import annotations
+
+from common.git_context import main
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/trellis/scripts/get_developer.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Get current developer name.
+
+This is a wrapper that uses common/paths.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import get_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    developer = get_developer()
+    if developer:
+        print(developer)
+    else:
+        print("Developer not initialized", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/trellis/scripts/handoff_generator.py

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+HANDOFF Document Generator
+
+Generates role-specific handoff documents for three-role collaboration.
+
+Templates:
+- PM: Summarize PRD core requirements
+- Designer: Design rationale + Mock data locations
+- Frontend: Implementation details + API integration points
+"""
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from common.paths import get_developer, get_repo_root
+
+# =============================================================================
+# Template Functions
+# =============================================================================
+
+
+def generate_handoff_pm(task_dir: Path, task_data: dict) -> str:
+    """Generate HANDOFF.md for PM role."""
+    task_id = task_data.get("id", "unknown")
+    title = task_data.get("title", "未命名任务")
+    developer = get_developer(get_repo_root()) or "unknown"
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    # Read PRD content
+    prd_file = task_dir / "prd.md"
+    prd_content = ""
+    if prd_file.exists():
+        prd_content = prd_file.read_text(encoding="utf-8")
+
+    template = f"""# {title} - 需求交接文档
+
+## 📋 任务信息
+- **功能ID**: {task_id}
+- **功能名称**: {title}
+- **完成人**: {developer}
+- **完成时间**: {now}
+
+## 🎯 核心需求
+
+**请AI根据PRD总结核心要点（2-3段）**
+
+PRD位置：`{task_dir.name}/prd.md`
+
+## 📄 产出文件
+
+- `prd.md` - 产品需求文档
+- `user-stories.md` - 用户故事（如有）
+- 其他补充文档（如有）
+
+## 🔑 关键设计要点
+
+**请Designer重点关注**：
+
+1. [TODO: AI填写关键功能点1]
+2. [TODO: AI填写关键功能点2]
+3. [TODO: AI填写关键功能点3]
+
+## ⚠️ 特别注意事项
+
+**设计实现时需要注意**：
+
+- [TODO: AI填写注意事项1 - 如UI布局要求]
+- [TODO: AI填写注意事项2 - 如交互特殊要求]
+- [TODO: AI填写注意事项3 - 如性能要求]
+
+## 🔗 相关资源
+
+- 设计稿: [TODO: 填写Figma链接]
+- API文档: [TODO: 填写API文档链接]
+- 参考资料: [TODO: 填写其他资源]
+
+## 📞 联系方式
+
+如有疑问，请联系 {developer}
+
+---
+
+## 附录：PRD内容摘要
+
+```
+{prd_content[:500]}...
+```
+
+> 完整PRD请查看 `{task_dir.name}/prd.md`
+"""
+
+    return template
+
+
+def generate_handoff_designer(task_dir: Path, task_data: dict, source_data: Optional[dict] = None) -> str:
+    """Generate HANDOFF.md for Designer role."""
+    task_id = task_data.get("id", "unknown")
+    title = task_data.get("title", "未命名任务")
+    developer = get_developer(get_repo_root()) or "unknown"
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    # Get upstream info
+    based_on = "N/A"
+    if source_data and "based_on" in source_data:
+        based_on = f"{source_data['based_on']['type']}/{source_data['based_on']['id']}"
+
+    template = f"""# {title} - 原型交接文档
+
+## 📋 任务信息
+- **功能ID**: {task_id}
+- **基于需求**: {based_on}
+- **完成人**: {developer}
+- **完成时间**: {now}
+
+## 🎨 设计说明
+
+**请AI总结设计思路（2-3段）**：
+
+- 整体布局思路
+- 主要组件设计
+- 交互流程设计
+
+## 📄 产出文件
+
+**请列出所有组件文件**：
+
+- `[ComponentName].tsx` - 组件说明
+- `[ComponentName].tsx` - 组件说明
+- ...
+
+## 🧩 组件结构
+
+```
+[TODO: AI绘制组件树]
+App
+├── LoginPage
+│   ├── LoginForm
+│   │   ├── EmailInput
+│   │   └── PasswordInput
+│   └── SocialLoginButtons
+└── ...
+```
+
+## 💾 Mock数据说明
+
+**当前使用的Mock数据**：
+
+```typescript
+// [TODO: AI填写Mock数据示例]
+const mockUser = {{
+  id: "1",
+  email: "test@example.com",
+  name: "Test User"
+}};
+
+// Mock登录逻辑位置：[TODO: 文件名:行号]
+const handleLogin = async () => {{
+  // TODO: 替换为真实API调用
+  setTimeout(() => setUser(mockUser), 1000);
+}};
+```
+
+## 🔄 需要Frontend补充的逻辑
+
+**请Frontend开发重点处理**：
+
+1. **API集成** - 替换Mock为真实API调用
+   - 位置: [TODO: 文件名:行号]
+   - 需要调用: [TODO: API端点]
+
+2. **错误处理** - 添加网络错误和业务错误处理
+   - 网络超时
+   - 登录失败提示
+   - 表单验证错误
+
+3. **状态管理** - 添加全局状态管理（如需要）
+   - 用户登录状态
+   - Token存储
+
+4. **持久化** - 实现"记住我"功能
+   - localStorage/Cookie
+   - Token刷新逻辑
+
+## ⚠️ 特别注意事项
+
+**保留以下设计**：
+
+- [TODO: 需要保留的交互细节]
+- [TODO: 需要保留的UI元素]
+- [TODO: 需要保留的样式]
+
+**可以优化的部分**：
+
+- [TODO: 可以优化的性能点]
+- [TODO: 可以调整的代码结构]
+
+## 📞 联系方式
+
+如有疑问，请联系 {developer}
+"""
+
+    return template
+
+
+def generate_handoff_frontend(task_dir: Path, task_data: dict, source_data: Optional[dict] = None) -> str:
+    """Generate HANDOFF.md for Frontend role."""
+    task_id = task_data.get("id", "unknown")
+    title = task_data.get("title", "未命名任务")
+    developer = get_developer(get_repo_root()) or "unknown"
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    # Get upstream info
+    based_on = "N/A"
+    if source_data and "based_on" in source_data:
+        based_on = f"{source_data['based_on']['type']}/{source_data['based_on']['id']}"
+
+    template = f"""# {title} - 生产代码交接文档
+
+## 📋 任务信息
+- **功能ID**: {task_id}
+- **基于原型**: {based_on}
+- **完成人**: {developer}
+- **完成时间**: {now}
+
+## 🎯 实现总结
+
+**请AI总结实现要点（2-3段）**：
+
+- 主要功能实现
+- API集成情况
+- 状态管理方案
+
+## 📄 产出文件
+
+**请列出修改的文件**：
+
+- `[FileName].tsx` - 修改说明
+- `[FileName].ts` - 修改说明
+- ...
+
+## 🔌 API集成
+
+**已集成的API**：
+
+| 端点 | 方法 | 用途 | 位置 |
+|------|------|------|------|
+| [TODO] | POST | [TODO] | [TODO:文件:行号] |
+
+## 🧪 测试说明
+
+**已添加的测试**：
+
+- [ ] 单元测试: [TODO: 测试文件]
+- [ ] 集成测试: [TODO: 测试文件]
+- [ ] E2E测试: [TODO: 测试文件]
+
+**测试覆盖率**: [TODO: X%]
+
+## 🐛 已知问题
+
+**遗留问题**（如有）：
+
+1. [TODO: 问题描述]
+   - 影响: [TODO]
+   - 计划修复时间: [TODO]
+
+## ⚠️ 部署注意事项
+
+**环境变量**：
+
+```bash
+# [TODO: 列出需要的环境变量]
+VITE_API_BASE_URL=https://api.example.com
+```
+
+**依赖项**：
+
+- [TODO: 新增的npm包]
+
+**数据库迁移**（如需要）：
+
+- [TODO: 迁移脚本]
+
+## 📞 联系方式
+
+如有疑问，请联系 {developer}
+"""
+
+    return template
+
+
+# =============================================================================
+# Main Function
+# =============================================================================
+
+
+def generate_handoff(task_dir: Path, role: str, task_data: dict, source_data: Optional[dict] = None) -> str:
+    """Generate HANDOFF.md based on role.
+
+    Args:
+        task_dir: Task directory path
+        role: Role type (pm, designer, frontend)
+        task_data: Task metadata from task.json
+        source_data: Source reference from source.json (optional)
+
+    Returns:
+        HANDOFF.md content
+    """
+    generators = {
+        "pm": generate_handoff_pm,
+        "designer": generate_handoff_designer,
+        "frontend": generate_handoff_frontend,
+    }
+
+    if role not in generators:
+        raise ValueError(f"Invalid role: {role}. Must be one of {list(generators.keys())}")
+
+    # Designer and Frontend can use source_data
+    if role in ("designer", "frontend"):
+        return generators[role](task_dir, task_data, source_data)
+    else:
+        return generators[role](task_dir, task_data)
+
+
+# =============================================================================
+# CLI Entry Point
+# =============================================================================
+
+
+def main() -> int:
+    """CLI entry point for testing."""
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(description="HANDOFF Document Generator")
+    parser.add_argument("task_dir", help="Task directory path")
+    parser.add_argument("role", choices=["pm", "designer", "frontend"], help="Role type")
+    parser.add_argument("--output", "-o", help="Output file path (default: HANDOFF.md in task dir)")
+
+    args = parser.parse_args()
+
+    task_dir = Path(args.task_dir)
+    if not task_dir.exists():
+        print(f"Error: Task directory not found: {task_dir}", file=sys.stderr)
+        return 1
+
+    # Read task.json
+    task_json = task_dir / "task.json"
+    if not task_json.exists():
+        print(f"Error: task.json not found in {task_dir}", file=sys.stderr)
+        return 1
+
+    task_data = json.loads(task_json.read_text(encoding="utf-8"))
+
+    # Read source.json (optional)
+    source_json = task_dir / "source.json"
+    source_data = None
+    if source_json.exists():
+        source_data = json.loads(source_json.read_text(encoding="utf-8"))
+
+    # Generate HANDOFF
+    handoff_content = generate_handoff(task_dir, args.role, task_data, source_data)
+
+    # Output
+    output_file = Path(args.output) if args.output else task_dir / "HANDOFF.md"
+    output_file.write_text(handoff_content, encoding="utf-8")
+
+    print(f"✓ Generated HANDOFF.md: {output_file}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())