core-cli 1.0.0__py3-none-any.whl

core_cli/resources/code/logging.py

@@ -0,0 +1,55 @@
+# src/cli/resources/code/logging.py
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+from shared.cli.command_meta import (
+    CommandBehavior,
+    CommandExposure,
+    CommandLayer,
+    command_meta,
+)
+
+from .hub import app
+
+
+console = Console()
+
+
+@app.command("logging")
+@command_meta(
+    canonical_name="code.logging",
+    behavior=CommandBehavior.MUTATE,
+    layer=CommandLayer.BODY,
+    exposure=CommandExposure.GOVERNOR_ONLY,
+    summary="Standardize logging across the codebase.",
+    dangerous=True,
+)
+@core_command(dangerous=True, requires_context=False)
+# ID: 5076493c-79a8-4f92-8c15-ddfd695d4275
+async def fix_logging_command(
+    ctx: typer.Context,
+    write: bool = typer.Option(
+        False, "--write", help="Convert print() to logger calls."
+    ),
+) -> None:
+    """
+    Standardize logging across the codebase.
+
+    Replaces print() statements and malformed f-strings in loggers with
+    constitutional standard logging (LOG-001/LOG-003).
+    """
+    mode = "Applying" if write else "Analyzing"
+    console.print(f"[bold cyan]🪵  {mode} Logging Standards...[/bold cyan]")
+    client = CoreApiClient()
+    initial = await client.run_fix("fix.logging", write=write)
+    run_id = initial.get("run_id")
+    if not run_id:
+        console.print(f"[red]fix.logging failed to dispatch: {initial}[/red]")
+        raise typer.Exit(1)
+    final = await client._poll_run(run_id)
+    if final.get("status") != "completed":
+        console.print(f"[red]fix.logging failed: {final.get('error') or final}[/red]")
+        raise typer.Exit(1)
+    console.print("[green]✓ fix.logging completed.[/green]")

core_cli/resources/code/test.py

@@ -0,0 +1,32 @@
+# src/core_cli/resources/code/test.py
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+from .hub import app
+
+
+console = Console()
+
+
+@app.command("test")
+@core_command(dangerous=False, requires_context=False)
+# ID: b89ff2a7-0bf3-47cf-90ba-66a3801630c3
+async def test_command() -> None:
+    """Run the project test suite via pytest."""
+    console.print("[bold cyan]🧪 Running test suite...[/bold cyan]")
+    client = CoreApiClient()
+    initial = await client.quality_tests()
+    run_id = initial.get("run_id")
+    if not run_id:
+        console.print(f"[red]quality.tests failed to dispatch: {initial}[/red]")
+        raise typer.Exit(1)
+    final = await client._poll_run(run_id)
+    if final.get("status") != "completed":
+        console.print(f"[red]quality.tests failed: {final.get('error') or final}[/red]")
+        raise typer.Exit(1)
+    console.print("[green]✓ tests completed.[/green]")

core_cli/resources/lane/__init__.py

@@ -0,0 +1,26 @@
+# src/cli/resources/lane/__init__.py
+"""Assisted Remediation Lane — external-agent contract (ADR-109, issue #652)."""
+
+from __future__ import annotations
+
+import typer
+
+from . import claim as claim_mod
+from . import list as list_mod
+from . import next as next_mod
+from . import propose as propose_mod
+
+
+app = typer.Typer(
+    name="lane",
+    help="Assisted Remediation Lane: work delegated findings under human-gated approval.",
+    no_args_is_help=True,
+)
+
+
+app.command("list")(list_mod.list_delegated)
+app.command("next")(next_mod.next_finding)
+app.command("claim")(claim_mod.claim)
+app.command("propose")(propose_mod.propose)
+
+__all__ = ["app"]

core_cli/resources/lane/claim.py

