spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/tasks_support.py

@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+"""Shared utilities for manipulating Spec Kitty task prompts.
+
+DEPRECATED: This module is deprecated as of v0.10.0.
+Use `spec-kitty agent tasks` commands instead.
+
+This file will be removed in the next release.
+See: src/specify_cli/cli/commands/agent/tasks.py
+
+Migration Guide:
+- tasks_cli.py update → spec-kitty agent tasks move-task
+- For all other operations, use the new agent tasks commands
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from specify_cli.legacy_detector import is_legacy_format
+
+# IMPORTANT: Keep in sync with scripts/tasks/task_helpers.py
+LANES: Tuple[str, ...] = ("planned", "doing", "for_review", "done")
+TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+class TaskCliError(RuntimeError):
+    """Raised when task operations cannot be completed safely."""
+
+
+def find_repo_root(start: Optional[Path] = None) -> Path:
+    """Find the MAIN repository root, even when inside a worktree.
+
+    This function correctly handles git worktrees by detecting when .git is a
+    file (worktree pointer) vs a directory (main repo), and following the
+    pointer back to the main repository.
+
+    Args:
+        start: Starting directory for search (defaults to cwd)
+
+    Returns:
+        Path to the main repository root
+
+    Raises:
+        TaskCliError: If repository root cannot be found
+    """
+    current = (start or Path.cwd()).resolve()
+
+    for candidate in [current, *current.parents]:
+        git_path = candidate / ".git"
+
+        if git_path.is_file():
+            # This is a worktree! The .git file contains a pointer to the main repo.
+            # Format: "gitdir: /path/to/main/.git/worktrees/worktree-name"
+            try:
+                content = git_path.read_text().strip()
+                if content.startswith("gitdir:"):
+                    gitdir = Path(content.split(":", 1)[1].strip())
+                    # Navigate: .git/worktrees/name -> .git -> main repo root
+                    # gitdir points to .git/worktrees/xxx, so .parent.parent is .git
+                    main_git_dir = gitdir.parent.parent
+                    main_repo = main_git_dir.parent
+                    if main_repo.exists():
+                        return main_repo
+            except (OSError, ValueError):
+                # If we can't read or parse the .git file, continue searching
+                pass
+
+        elif git_path.is_dir():
+            # This is the main repo (or a regular git repo)
+            return candidate
+
+        # Also check for .kittify marker (fallback for non-git scenarios)
+        if (candidate / ".kittify").exists():
+            return candidate
+
+    raise TaskCliError("Unable to locate repository root (missing .git or .kittify).")
+
+
+def run_git(args: List[str], cwd: Path, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a git command inside the repository."""
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=str(cwd),
+            check=check,
+            text=True,
+            capture_output=True,
+        )
+    except FileNotFoundError as exc:
+        raise TaskCliError("git is not available on PATH.") from exc
+    except subprocess.CalledProcessError as exc:
+        if check:
+            message = exc.stderr.strip() or exc.stdout.strip() or "Unknown git error"
+            raise TaskCliError(message)
+        return exc
+
+
+def ensure_lane(value: str) -> str:
+    lane = value.strip().lower()
+    if lane not in LANES:
+        raise TaskCliError(f"Invalid lane '{value}'. Expected one of {', '.join(LANES)}.")
+    return lane
+
+
+def now_utc() -> str:
+    return datetime.now(timezone.utc).strftime(TIMESTAMP_FORMAT)
+
+
+def git_status_lines(repo_root: Path) -> List[str]:
+    result = run_git(["status", "--porcelain"], cwd=repo_root, check=True)
+    return [line for line in result.stdout.splitlines() if line.strip()]
+
+
+def normalize_note(note: Optional[str], target_lane: str) -> str:
+    default = f"Moved to {target_lane}"
+    cleaned = (note or default).strip()
+    return cleaned or default
+
+
+def detect_conflicting_wp_status(
+    status_lines: List[str], feature: str, old_path: Path, new_path: Path
+) -> List[str]:
+    """Return staged work-package entries unrelated to the requested move."""
+    prefix = f"kitty-specs/{feature}/tasks/"
+    allowed = {
+        str(old_path).lstrip("./"),
+        str(new_path).lstrip("./"),
+    }
+    conflicts = []
+    for line in status_lines:
+        path = line[3:] if len(line) > 3 else ""
+        if not path.startswith(prefix):
+            continue
+        clean = path.strip()
+        if clean not in allowed:
+            conflicts.append(line)
+    return conflicts
+
+
+def match_frontmatter_line(frontmatter: str, key: str) -> Optional[re.Match]:
+    pattern = re.compile(
+        rf"^({re.escape(key)}:\s*)(\".*?\"|'.*?'|[^#\n]*)(.*)$",
+        flags=re.MULTILINE,
+    )
+    return pattern.search(frontmatter)
+
+
+def extract_scalar(frontmatter: str, key: str) -> Optional[str]:
+    match = match_frontmatter_line(frontmatter, key)
+    if not match:
+        return None
+    raw_value = match.group(2).strip()
+    if raw_value.startswith('"') and raw_value.endswith('"'):
+        return raw_value[1:-1]
+    if raw_value.startswith("'") and raw_value.endswith("'"):
+        return raw_value[1:-1]
+    return raw_value.strip() or None
+
+
+def set_scalar(frontmatter: str, key: str, value: str) -> str:
+    """Replace or insert a scalar value while preserving trailing comments."""
+    match = match_frontmatter_line(frontmatter, key)
+    replacement_line = f'{key}: "{value}"'
+    if match:
+        prefix = match.group(1)
+        comment = match.group(3)
+        comment_suffix = f"{comment}" if comment else ""
+        return (
+            frontmatter[: match.start()]
+            + f'{prefix}"{value}"{comment_suffix}'
+            + frontmatter[match.end() :]
+        )
+
+    insertion = f"{replacement_line}\n"
+    history_match = re.search(r"^\s*history:\s*$", frontmatter, flags=re.MULTILINE)
+    if history_match:
+        idx = history_match.start()
+        return frontmatter[:idx] + insertion + frontmatter[idx:]
+
+    if frontmatter and not frontmatter.endswith("\n"):
+        frontmatter += "\n"
+    return frontmatter + insertion
+
+
+def split_frontmatter(text: str) -> Tuple[str, str, str]:
+    """Return (frontmatter, body, padding) while preserving spacing after frontmatter."""
+    normalized = text.replace("\r\n", "\n")
+    if not normalized.startswith("---\n"):
+        return "", normalized, ""
+
+    closing_idx = normalized.find("\n---", 4)
+    if closing_idx == -1:
+        return "", normalized, ""
+
+    front = normalized[4:closing_idx]
+    tail = normalized[closing_idx + 4 :]
+    padding = ""
+    while tail.startswith("\n"):
+        padding += "\n"
+        tail = tail[1:]
+    return front, tail, padding
+
+
+def build_document(frontmatter: str, body: str, padding: str) -> str:
+    frontmatter = frontmatter.rstrip("\n")
+    doc = f"---\n{frontmatter}\n---"
+    if padding or body:
+        doc += padding or "\n"
+    doc += body
+    if not doc.endswith("\n"):
+        doc += "\n"
+    return doc
+
+
+def append_activity_log(body: str, entry: str) -> str:
+    header = "## Activity Log"
+    if header not in body:
+        block = f"{header}\n\n{entry}\n"
+        if body and not body.endswith("\n\n"):
+            return body.rstrip() + "\n\n" + block
+        return body + "\n" + block if body else block
+
+    pattern = re.compile(r"(## Activity Log.*?)(?=\n## |\Z)", flags=re.DOTALL)
+    match = pattern.search(body)
+    if not match:
+        return body + ("\n" if not body.endswith("\n") else "") + entry + "\n"
+
+    section = match.group(1).rstrip()
+    if not section.endswith("\n"):
+        section += "\n"
+    section += f"{entry}\n"
+    return body[: match.start(1)] + section + body[match.end(1) :]
+
+
+def activity_entries(body: str) -> List[Dict[str, str]]:
+    pattern = re.compile(
+        r"^\s*-\s*"
+        r"(?P<timestamp>[0-9T:-]+Z)\s*[–-]\s*"
+        r"(?P<agent>[^–-]+?)\s*[–-]\s*"
+        r"(?:shell_pid=(?P<shell>[^–-]*?)\s*[–-]\s*)?"
+        r"lane=(?P<lane>[a-z_]+)\s*[–-]\s*"
+        r"(?P<note>.*)$",
+        flags=re.MULTILINE,
+    )
+    entries: List[Dict[str, str]] = []
+    for match in pattern.finditer(body):
+        entries.append(
+            {
+                "timestamp": match.group("timestamp").strip(),
+                "agent": match.group("agent").strip(),
+                "lane": match.group("lane").strip(),
+                "note": match.group("note").strip(),
+                "shell_pid": (match.group("shell") or "").strip(),
+            }
+        )
+    return entries
+
+
+@dataclass
+class WorkPackage:
+    feature: str
+    path: Path
+    current_lane: str
+    relative_subpath: Path
+    frontmatter: str
+    body: str
+    padding: str
+
+    @property
+    def work_package_id(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "work_package_id")
+
+    @property
+    def title(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "title")
+
+    @property
+    def assignee(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "assignee")
+
+    @property
+    def agent(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "agent")
+
+    @property
+    def shell_pid(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "shell_pid")
+
+    @property
+    def lane(self) -> Optional[str]:
+        return extract_scalar(self.frontmatter, "lane")
+
+
+def locate_work_package(repo_root: Path, feature: str, wp_id: str) -> WorkPackage:
+    """Locate a work package by ID, supporting both legacy and new formats.
+
+    Always uses main repo's kitty-specs/ regardless of current directory.
+    Worktrees should not contain kitty-specs/ (excluded via sparse checkout).
+
+    Legacy format: WP files in tasks/{lane}/ subdirectories
+    New format: WP files in flat tasks/ directory with lane in frontmatter
+    """
+    from specify_cli.core.paths import get_main_repo_root
+
+    # Always use main repo's kitty-specs - it's the source of truth
+    # This fixes the bug where worktree's stale kitty-specs/ would be used
+    main_root = get_main_repo_root(repo_root)
+    feature_path = main_root / "kitty-specs" / feature
+
+    tasks_root = feature_path / "tasks"
+    if not tasks_root.exists():
+        raise TaskCliError(f"Feature '{feature}' has no tasks directory at {tasks_root}.")
+
+    # Use exact WP ID matching with word boundary to avoid WP04 matching WP04b
+    # Matches: WP04.md, WP04-something.md, WP04_something.md
+    # Does NOT match: WP04b.md, WP04b-something.md
+    wp_pattern = re.compile(rf"^{re.escape(wp_id)}(?:[-_.]|\.md$)")
+
+    use_legacy = is_legacy_format(feature_path)
+    candidates = []
+
+    if use_legacy:
+        # Legacy format: search lane subdirectories
+        for lane_dir in tasks_root.iterdir():
+            if not lane_dir.is_dir():
+                continue
+            lane = lane_dir.name
+            for path in lane_dir.rglob("*.md"):
+                if wp_pattern.match(path.name):
+                    candidates.append((lane, path, lane_dir))
+    else:
+        # New format: search flat tasks/ directory
+        for path in tasks_root.glob("*.md"):
+            if path.name.lower() == "readme.md":
+                continue
+            if wp_pattern.match(path.name):
+                # Get lane from frontmatter
+                lane = get_lane_from_frontmatter(path, warn_on_missing=False)
+                candidates.append((lane, path, tasks_root))
+
+    if not candidates:
+        raise TaskCliError(f"Work package '{wp_id}' not found under kitty-specs/{feature}/tasks.")
+    if len(candidates) > 1:
+        joined = "\n".join(str(item[1].relative_to(repo_root)) for item in candidates)
+        raise TaskCliError(
+            f"Multiple files matched '{wp_id}'. Refine the ID or clean duplicates:\n{joined}"
+        )
+
+    lane, path, base_dir = candidates[0]
+    text = path.read_text(encoding="utf-8-sig")
+    front, body, padding = split_frontmatter(text)
+    relative = path.relative_to(base_dir)
+    return WorkPackage(
+        feature=feature,
+        path=path,
+        current_lane=lane,
+        relative_subpath=relative,
+        frontmatter=front,
+        body=body,
+        padding=padding,
+    )
+
+
+def load_meta(meta_path: Path) -> Dict:
+    if not meta_path.exists():
+        raise TaskCliError(f"Meta file not found at {meta_path}")
+    return json.loads(meta_path.read_text(encoding="utf-8-sig"))
+
+
+def get_lane_from_frontmatter(wp_path: Path, warn_on_missing: bool = True) -> str:
+    """Extract lane from WP file frontmatter.
+
+    This is the authoritative way to determine a work package's lane
+    in the frontmatter-only lane system.
+
+    Args:
+        wp_path: Path to the work package markdown file
+        warn_on_missing: If True, print warning when lane field is missing
+
+    Returns:
+        Lane value (planned, doing, for_review, done)
+
+    Raises:
+        ValueError: If lane value is not in LANES
+    """
+    content = wp_path.read_text(encoding="utf-8-sig")
+    frontmatter, _, _ = split_frontmatter(content)
+
+    lane = extract_scalar(frontmatter, "lane")
+
+    if lane is None:
+        if warn_on_missing:
+            # Import here to avoid circular dependency issues
+            try:
+                from rich.console import Console
+                console = Console(stderr=True)
+                console.print(
+                    f"[yellow]Warning: {wp_path.name} missing lane field, "
+                    f"defaulting to 'planned'[/yellow]"
+                )
+            except ImportError:
+                import sys
+                print(
+                    f"Warning: {wp_path.name} missing lane field, defaulting to 'planned'",
+                    file=sys.stderr
+                )
+        return "planned"
+
+    if lane not in LANES:
+        raise ValueError(
+            f"Invalid lane '{lane}' in {wp_path.name}. "
+            f"Valid lanes: {', '.join(LANES)}"
+        )
+
+    return lane
+
+
+__all__ = [
+    "LANES",
+    "TIMESTAMP_FORMAT",
+    "TaskCliError",
+    "WorkPackage",
+    "append_activity_log",
+    "activity_entries",
+    "build_document",
+    "detect_conflicting_wp_status",
+    "ensure_lane",
+    "extract_scalar",
+    "find_repo_root",
+    "get_lane_from_frontmatter",
+    "git_status_lines",
+    "is_legacy_format",
+    "load_meta",
+    "locate_work_package",
+    "match_frontmatter_line",
+    "normalize_note",
+    "now_utc",
+    "run_git",
+    "set_scalar",
+    "split_frontmatter",
+]

