deviatdd 2.5.1__py3-none-any.whl

deviate/cli/_common.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import inspect
+import json
+import re
+import subprocess
+from contextlib import redirect_stdout
+from functools import wraps
+from io import StringIO
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from deviate.core._shared import git_env as _git_env
+from deviate.core.constitution import resolve_constitution, validate_constitution
+from deviate.prompts.assembly import assemble_prompt
+from deviate.state.config import TransitionViolationError
+
+console = Console()
+
+
+def with_json_quiet(func):
+    """Decorator that injects ``--json`` and ``--quiet`` options into a Typer command.
+
+    ``--json``: capture stdout, serialize the command's return value as JSON,
+    print only JSON to stdout.
+
+    ``--quiet``: suppress stdout while preserving stderr output.
+
+    Flags are orthogonal: ``--json --quiet`` emits JSON on stdout and errors
+    on stderr.
+    """
+    sig = inspect.signature(func)
+    orig_params = list(sig.parameters.values())
+
+    new_params = list(orig_params)
+    new_params.extend(
+        [
+            inspect.Parameter(
+                "json",
+                inspect.Parameter.KEYWORD_ONLY,
+                default=typer.Option(
+                    False, "--json", help="Output result as JSON contract"
+                ),
+                annotation=bool,
+            ),
+            inspect.Parameter(
+                "quiet",
+                inspect.Parameter.KEYWORD_ONLY,
+                default=typer.Option(False, "--quiet", help="Suppress non-JSON output"),
+                annotation=bool,
+            ),
+        ]
+    )
+
+    @wraps(func)
+    def wrapper(**kwargs: object) -> object:
+        json_flag = kwargs.pop("json", False)
+        quiet_flag = kwargs.pop("quiet", False)
+
+        def _captured() -> object:
+            buf = StringIO()
+            with redirect_stdout(buf):
+                return func(**kwargs)
+
+        if json_flag:
+            result = _captured()
+            typer.echo(json.dumps(result))
+        elif quiet_flag:
+            result = _captured()
+        else:
+            result = func(**kwargs)
+        return result
+
+    wrapper.__signature__ = sig.replace(parameters=new_params)
+    return wrapper
+
+
+def _extract_epic_num(slug: str) -> str:
+    """Extract the leading numeric prefix from an epic slug.
+
+    ``001-deviate-cli-bootstrapping`` → ``001``
+    """
+    m = re.match(r"(\d+)", slug)
+    return m.group(1) if m else slug
+
+
+def _extract_issue_num(issue_id: str) -> str:
+    """Extract the numeric suffix from an issue ID.
+
+    ``ISS-001-006`` → ``006``, ``TSK-042`` → ``042``
+    """
+    m = re.search(r"-(\d+)$", issue_id)
+    return m.group(1) if m else issue_id
+
+
+def _halt(phase: str, message: str) -> None:
+    console.print(f"[red]{phase}_HALTED: {message}[/]")
+    raise SystemExit(1)
+
+
+def _handle_missing_dot_dir(phase: str) -> None:
+    _halt(phase, ".deviate/ not found, run 'deviate init' first")
+
+
+def _handle_transition_error(phase: str, error: TransitionViolationError) -> None:
+    _halt(phase, str(error))
+
+
+def _validate_constitution(phase: str = "CONSTITUTION") -> Path:
+    try:
+        const_path = resolve_constitution(Path.cwd())
+        if not validate_constitution(const_path):
+            _halt(phase, "constitution validation failed")
+        return const_path
+    except FileNotFoundError:
+        _halt(phase, "constitution.md not found")
+
+
+def _load_manifest(path: Path, phase: str) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, FileNotFoundError) as e:
+        _halt(phase, f"invalid manifest at {path} — {e}")
+
+
+def _run_pre_commit_hooks(worktree_path: Path | None = None) -> None:
+    """Ensure .githooks/ is configured as hooks path if the directory exists."""
+    repo = worktree_path or Path.cwd()
+    githooks_dir = repo / ".githooks"
+    if not githooks_dir.is_dir():
+        console.print("[dim]PRE_COMMIT_SKIP[/] no .githooks/ directory")
+        return
+    try:
+        subprocess.run(
+            ["git", "config", "core.hooksPath", str(githooks_dir)],
+            cwd=repo,
+            env=_git_env(),
+            check=True,
+            capture_output=True,
+        )
+        console.print("[green]PRE_COMMIT_HOOKS[/] hooks path set to .githooks/")
+    except subprocess.CalledProcessError:
+        console.print("[yellow]PRE_COMMIT_WARN[/] could not set hooks path")
+
+
+def _build_slim_prompt(phase: str, contract: dict[str, str]) -> str:
+    repo_root = Path.cwd()
+    constitution_path = repo_root / "specs" / "constitution.md"
+    return assemble_prompt(
+        template_name=phase,
+        context=contract,
+        constitution_path=constitution_path,
+    )