@@ -0,0 +1,48 @@
+# src/cli/resources/lane/claim.py
+"""`core-admin lane claim` — mark a delegated finding as being worked."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: 6a166026-f99f-4c6c-9a8e-2d415ee10961
+async def claim(
+    finding_id: str = typer.Argument(
+        ..., help="Delegated finding id (from `lane list`/`lane next`)."
+    ),
+    agent: str = typer.Option(
+        "claude-code", "--agent", "-a", help="Identity of the working agent."
+    ),
+) -> None:
+    """Mark a delegated finding as being worked, so it is tracked, not parked.
+
+    Claiming does not change the finding's status — it stays a live lane item —
+    it only records who is working it (ADR-109 §2).
+    """
+    client = CoreApiClient()
+    try:
+        await client.lane.claim(finding_id, agent=agent)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            console.print(f"[red]Not a live delegated lane item:[/red] {finding_id}")
+            raise typer.Exit(code=1) from exc
+        raise
+
+    console.print(
+        f"[green]Claimed.[/green] Finding [cyan]{finding_id}[/cyan] is now marked "
+        f"in-progress by [yellow]{agent}[/yellow]."
+    )

core_cli/resources/lane/list.py

@@ -0,0 +1,50 @@
+# src/cli/resources/lane/list.py
+"""`core-admin lane list` — show the Assisted Remediation Lane work queue."""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+_DEFAULT_LIMIT = 20
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: 0f0c8d2e-5b4a-4c1e-9a7f-2d3b6e8c1a44
+async def list_delegated(
+    limit: int = typer.Option(
+        _DEFAULT_LIMIT, "--limit", "-n", help="Max delegated findings to show."
+    ),
+    full_ids: bool = typer.Option(
+        False, "--full-ids", "-f", help="Show full finding IDs instead of truncating."
+    ),
+) -> None:
+    """List delegated findings awaiting assisted remediation (indeterminate + human)."""
+    client = CoreApiClient()
+    response = await client.lane.list_delegated(limit=limit)
+    findings = response["findings"]
+
+    if not findings:
+        console.print("[green]Lane is empty — no delegated findings.[/green]")
+        return
+
+    table = Table(title=f"Assisted Lane — delegated findings ({response['count']})")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Subject", style="white")
+    table.add_column("Created", style="dim")
+    for f in findings:
+        fid = f["id"] if full_ids else f["id"][:8]
+        created = (f.get("created_at") or "")[:19].replace("T", " ")
+        table.add_row(fid, f.get("subject", ""), created)
+    console.print(table)

core_cli/resources/lane/next.py

@@ -0,0 +1,82 @@
+# src/cli/resources/lane/next.py
+"""`core-admin lane next` — pull the next delegated finding to work."""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+from rich.console import Console
+from rich.panel import Panel
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: 3c29ca1d-17fb-4406-8293-b565b36c70d1
+async def next_finding() -> None:
+    """Show the oldest delegated finding (the FIFO head of the lane) with detail.
+
+    The agent's "pull next work" surface. The rich context bundle (related
+    files, guidance, rule text) is the deferred #653 exporter; for now this
+    surfaces the finding's own payload so you know what to work next.
+    """
+    client = CoreApiClient()
+    try:
+        finding = await client.lane.next_delegated()
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            console.print("[green]Lane is empty — no delegated findings.[/green]")
+            return
+        raise
+
+    payload = finding.get("payload") or {}
+    bundle = finding.get("bundle") or {}
+    rule_info = bundle.get("rule") or {}
+    remediation = bundle.get("remediation") or {}
+
+    rule = rule_info.get("id") or payload.get("rule") or payload.get("rule_id") or "—"
+    file = payload.get("file") or payload.get("file_path") or "—"
+    message = payload.get("message") or payload.get("description") or ""
+    claimed_by = payload.get("lane_claimed_by")
+    created = (finding.get("created_at") or "")[:19].replace("T", " ")
+
+    lines = [
+        f"[bold]ID[/bold]       {finding['id']}",
+        f"[bold]Subject[/bold]  {finding.get('subject', '')}",
+        f"[bold]Rule[/bold]     [cyan]{rule}[/cyan]",
+        f"[bold]File[/bold]     {file}",
+        f"[bold]Created[/bold]  {created}",
+    ]
+    if claimed_by:
+        lines.append(f"[bold]Claimed[/bold]  [yellow]{claimed_by}[/yellow]")
+    if message:
+        lines.append(f"\n{message}")
+
+    # #653 context bundle — why the rule exists + the remediation hint.
+    if rule_info.get("in_registry") is False:
+        lines.append(
+            "\n[yellow]⚠ This rule id is not in the active registry[/yellow] — "
+            "likely renamed/retired (cf. #657). This finding should be "
+            "[bold]resolved[/bold], not worked: no fix can clear a dead rule id."
+        )
+    if rule_info.get("rationale"):
+        lines.append(f"\n[bold]Why this rule[/bold]\n{rule_info['rationale']}")
+    if remediation.get("description"):
+        status = remediation.get("status") or ""
+        suffix = f" [dim]({status})[/dim]" if status else ""
+        lines.append(
+            f"\n[bold]Remediation guidance[/bold]{suffix}\n{remediation['description']}"
+        )
+
+    console.print(Panel("\n".join(lines), title="Assisted Lane — next finding"))
+    console.print(
+        "[dim]Claim it with `core-admin lane claim <id> --agent <you>`, then "
+        "propose a fix with `core-admin lane propose <id> --patch <file>`.[/dim]"
+    )

core_cli/resources/lane/propose.py

@@ -0,0 +1,119 @@
+# src/cli/resources/lane/propose.py
+"""`core-admin lane propose` — submit a validated agent diff for a delegated finding."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+_VALIDATE_ACTION = "assisted.validate_diff"
+
+
+@core_command(dangerous=False, requires_context=False)
+# ID: e0f6bd92-4391-4d80-b0e7-40f2e5f32de6
+async def propose(
+    finding_id: str = typer.Argument(
+        ..., help="Delegated finding id (from `lane list`)."
+    ),
+    patch_file: Path = typer.Option(
+        ...,
+        "--patch",
+        "-p",
+        help="Path to the unified diff the agent produced for this finding.",
+        exists=True,
+        dir_okay=False,
+        readable=True,
+    ),
+) -> None:
+    """Validate an agent-authored diff and, if it clears, submit it for approval.
+
+    Flow (ADR-109): read the finding's rule, run ``assisted.validate_diff``
+    against the diff in a throwaway worktree (apply + ruff + the offending rule
+    must no longer fire + mapped tests), and only on a clean verdict create the
+    human-gated proposal and move the finding out of the inbox into "being
+    worked". A diff that fails validation never reaches the approval queue.
+    """
+    client = CoreApiClient()
+
+    # 1. Recover the finding's rule — the gate needs it, and a 404 here means
+    #    the finding is not a live lane item (already worked / not delegated).
+    finding = await client.lane.get_delegated(finding_id)
+    payload = finding.get("payload") or {}
+    rule = payload.get("rule") or payload.get("rule_id") or "unknown"
+
+    # The finding's subject file — the gate validates that the rule no longer
+    # flags *this* file, not just the diff's touched files (ADR-109 mechanism
+    # §4; needed when the fix lives in a different file than the subject, e.g.
+    # a detector-bug fix). Prefer the payload; fall back to the subject's
+    # trailing "lang::rule::path" segment.
+    subject_file = payload.get("file") or payload.get("file_path")
+    if not subject_file:
+        subject = finding.get("subject") or ""
+        if "::" in subject:
+            subject_file = subject.rsplit("::", 1)[-1] or None
+    subject_files = [subject_file] if subject_file else []
+
+    patch = patch_file.read_text(encoding="utf-8")
+
+    # 2. Validate the diff in a hermetic worktree via the general action-run
+    #    surface (decoupled from this command's process).
+    console.print(f"[dim]Validating diff against rule [cyan]{rule}[/cyan]…[/dim]")
+    run = await client.run_fix(
+        _VALIDATE_ACTION,
+        params={
+            "patch": patch,
+            "finding_rule": rule,
+            "subject_files": subject_files,
+        },
+    )
+    run_id = run["run_id"]
+    terminal = await client._poll_run(run_id)
+    result = terminal.get("result") or {}
+    data = result.get("data") or {}
+
+    if not result.get("ok"):
+        # A diff that patches a graph-dependent audit engine (knowledge_gate)
+        # cannot be subprocess-validated — surface distinctly from a plain fix
+        # failure (ADR-141 D1). Accept both the new key and the legacy key
+        # during the one-cycle migration window (ADR-141 D6).
+        if data.get("must_refuse_engines") or data.get("self_referential_engines"):
+            console.print(
+                "[yellow]This finding's fix modifies a graph-dependent audit "
+                "engine — the assisted lane cannot validate it.[/yellow]"
+            )
+            console.print(f"  [dim]{data.get('error', '')}[/dim]")
+            raise typer.Exit(code=1)
+        console.print("[red]Validation failed — diff is not approvable.[/red]")
+        for check, passed in (data.get("validation_results") or {}).items():
+            mark = "[green]✓[/green]" if passed else "[red]✗[/red]"
+            console.print(f"  {mark} {check}")
+        if data.get("error"):
+            console.print(f"  [red]{data['error']}[/red]")
+        raise typer.Exit(code=1)
+
+    # 3. Ingest the validated diff as a governed, human-gated proposal. The
+    #    endpoint re-reads the persisted verdict (run_id) before creating it.
+    proposed = await client.lane.propose(
+        finding_id, patch=patch, validation_run_id=run_id
+    )
+    files = proposed.get("scope_files", [])
+    console.print(
+        f"[green]Validated and proposed.[/green] Proposal "
+        f"[cyan]{proposed['proposal_id']}[/cyan] "
+        f"({len(files)} file(s)) is awaiting your approval."
+    )
+    console.print(
+        "[dim]Review and approve with "
+        "`core-admin proposals approve <proposal-id>`.[/dim]"
+    )

