a2c-cli 0.2.1__py3-none-any.whl

a2c_cli/main.py

@@ -0,0 +1,329 @@
+"""CLI entrypoint and command groups."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from a2c_cli.commands.apply import (
+    apply_epic_draft_cmd,
+    apply_task_intake_draft_cmd,
+    apply_tasks_from_epic_cmd,
+)
+from a2c_cli.commands.doctor import doctor_cmd
+from a2c_cli.commands.list_cmd import list_epics, list_sprints, list_tasks
+from a2c_cli.commands.plan import create_epic_cmd, create_task_cmd, decompose_epic_cmd
+from a2c_cli.commands.show import (
+    show_draft_epic,
+    show_draft_task,
+    show_draft_task_intake,
+    show_epic,
+    show_sprint,
+    show_task,
+)
+from a2c_cli.commands.validate import validate_cmd
+from a2c_core import __version__
+
+app = typer.Typer(
+    name="a2c",
+    help="Architecture-to-Commit (A2C) — inspect, validate, and plan repositories",
+    no_args_is_help=True,
+)
+
+list_app = typer.Typer(help="List planning artifacts")
+show_app = typer.Typer(help="Show one planning artifact")
+plan_app = typer.Typer(help="AI-assisted planning proposals (review-first)")
+apply_app = typer.Typer(help="Apply validated proposals into planning/")
+
+PathOption = Annotated[
+    Path | None,
+    typer.Option("--path", "-C", help="Repository path (default: current directory)"),
+]
+
+
+@app.callback()
+def main() -> None:
+    """A2C command-line interface."""
+
+
+@app.command("version")
+def version_cmd() -> None:
+    """Print the a2c-core product version."""
+    typer.echo(f"a2c-core {__version__}")
+
+
+@app.command("validate")
+def validate(path: PathOption = None) -> None:
+    """Validate config and planning artifacts."""
+    validate_cmd(path)
+
+
+@list_app.command("epics")
+def list_epics_cmd(path: PathOption = None) -> None:
+    list_epics(path)
+
+
+@list_app.command("tasks")
+def list_tasks_cmd(path: PathOption = None) -> None:
+    list_tasks(path)
+
+
+@list_app.command("sprints")
+def list_sprints_cmd(path: PathOption = None) -> None:
+    list_sprints(path)
+
+
+app.add_typer(list_app, name="list")
+
+
+@show_app.command("epic")
+def show_epic_cmd(
+    artifact_id: Annotated[str, typer.Argument(help="Epic id")],
+    path: PathOption = None,
+) -> None:
+    show_epic(artifact_id, path)
+
+
+@show_app.command("task")
+def show_task_cmd(
+    artifact_id: Annotated[str, typer.Argument(help="Task id")],
+    path: PathOption = None,
+) -> None:
+    show_task(artifact_id, path)
+
+
+@show_app.command("sprint")
+def show_sprint_cmd(
+    artifact_id: Annotated[str, typer.Argument(help="Sprint id")],
+    path: PathOption = None,
+) -> None:
+    show_sprint(artifact_id, path)
+
+
+@show_app.command("draft-epic")
+def show_draft_epic_cmd(
+    epic_id: Annotated[str, typer.Argument(help="Proposed epic id for the cached draft")],
+    path: PathOption = None,
+) -> None:
+    """Show one proposed epic draft (not applied)."""
+    show_draft_epic(epic_id, path)
+
+
+@show_app.command("draft-task-intake")
+def show_draft_task_intake_cmd(
+    draft_key: Annotated[str, typer.Argument(help="Draft key from plan create-task")],
+    path: PathOption = None,
+) -> None:
+    """Show one proposed single-task intake draft (not applied)."""
+    show_draft_task_intake(draft_key, path)
+
+
+@show_app.command("draft-task")
+def show_draft_task_cmd(
+    epic_id: Annotated[str, typer.Argument(help="Epic id for the cached proposal")],
+    draft_index: Annotated[int, typer.Argument(help="1-based draft index")],
+    path: PathOption = None,
+) -> None:
+    """Show one proposed task draft (not yet applied)."""
+    show_draft_task(epic_id, draft_index, path)
+
+
+app.add_typer(show_app, name="show")
+
+
+@plan_app.command("create-epic")
+def plan_create_epic_cmd(
+    path: PathOption = None,
+    from_text: Annotated[
+        str | None,
+        typer.Option("--from-text", help="Short feature brief as inline text"),
+    ] = None,
+    from_file: Annotated[
+        Path | None,
+        typer.Option("--from-file", help="Path to a Markdown or text brief"),
+    ] = None,
+    use_stdin: Annotated[
+        bool,
+        typer.Option("--stdin", help="Read brief from standard input"),
+    ] = False,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help="AI provider (mock, openai, local, ollama)"),
+    ] = None,
+    fixture: Annotated[
+        Path | None,
+        typer.Option("--fixture", help="JSON fixture for mock provider"),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override decomposition.model from config"),
+    ] = None,
+    endpoint: Annotated[
+        str | None,
+        typer.Option("--endpoint", help="Override decomposition.endpoint from config"),
+    ] = None,
+) -> None:
+    """Propose an epic draft from a brief without writing planning files."""
+    create_epic_cmd(
+        path,
+        from_text=from_text,
+        from_file=from_file,
+        use_stdin=use_stdin,
+        provider_name=provider,
+        fixture_path=fixture,
+        model=model,
+        endpoint=endpoint,
+    )
+
+
+@plan_app.command("create-task")
+def plan_create_task_cmd(
+    path: PathOption = None,
+    from_text: Annotated[
+        str | None,
+        typer.Option("--from-text", help="Short description or bug report text"),
+    ] = None,
+    from_file: Annotated[
+        Path | None,
+        typer.Option("--from-file", help="Path to a text or Markdown intake file"),
+    ] = None,
+    from_task_json: Annotated[
+        Path | None,
+        typer.Option(
+            "--from-task-json",
+            help="Path to a single decomposition-style task JSON object (no LLM)",
+        ),
+    ] = None,
+    use_stdin: Annotated[
+        bool,
+        typer.Option("--stdin", help="Read intake text from standard input"),
+    ] = False,
+    task_type: Annotated[
+        str | None,
+        typer.Option("--type", help="Task template: feature or bug"),
+    ] = None,
+    use_bug: Annotated[
+        bool,
+        typer.Option("--bug", help="Use bug intake template (same as --type bug)"),
+    ] = False,
+    epic: Annotated[
+        str | None,
+        typer.Option("--epic", help="Optional epic id to link the task to"),
+    ] = None,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help="AI provider (mock, openai, local, ollama)"),
+    ] = None,
+    fixture: Annotated[
+        Path | None,
+        typer.Option("--fixture", help="JSON fixture for mock provider"),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override decomposition.model from config"),
+    ] = None,
+    endpoint: Annotated[
+        str | None,
+        typer.Option("--endpoint", help="Override decomposition.endpoint from config"),
+    ] = None,
+) -> None:
+    """Propose a single task draft from raw input without writing planning files."""
+    create_task_cmd(
+        path,
+        from_text=from_text,
+        from_file=from_file,
+        from_task_json=from_task_json,
+        use_stdin=use_stdin,
+        task_type=task_type,
+        use_bug=use_bug,
+        epic_id=epic,
+        provider_name=provider,
+        fixture_path=fixture,
+        model=model,
+        endpoint=endpoint,
+    )
+
+
+@plan_app.command("decompose-epic")
+def plan_decompose_epic_cmd(
+    epic_id: Annotated[str, typer.Argument(help="Epic id to decompose")],
+    path: PathOption = None,
+    provider: Annotated[
+        str | None,
+        typer.Option("--provider", help="AI provider (mock, openai, local, ollama)"),
+    ] = None,
+    fixture: Annotated[
+        Path | None,
+        typer.Option("--fixture", help="JSON fixture for mock provider"),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Override decomposition.model from config"),
+    ] = None,
+    endpoint: Annotated[
+        str | None,
+        typer.Option("--endpoint", help="Override decomposition.endpoint from config"),
+    ] = None,
+) -> None:
+    """Propose task drafts for an epic without writing planning files."""
+    decompose_epic_cmd(
+        epic_id,
+        path,
+        provider_name=provider,
+        fixture_path=fixture,
+        model=model,
+        endpoint=endpoint,
+    )
+
+
+app.add_typer(plan_app, name="plan")
+
+
+@apply_app.command("draft-epic")
+def apply_draft_epic_command(
+    epic_id: Annotated[str, typer.Argument(help="Proposed epic id with a cached draft")],
+    path: PathOption = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite an existing epic file with the same id"),
+    ] = False,
+) -> None:
+    """Apply a cached epic draft into planning/epics/."""
+    apply_epic_draft_cmd(epic_id, path, force=force)
+
+
+@apply_app.command("draft-task")
+def apply_draft_task_command(
+    draft_key: Annotated[str, typer.Argument(help="Draft key from plan create-task")],
+    path: PathOption = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite an existing task file with the same id"),
+    ] = False,
+) -> None:
+    """Apply a cached single-task intake draft into planning/tasks/."""
+    apply_task_intake_draft_cmd(draft_key, path, force=force)
+
+
+@apply_app.command("tasks-from-epic")
+def apply_tasks_from_epic_command(
+    epic_id: Annotated[str, typer.Argument(help="Epic id with a cached proposal")],
+    path: PathOption = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite existing task files with the same id"),
+    ] = False,
+) -> None:
+    """Apply cached task drafts for an epic into planning/tasks/."""
+    apply_tasks_from_epic_cmd(epic_id, path, force=force)
+
+
+app.add_typer(apply_app, name="apply")
+
+
+@app.command("doctor")
+def doctor(path: PathOption = None) -> None:
+    """Check repository structure and readiness."""
+    doctor_cmd(path)

a2c_cli/output.py

@@ -0,0 +1,367 @@
+"""Human-readable CLI output formatters."""
+
+from __future__ import annotations
+
+import re
+
+import typer
+
+from a2c_core.errors import ValidationIssue
+from a2c_core.schemas.artifacts import Epic, Sprint, Task
+from a2c_core.schemas.workflows_io import (
+    EpicDecompositionProposal,
+    EpicDraftProposal,
+    TaskDraftItem,
+    TaskIntakeDraftProposal,
+)
+from a2c_core.services.doctor import DoctorReport
+from a2c_core.services.inspection import InspectionResult
+
+_BODY_SECTION_RE = re.compile(r"^##\s+(.+)$", re.MULTILINE)
+
+
+def format_validation_report(result: InspectionResult) -> None:
+    """Print validate command summary."""
+    if result.root is None:
+        typer.echo("A2C validation: FAILED")
+        typer.echo("error: not inside an A2C repository", err=True)
+        if result.errors:
+            _echo_issue_block("Errors", result.errors, err=True)
+        return
+
+    status = "PASSED" if result.ok else "FAILED"
+    typer.echo(f"A2C validation: {status}")
+    if result.root is not None:
+        typer.echo(f"Repository: {result.root}")
+
+    typer.echo("")
+    typer.echo("Planning artifacts:")
+    for summary in result.summaries:
+        invalid = _invalid_count(result.errors, summary.kind)
+        valid = max(summary.parsed - invalid, 0)
+        found = summary.parsed + summary.loader_errors
+        typer.echo(
+            f"  {summary.kind + 's':7}  found {found:2d}  "
+            f"valid {valid:2d}  invalid {invalid + summary.loader_errors:2d}"
+        )
+
+    if result.warnings:
+        typer.echo("")
+        _echo_issue_block("Warnings", result.warnings)
+
+    if result.errors:
+        typer.echo("")
+        _echo_issue_block("Errors", result.errors, err=True)
+
+
+def _invalid_count(errors: list[ValidationIssue], kind: str) -> int:
+    segment = f"planning/{kind}s/"
+    paths = {
+        issue.path for issue in errors if issue.path and segment in issue.path.replace("\\", "/")
+    }
+    return len(paths)
+
+
+def _echo_issue_block(title: str, issues: list[ValidationIssue], *, err: bool = False) -> None:
+    typer.echo(f"{title} ({len(issues)}):", err=err)
+    for issue in issues:
+        path = issue.path or "-"
+        typer.echo(f"  {path}: [{issue.code}] {issue.message}", err=err)
+
+
+def format_epic_list(epics: list[Epic]) -> None:
+    if not epics:
+        typer.echo("No epics found.")
+        return
+    typer.echo(f"{'ID':<24} {'STATUS':<12} TITLE")
+    for epic in sorted(epics, key=lambda item: item.id):
+        typer.echo(f"{epic.id:<24} {epic.status:<12} {epic.title}")
+
+
+def format_task_list(tasks: list[Task]) -> None:
+    if not tasks:
+        typer.echo("No tasks found.")
+        return
+    typer.echo(f"{'ID':<24} {'STATUS':<12} {'EPIC':<18} TITLE")
+    for task in sorted(tasks, key=lambda item: item.id):
+        epic = task.epic_id or "-"
+        typer.echo(f"{task.id:<24} {task.status:<12} {epic:<18} {task.title}")
+
+
+def format_sprint_list(sprints: list[Sprint]) -> None:
+    if not sprints:
+        typer.echo("No sprints found.")
+        return
+    typer.echo(f"{'ID':<24} {'STATUS':<12} TITLE")
+    for sprint in sorted(sprints, key=lambda item: item.id):
+        typer.echo(f"{sprint.id:<24} {sprint.status:<12} {sprint.title}")
+
+
+def format_epic_show(epic: Epic) -> None:
+    _format_artifact_show(
+        kind="Epic",
+        artifact_id=epic.id,
+        title=epic.title,
+        status=epic.status,
+        fields=[
+            ("Summary", epic.summary),
+            ("Tasks", ", ".join(epic.task_ids) if epic.task_ids else None),
+        ],
+        body=epic.body,
+    )
+
+
+def format_task_show(task: Task) -> None:
+    _format_artifact_show(
+        kind="Task",
+        artifact_id=task.id,
+        title=task.title,
+        status=task.status,
+        fields=[
+            ("Epic", task.epic_id),
+        ],
+        body=task.body,
+    )
+
+
+def format_sprint_show(sprint: Sprint) -> None:
+    _format_artifact_show(
+        kind="Sprint",
+        artifact_id=sprint.id,
+        title=sprint.title,
+        status=sprint.status,
+        fields=[
+            ("Tasks", ", ".join(sprint.task_ids) if sprint.task_ids else None),
+        ],
+        body=sprint.body,
+    )
+
+
+def _format_artifact_show(
+    *,
+    kind: str,
+    artifact_id: str,
+    title: str,
+    status: str,
+    fields: list[tuple[str, str | None]],
+    body: str,
+) -> None:
+    typer.echo(f"{kind}: {artifact_id}")
+    typer.echo(f"Title:  {title}")
+    typer.echo(f"Status: {status}")
+    for label, value in fields:
+        if value:
+            typer.echo(f"{label + ':':<8} {value}")
+
+    sections = _extract_body_sections(body)
+    if sections:
+        typer.echo("")
+        for heading, content in sections:
+            typer.echo(f"## {heading}")
+            typer.echo(content.strip())
+            typer.echo("")
+    elif body.strip():
+        typer.echo("")
+        typer.echo(body.strip())
+
+
+def _extract_body_sections(body: str) -> list[tuple[str, str]]:
+    matches = list(_BODY_SECTION_RE.finditer(body))
+    if not matches:
+        return []
+    sections: list[tuple[str, str]] = []
+    for index, match in enumerate(matches):
+        heading = match.group(1).strip()
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        content = body[start:end].strip()
+        if content:
+            sections.append((heading, content))
+    return sections
+
+
+def format_doctor_report(report: DoctorReport) -> None:
+    if report.root is None:
+        typer.echo("A2C doctor: not inside an A2C repository")
+        for check in report.checks:
+            typer.echo(f"  [FAIL] {check.name}: {check.message}")
+        return
+
+    status = "healthy" if report.ok else "issues found"
+    typer.echo(f"A2C doctor: {status}")
+    typer.echo(f"Repository: {report.root}")
+    typer.echo("")
+    for check in report.checks:
+        label = "ok" if check.ok else "FAIL"
+        typer.echo(f"  [{label:4}] {check.name}: {check.message}")
+
+
+def format_decomposition_summary(proposal: EpicDecompositionProposal) -> None:
+    """Print a review summary for proposed task drafts."""
+    typer.echo(f"A2C plan: proposed tasks for epic {proposal.epic_id} (drafts — not applied)")
+    typer.echo("")
+    typer.echo("Summary:")
+    typer.echo(proposal.summary.strip())
+    typer.echo("")
+    typer.echo(f"Proposed tasks ({len(proposal.tasks)}):")
+    if not proposal.tasks:
+        typer.echo("  (none)")
+        return
+    typer.echo(f"  {'#':<4} {'ID':<24} {'STATUS':<12} TITLE")
+    for index, draft in enumerate(proposal.tasks, start=1):
+        typer.echo(f"  {index:<4} {draft.id:<24} {draft.status:<12} {draft.title}")
+        summary_line = _first_summary_line(draft.body)
+        if summary_line:
+            typer.echo(f"       {summary_line}")
+        if draft.rationale:
+            typer.echo(f"       rationale: {draft.rationale}")
+    typer.echo("")
+    typer.echo("Next: review drafts, then run apply tasks-from-epic to write files.")
+
+
+def format_draft_task_show(draft: TaskDraftItem, *, index: int, epic_id: str) -> None:
+    """Print one proposed task draft in detail."""
+    typer.echo(f"Draft task #{index} for epic {epic_id} (not applied)")
+    typer.echo(f"ID:     {draft.id}")
+    typer.echo(f"Title:  {draft.title}")
+    typer.echo(f"Status: {draft.status}")
+    typer.echo(f"Epic:   {draft.epic_id}")
+    if draft.rationale:
+        typer.echo(f"Why:    {draft.rationale}")
+
+    sections = _extract_body_sections(draft.body)
+    if sections:
+        typer.echo("")
+        for heading, content in sections:
+            typer.echo(f"## {heading}")
+            typer.echo(content.strip())
+            typer.echo("")
+    elif draft.body.strip():
+        typer.echo("")
+        typer.echo(draft.body.strip())
+
+
+def format_apply_epic_summary(epic_id: str) -> None:
+    typer.echo(f"Created epic {epic_id} in planning/epics/{epic_id}.md")
+
+
+def format_create_epic_summary(proposal: EpicDraftProposal) -> None:
+    """Print a review summary for a proposed epic draft."""
+    epic = proposal.epic
+    typer.echo(f"A2C plan: proposed epic {epic.id} (draft — not applied)")
+    typer.echo("")
+    typer.echo(f"ID:     {epic.id}")
+    typer.echo(f"Title:  {epic.title}")
+    typer.echo(f"Status: {epic.status}")
+    if epic.summary:
+        typer.echo(f"Summary: {epic.summary}")
+
+    sections = _extract_body_sections(epic.body)
+    if sections:
+        typer.echo("")
+        typer.echo("Sections:")
+        for heading, content in sections:
+            preview = _first_content_line(content)
+            if preview:
+                typer.echo(f"  ## {heading}: {preview}")
+            else:
+                typer.echo(f"  ## {heading}")
+
+    typer.echo("")
+    typer.echo("Next: review the draft, then run apply draft-epic to write planning/epics/.")
+
+
+def format_create_task_summary(proposal: TaskIntakeDraftProposal) -> None:
+    """Print a review summary for a proposed task intake draft."""
+    typer.echo(f"A2C plan: proposed task draft {proposal.draft_key} (not applied)")
+    typer.echo("")
+    typer.echo(f"Draft key: {proposal.draft_key}")
+    typer.echo("Task ID:   (allocated at apply)")
+    typer.echo(f"Title:     {proposal.title}")
+    typer.echo(f"Type:      {proposal.task_kind}")
+    typer.echo(f"Status:    {proposal.status}")
+    if proposal.epic_id:
+        typer.echo(f"Epic:      {proposal.epic_id}")
+
+    sections = _extract_body_sections(proposal.body)
+    if sections:
+        typer.echo("")
+        typer.echo("Sections:")
+        for heading, content in sections:
+            preview = _first_content_line(content)
+            if preview:
+                typer.echo(f"  ## {heading}: {preview}")
+            else:
+                typer.echo(f"  ## {heading}")
+
+    typer.echo("")
+    typer.echo("Next: review the draft, then run apply draft-task to write planning/tasks/.")
+
+
+def format_draft_task_intake_show(proposal: TaskIntakeDraftProposal) -> None:
+    """Print one proposed task intake draft in detail."""
+    typer.echo(f"Draft task {proposal.draft_key} (not applied)")
+    typer.echo("Task ID:   (allocated at apply)")
+    typer.echo(f"Title:     {proposal.title}")
+    typer.echo(f"Type:      {proposal.task_kind}")
+    typer.echo(f"Status:    {proposal.status}")
+    if proposal.epic_id:
+        typer.echo(f"Epic:      {proposal.epic_id}")
+
+    sections = _extract_body_sections(proposal.body)
+    if sections:
+        typer.echo("")
+        for heading, content in sections:
+            typer.echo(f"## {heading}")
+            typer.echo(content.strip())
+            typer.echo("")
+    elif proposal.body.strip():
+        typer.echo("")
+        typer.echo(proposal.body.strip())
+
+
+def format_apply_task_intake_summary(task_id: str, *, title: str, epic_id: str | None) -> None:
+    typer.echo(f"Created task {task_id} in planning/tasks/{task_id}.md")
+    typer.echo(f"Title: {title}")
+    if epic_id:
+        typer.echo(f"Epic:  {epic_id}")
+
+
+def format_draft_epic_show(proposal: EpicDraftProposal) -> None:
+    """Print one proposed epic draft in detail."""
+    epic = proposal.epic
+    typer.echo(f"Draft epic {epic.id} (not applied)")
+    typer.echo(f"Title:  {epic.title}")
+    typer.echo(f"Status: {epic.status}")
+    if epic.summary:
+        typer.echo(f"Summary: {epic.summary}")
+
+    sections = _extract_body_sections(epic.body)
+    if sections:
+        typer.echo("")
+        for heading, content in sections:
+            typer.echo(f"## {heading}")
+            typer.echo(content.strip())
+            typer.echo("")
+    elif epic.body.strip():
+        typer.echo("")
+        typer.echo(epic.body.strip())
+
+
+def format_apply_summary(epic_id: str, created_ids: list[str]) -> None:
+    joined = ", ".join(created_ids)
+    typer.echo(f"Created {len(created_ids)} new tasks for {epic_id}: {joined}")
+
+
+def _first_content_line(content: str) -> str | None:
+    line = content.strip().splitlines()[0] if content.strip() else ""
+    return line or None
+
+
+def _first_summary_line(body: str) -> str | None:
+    sections = _extract_body_sections(body)
+    for heading, content in sections:
+        if heading.lower() == "summary":
+            first_line = content.strip().splitlines()[0] if content.strip() else ""
+            return first_line or None
+    return None