deviate/cli/adhoc.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+from deviate.cli._common import console
+from deviate.core._shared import git_env as _git_env
+from deviate.core.complexity import ClassificationResult, ComplexityGate
+from deviate.core.convention import format_commit_message
+from deviate.state.ledger import AdhocRecord
+
+adhoc_app = typer.Typer(no_args_is_help=True)
+
+_FLOW_REF_PATTERN = re.compile(r"^FLOW-\d{2,}$")
+_FLOW_REF_FORMAT_HINT = "expected format: FLOW-XX with at least two digits"
+
+
+def _adhoc_ledger_path() -> Path:
+    return Path.cwd() / "specs" / "adhoc.jsonl"
+
+
+def _exit_with_error(message: str, code: int = 1) -> None:
+    console.print(f"[red]{message}[/]")
+    raise typer.Exit(code=code)
+
+
+def _read_adhoc_ledger(path: Path) -> dict[str, dict]:
+    if not path.exists():
+        return {}
+    records: dict[str, dict] = {}
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+                if isinstance(rec, dict):
+                    issue_id = rec.get("issue_id")
+                    if issue_id:
+                        records[issue_id] = rec
+            except json.JSONDecodeError:
+                continue
+    return records
+
+
+def _emit_contract(status: str, **fields: object) -> None:
+    contract: dict[str, object] = {"status": status, **fields}
+    print(json.dumps(contract, indent=2))
+
+
+def _parse_flow_refs(raw: str | None) -> list[str]:
+    if raw is None:
+        return []
+    tokens = [token.strip() for token in raw.split(",") if token.strip()]
+    for token in tokens:
+        if not _FLOW_REF_PATTERN.match(token):
+            _exit_with_error(
+                f"INVALID_FLOW_REF {token!r} is not a valid flow ID "
+                f"({_FLOW_REF_FORMAT_HINT})"
+            )
+    return tokens
+
+
+@adhoc_app.command()
+def pre(
+    description: str = typer.Argument(..., help="Task description to classify"),
+    skip_gates: bool = typer.Option(
+        False,
+        "--skip-gates",
+        help="Skip complexity gate rejection for HIGH complexity tasks",
+    ),
+    flow_ref: str | None = typer.Option(
+        None,
+        "--flow-ref",
+        help="Comma-separated FLOW-XX IDs (e.g. FLOW-01,FLOW-02)",
+    ),
+) -> None:
+    """Classify an ad-hoc task description and record it for execution."""
+    flow_refs = _parse_flow_refs(flow_ref)
+    result: ClassificationResult = ComplexityGate.classify(description)
+
+    if result.level == "HIGH" and not skip_gates:
+        _exit_with_error(
+            "COMPLEXITY_GATE_REJECTION HIGH complexity tasks require "
+            "--skip-gates to proceed"
+        )
+
+    record = AdhocRecord(
+        issue_id=f"adhoc-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}",
+        description=description,
+        execution_mode=result.execution_mode,
+        status="PENDING",
+        flow_refs=flow_refs,
+    )
+
+    ledger_path = _adhoc_ledger_path()
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    with ledger_path.open("a", encoding="utf-8") as f:
+        f.write(record.model_dump_json() + "\n")
+
+    console.print(
+        f"[green]{result.execution_mode}[/] execution_mode={result.execution_mode}"
+    )
+    _emit_contract(
+        status="READY",
+        execution_mode=result.execution_mode,
+        description=description,
+        issue_id=record.issue_id,
+        flow_refs=flow_refs,
+    )
+
+
+@adhoc_app.command()
+def post(
+    issue_id: str = typer.Argument(..., help="Issue/manifest ID"),
+    title: str = typer.Option(
+        "", "--title", "-t", help="Issue title for commit message"
+    ),
+) -> None:
+    """Stage, commit ad-hoc issue artifacts, and mark record as completed."""
+    root = Path.cwd()
+
+    # --- Commit step (skip if not a git repo) ---
+    if (root / ".git").is_dir():
+        subject = f"docs(adhoc): add issue {issue_id}"
+        if title:
+            subject += f" - {title}"
+        message = format_commit_message(subject, root)
+
+        staged = subprocess.run(
+            ["git", "diff", "--cached", "--quiet"], cwd=root, env=_git_env()
+        )
+        unstaged = subprocess.run(["git", "diff", "--quiet"], cwd=root, env=_git_env())
+        untracked = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            env=_git_env(),
+        )
+        has_untracked = bool(untracked.stdout.strip())
+
+        if staged.returncode != 0 or unstaged.returncode != 0 or has_untracked:
+            subprocess.run(["git", "add", "-A"], cwd=root, env=_git_env(), check=False)
+            result = subprocess.run(
+                ["git", "commit", "-m", message, "--no-verify"],
+                cwd=root,
+                env=_git_env(),
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                console.print(f"[green]COMMITTED[/] adhoc issue {issue_id}")
+            else:
+                console.print(f"[red]COMMIT_FAILED[/] {result.stderr.strip()}")
+                raise typer.Exit(code=1)
+        else:
+            console.print("[yellow]COMMIT_SKIP[/] no changes to commit")
+    else:
+        console.print("[dim]COMMIT_SKIP[/] not a git repository")
+
+    # --- Mark adhoc record as COMPLETED ---
+    ledger_path = _adhoc_ledger_path()
+    records = _read_adhoc_ledger(ledger_path)
+    found = records.get(issue_id)
+
+    if found is None:
+        _exit_with_error(f"MANIFEST_NOT_FOUND No record found with issue_id={issue_id}")
+
+    completed = found.copy()
+    completed["status"] = "COMPLETED"
+    completed["timestamp"] = datetime.now(timezone.utc).isoformat()
+    with ledger_path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(completed) + "\n")
+    console.print(f"[green]COMPLETED[/] {issue_id}")
+
+    _emit_contract(status="COMPLETED", issue_id=issue_id)

