a2c-cli 0.2.1__py3-none-any.whl

a2c_cli/__init__.py

@@ -0,0 +1 @@
+"""A2C command-line interface — thin layer over a2c_core."""

a2c_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules (Milestone 3+)."""

a2c_cli/commands/apply.py

@@ -0,0 +1,111 @@
+"""Apply commands — write validated proposals into planning/."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from a2c_cli.context import echo_issues
+from a2c_cli.exit_codes import EXIT_NO_PROPOSAL, EXIT_NOT_FOUND, EXIT_VALIDATION_FAILED
+from a2c_cli.output import (
+    format_apply_epic_summary,
+    format_apply_summary,
+    format_apply_task_intake_summary,
+)
+from a2c_core.errors import A2C_WORKFLOW_001, A2C_WORKFLOW_003, A2C_WORKFLOW_004
+from a2c_core.services import apply_epic_draft, apply_task_intake_draft, apply_tasks_from_epic
+
+
+def apply_epic_draft_cmd(
+    epic_id: str,
+    path: Path | None,
+    *,
+    force: bool,
+) -> None:
+    """Apply a cached epic draft into planning/epics/."""
+    result = apply_epic_draft(path, epic_id, force=force)
+    if not result.ok:
+        if any(issue.code == A2C_WORKFLOW_001 for issue in result.errors):
+            typer.echo("A2C apply: no valid epic draft", err=True)
+            echo_issues("Errors", result.errors, err=True)
+            raise typer.Exit(EXIT_NO_PROPOSAL)
+        if any(issue.code == A2C_WORKFLOW_003 for issue in result.errors):
+            typer.echo("A2C apply: epic id conflict", err=True)
+            echo_issues("Errors", result.errors, err=True)
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        typer.echo("A2C apply: failed", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    format_apply_epic_summary(result.value)
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)
+
+
+def apply_task_intake_draft_cmd(
+    draft_key: str,
+    path: Path | None,
+    *,
+    force: bool,
+) -> None:
+    """Apply a cached single-task intake draft into planning/tasks/."""
+    result = apply_task_intake_draft(path, draft_key, force=force)
+    if not result.ok:
+        if any(issue.code == A2C_WORKFLOW_001 for issue in result.errors):
+            typer.echo("A2C apply: no valid task draft", err=True)
+            echo_issues("Errors", result.errors, err=True)
+            raise typer.Exit(EXIT_NO_PROPOSAL)
+        if any(issue.code == A2C_WORKFLOW_003 for issue in result.errors):
+            typer.echo("A2C apply: task id conflict", err=True)
+            echo_issues("Errors", result.errors, err=True)
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        typer.echo("A2C apply: failed", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    task = result.value
+    format_apply_task_intake_summary(
+        task.id,
+        title=task.title,
+        epic_id=task.epic_id,
+    )
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)
+
+
+def apply_tasks_from_epic_cmd(
+    epic_id: str,
+    path: Path | None,
+    *,
+    force: bool,
+) -> None:
+    """Apply cached task drafts for an epic into planning/tasks/."""
+    result = apply_tasks_from_epic(path, epic_id, force=force)
+    if not result.ok:
+        if any(issue.code == A2C_WORKFLOW_004 for issue in result.errors):
+            typer.echo("A2C apply: epic not found", err=True)
+            raise typer.Exit(EXIT_NOT_FOUND)
+        if any(issue.code == A2C_WORKFLOW_001 for issue in result.errors):
+            typer.echo("A2C apply: no valid proposal", err=True)
+            echo_issues("Errors", result.errors, err=True)
+            raise typer.Exit(EXIT_NO_PROPOSAL)
+        typer.echo("A2C apply: failed", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    format_apply_summary(epic_id, result.value)
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)

a2c_cli/commands/doctor.py