core_cli/resources/project/__init__.py

@@ -0,0 +1,21 @@
+"""Consumer project lifecycle commands."""
+
+from __future__ import annotations
+
+import typer
+
+
+app = typer.Typer(
+    name="project",
+    help="Operations for project lifecycle: onboarding and documentation.",
+    no_args_is_help=True,
+)
+
+from . import (  # noqa: E402, F401
+    docs,
+    onboard,
+    scout,
+)
+
+
+__all__ = ["app"]

core_cli/resources/project/docs.py

@@ -0,0 +1,41 @@
+# src/core_cli/resources/project/docs.py
+
+"""Generate capability reference documentation — consumer CLI over HTTP (ADR-146 D2)."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+from . import app
+
+
+console = Console()
+
+
+@app.command("docs")
+@core_command(dangerous=False, requires_context=False)
+# ID: 6759f022-9e30-474c-8ea3-4740ee55249c
+async def generate_project_docs(
+    ctx: typer.Context,
+    output: str = typer.Option(
+        "docs/10_CAPABILITY_REFERENCE.md",
+        "--output",
+        "-o",
+        help="Target path for the reference doc.",
+    ),
+) -> None:
+    """Generate the canonical Capability Reference documentation.
+
+    Extracts all public symbols and their intent from the database.
+    """
+    console.print(
+        f"[bold cyan]Generating capability reference to:[/bold cyan] {output}"
+    )
+    client = CoreApiClient()
+    result = await client.project.generate_docs(output=output)
+    out = result.get("output", output)
+    console.print(f"[green]Documentation updated: {out}[/green]")

core_cli/resources/project/onboard.py

@@ -0,0 +1,110 @@
+# src/core_cli/resources/project/onboard.py
+
+"""BYOR onboarding commands — consumer CLI over HTTP (ADR-146 D2)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from api.cli import CoreApiClient
+from cli.utils import core_command
+
+from . import app
+
+
+console = Console()
+
+
+@app.command("onboard")
+@core_command(dangerous=True, requires_context=False, requires_brain_services=False)
+# ID: e625b650-05c8-421e-9cf7-073917b43dc9
+async def onboard_project(
+    ctx: typer.Context,
+    path: Path = typer.Argument(..., help="Path to existing repository."),
+    write: bool = typer.Option(
+        False, "--write", help="Write .intent/ directory to the target path."
+    ),
+    stage: bool = typer.Option(
+        False,
+        "--stage",
+        help=(
+            "Write to work/staged/<name>/ for inspection before promoting "
+            "(ADR-123). Requires --write; ignored in dry-run mode."
+        ),
+    ),
+) -> None:
+    """Onboard an existing repository into CORE governance — Phase A (BYOR).
+
+    Delivers the machinery floor (META schemas, taxonomies, constitution stub,
+    enforcement/config) into the target's .intent/. No rules are included; run
+    `project scout` afterwards to induce and ratify rules for this repo (ADR-119).
+    Dry-run by default; pass --write to apply.
+
+    Pass --write --stage to write to work/staged/<name>/ first, inspect the
+    files, then run `project onboard promote <path>` to deliver to the target.
+    """
+    if stage and not write:
+        console.print(
+            "[yellow]--stage has no effect without --write "
+            "(dry-run already previews the delivery).[/yellow]"
+        )
+
+    if stage and write:
+        mode_label = "Staging onboard for (→ staged/<name>)"
+    elif write:
+        mode_label = "Onboarding"
+    else:
+        mode_label = "Previewing onboarding for"
+
+    console.print(
+        f"[bold cyan]{mode_label} repository (Phase A — machinery floor):[/bold cyan] {path}"
+    )
+
+    client = CoreApiClient()
+    try:
+        result = await client.project.onboard(str(path), write=write, stage=stage)
+    except Exception as exc:
+        console.print(f"[red]Onboard failed: {exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    mode = result.get("mode", "dry-run")
+    stage_dir = result.get("stage_dir")
+
+    if stage_dir:
+        console.print(
+            f"\n[bold green]Staged to[/bold green] {stage_dir}/.intent\n"
+            f"[dim]Inspect, then run:[/dim]  "
+            f"[bold]core-admin project onboard promote {path}[/bold]"
+        )
+    elif mode == "dry-run":
+        console.print("[yellow]DRY-RUN complete. Pass --write to apply.[/yellow]")
+    else:
+        console.print(f"[green]Onboarding complete ({mode}).[/green]")
+
+
+@app.command("promote")
+@core_command(dangerous=True, requires_context=False, requires_brain_services=False)
+# ID: d2eafb4d-7ead-4d04-bb89-8d78eda8a582
+async def promote_onboard(
+    ctx: typer.Context,
+    path: Path = typer.Argument(
+        ...,
+        help="Target repository path (same path used with --stage).",
+    ),
+) -> None:
+    """Promote a staged machinery floor into the target repository (ADR-123).
+
+    Reads from work/staged/<name>/.intent/ (within CORE's repo) and writes to
+    <path>/.intent/. Run `project onboard promote --help` for full lifecycle details.
+    """
+    console.print(f"[bold cyan]Promoting staged onboard to:[/bold cyan] {path}")
+    client = CoreApiClient()
+    try:
+        await client.project.promote(str(path))
+    except Exception as exc:
+        console.print(f"[red]Promote failed: {exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"[bold green]Promoted to[/bold green] {Path(path).resolve() / '.intent'}")