specify_cli/template/__init__.py

@@ -0,0 +1,47 @@
+"""Template management for spec-kitty."""
+
+from .manager import (
+    copy_package_tree,
+    copy_specify_base_from_local,
+    copy_specify_base_from_package,
+    get_local_repo_root,
+)
+from .renderer import (
+    DEFAULT_PATH_PATTERNS,
+    parse_frontmatter,
+    render_template,
+    rewrite_paths,
+)
+from .asset_generator import (
+    generate_agent_assets,
+    prepare_command_templates,
+    render_command_template,
+)
+from .github_client import (
+    GitHubClientError,
+    SSL_CONTEXT,
+    build_http_client,
+    download_and_extract_template,
+    download_template_from_github,
+    parse_repo_slug,
+)
+
+__all__ = [
+    "GitHubClientError",
+    "SSL_CONTEXT",
+    "build_http_client",
+    "copy_package_tree",
+    "copy_specify_base_from_local",
+    "copy_specify_base_from_package",
+    "DEFAULT_PATH_PATTERNS",
+    "download_and_extract_template",
+    "download_template_from_github",
+    "generate_agent_assets",
+    "get_local_repo_root",
+    "parse_frontmatter",
+    "parse_repo_slug",
+    "prepare_command_templates",
+    "render_command_template",
+    "render_template",
+    "rewrite_paths",
+]