deviate/cli/constitution.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import importlib.resources
+import json
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+from rich.console import Console
+
+from deviate.core.commit import commit_artifact
+from deviate.core.convention import format_commit_message
+from deviate.core.constitution import (
+    extract_commands,
+    validate_constitution,
+    validate_sections,
+)
+
+
+constitution_app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _fail_with(reason: str) -> NoReturn:
+    print(json.dumps({"status": "FAILURE", "reason": reason}))
+    raise typer.Exit(code=1)
+
+
+def _read_seed(filename: str) -> str | None:
+    try:
+        seed = importlib.resources.files("deviate.prompts").joinpath(filename)
+        return seed.read_text(encoding="utf-8")
+    except (ModuleNotFoundError, FileNotFoundError):
+        console.print(f"  [red]ERROR[/] {filename} not found in package")
+        return None
+
+
+@constitution_app.command()
+def generate(
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite existing constitution.md"
+    ),
+) -> None:
+    """Scaffold a placeholder specs/constitution.md.
+
+    The placeholder is populated by ``/research`` during the macro layer.
+    """
+    specs_dir = Path.cwd() / "specs"
+    const_path = specs_dir / "constitution.md"
+
+    if const_path.exists() and not force:
+        console.print(
+            "  [yellow]SKIP[/] specs/constitution.md already exists."
+            " Use --force to overwrite."
+        )
+        return
+
+    seed = _read_seed("constitution_seed.md")
+    if seed is None:
+        raise typer.Exit(code=1)
+
+    specs_dir.mkdir(parents=True, exist_ok=True)
+    const_path.write_text(seed, encoding="utf-8")
+    console.print(f"  [green]CREATE[/] {const_path.relative_to(Path.cwd())}")
+
+
+@constitution_app.command()
+def pre() -> None:
+    """Validate constitution and extract commands."""
+    repo_root = Path.cwd()
+    const_path = repo_root / "specs" / "constitution.md"
+
+    if not const_path.exists():
+        _fail_with(f"constitution.md not found at {const_path}")
+
+    if not validate_constitution(const_path):
+        _fail_with("constitution validation failed")
+
+    missing = validate_sections(const_path, ["## TESTING_PROTOCOLS"])
+    if missing:
+        _fail_with(f"Missing required section: {missing[0]}")
+
+    commands = extract_commands(const_path)
+    print(json.dumps(commands))
+
+
+@constitution_app.command()
+def post(
+    manifest: str = typer.Argument(..., help="Path to manifest JSON"),
+) -> None:
+    """Validate constitution sections and commit."""
+    manifest_path = Path(manifest)
+
+    if not manifest_path.exists():
+        _fail_with(f"manifest not found at {manifest_path}")
+
+    manifest_data = json.loads(manifest_path.read_text())
+    sections = manifest_data.get("sections", [])
+    const_rel_path = manifest_data.get("constitution_path", "specs/constitution.md")
+
+    const_path = Path.cwd() / const_rel_path
+
+    missing = validate_sections(const_path, sections)
+    if missing:
+        _fail_with(f"Missing sections: {', '.join(missing)}")
+
+    commit_artifact(
+        path=const_path,
+        message=format_commit_message(
+            "chore(constitution): update constitution", Path.cwd()
+        ),
+    )
+    print(json.dumps({"status": "SUCCESS"}))

