@fifine/aim-studio 0.0.1

package/dist/templates/aim/scripts/common/task_utils.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""
+Task utility functions.
+
+Provides:
+    is_safe_task_path  - Validate task path is safe to operate on
+    find_task_by_name  - Find task directory by name
+    archive_task_dir   - Archive task to monthly directory
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root
+
+
+# =============================================================================
+# Path Safety
+# =============================================================================
+
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
+    """Check if a relative task path is safe to operate on.
+
+    Args:
+        task_path: Task path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if safe, False if dangerous.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    # Check empty or null
+    if not task_path or task_path == "null":
+        print("Error: empty or null task path", file=sys.stderr)
+        return False
+
+    # Reject absolute paths
+    if task_path.startswith("/"):
+        print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Reject ".", "..", paths starting with "./" or "../", or containing ".."
+    if task_path in (".", "..") or task_path.startswith("./") or task_path.startswith("../") or ".." in task_path:
+        print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Final check: ensure resolved path is not the repo root
+    abs_path = repo_root / task_path
+    if abs_path.exists():
+        try:
+            resolved = abs_path.resolve()
+            root_resolved = repo_root.resolve()
+            if resolved == root_resolved:
+                print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
+                return False
+        except (OSError, IOError):
+            pass
+
+    return True
+
+
+# =============================================================================
+# Task Lookup
+# =============================================================================
+
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
+    """Find task directory by name (exact or suffix match).
+
+    Args:
+        task_name: Task name to find.
+        tasks_dir: Tasks directory path.
+
+    Returns:
+        Absolute path to task directory, or None if not found.
+    """
+    if not task_name or not tasks_dir or not tasks_dir.is_dir():
+        return None
+
+    # Try exact match first
+    exact_match = tasks_dir / task_name
+    if exact_match.is_dir():
+        return exact_match
+
+    # Try suffix match (e.g., "my-task" matches "01-21-my-task")
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name.endswith(f"-{task_name}"):
+            return d
+
+    return None
+
+
+# =============================================================================
+# Archive Operations
+# =============================================================================
+
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
+    """Archive a task directory to archive/{YYYY-MM}/.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to archived directory, or None on error.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return None
+
+    # Get tasks directory (parent of the task)
+    tasks_dir = task_dir_abs.parent
+    archive_dir = tasks_dir / "archive"
+    year_month = datetime.now().strftime("%Y-%m")
+    month_dir = archive_dir / year_month
+
+    # Create archive directory
+    try:
+        month_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
+        return None
+
+    # Move task to archive
+    task_name = task_dir_abs.name
+    dest = month_dir / task_name
+
+    try:
+        shutil.move(str(task_dir_abs), str(dest))
+    except (OSError, IOError, shutil.Error) as e:
+        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
+        return None
+
+    return dest
+
+
+def archive_task_complete(
+    task_dir_abs: Path,
+    repo_root: Path | None = None
+) -> dict[str, str]:
+    """Complete archive workflow: archive directory.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with archive result info.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return {}
+
+    archive_dest = archive_task_dir(task_dir_abs, repo_root)
+    if archive_dest:
+        return {"archived_to": str(archive_dest)}
+
+    return {}
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    from .paths import get_tasks_dir
+
+    repo = get_repo_root()
+    tasks = get_tasks_dir(repo)
+
+    print(f"Tasks dir: {tasks}")
+    print(f"is_safe_task_path('.aim-studio/tasks/test'): {is_safe_task_path('.aim-studio/tasks/test', repo)}")
+    print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")

package/dist/templates/aim/scripts/common/worktree.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+Worktree utilities for Multi-Agent Pipeline.
+
+Provides:
+    get_worktree_config         - Get worktree.yaml path
+    get_worktree_base_dir       - Get worktree storage directory
+    get_worktree_copy_files     - Get files to copy list
+    get_worktree_post_create_hooks - Get post-create hooks
+    get_agents_dir              - Get agents registry directory
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .paths import (
+    DIR_WORKFLOW,
+    get_repo_root,
+    get_workspace_dir,
+)
+
+
+# =============================================================================
+# YAML Simple Parser (no dependencies)
+# =============================================================================
+
+def parse_simple_yaml(content: str) -> dict:
+    """Parse simple YAML (only supports key: value and lists).
+
+    Args:
+        content: YAML content string.
+
+    Returns:
+        Parsed dict.
+    """
+    result: dict = {}
+    current_list: list | None = None
+
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if stripped.startswith("- "):
+            if current_list is not None:
+                current_list.append(stripped[2:].strip().strip('"').strip("'"))
+        elif ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if value:
+                result[key] = value
+                _ = None
+                current_list = None
+            else:
+                _ = key
+                current_list = []
+                result[key] = current_list
+
+    return result
+
+
+def _yaml_get_value(config_file: Path, key: str) -> str | None:
+    """Read simple value from worktree.yaml.
+
+    Args:
+        config_file: Path to config file.
+        key: Key to read.
+
+    Returns:
+        Value string or None.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        data = parse_simple_yaml(content)
+        value = data.get(key)
+        if isinstance(value, str):
+            return value
+    except (OSError, IOError):
+        pass
+    return None
+
+
+def _yaml_get_list(config_file: Path, section: str) -> list[str]:
+    """Read list from worktree.yaml.
+
+    Args:
+        config_file: Path to config file.
+        section: Section name.
+
+    Returns:
+        List of items.
+    """
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        data = parse_simple_yaml(content)
+        value = data.get(section)
+        if isinstance(value, list):
+            return [str(item) for item in value]
+    except (OSError, IOError):
+        pass
+    return []
+
+
+# =============================================================================
+# Worktree Configuration
+# =============================================================================
+
+# Worktree config file relative path (relative to repo root)
+WORKTREE_CONFIG_PATH = f"{DIR_WORKFLOW}/worktree.yaml"
+
+
+def get_worktree_config(repo_root: Path | None = None) -> Path:
+    """Get worktree.yaml config file path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to config file.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / WORKTREE_CONFIG_PATH
+
+
+def get_worktree_base_dir(repo_root: Path | None = None) -> Path:
+    """Get worktree base directory.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to worktree base directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    config = get_worktree_config(repo_root)
+    worktree_dir = _yaml_get_value(config, "worktree_dir")
+
+    # Default value
+    if not worktree_dir:
+        worktree_dir = "../worktrees"
+
+    # Handle relative path
+    if worktree_dir.startswith("../") or worktree_dir.startswith("./"):
+        # Relative to repo_root
+        return repo_root / worktree_dir
+    else:
+        # Absolute path
+        return Path(worktree_dir)
+
+
+def get_worktree_copy_files(repo_root: Path | None = None) -> list[str]:
+    """Get files to copy list.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of file paths to copy.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    config = get_worktree_config(repo_root)
+    return _yaml_get_list(config, "copy")
+
+
+def get_worktree_post_create_hooks(repo_root: Path | None = None) -> list[str]:
+    """Get post_create hooks.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of commands to run.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    config = get_worktree_config(repo_root)
+    return _yaml_get_list(config, "post_create")
+
+
+# =============================================================================
+# Agents Registry
+# =============================================================================
+
+def get_agents_dir(repo_root: Path | None = None) -> Path | None:
+    """Get agents directory for current developer.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to agents directory, or None if no workspace.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    workspace_dir = get_workspace_dir(repo_root)
+    if workspace_dir:
+        return workspace_dir / ".agents"
+    return None
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    print(f"Repository root: {repo}")
+    print(f"Worktree config: {get_worktree_config(repo)}")
+    print(f"Worktree base dir: {get_worktree_base_dir(repo)}")
+    print(f"Copy files: {get_worktree_copy_files(repo)}")
+    print(f"Post create hooks: {get_worktree_post_create_hooks(repo)}")
+    print(f"Agents dir: {get_agents_dir(repo)}")

package/dist/templates/aim/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 AIM Studio for the first time.
+
+Usage:
+    python3 create_bootstrap.py [project-type]
+
+Arguments:
+    project-type: frontend | backend | fullstack (default: fullstack)
+
+Prerequisites:
+    - .aim-studio/.developer must exist (run init_developer.py first)
+
+Creates:
+    .aim-studio/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 AIM Studio! This is your first task.
+
+AI agents use `.aim-studio/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 |
+|------|------------------|
+| `.aim-studio/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.aim-studio/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.aim-studio/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.aim-studio/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.aim-studio/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 |
+|------|------------------|
+| `.aim-studio/spec/frontend/directory-structure.md` | Component/page/hook organization |
+| `.aim-studio/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.aim-studio/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.aim-studio/spec/frontend/state-management.md` | State library, patterns, what goes where |
+| `.aim-studio/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.aim-studio/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+"""
+
+
+def write_prd_footer() -> str:
+    """Write PRD footer section."""
+    return """
+
+### Thinking Guides (Optional)
+
+The `.aim-studio/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 ./.aim-studio/scripts/task.py finish
+python3 ./.aim-studio/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 = [".aim-studio/spec/frontend/"]
+    elif project_type == "backend":
+        subtasks = [
+            {"name": "Fill backend guidelines", "status": "pending"},
+            {"name": "Add code examples", "status": "pending"},
+        ]
+        related_files = [".aim-studio/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 = [".aim-studio/spec/backend/", ".aim-studio/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/aim/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()