@@ -0,0 +1,23 @@
+"""Doctor command — repository health checks."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from a2c_cli.exit_codes import EXIT_NOT_A2C_REPO, EXIT_VALIDATION_FAILED
+from a2c_cli.output import format_doctor_report
+from a2c_core.services import check_repository_health
+
+
+def doctor_cmd(path: Path | None = None) -> None:
+    """Check A2C repository structure and readiness."""
+    report = check_repository_health(path)
+    format_doctor_report(report)
+
+    if report.root is None:
+        raise typer.Exit(EXIT_NOT_A2C_REPO)
+    if not report.ok:
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+    raise typer.Exit(0)

a2c_cli/commands/list_cmd.py

@@ -0,0 +1,26 @@
+"""List planning artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from a2c_cli.context import require_snapshot
+from a2c_cli.output import format_epic_list, format_sprint_list, format_task_list
+
+
+def list_epics(path: Path | None = None) -> None:
+    """List epics under planning/epics/."""
+    snapshot = require_snapshot(path)
+    format_epic_list(snapshot.epics)
+
+
+def list_tasks(path: Path | None = None) -> None:
+    """List tasks under planning/tasks/."""
+    snapshot = require_snapshot(path)
+    format_task_list(snapshot.tasks)
+
+
+def list_sprints(path: Path | None = None) -> None:
+    """List sprints under planning/sprints/."""
+    snapshot = require_snapshot(path)
+    format_sprint_list(snapshot.sprints)

a2c_cli/commands/plan.py