deviate/cli/feature.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+import typer
+from deviate.cli._common import console
+from deviate.core._shared import git_env
+from deviate.state.config import SessionState, resolve_graphite_config
+
+feature_app = typer.Typer(no_args_is_help=True)
+
+
+def _derive_slug(title: str) -> str:
+    slug = title.lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)
+    slug = slug.strip("-")
+    return slug
+
+
+def _create_feature_directory(slug: str, repo_path: Path) -> Path:
+    spec_dir = repo_path / "specs" / slug
+    spec_dir.mkdir(parents=True, exist_ok=True)
+    return spec_dir
+
+
+def _create_feature_branch(slug: str, repo_path: Path) -> None:
+    """Create `feat/<slug>` via Graphite (`gt create -am`) or git.
+
+    Git Isolation: never `git checkout -b` — agents running TDD cycles
+    must not mutate branch state. This CLI command is the only
+    sanctioned entry point for branch creation in a worktree.
+    """
+    branch_name = f"feat/{slug}"
+
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", "--quiet", branch_name],
+        cwd=repo_path,
+        env=git_env(),
+        capture_output=True,
+    )
+    if result.returncode == 0:
+        return
+
+    if resolve_graphite_config(repo_path):
+        try:
+            subprocess.run(
+                ["gt", "create", "-am", branch_name],
+                cwd=repo_path,
+                env=git_env(),
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except FileNotFoundError:
+            console.print(
+                "[red]GRAPHITE_NOT_FOUND[/] Graphite CLI (gt) not found on PATH.\n"
+                "See https://graphite.dev/docs/cli for installation instructions."
+            )
+            raise typer.Exit(code=1)
+        except subprocess.CalledProcessError as e:
+            detail = e.stderr.strip() if e.stderr else "Graphite CLI (gt) failed."
+            console.print(
+                f"[red]GRAPHITE_FAILED[/] {detail} "
+                "See https://graphite.dev/docs/cli for installation instructions."
+            )
+            raise typer.Exit(code=1)
+        return
+
+    subprocess.run(
+        ["git", "branch", branch_name],
+        cwd=repo_path,
+        env=git_env(),
+        check=True,
+    )
+
+
+@feature_app.command()
+def create(
+    title: str = typer.Argument(..., help="Feature title"),
+    slug: str | None = typer.Option(None, "--slug", help="Override derived slug"),
+) -> None:
+    repo_path = Path.cwd()
+    final_slug = slug or _derive_slug(title)
+
+    _create_feature_directory(final_slug, repo_path)
+    _create_feature_branch(final_slug, repo_path)
+
+    session_dir = repo_path / ".deviate"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    session = SessionState()
+    session_path = session_dir / "session.json"
+    session.save(session_path)