specify_cli/template/asset_generator.py

@@ -0,0 +1,206 @@
+"""Agent-specific asset rendering helpers."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Dict, Mapping
+
+from specify_cli.core.config import AGENT_COMMAND_CONFIG
+from specify_cli.template.renderer import render_template, rewrite_paths
+
+
+def prepare_command_templates(
+    base_templates_dir: Path,
+    mission_templates_dir: Path | None,
+) -> Path:
+    """Prepare command templates with mission overrides applied.
+
+    Returns a directory containing base templates, with any mission templates
+    overlaid to enhance/override the central command set.
+    """
+    if not mission_templates_dir or not mission_templates_dir.exists():
+        return base_templates_dir
+
+    merged_dir = base_templates_dir.parent / f".merged-{mission_templates_dir.parent.name}"
+    if merged_dir.exists():
+        shutil.rmtree(merged_dir)
+
+    shutil.copytree(base_templates_dir, merged_dir)
+    for template_path in mission_templates_dir.glob("*.md"):
+        shutil.copy2(template_path, merged_dir / template_path.name)
+
+    return merged_dir
+
+
+def generate_agent_assets(command_templates_dir: Path, project_path: Path, agent_key: str, script_type: str) -> None:
+    """Render every command template for the selected agent."""
+    config = AGENT_COMMAND_CONFIG[agent_key]
+    output_dir = project_path / config["dir"]
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if not command_templates_dir.exists():
+        _raise_template_discovery_error(command_templates_dir)
+
+    for template_path in sorted(command_templates_dir.glob("*.md")):
+        rendered = render_command_template(
+            template_path,
+            script_type,
+            agent_key,
+            config["arg_format"],
+            config["ext"],
+        )
+        ext = config["ext"]
+        stem = template_path.stem
+        if agent_key == "codex":
+            stem = stem.replace("-", "_")
+        filename = f"spec-kitty.{stem}.{ext}" if ext else f"spec-kitty.{stem}"
+        (output_dir / filename).write_text(rendered, encoding="utf-8")
+
+    if agent_key == "copilot":
+        vscode_settings = command_templates_dir.parent / "vscode-settings.json"
+        if vscode_settings.exists():
+            vscode_dest = project_path / ".vscode"
+            vscode_dest.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(vscode_settings, vscode_dest / "settings.json")
+
+
+def render_command_template(
+    template_path: Path,
+    script_type: str,
+    agent_key: str,
+    arg_format: str,
+    extension: str,
+) -> str:
+    """Render a single command template for an agent."""
+
+    def build_variables(metadata: Dict[str, object]) -> Mapping[str, str]:
+        scripts = metadata.get("scripts") or {}
+        agent_scripts = metadata.get("agent_scripts") or {}
+        if not isinstance(scripts, dict):
+            scripts = {}
+        if not isinstance(agent_scripts, dict):
+            agent_scripts = {}
+        script_command = scripts.get(
+            script_type, f"(Missing script command for {script_type})"
+        )
+        agent_script_command = agent_scripts.get(script_type)
+        return {
+            "{SCRIPT}": script_command,
+            "{AGENT_SCRIPT}": agent_script_command or "",
+            "{ARGS}": arg_format,
+            "__AGENT__": agent_key,
+        }
+
+    metadata, rendered_body, raw_frontmatter = render_template(
+        template_path, variables=build_variables
+    )
+    description = str(metadata.get("description", "")).strip()
+
+    frontmatter_clean = _filter_frontmatter(raw_frontmatter)
+    if frontmatter_clean:
+        frontmatter_clean = rewrite_paths(frontmatter_clean)
+
+    if extension == "toml":
+        # Convert Markdown variable syntax to TOML/Gemini variable syntax
+        # Gemini CLI uses {{args}} instead of $ARGUMENTS
+        # See: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md
+        rendered_body = _convert_markdown_syntax_to_format(rendered_body, "toml")
+
+        description_value = description
+        if description_value.startswith('"') and description_value.endswith('"'):
+            description_value = description_value[1:-1]
+        description_value = description_value.replace('"', '\\"')
+        body_text = rendered_body
+        if not body_text.endswith("\n"):
+            body_text += "\n"
+        return f'description = "{description_value}"\n\nprompt = """\n{body_text}"""\n'
+
+    if frontmatter_clean:
+        result = f"---\n{frontmatter_clean}\n---\n\n{rendered_body}"
+    else:
+        result = rendered_body
+    return result if result.endswith("\n") else result + "\n"
+
+
+def _convert_markdown_syntax_to_format(content: str, target_format: str) -> str:
+    """Convert Markdown variable syntax to target format syntax.
+
+    Args:
+        content: Rendered template content in Markdown syntax
+        target_format: Target format (e.g., "toml" for Gemini)
+
+    Returns:
+        Content with variable syntax converted to target format
+
+    Conversion rules:
+    - Markdown (Claude/Codex): $ARGUMENTS, $AGENT_SCRIPT
+    - TOML (Gemini): {{args}} (per https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md)
+    """
+    if target_format == "toml":
+        # Convert Claude/Codex Markdown variable syntax to Gemini TOML syntax
+        # $ARGUMENTS → {{args}}
+        content = content.replace("$ARGUMENTS", "{{args}}")
+        return content
+
+    # For other formats, return unchanged
+    return content
+
+
+def _filter_frontmatter(frontmatter_text: str) -> str:
+    filtered_lines: list[str] = []
+    skipping_block = False
+    for line in frontmatter_text.splitlines():
+        stripped = line.strip()
+        if skipping_block:
+            if line.startswith((" ", "\t")):
+                continue
+            skipping_block = False
+        if stripped in {"scripts:", "agent_scripts:"}:
+            skipping_block = True
+            continue
+        filtered_lines.append(line)
+    return "\n".join(filtered_lines)
+
+
+def _raise_template_discovery_error(commands_dir: Path) -> None:
+    """Raise an informative error about template discovery failure."""
+    env_root = os.environ.get("SPEC_KITTY_TEMPLATE_ROOT")
+    remote_repo = os.environ.get("SPECIFY_TEMPLATE_REPO")
+
+    error_msg = (
+        "Templates could not be found in any of the expected locations:\n\n"
+        "Checked paths (in order):\n"
+        f"  ✗ Packaged resources (bundled with CLI)\n"
+        f"  ✗ Environment variable SPEC_KITTY_TEMPLATE_ROOT" +
+        (f" = {env_root}" if env_root else " (not set)") + "\n" +
+        f"  ✗ Remote repository SPECIFY_TEMPLATE_REPO" +
+        (f" = {remote_repo}" if remote_repo else " (not configured)") + "\n\n"
+        "To fix this, try one of these approaches:\n\n"
+        "1. Reinstall from PyPI (recommended for end users):\n"
+        "   pip install --upgrade spec-kitty-cli\n\n"
+        "2. Use --template-root flag (for development):\n"
+        "   spec-kitty init . --template-root=/path/to/spec-kitty\n\n"
+        "3. Set environment variable (for development):\n"
+        "   export SPEC_KITTY_TEMPLATE_ROOT=/path/to/spec-kitty\n"
+        "   spec-kitty init .\n\n"
+        "4. Configure remote repository:\n"
+        "   export SPECIFY_TEMPLATE_REPO=owner/repo\n"
+        "   spec-kitty init .\n\n"
+        "For development installs from source, use:\n"
+        "   export SPEC_KITTY_TEMPLATE_ROOT=$(git rev-parse --show-toplevel)\n"
+        "   spec-kitty init . --ai=claude"
+    )
+
+    raise FileNotFoundError(error_msg)
+
+
+__all__ = [
+    "generate_agent_assets",
+    "prepare_command_templates",
+    "render_command_template",
+    "_convert_markdown_syntax_to_format",
+]