taskledger 0.1.0__py3-none-any.whl

taskledger/cli_validate.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, cast
+
+import typer
+
+from taskledger.api.task_runs import (
+    add_validation_check,
+    finish_validation,
+    show_task_run,
+    start_validation,
+    validation_status,
+    waive_criterion,
+)
+from taskledger.cli_common import (
+    TaskOption,
+    cli_state_from_context,
+    emit_error,
+    emit_payload,
+    launch_error_exit_code,
+    resolve_cli_task,
+)
+from taskledger.errors import LaunchError
+from taskledger.services.actors import resolve_actor, resolve_harness
+
+
+def _render_validation_status(payload: dict[str, Any]) -> str:
+    """Render validation gate report to human-readable text."""
+    lines = []
+
+    task_id = payload.get("task_id", "?")
+    task_slug = payload.get("task_slug", "?")
+    lines.append(f"Validation status for {task_slug} ({task_id})")
+    lines.append("")
+
+    run_id = payload.get("run_id", "?")
+    lines.append(f"Run: {run_id}")
+    lines.append("")
+
+    accepted_plan = payload.get("accepted_plan", {})
+    plan_version = accepted_plan.get("version", "none")
+    plan_status = accepted_plan.get("status", "none")
+    lines.append(f"Accepted plan: v{plan_version} {plan_status}")
+
+    implementation = payload.get("implementation", {})
+    impl_run_id = implementation.get("run_id", "none")
+    impl_status = implementation.get("status", "none")
+    lines.append(f"Implementation: {impl_run_id} {impl_status}")
+    lines.append("")
+
+    lines.append("Criteria:")
+    criteria = payload.get("criteria", [])
+    for crit in criteria:
+        crit_id = crit.get("id", "?")
+        mandatory = "[mandatory]" if crit.get("mandatory") else ""
+        latest_status = crit.get("latest_status", "not_run")
+        satisfied = crit.get("satisfied", False)
+        checkbox = "[x]" if satisfied else "[ ]"
+        text = crit.get("text", "")
+        lines.append(f"  {checkbox} {crit_id} {mandatory} {latest_status}")
+        if text:
+            lines.append(f"      {text}")
+        evidence = crit.get("evidence", [])
+        if evidence:
+            lines.append(f"      evidence: {', '.join(evidence)}")
+    lines.append("")
+
+    todos = payload.get("todos", {})
+    open_todos = todos.get("open_mandatory", [])
+    if open_todos:
+        lines.append("Mandatory todos:")
+        for todo_id in open_todos:
+            lines.append(f"  [ ] {todo_id}")
+        lines.append("")
+
+    dependencies = payload.get("dependencies", {})
+    dep_blockers = dependencies.get("blockers", [])
+    if dep_blockers:
+        lines.append("Dependencies:")
+        for blocker in dep_blockers:
+            lines.append(f"  - {blocker}")
+        lines.append("")
+
+    can_finish = payload.get("can_finish_passed", False)
+    lines.append(f"Can finish passed: {'yes' if can_finish else 'no'}")
+
+    blockers = payload.get("blockers", [])
+    if blockers:
+        lines.append("")
+        lines.append("Blockers:")
+        for blocker in blockers:
+            kind = blocker.get("kind", "?")
+            ref = blocker.get("ref", "")
+            message = blocker.get("message", "")
+            hint = blocker.get("command_hint", "")
+            ref_str = f" {ref}" if ref else ""
+            lines.append(f"  - {kind}{ref_str}: {message}")
+            if hint:
+                lines.append(f"    {hint}")
+
+    return "\n".join(lines)
+
+
+def register_validate_v2_commands(app: typer.Typer) -> None:
+    @app.command("start")
+    def start_command(
+        ctx: typer.Context,
+        task_ref: TaskOption = None,
+        actor: Annotated[
+            str | None,
+            typer.Option("--actor", help="Actor type: user, agent, or system."),
+        ] = None,
+        actor_name: Annotated[
+            str | None,
+            typer.Option("--actor-name", help="Actor name."),
+        ] = None,
+        actor_role: Annotated[
+            str | None,
+            typer.Option("--actor-role", help="Actor role in task lifecycle."),
+        ] = None,
+        harness: Annotated[
+            str | None,
+            typer.Option("--harness", help="Harness name."),
+        ] = None,
+        session_id: Annotated[
+            str | None,
+            typer.Option("--session-id", help="Session identifier."),
+        ] = None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            task = resolve_cli_task(state.cwd, task_ref)
+            resolved_actor = resolve_actor(
+                actor_type=actor,
+                actor_name=actor_name,
+                role=actor_role,
+                session_id=session_id,
+            )
+            resolved_harness = resolve_harness(name=harness, session_id=session_id)
+            payload = start_validation(
+                state.cwd,
+                task.id,
+                actor=resolved_actor,
+                harness=resolved_harness,
+            )
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        emit_payload(ctx, payload, human=f"started validation {payload['run_id']}")
+
+    def _emit_check(
+        ctx: typer.Context,
+        *,
+        name: str | None,
+        criterion: str | None,
+        status: str,
+        details: str | None,
+        evidence: list[str] | None,
+        task_ref: str | None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            task = resolve_cli_task(state.cwd, task_ref)
+            run = add_validation_check(
+                state.cwd,
+                task.id,
+                name=name,
+                criterion_id=criterion,
+                status=status,
+                details=details,
+                evidence=tuple(evidence or ()),
+            )
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        emit_payload(ctx, run.to_dict(), human=f"added check to {run.run_id}")
+
+    @app.command("check")
+    def check_command(
+        ctx: typer.Context,
+        criterion: Annotated[str, typer.Option("--criterion")],
+        status: Annotated[str, typer.Option("--status")] = "pass",
+        evidence: Annotated[list[str] | None, typer.Option("--evidence")] = None,
+        name: Annotated[str | None, typer.Option("--name")] = None,
+        details: Annotated[str | None, typer.Option("--details")] = None,
+        task_ref: TaskOption = None,
+    ) -> None:
+        _emit_check(
+            ctx,
+            name=name,
+            criterion=criterion,
+            status=status,
+            details=details,
+            evidence=evidence,
+            task_ref=task_ref,
+        )
+
+    @app.command("finish")
+    def finish_command(
+        ctx: typer.Context,
+        result: Annotated[str, typer.Option("--result")],
+        summary: Annotated[str, typer.Option("--summary")],
+        recommendation: Annotated[str | None, typer.Option("--recommendation")] = None,
+        task_ref: TaskOption = None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            task = resolve_cli_task(state.cwd, task_ref)
+            payload = finish_validation(
+                state.cwd,
+                task.id,
+                result=result,
+                summary=summary,
+                recommendation=recommendation,
+            )
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        emit_payload(ctx, payload, human=f"finished validation {payload['run_id']}")
+
+    @app.command("show")
+    def show_command(
+        ctx: typer.Context,
+        run_id: Annotated[str | None, typer.Option("--run")] = None,
+        task_ref: TaskOption = None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            task = resolve_cli_task(state.cwd, task_ref)
+            payload = show_task_run(
+                state.cwd,
+                task.id,
+                run_id=run_id,
+                run_type="validation",
+            )
+            status_payload = validation_status(state.cwd, task.id, run_id=run_id)
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        run = payload["run"]
+        assert isinstance(run, dict)
+        status_result = cast(dict[str, Any], status_payload.get("result", {}))
+        human_output = _render_validation_status(status_result)
+        emit_payload(ctx, payload, human=human_output)
+
+    @app.command("status")
+    def status_command(
+        ctx: typer.Context,
+        task_ref: TaskOption = None,
+        run: Annotated[str | None, typer.Option("--run")] = None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            task = resolve_cli_task(state.cwd, task_ref)
+            payload = validation_status(state.cwd, task.id, run_id=run)
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        result = cast(dict[str, Any], payload.get("result", {}))
+        human_output = _render_validation_status(result)
+        emit_payload(ctx, payload, human=human_output)
+
+    @app.command("waive")
+    def waive_command(
+        ctx: typer.Context,
+        criterion: Annotated[str, typer.Option("--criterion")],
+        reason: Annotated[str, typer.Option("--reason")],
+        actor: Annotated[str, typer.Option("--actor")] = "user",
+        task_ref: TaskOption = None,
+    ) -> None:
+        state = cli_state_from_context(ctx)
+        try:
+            if actor != "user":
+                raise LaunchError("Only user actors can waive criteria.")
+            task = resolve_cli_task(state.cwd, task_ref)
+            run = waive_criterion(
+                state.cwd,
+                task.id,
+                criterion_id=criterion,
+                reason=reason,
+            )
+        except LaunchError as exc:
+            emit_error(ctx, exc)
+            raise typer.Exit(code=launch_error_exit_code(exc)) from exc
+        emit_payload(ctx, run.to_dict(), human=f"waived criterion {criterion}")

taskledger/command_inventory.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+STABLE_FOR_AGENTS = "stable_for_agents"
+BETA_FOR_AGENTS = "beta_for_agents"
+HUMAN_ORIENTED = "human_oriented"
+REPAIR = "repair"
+
+COMMAND_METADATA: dict[str, tuple[str, str]] = {
+    "init": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "next-action": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "view": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "serve": (HUMAN_ORIENTED, "safe_read_only"),
+    "can": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "reindex": (REPAIR, "ledger_mutation"),
+    "export": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "import": (REPAIR, "ledger_mutation"),
+    "snapshot": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "context": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "search": (BETA_FOR_AGENTS, "safe_read_only"),
+    "grep": (BETA_FOR_AGENTS, "safe_read_only"),
+    "symbols": (BETA_FOR_AGENTS, "safe_read_only"),
+    "deps": (BETA_FOR_AGENTS, "safe_read_only"),
+    "task create": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "task active": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "task activate": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task deactivate": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "task edit": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task cancel": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task close": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "task dossier": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "task events": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan start": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan propose": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan draft": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan regenerate": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan upsert": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan materialize-todos": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan diff": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan lint": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "plan approve": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan accept": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan command": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan reject": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "plan revise": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "question add": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "question list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "question answer": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "question answer-many": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "question dismiss": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "question open": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "question status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "question answers": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "implement start": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement restart": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement log": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement change": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement scan-changes": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement command": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement deviation": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement artifact": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement finish": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "implement show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "implement status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "implement checklist": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "validate start": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "validate check": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "validate finish": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "validate status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "validate waive": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "validate show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "todo add": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "todo list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "todo done": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "todo undone": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "todo show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "todo status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "todo next": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "intro create": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "intro list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "intro show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "intro link": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "file add": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "file remove": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "file list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "link add": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "link list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "link remove": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "require add": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "require list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "require remove": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "require waive": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "lock show": (REPAIR, "safe_read_only"),
+    "lock break": (REPAIR, "ledger_mutation"),
+    "lock list": (REPAIR, "safe_read_only"),
+    "handoff show": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "handoff create": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "handoff list": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "handoff claim": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "handoff close": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "handoff cancel": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "handoff plan-context": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "handoff implementation-context": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "handoff validation-context": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "actor whoami": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "actor set": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "actor clear": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "harness set": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "harness clear": (STABLE_FOR_AGENTS, "ledger_mutation"),
+    "doctor": (REPAIR, "safe_read_only"),
+    "doctor locks": (REPAIR, "safe_read_only"),
+    "doctor schema": (REPAIR, "safe_read_only"),
+    "doctor indexes": (REPAIR, "safe_read_only"),
+    "repair index": (REPAIR, "ledger_mutation"),
+    "repair lock": (REPAIR, "ledger_mutation"),
+    "repair task": (REPAIR, "ledger_mutation"),
+    "repair task-dirs": (REPAIR, "ledger_mutation"),
+    "migrate status": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "migrate plan": (STABLE_FOR_AGENTS, "safe_read_only"),
+    "migrate apply": (REPAIR, "ledger_mutation"),
+}

taskledger/domain/__init__.py

@@ -0,0 +1,2 @@
+from taskledger.domain.models import *  # noqa: F401,F403
+from taskledger.domain.states import *  # noqa: F401,F403