taskledger 0.1.0__py3-none-any.whl

taskledger/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from taskledger._version import __version__
+
+__all__ = ["__version__"]

taskledger/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m taskledger."""
+
+from taskledger.cli import cli_main
+
+if __name__ == "__main__":
+    cli_main()

taskledger/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

taskledger/api/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+__all__ = [
+    "handoff",
+    "introductions",
+    "locks",
+    "plans",
+    "project",
+    "questions",
+    "search",
+    "task_runs",
+    "tasks",
+]

taskledger/api/handoff.py

@@ -0,0 +1,247 @@
+import hashlib
+from pathlib import Path
+from typing import cast
+
+from taskledger.domain.models import ActorRef, HarnessRef, TaskHandoffRecord
+from taskledger.domain.states import normalize_actor_type
+from taskledger.errors import LaunchError
+from taskledger.services.handoff import (
+    build_context_request,
+    build_handoff_payload,
+    render_handoff,
+    render_markdown_handoff,
+)
+from taskledger.storage.task_store import (
+    handoff_markdown_path,
+    list_handoffs,
+    resolve_handoff,
+    resolve_task,
+    resolve_v2_paths,
+    save_handoff,
+)
+
+
+def create_handoff(
+    workspace_root: Path,
+    task_ref: str,
+    *,
+    mode: str,
+    context_for: str | None = None,
+    scope: str | None = None,
+    todo_id: str | None = None,
+    focus_run_id: str | None = None,
+    intended_actor_type: str | None = None,
+    intended_actor_name: str | None = None,
+    intended_harness: str | None = None,
+    summary: str | None = None,
+    next_action: str | None = None,
+    actor: ActorRef | None = None,
+    harness: HarnessRef | None = None,
+) -> dict[str, object]:
+    """Create and save a handoff record."""
+    from taskledger.ids import next_project_id
+    from taskledger.services.actors import resolve_actor, resolve_harness
+    from taskledger.timeutils import utc_now_iso
+
+    resolved_actor = actor or resolve_actor()
+    resolved_harness = harness or resolve_harness()
+
+    task = resolve_task(workspace_root, task_ref)
+    request = build_context_request(
+        mode=mode,
+        context_for=context_for,
+        scope=scope,
+        todo_id=todo_id,
+        focus_run_id=focus_run_id,
+        format_name="markdown",
+    )
+    payload = build_handoff_payload(
+        workspace_root,
+        task.id,
+        mode=request.mode,
+        context_for=request.context_for,
+        scope=request.scope,
+        todo_id=request.todo_id,
+        focus_run_id=request.focus_run_id,
+        format_name="markdown",
+    )
+    context_body = render_markdown_handoff(payload)
+    context_hash = f"sha256:{hashlib.sha256(context_body.encode('utf-8')).hexdigest()}"
+    existing_handoffs = list_handoffs(workspace_root, task.id)
+    existing_ids = [h.handoff_id for h in existing_handoffs]
+
+    handoff_id = next_project_id("handoff", existing_ids)
+    handoff = TaskHandoffRecord(
+        handoff_id=handoff_id,
+        task_id=task.id,
+        mode=request.mode,
+        context_for=request.context_for,
+        scope=request.scope,
+        todo_id=request.todo_id,
+        focus_run_id=request.focus_run_id,
+        context_format="markdown",
+        context_hash=context_hash,
+        generated_at=utc_now_iso(),
+        status="open",
+        created_by=resolved_actor,
+        created_from_harness=resolved_harness,
+        intended_actor_type=(
+            normalize_actor_type(intended_actor_type) if intended_actor_type else None
+        ),
+        intended_actor_name=intended_actor_name,
+        intended_harness=intended_harness,
+        summary=summary,
+        next_action=next_action,
+        context_body=context_body,
+    )
+    path = save_handoff(workspace_root, handoff)
+    result = handoff.to_dict()
+    result.pop("context_body", None)
+    try:
+        result["context_path"] = str(path.relative_to(workspace_root))
+    except ValueError:
+        result["context_path"] = str(path)
+    return result
+
+
+def list_all_handoffs(workspace_root: Path, task_ref: str) -> list[dict[str, object]]:
+    """List all handoffs for a task."""
+    task = resolve_task(workspace_root, task_ref)
+    handoffs = list_handoffs(workspace_root, task.id)
+    return [h.to_dict() for h in handoffs]
+
+
+def show_handoff(
+    workspace_root: Path,
+    task_ref: str,
+    handoff_ref: str,
+    *,
+    format_name: str = "text",
+) -> str | dict[str, object]:
+    """Get a specific handoff."""
+    task = resolve_task(workspace_root, task_ref)
+    handoff = resolve_handoff(workspace_root, task.id, handoff_ref)
+    path = handoff_markdown_path(
+        resolve_v2_paths(workspace_root), task.id, handoff.handoff_id
+    )
+    context_path: str
+    try:
+        context_path = str(path.relative_to(workspace_root))
+    except ValueError:
+        context_path = str(path)
+    if format_name == "markdown":
+        if handoff.context_body.strip():
+            body = handoff.context_body
+            return body if body.endswith("\n") else body + "\n"
+        return cast(
+            str,
+            render_handoff(
+                workspace_root,
+                task.id,
+                mode=handoff.mode,
+                context_for=handoff.context_for,
+                scope=handoff.scope,
+                todo_id=handoff.todo_id,
+                focus_run_id=handoff.focus_run_id,
+                format_name="markdown",
+            ),
+        )
+    payload = handoff.to_dict()
+    payload["context_path"] = context_path
+    if format_name == "json":
+        return payload
+    if format_name != "text":
+        raise LaunchError(f"Unsupported handoff format: {format_name}")
+    lines = [
+        f"Handoff {handoff.handoff_id}",
+        f"mode: {handoff.mode}",
+        f"context_for: {handoff.context_for or 'none'}",
+        f"scope: {handoff.scope}",
+        f"status: {handoff.status}",
+        f"context_path: {context_path}",
+        f"context_hash: {handoff.context_hash or 'none'}",
+    ]
+    if handoff.todo_id:
+        lines.append(f"todo_id: {handoff.todo_id}")
+    if handoff.focus_run_id:
+        lines.append(f"focus_run_id: {handoff.focus_run_id}")
+    return "\n".join(lines)
+
+
+def claim_handoff_api(
+    workspace_root: Path,
+    task_ref: str,
+    handoff_ref: str,
+    *,
+    actor: ActorRef | None = None,
+    harness: HarnessRef | None = None,
+    new_run_id: str | None = None,
+) -> dict[str, object]:
+    """Claim a handoff, transitioning from 'open' to 'claimed'."""
+    from taskledger.services.handoff_lifecycle import claim_handoff
+
+    task = resolve_task(workspace_root, task_ref)
+    handoff = claim_handoff(
+        workspace_root,
+        task.id,
+        handoff_ref,
+        actor=actor,
+        harness=harness,
+        new_run_id=new_run_id,
+    )
+    return handoff.to_dict()
+
+
+def close_handoff_api(
+    workspace_root: Path,
+    task_ref: str,
+    handoff_ref: str,
+    *,
+    actor: ActorRef | None = None,
+    reason: str | None = None,
+) -> dict[str, object]:
+    """Close a handoff, transitioning from 'claimed' to 'closed'."""
+    from taskledger.services.handoff_lifecycle import close_handoff
+
+    task = resolve_task(workspace_root, task_ref)
+    handoff = close_handoff(
+        workspace_root,
+        task.id,
+        handoff_ref,
+        actor=actor,
+        reason=reason,
+    )
+    return handoff.to_dict()
+
+
+def cancel_handoff_api(
+    workspace_root: Path,
+    task_ref: str,
+    handoff_ref: str,
+    *,
+    actor: ActorRef | None = None,
+    reason: str | None = None,
+) -> dict[str, object]:
+    """Cancel a handoff, transitioning from 'open' to 'cancelled'."""
+    from taskledger.services.handoff_lifecycle import cancel_handoff
+
+    task = resolve_task(workspace_root, task_ref)
+    handoff = cancel_handoff(
+        workspace_root,
+        task.id,
+        handoff_ref,
+        actor=actor,
+        reason=reason,
+    )
+    return handoff.to_dict()
+
+
+__all__ = [
+    "render_handoff",
+    "create_handoff",
+    "list_all_handoffs",
+    "show_handoff",
+    "claim_handoff_api",
+    "close_handoff_api",
+    "cancel_handoff_api",
+]

taskledger/api/introductions.py

@@ -0,0 +1,9 @@
+from taskledger.services.tasks import create_introduction, link_introduction
+from taskledger.storage.task_store import list_introductions, resolve_introduction
+
+__all__ = [
+    "create_introduction",
+    "list_introductions",
+    "resolve_introduction",
+    "link_introduction",
+]

taskledger/api/locks.py

@@ -0,0 +1,4 @@
+from taskledger.services.tasks import break_lock, list_locks, show_lock
+from taskledger.storage.task_store import load_active_locks
+
+__all__ = ["show_lock", "break_lock", "list_locks", "load_active_locks"]

taskledger/api/plans.py

@@ -0,0 +1,31 @@
+from taskledger.services.plan_lint import lint_plan
+from taskledger.services.tasks import (
+    approve_plan,
+    diff_plan,
+    list_plan_versions,
+    materialize_plan_todos,
+    propose_plan,
+    regenerate_plan_from_answers,
+    reject_plan,
+    revise_plan,
+    run_planning_command,
+    show_plan,
+    start_planning,
+    upsert_plan,
+)
+
+__all__ = [
+    "start_planning",
+    "propose_plan",
+    "upsert_plan",
+    "list_plan_versions",
+    "show_plan",
+    "diff_plan",
+    "approve_plan",
+    "regenerate_plan_from_answers",
+    "materialize_plan_todos",
+    "reject_plan",
+    "revise_plan",
+    "run_planning_command",
+    "lint_plan",
+]

taskledger/api/project.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from taskledger.domain.policies import derive_active_stage
+from taskledger.exchange import (
+    export_project_payload,
+    import_project_payload,
+    parse_project_import_payload,
+    write_project_snapshot,
+)
+from taskledger.services.doctor import inspect_v2_project
+from taskledger.storage.init import init_project_state
+from taskledger.storage.locks import lock_is_expired
+from taskledger.storage.paths import resolve_project_paths
+from taskledger.storage.task_store import (
+    list_changes,
+    list_introductions,
+    list_plans,
+    list_questions,
+    list_runs,
+    list_tasks,
+    load_active_locks,
+    load_active_task_state,
+    resolve_task,
+)
+
+
+def init_project(
+    workspace_root: Path,
+    *,
+    taskledger_dir: Path | None = None,
+) -> dict[str, object]:
+    paths, created = init_project_state(workspace_root, taskledger_dir=taskledger_dir)
+    return {
+        "kind": "taskledger_init",
+        "root": str(paths.project_dir),
+        "project_dir": str(paths.project_dir),
+        "workspace_root": str(paths.workspace_root),
+        "config_path": str(paths.config_path),
+        "taskledger_dir": str(paths.taskledger_dir),
+        "created": created,
+    }
+
+
+def project_status_summary(workspace_root: Path) -> dict[str, object]:
+    doctor = inspect_v2_project(workspace_root)
+    paths = resolve_project_paths(workspace_root)
+    return {
+        "kind": "taskledger_status",
+        "workspace_root": str(paths.workspace_root),
+        "config_path": str(paths.config_path),
+        "taskledger_dir": str(paths.taskledger_dir),
+        "project_dir": str(paths.project_dir),
+        "counts": _project_counts(workspace_root),
+        "healthy": bool(doctor["healthy"]),
+        "active_task": _active_task_status(workspace_root),
+    }
+
+
+def project_status(workspace_root: Path) -> dict[str, object]:
+    doctor = inspect_v2_project(workspace_root)
+    tasks = list_tasks(workspace_root)
+    locks = load_active_locks(workspace_root)
+    paths = resolve_project_paths(workspace_root)
+    return {
+        "kind": "taskledger_status",
+        "workspace_root": str(paths.workspace_root),
+        "config_path": str(paths.config_path),
+        "taskledger_dir": str(paths.taskledger_dir),
+        "project_dir": str(paths.project_dir),
+        "counts": _project_counts(workspace_root),
+        "healthy": bool(doctor["healthy"]),
+        "active_task": _active_task_status(workspace_root),
+        "errors": list(cast(list[object], doctor["errors"])),
+        "warnings": list(cast(list[object], doctor["warnings"])),
+        "repair_hints": list(cast(list[object], doctor["repair_hints"])),
+        "tasks": [
+            {
+                "id": task.id,
+                "slug": task.slug,
+                "title": task.title,
+                "status": task.status_stage,
+                "status_stage": task.status_stage,
+                "active_stage": derive_active_stage(
+                    next(
+                        (
+                            lock
+                            for lock in locks
+                            if lock.task_id == task.id and not lock_is_expired(lock)
+                        ),
+                        None,
+                    ),
+                    list_runs(workspace_root, task.id),
+                ),
+                "accepted_plan_version": task.accepted_plan_version,
+                "latest_plan_version": task.latest_plan_version,
+            }
+            for task in tasks
+        ],
+        "doctor": doctor,
+    }
+
+
+def project_doctor(workspace_root: Path) -> dict[str, object]:
+    return inspect_v2_project(workspace_root)
+
+
+def project_export(
+    workspace_root: Path,
+    *,
+    include_bodies: bool = False,
+    include_run_artifacts: bool = False,
+) -> dict[str, object]:
+    return export_project_payload(
+        workspace_root,
+        include_bodies=include_bodies,
+        include_run_artifacts=include_run_artifacts,
+    )
+
+
+def project_import(
+    workspace_root: Path,
+    *,
+    text: str,
+    format_name: str = "json",
+    replace: bool = False,
+) -> dict[str, object]:
+    payload = parse_project_import_payload(text, format_name=format_name)
+    return import_project_payload(workspace_root, payload=payload, replace=replace)
+
+
+def project_snapshot(
+    workspace_root: Path,
+    *,
+    output_dir: Path,
+    include_bodies: bool = False,
+    include_run_artifacts: bool = False,
+) -> dict[str, object]:
+    return write_project_snapshot(
+        workspace_root,
+        output_dir=output_dir,
+        include_bodies=include_bodies,
+        include_run_artifacts=include_run_artifacts,
+    )
+
+
+def _project_counts(workspace_root: Path) -> dict[str, int]:
+    tasks = list_tasks(workspace_root)
+    return {
+        "tasks": len(tasks),
+        "introductions": len(list_introductions(workspace_root)),
+        "plans": sum(len(list_plans(workspace_root, task.id)) for task in tasks),
+        "questions": sum(
+            len(list_questions(workspace_root, task.id)) for task in tasks
+        ),
+        "runs": sum(len(list_runs(workspace_root, task.id)) for task in tasks),
+        "changes": sum(len(list_changes(workspace_root, task.id)) for task in tasks),
+        "locks": len(load_active_locks(workspace_root)),
+    }
+
+
+def _active_task_status(workspace_root: Path) -> dict[str, object] | None:
+    state = load_active_task_state(workspace_root)
+    if state is None:
+        return None
+    task = resolve_task(workspace_root, state.task_id)
+    return {
+        "task_id": task.id,
+        "slug": task.slug,
+        "title": task.title,
+        "status_stage": task.status_stage,
+    }
+
+
+__all__ = [
+    "init_project",
+    "project_status_summary",
+    "project_status",
+    "project_doctor",
+    "project_export",
+    "project_import",
+    "project_snapshot",
+]

taskledger/api/questions.py

@@ -0,0 +1,19 @@
+from taskledger.services.tasks import (
+    add_question,
+    answer_question,
+    answer_questions,
+    dismiss_question,
+    list_open_questions,
+    question_status,
+)
+from taskledger.storage.task_store import list_questions
+
+__all__ = [
+    "add_question",
+    "list_questions",
+    "list_open_questions",
+    "answer_question",
+    "answer_questions",
+    "dismiss_question",
+    "question_status",
+]

taskledger/api/search.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from taskledger.search import (
+    ProjectDependencyInfo,
+    ProjectSearchMatch,
+)
+from taskledger.search import (
+    grep_project as _grep_project,
+)
+from taskledger.search import (
+    module_dependencies as _module_dependencies,
+)
+from taskledger.search import (
+    search_project as _search_project,
+)
+from taskledger.search import (
+    symbols_project as _symbols_project,
+)
+from taskledger.storage.init import ensure_project_exists
+
+
+def search_workspace(
+    workspace_root: Path,
+    *,
+    query: str,
+    repo_refs: tuple[str, ...] = (),
+    limit: int = 50,
+) -> list[ProjectSearchMatch]:
+    return _search_project(
+        ensure_project_exists(workspace_root),
+        query=query,
+        repo_refs=repo_refs,
+        limit=limit,
+    )
+
+
+def grep_workspace(
+    workspace_root: Path,
+    *,
+    pattern: str,
+    repo_refs: tuple[str, ...] = (),
+    limit: int = 100,
+) -> list[ProjectSearchMatch]:
+    return _grep_project(
+        ensure_project_exists(workspace_root),
+        pattern=pattern,
+        repo_refs=repo_refs,
+        limit=limit,
+    )
+
+
+def symbols_workspace(
+    workspace_root: Path,
+    *,
+    query: str,
+    repo_refs: tuple[str, ...] = (),
+    limit: int = 50,
+) -> list[ProjectSearchMatch]:
+    return _symbols_project(
+        ensure_project_exists(workspace_root),
+        query=query,
+        repo_refs=repo_refs,
+        limit=limit,
+    )
+
+
+def dependencies_for_module(
+    workspace_root: Path,
+    *,
+    repo_ref: str,
+    module: str,
+) -> ProjectDependencyInfo:
+    return _module_dependencies(
+        ensure_project_exists(workspace_root),
+        repo_ref=repo_ref,
+        module=module,
+    )
+
+
+__all__ = [
+    "search_workspace",
+    "grep_workspace",
+    "symbols_workspace",
+    "dependencies_for_module",
+]

taskledger/api/task_runs.py

@@ -0,0 +1,38 @@
+from taskledger.services.tasks import (
+    add_change,
+    add_implementation_artifact,
+    add_implementation_deviation,
+    add_validation_check,
+    finish_implementation,
+    finish_validation,
+    log_implementation,
+    restart_implementation,
+    run_implementation_command,
+    scan_changes,
+    show_task_run,
+    start_implementation,
+    start_validation,
+    validation_status,
+    waive_criterion,
+)
+from taskledger.storage.task_store import list_changes, list_runs
+
+__all__ = [
+    "start_implementation",
+    "restart_implementation",
+    "log_implementation",
+    "add_implementation_deviation",
+    "add_implementation_artifact",
+    "add_change",
+    "finish_implementation",
+    "scan_changes",
+    "run_implementation_command",
+    "start_validation",
+    "add_validation_check",
+    "finish_validation",
+    "validation_status",
+    "waive_criterion",
+    "show_task_run",
+    "list_runs",
+    "list_changes",
+]