@@ -0,0 +1,322 @@
+"""Plan commands — AI-assisted proposal generation."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from a2c_cli.context import echo_issues, require_inspection
+from a2c_cli.exit_codes import EXIT_NOT_FOUND, EXIT_VALIDATION_FAILED
+from a2c_cli.output import (
+    format_create_epic_summary,
+    format_create_task_summary,
+    format_decomposition_summary,
+)
+from a2c_core.errors import A2C_PROVIDER_004, A2C_WORKFLOW_004, ValidationIssue
+from a2c_core.schemas.workflows_io import TaskIntakeKind
+from a2c_core.services import (
+    create_epic_from_brief,
+    create_task_from_input,
+    create_task_from_task_json,
+    decompose_epic,
+)
+from a2c_core.workflows.provider_errors import ProviderError
+from a2c_core.workflows.providers.resolver import (
+    merge_decomposition_settings,
+    resolve_create_epic_provider,
+    resolve_create_task_provider,
+    resolve_decomposition_provider,
+)
+
+
+def _collect_brief(
+    *,
+    from_text: str | None,
+    from_file: Path | None,
+    use_stdin: bool,
+) -> str:
+    modes = [from_text is not None, from_file is not None, use_stdin]
+    if sum(modes) != 1:
+        typer.echo(
+            "error: provide exactly one input: --from-text, --from-file, or --stdin",
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    if from_text is not None:
+        return from_text
+    if from_file is not None:
+        if not from_file.is_file():
+            typer.echo(f"error: brief file not found: {from_file}", err=True)
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        return from_file.read_text(encoding="utf-8")
+    return sys.stdin.read()
+
+
+def _resolve_task_kind(*, task_type: str | None, use_bug: bool) -> TaskIntakeKind:
+    if use_bug or task_type == "bug":
+        return "bug"
+    if task_type is not None and task_type != "feature":
+        typer.echo(
+            f"error: unsupported task type {task_type!r}; use feature or bug",
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+    return "feature"
+
+
+def _collect_task_input(
+    *,
+    from_text: str | None,
+    from_file: Path | None,
+    from_task_json: Path | None,
+    use_stdin: bool,
+) -> str | None:
+    modes = [
+        from_text is not None,
+        from_file is not None,
+        from_task_json is not None,
+        use_stdin,
+    ]
+    if sum(modes) != 1:
+        typer.echo(
+            "error: provide exactly one input: --from-text, --from-file, "
+            "--from-task-json, or --stdin",
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    if from_task_json is not None:
+        return None
+
+    if from_text is not None:
+        return from_text
+    if from_file is not None:
+        if not from_file.is_file():
+            typer.echo(f"error: intake file not found: {from_file}", err=True)
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        return from_file.read_text(encoding="utf-8")
+    return sys.stdin.read()
+
+
+def _reject_provider_flags_with_task_json(
+    *,
+    from_task_json: Path | None,
+    provider_name: str | None,
+    fixture_path: Path | None,
+    model: str | None,
+    endpoint: str | None,
+) -> None:
+    if from_task_json is None:
+        return
+    blocked = [
+        name
+        for name, value in (
+            ("--provider", provider_name),
+            ("--fixture", fixture_path),
+            ("--model", model),
+            ("--endpoint", endpoint),
+        )
+        if value is not None
+    ]
+    if blocked:
+        joined = ", ".join(blocked)
+        typer.echo(
+            f"error: {joined} cannot be used with --from-task-json",
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+
+def create_task_cmd(
+    path: Path | None,
+    *,
+    from_text: str | None,
+    from_file: Path | None,
+    from_task_json: Path | None,
+    use_stdin: bool,
+    task_type: str | None,
+    use_bug: bool,
+    epic_id: str | None,
+    provider_name: str | None,
+    fixture_path: Path | None,
+    model: str | None,
+    endpoint: str | None,
+) -> None:
+    """Generate and review a proposed single task draft from raw input."""
+    _reject_provider_flags_with_task_json(
+        from_task_json=from_task_json,
+        provider_name=provider_name,
+        fixture_path=fixture_path,
+        model=model,
+        endpoint=endpoint,
+    )
+
+    if from_task_json is not None:
+        if not from_task_json.is_file():
+            typer.echo(f"error: task JSON file not found: {from_task_json}", err=True)
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        result = create_task_from_task_json(path, from_task_json, epic_id=epic_id)
+    else:
+        input_text = _collect_task_input(
+            from_text=from_text,
+            from_file=from_file,
+            from_task_json=None,
+            use_stdin=use_stdin,
+        )
+        assert input_text is not None
+        task_kind = _resolve_task_kind(task_type=task_type, use_bug=use_bug)
+        inspection = require_inspection(path)
+        assert inspection.snapshot is not None
+        config = merge_decomposition_settings(
+            inspection.snapshot.config,
+            model=model,
+            endpoint=endpoint,
+        )
+        try:
+            provider = resolve_create_task_provider(
+                provider_name=provider_name,
+                config=config,
+                fixture_path=fixture_path,
+                repo_root=inspection.root,
+            )
+        except ProviderError as exc:
+            typer.echo("A2C plan: provider configuration failed", err=True)
+            echo_issues(
+                "Errors",
+                [ValidationIssue(code=exc.code, message=exc.message, path="provider")],
+                err=True,
+            )
+            raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+
+        result = create_task_from_input(
+            path,
+            input_text,
+            provider,
+            task_kind=task_kind,
+            epic_id=epic_id,
+        )
+
+    if not result.ok:
+        typer.echo("A2C plan: task authoring failed", err=True)
+        if any(issue.code == A2C_WORKFLOW_004 for issue in result.errors):
+            raise typer.Exit(EXIT_NOT_FOUND)
+        if any(issue.code == A2C_PROVIDER_004 for issue in result.errors):
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    format_create_task_summary(result.value)
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)
+
+
+def create_epic_cmd(
+    path: Path | None,
+    *,
+    from_text: str | None,
+    from_file: Path | None,
+    use_stdin: bool,
+    provider_name: str | None,
+    fixture_path: Path | None,
+    model: str | None,
+    endpoint: str | None,
+) -> None:
+    """Generate and review a proposed epic draft from a short brief."""
+    brief = _collect_brief(from_text=from_text, from_file=from_file, use_stdin=use_stdin)
+    inspection = require_inspection(path)
+    assert inspection.snapshot is not None
+    config = merge_decomposition_settings(
+        inspection.snapshot.config,
+        model=model,
+        endpoint=endpoint,
+    )
+    try:
+        provider = resolve_create_epic_provider(
+            provider_name=provider_name,
+            config=config,
+            fixture_path=fixture_path,
+            repo_root=inspection.root,
+        )
+    except ProviderError as exc:
+        typer.echo("A2C plan: provider configuration failed", err=True)
+        echo_issues(
+            "Errors",
+            [ValidationIssue(code=exc.code, message=exc.message, path="provider")],
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+
+    result = create_epic_from_brief(path, brief, provider)
+    if not result.ok:
+        typer.echo("A2C plan: epic authoring failed", err=True)
+        if any(issue.code == A2C_PROVIDER_004 for issue in result.errors):
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    format_create_epic_summary(result.value)
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)
+
+
+def decompose_epic_cmd(
+    epic_id: str,
+    path: Path | None,
+    *,
+    provider_name: str | None,
+    fixture_path: Path | None,
+    model: str | None,
+    endpoint: str | None,
+) -> None:
+    """Generate and review proposed task drafts for an epic."""
+    inspection = require_inspection(path)
+    assert inspection.snapshot is not None
+    config = merge_decomposition_settings(
+        inspection.snapshot.config,
+        model=model,
+        endpoint=endpoint,
+    )
+    try:
+        provider = resolve_decomposition_provider(
+            provider_name=provider_name,
+            config=config,
+            fixture_path=fixture_path,
+            repo_root=inspection.root,
+        )
+    except ProviderError as exc:
+        typer.echo("A2C plan: provider configuration failed", err=True)
+        echo_issues(
+            "Errors",
+            [ValidationIssue(code=exc.code, message=exc.message, path="provider")],
+            err=True,
+        )
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+
+    result = decompose_epic(path, epic_id, provider)
+    if not result.ok:
+        typer.echo("A2C plan: decomposition failed", err=True)
+        if any(issue.code == A2C_WORKFLOW_004 for issue in result.errors):
+            raise typer.Exit(EXIT_NOT_FOUND)
+        if any(issue.code == A2C_PROVIDER_004 for issue in result.errors):
+            raise typer.Exit(EXIT_VALIDATION_FAILED)
+        echo_issues("Errors", result.errors, err=True)
+        if result.warnings:
+            echo_issues("Warnings", result.warnings)
+        raise typer.Exit(EXIT_VALIDATION_FAILED)
+
+    assert result.value is not None
+    format_decomposition_summary(result.value)
+    if result.warnings:
+        typer.echo("")
+        echo_issues("Warnings", result.warnings)

a2c_cli/commands/show.py

@@ -0,0 +1,98 @@
+"""Show a single planning artifact."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from a2c_cli.context import echo_issues, exit_not_found, require_snapshot
+from a2c_cli.exit_codes import EXIT_NO_PROPOSAL, EXIT_NOT_FOUND
+from a2c_cli.output import (
+    format_draft_epic_show,
+    format_draft_task_intake_show,
+    format_draft_task_show,
+    format_epic_show,
+    format_sprint_show,
+    format_task_show,
+)
+from a2c_core.services import (
+    get_cached_epic_draft,
+    get_cached_proposal,
+    get_cached_task_intake_draft,
+)
+
+
+def show_epic(artifact_id: str, path: Path | None = None) -> None:
+    """Show one epic by id."""
+    snapshot = require_snapshot(path)
+    for epic in snapshot.epics:
+        if epic.id == artifact_id:
+            format_epic_show(epic)
+            return
+    exit_not_found("epic", artifact_id)
+
+
+def show_task(artifact_id: str, path: Path | None = None) -> None:
+    """Show one task by id."""
+    snapshot = require_snapshot(path)
+    for task in snapshot.tasks:
+        if task.id == artifact_id:
+            format_task_show(task)
+            return
+    exit_not_found("task", artifact_id)
+
+
+def show_sprint(artifact_id: str, path: Path | None = None) -> None:
+    """Show one sprint by id."""
+    snapshot = require_snapshot(path)
+    for sprint in snapshot.sprints:
+        if sprint.id == artifact_id:
+            format_sprint_show(sprint)
+            return
+    exit_not_found("sprint", artifact_id)
+
+
+def show_draft_epic(epic_id: str, path: Path | None = None) -> None:
+    """Show a proposed epic draft from cache."""
+    result = get_cached_epic_draft(path, epic_id)
+    if not result.ok:
+        typer.echo("A2C show: epic draft not available", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        raise typer.Exit(EXIT_NO_PROPOSAL)
+
+    assert result.value is not None
+    format_draft_epic_show(result.value)
+
+
+def show_draft_task_intake(draft_key: str, path: Path | None = None) -> None:
+    """Show a proposed single-task intake draft from cache."""
+    result = get_cached_task_intake_draft(path, draft_key)
+    if not result.ok:
+        typer.echo("A2C show: task intake draft not available", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        raise typer.Exit(EXIT_NO_PROPOSAL)
+
+    assert result.value is not None
+    format_draft_task_intake_show(result.value)
+
+
+def show_draft_task(epic_id: str, draft_index: int, path: Path | None = None) -> None:
+    """Show one proposed task draft from a cached decomposition."""
+    result = get_cached_proposal(path, epic_id)
+    if not result.ok:
+        typer.echo("A2C show: draft task not available", err=True)
+        echo_issues("Errors", result.errors, err=True)
+        raise typer.Exit(EXIT_NO_PROPOSAL)
+
+    assert result.value is not None
+    proposal = result.value
+    if draft_index < 1 or draft_index > len(proposal.tasks):
+        typer.echo(
+            f"error: draft index {draft_index} out of range (1..{len(proposal.tasks)})",
+            err=True,
+        )
+        raise typer.Exit(EXIT_NOT_FOUND)
+
+    draft = proposal.tasks[draft_index - 1]
+    format_draft_task_show(draft, index=draft_index, epic_id=epic_id)

a2c_cli/commands/validate.py

@@ -0,0 +1,22 @@
+"""Validate command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from a2c_cli.exit_codes import EXIT_NOT_A2C_REPO, EXIT_VALIDATION_FAILED
+from a2c_cli.output import format_validation_report
+from a2c_core.services import inspect_repository
+
+
+def validate_cmd(path: Path | None = None) -> None:
+    """Validate A2C config and planning artifacts."""
+    result = inspect_repository(path)
+    format_validation_report(result)
+
+    if result.root is None:
+        raise typer.Exit(EXIT_NOT_A2C_REPO)
+    if result.errors:
+        raise typer.Exit(EXIT_VALIDATION_FAILED)

a2c_cli/context.py

@@ -0,0 +1,56 @@
+"""Shared CLI context — repository resolution and errors."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+
+from a2c_cli.exit_codes import EXIT_NOT_A2C_REPO, EXIT_NOT_FOUND
+from a2c_core.errors import A2C_REPO_001
+from a2c_core.services import inspect_repository
+from a2c_core.services.inspection import InspectionResult
+from a2c_core.services.repo import RepositorySnapshot
+
+_NOT_A2C_MESSAGE = (
+    "Not inside an A2C repository. Expected a root marker such as "
+    "AGENTS.md, docs/workflow-manifest.yaml, or .a2c/config.yaml."
+)
+
+
+def require_inspection(start: Path | None = None) -> InspectionResult:
+    """Load repository inspection or exit when not in an A2C repo."""
+    result = inspect_repository(start)
+    if result.root is None:
+        issue = result.errors[0] if result.errors else None
+        if issue and issue.code == A2C_REPO_001:
+            typer.echo(f"error: {_NOT_A2C_MESSAGE}", err=True)
+        else:
+            typer.echo("error: unable to locate A2C repository root", err=True)
+        raise typer.Exit(EXIT_NOT_A2C_REPO)
+    return result
+
+
+def require_snapshot(start: Path | None = None) -> RepositorySnapshot:
+    """Return a loaded snapshot for read-only list/show commands."""
+    result = require_inspection(start)
+    assert result.snapshot is not None
+    return result.snapshot
+
+
+def exit_not_found(kind: str, artifact_id: str) -> None:
+    """Exit when a planning artifact id cannot be resolved."""
+    typer.echo(f"error: {kind} {artifact_id!r} not found", err=True)
+    raise typer.Exit(EXIT_NOT_FOUND)
+
+
+def echo_issues(label: str, issues: list, *, err: bool = False) -> None:
+    """Print structured validation issues."""
+    if not issues:
+        return
+    stream = sys.stderr if err else sys.stdout
+    typer.echo(f"{label} ({len(issues)}):", err=err)
+    for issue in issues:
+        path = issue.path or "-"
+        typer.echo(f"  {path}: [{issue.code}] {issue.message}", err=err, file=stream)

a2c_cli/exit_codes.py

@@ -0,0 +1,10 @@
+"""CLI exit codes for CI and scripting."""
+
+from __future__ import annotations
+
+EXIT_OK = 0
+EXIT_VALIDATION_FAILED = 1
+EXIT_NOT_A2C_REPO = 2
+EXIT_NOT_FOUND = 3
+EXIT_USAGE = 4
+EXIT_NO_PROPOSAL = 5