taskgate 0.1.0__py3-none-any.whl

taskgate/commands/registry.py

@@ -0,0 +1,70 @@
+"""Registry maintenance commands: init, validate, render, sort."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .. import model, ordering, render, store
+from .common import EMPTY_REGISTRY, identity
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    project = store.open_project(create=True)
+    path = project.tasks_file
+    if path.exists() and not args.force:
+        print(f"error: {path} already exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    tasks = store.read_seed(args.seed) if args.seed else EMPTY_REGISTRY["tasks"]
+    with store.locked(project):
+        store.save(project, {"version": 1, "tasks": tasks})
+        store.append_log(project, "init", "-", identity(args), {"seed": args.seed or "-"})
+    print(f"initialized {path} ({len(tasks)} tasks)")
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    data = store.load(project)
+    errors = model.validate(data, project.config)
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+    print(f"OK: {len(data.get('tasks', []))} tasks, schema + flow rules valid")
+    return 0
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    data = store.load(project)
+    text = render.render(data, project.config)
+    path = project.view_file
+    if args.check:
+        if not path.exists():
+            print(f"error: {path} missing (run 'render' first)", file=sys.stderr)
+            return 1
+        if path.read_text(encoding="utf-8") != text:
+            print(f"error: {path} drifted from tasks.json (run 'render')", file=sys.stderr)
+            return 1
+        print("OK: view in sync")
+        return 0
+    target = Path(args.out) if args.out else path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+    print(f"rendered {target}")
+    return 0
+
+
+def cmd_sort(args: argparse.Namespace) -> int:
+    project = store.open_project()
+    with store.locked(project):
+        data = store.load(project)
+        before = [t.get("id") for t in data.get("tasks", [])]
+        data["tasks"] = ordering.sorted_tasks(data.get("tasks", []))
+        store.save(project, data)
+        reordered = before != [t.get("id") for t in data["tasks"]]
+        store.append_log(project, "sort", "-", identity(args), {"reordered": reordered})
+    print("sorted tasks.json" if reordered else "already sorted")
+    return 0

taskgate/config.py

@@ -0,0 +1,135 @@
+"""Project configuration: ``taskgate.toml`` at the project root (optional, every key has a default)."""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE = "taskgate.toml"
+DEFAULT_DATA_DIR = ".taskgate"
+DEFAULT_ID_PATTERN = r"^[A-Za-z][A-Za-z0-9]*-\d+$"
+
+
+@dataclass(frozen=True)
+class Config:
+    """Policy and layout of one project.
+
+    ``planners`` are the identities allowed to add, move and re-link tasks, and
+    ``reviewer`` is the identity whose result closes a task. Identities are
+    declared by the caller (``--by`` / ``TASKGATE_BY``): this is a process
+    barrier between roles, not authentication.
+    """
+
+    data_dir: str = DEFAULT_DATA_DIR
+    title: str = "Tasks"
+    id_pattern: str = DEFAULT_ID_PATTERN
+    phase_names: dict[int, str] = field(default_factory=dict)
+    planners: tuple[str, ...] = ("human",)
+    reviewer: str = "reviewer"
+    owners: tuple[str, ...] | None = None
+    require_review: bool = True
+    review_delay_seconds: int = 60
+    quality: dict[str, list[list[str]]] = field(default_factory=dict)
+
+    @property
+    def id_regex(self) -> re.Pattern[str]:
+        """Compiled ``id_pattern``; a named group ``phase`` ties the id to the task's phase."""
+        return re.compile(self.id_pattern)
+
+
+def _strings(raw: Any, key: str) -> tuple[str, ...]:
+    if not isinstance(raw, list) or not all(isinstance(x, str) and x for x in raw):
+        raise SystemExit(f"error: {CONFIG_FILE}: {key} must be a list of non-empty strings")
+    return tuple(raw)
+
+
+def parse(raw: dict[str, Any]) -> Config:
+    """Build a ``Config`` from parsed TOML, rejecting unknown keys and bad values."""
+    known = {
+        "data_dir", "title", "id_pattern", "phase_names", "planners", "reviewer",
+        "owners", "require_review", "review_delay_seconds", "quality",
+    }
+    unknown = sorted(set(raw) - known)
+    if unknown:
+        raise SystemExit(f"error: {CONFIG_FILE}: unknown keys {', '.join(unknown)}")
+    base = Config()
+    values: dict[str, Any] = {}
+    for key in ("data_dir", "title", "id_pattern", "reviewer"):
+        if key in raw:
+            if not isinstance(raw[key], str) or not raw[key]:
+                raise SystemExit(f"error: {CONFIG_FILE}: {key} must be a non-empty string")
+            values[key] = raw[key]
+    for key in ("planners", "owners"):
+        if key in raw:
+            values[key] = _strings(raw[key], key)
+    for key in ("require_review",):
+        if key in raw:
+            if not isinstance(raw[key], bool):
+                raise SystemExit(f"error: {CONFIG_FILE}: {key} must be true or false")
+            values[key] = raw[key]
+    if "review_delay_seconds" in raw:
+        delay = raw["review_delay_seconds"]
+        if not isinstance(delay, int) or isinstance(delay, bool) or delay < 0:
+            raise SystemExit(f"error: {CONFIG_FILE}: review_delay_seconds must be an integer >= 0")
+        values["review_delay_seconds"] = delay
+    if "phase_names" in raw:
+        names = raw["phase_names"]
+        if not isinstance(names, dict) or not all(k.isdigit() and isinstance(v, str) for k, v in names.items()):
+            raise SystemExit(f"error: {CONFIG_FILE}: phase_names must map phase numbers to strings")
+        values["phase_names"] = {int(k): v for k, v in names.items()}
+    if "quality" in raw:
+        gates = raw["quality"]
+        ok = isinstance(gates, dict) and all(
+            isinstance(cmds, list) and cmds and all(
+                isinstance(c, list) and c and all(isinstance(a, str) for a in c) for c in cmds
+            )
+            for cmds in gates.values()
+        )
+        if not ok:
+            raise SystemExit(
+                f"error: {CONFIG_FILE}: quality.<name> must be a non-empty list of argv arrays"
+            )
+        values["quality"] = {name: [list(c) for c in cmds] for name, cmds in gates.items()}
+    config = Config(**{**base.__dict__, **values})
+    try:
+        re.compile(config.id_pattern)
+    except re.error as exc:
+        raise SystemExit(f"error: {CONFIG_FILE}: id_pattern is not a valid regex: {exc}") from exc
+    return config
+
+
+def load(root: Path) -> Config:
+    """Read ``taskgate.toml`` from ``root``; defaults when it does not exist."""
+    path = root / CONFIG_FILE
+    if not path.is_file():
+        return Config()
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SystemExit(f"error: {path}: {exc}") from exc
+    return parse(raw)
+
+
+def find_root(start: Path | None = None) -> Path:
+    """Project root: ``TASKGATE_ROOT``, else the nearest ancestor with a config or data directory."""
+    env = os.environ.get("TASKGATE_ROOT")
+    if env:
+        return Path(env).expanduser().resolve()
+    here = (start or Path.cwd()).resolve()
+    for parent in (here, *here.parents):
+        if (parent / CONFIG_FILE).is_file() or (parent / DEFAULT_DATA_DIR).is_dir():
+            return parent
+    raise SystemExit(
+        "error: no taskgate project found above the current directory "
+        "(run 'taskgate init' or set TASKGATE_ROOT)"
+    )
+
+
+def init_root() -> Path:
+    """Where ``init`` creates a project: ``TASKGATE_ROOT`` or the current directory."""
+    env = os.environ.get("TASKGATE_ROOT")
+    return Path(env).expanduser().resolve() if env else Path.cwd().resolve()

taskgate/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server."""

taskgate/mcp/bridge.py

@@ -0,0 +1,42 @@
+"""Adapters to the outside world: the CLI and subprocesses.
+
+Tool modules call these through the module (``bridge.run_cli(...)``), so tests
+can replace one function here and every tool sees it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import subprocess
+
+from .. import config as config_mod
+from ..cli import main as cli_main
+
+PROCESS_TIMEOUT_SECONDS = 1200
+
+
+def run_cli(argv: list[str]) -> str:
+    """Run a CLI command capturing stdout/stderr; raise on non-zero exit."""
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        code = cli_main(argv)
+    output = out.getvalue().strip()
+    if code != 0:
+        raise RuntimeError(err.getvalue().strip() or output or f"exit code {code}")
+    return output or "ok"
+
+
+def run_process(command: list[str]) -> tuple[int, str]:
+    """Run a quality-gate command in the project root and capture its (tail of) output."""
+    root = config_mod.find_root()
+    try:
+        completed = subprocess.run(
+            command, cwd=root, capture_output=True, text=True, check=False, timeout=PROCESS_TIMEOUT_SECONDS
+        )
+    except subprocess.TimeoutExpired as exc:
+        return 124, f"timeout: {' '.join(command)} ({exc.timeout}s)"
+    except OSError as exc:
+        return 127, f"cannot run {' '.join(command)}: {exc}"
+    output = "\n".join(part.strip() for part in (completed.stdout, completed.stderr) if part.strip())
+    return completed.returncode, output[-4000:]

taskgate/mcp/protocol.py

@@ -0,0 +1,76 @@
+"""JSON-RPC 2.0 dispatcher and stdio loop (MCP stdio transport, newline-delimited).
+
+Everything written to stdout is protocol; tool output is captured into the
+content envelope, so handler print chatter never touches the stream.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from . import registry
+
+DEFAULT_PROTOCOL_VERSION = "2025-06-18"
+
+
+def _ok(request_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+
+def handle_request(
+    request: dict[str, Any],
+    *,
+    tools: dict[str, registry.ToolSpec],
+    server_info: dict[str, str],
+) -> dict[str, Any] | None:
+    """Pure JSON-RPC dispatcher. Returns None for notifications."""
+    method = request.get("method", "")
+    request_id = request.get("id")
+    if method.startswith("notifications/") or request_id is None:
+        return None
+    if method == "initialize":
+        params = request.get("params") or {}
+        return _ok(request_id, {
+            "protocolVersion": params.get("protocolVersion", DEFAULT_PROTOCOL_VERSION),
+            "capabilities": {"tools": {}},
+            "serverInfo": server_info,
+        })
+    if method == "ping":
+        return _ok(request_id, {})
+    if method == "tools/list":
+        return _ok(request_id, {"tools": [{k: v for k, v in spec.items() if k != "handler"} for spec in tools.values()]})
+    if method == "tools/call":
+        params = request.get("params") or {}
+        name = str(params.get("name", ""))
+        spec = tools.get(name)
+        if spec is None:
+            return _error(request_id, -32601, f"unknown tool {name!r}")
+        try:
+            text = spec["handler"](params.get("arguments") or {})
+        except (Exception, SystemExit) as exc:  # tool errors ride in the envelope
+            return _ok(request_id, {"content": [{"type": "text", "text": str(exc)}], "isError": True})
+        return _ok(request_id, {"content": [{"type": "text", "text": text}], "isError": False})
+    return _error(request_id, -32601, f"method not found: {method}")
+
+
+def serve(*, tools: dict[str, registry.ToolSpec], server_info: dict[str, str]) -> None:
+    """Run the stdio loop until EOF, answering each line on stdout."""
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            response: dict[str, Any] | None = _error(None, -32700, "parse error")
+        else:
+            response = handle_request(request, tools=tools, server_info=server_info)
+        if response is not None:
+            sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+            sys.stdout.flush()

taskgate/mcp/registry.py

@@ -0,0 +1,44 @@
+"""Tool table, decorator and argument helper."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+Handler = Callable[[dict[str, Any]], str]
+ToolSpec = dict[str, Any]
+
+
+class Registry:
+    """A tool table: name -> spec (``name``, ``description``, ``inputSchema``, ``handler``)."""
+
+    def __init__(self) -> None:
+        self.tools: dict[str, ToolSpec] = {}
+
+    def tool(
+        self, name: str, description: str, input_schema: dict[str, Any], *, read_only: bool = False
+    ) -> Callable[[Handler], Handler]:
+        """Decorator registering a handler. ``read_only`` lets clients skip the approval prompt."""
+
+        def decorator(func: Handler) -> Handler:
+            spec: ToolSpec = {
+                "name": name,
+                "description": description,
+                "inputSchema": {"type": "object", **input_schema},
+                "annotations": {"readOnlyHint": read_only},
+                "handler": func,
+            }
+            self.tools[name] = spec
+            return func
+
+        return decorator
+
+
+REGISTRY = Registry()
+TOOLS = REGISTRY.tools
+tool = REGISTRY.tool
+
+
+def arg(value: dict[str, Any], key: str, default: Any = None) -> Any:
+    """Read ``key`` from a tool's arguments with an optional default."""
+    return value.get(key, default)

taskgate/mcp/server.py

@@ -0,0 +1,25 @@
+"""MCP stdio server for the task registry (stdlib-only)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .. import __version__
+from . import protocol, registry, tools  # noqa: F401  (importing tools registers them)
+
+SERVER_INFO = {"name": "taskgate", "version": __version__}
+
+
+def handle_request(request: dict[str, Any]) -> dict[str, Any] | None:
+    """JSON-RPC dispatcher bound to this server's tools. Returns None for notifications."""
+    return protocol.handle_request(request, tools=registry.TOOLS, server_info=SERVER_INFO)
+
+
+def serve() -> None:
+    """Run the stdio loop until EOF."""
+    protocol.serve(tools=registry.TOOLS, server_info=SERVER_INFO)
+
+
+def run() -> None:
+    """Console-script entry point (``taskgate-mcp``)."""
+    serve()

taskgate/mcp/tools.py

@@ -0,0 +1,207 @@
+"""MCP tools: thin wrappers over the CLI commands, plus the configurable quality gate."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .. import config as config_mod
+from .. import model
+from . import bridge
+from .registry import arg, tool
+
+_STATUSES = list(model.STATUSES)
+
+
+@tool(
+    "task_list",
+    "List tasks (optional status filter).",
+    {"properties": {"status": {"type": "string", "enum": _STATUSES}}},
+    read_only=True,
+)
+def task_list(args: dict[str, Any]) -> str:
+    return bridge.run_cli(["list", *(["--status", arg(args, "status")] if arg(args, "status") else [])])
+
+
+@tool(
+    "task_next",
+    "Show the one task that may start now: the queue head, planned, with dependencies and the phase gate met.",
+    {"properties": {"owner": {"type": "string"}}},
+    read_only=True,
+)
+def task_next(args: dict[str, Any]) -> str:
+    return bridge.run_cli(["next", *(["--owner", arg(args, "owner")] if arg(args, "owner") else [])])
+
+
+@tool(
+    "task_claim",
+    "Claim a planned task (-> in_progress, sets owner and started). Refused unless every earlier task is "
+    "done/cancelled (order and phase gate) and its dependencies are done.",
+    {"properties": {"id": {"type": "string"}, "by": {"type": "string"}, "force": {"type": "boolean"}},
+     "required": ["id"]},
+)
+def task_claim(args: dict[str, Any]) -> str:
+    argv = ["claim", arg(args, "id")]
+    if arg(args, "by"):
+        argv += ["--by", arg(args, "by")]
+    if arg(args, "force"):
+        argv.append("--force")
+    return bridge.run_cli(argv)
+
+
+@tool(
+    "task_update",
+    "Advance a task's status and record evidence (transitions are enforced). Send verification_result and "
+    "review_result in SEPARATE calls: the caller identity (by) is the verifier; a review must come from the "
+    "configured reviewer identity, a different one, after the configured delay since the stored verification, "
+    "must list the commands it checked in checks=[...]; closing as done needs a fresh review_result in the same "
+    "call (unless the project sets require_review = false).",
+    {"properties": {
+        "id": {"type": "string"},
+        "status": {"type": "string", "enum": _STATUSES},
+        "reason": {"type": "string"},
+        "verification_result": {"type": "object"},
+        "review_result": {"type": "object"},
+        "by": {"type": "string"},
+    }, "required": ["id"]},
+)
+def task_update(args: dict[str, Any]) -> str:
+    argv = ["update", arg(args, "id")]
+    for key, flag in (("status", "--status"), ("reason", "--reason"), ("by", "--by")):
+        if arg(args, key):
+            argv += [flag, arg(args, key)]
+    for key, flag in (("verification_result", "--verification-result"), ("review_result", "--review-result")):
+        if arg(args, key) is not None:
+            argv += [flag, json.dumps(arg(args, key))]
+    return bridge.run_cli(argv)
+
+
+@tool(
+    "task_render",
+    "Render the Markdown view from tasks.json; check=true fails on drift instead of writing.",
+    {"properties": {"check": {"type": "boolean", "default": False}}},
+)
+def task_render(args: dict[str, Any]) -> str:
+    return bridge.run_cli(["render", *(["--check"] if arg(args, "check", False) else [])])
+
+
+@tool("task_validate", "Validate tasks.json: schema, status transitions and evidence gates.", {"properties": {}},
+      read_only=True)
+def task_validate(args: dict[str, Any]) -> str:
+    return bridge.run_cli(["validate"])
+
+
+@tool(
+    "task_add",
+    "Add a draft/planned task (duplicate ids and closed phases are rejected). Only identities listed in "
+    "'planners' of taskgate.toml may add tasks; pass by explicitly.",
+    {"properties": {
+        "id": {"type": "string"},
+        "title": {"type": "string"},
+        "phase": {"type": "integer", "minimum": 0},
+        "verification_cmd": {"type": "string"},
+        "spec": {"type": "string"},
+        "status": {"type": "string", "enum": list(model.ADD_STATUSES)},
+        "owner": {"type": "string"},
+        "depends": {"type": "array", "items": {"type": "string"}},
+        "by": {"type": "string"},
+    }, "required": ["id", "title", "verification_cmd", "by"]},
+)
+def task_add(args: dict[str, Any]) -> str:
+    argv = ["add", "--id", arg(args, "id"), "--title", arg(args, "title"),
+            "--verification-cmd", arg(args, "verification_cmd"), "--by", arg(args, "by")]
+    if arg(args, "phase") is not None:
+        argv += ["--phase", str(arg(args, "phase"))]
+    for key, flag in (("spec", "--spec"), ("status", "--status"), ("owner", "--owner")):
+        if arg(args, key):
+            argv += [flag, arg(args, key)]
+    if arg(args, "depends"):
+        argv += ["--depends", ",".join(arg(args, "depends"))]
+    return bridge.run_cli(argv)
+
+
+@tool(
+    "task_sort",
+    "Reset the execution order to phase, then id; discards any order set with task_move.",
+    {"properties": {"by": {"type": "string"}}},
+)
+def task_sort(args: dict[str, Any]) -> str:
+    return bridge.run_cli(["sort", *(["--by", arg(args, "by")] if arg(args, "by") else [])])
+
+
+@tool(
+    "task_move",
+    "Change the execution order: place a draft/planned task directly before or after another. Never in front "
+    "of a task that is in flight or done, and phases stay ascending. Planners only; pass exactly one of "
+    "before/after.",
+    {"properties": {"id": {"type": "string"}, "before": {"type": "string"}, "after": {"type": "string"},
+                    "by": {"type": "string"}}, "required": ["id", "by"]},
+)
+def task_move(args: dict[str, Any]) -> str:
+    before, after = arg(args, "before"), arg(args, "after")
+    if bool(before) == bool(after):
+        raise ValueError("pass exactly one of before or after")
+    return bridge.run_cli(["move", arg(args, "id"), "--before" if before else "--after", before or after,
+                           "--by", arg(args, "by")])
+
+
+@tool(
+    "task_depends",
+    "Change the dependencies of a draft/planned task: set (replace; [] clears), add and/or remove ids. Each "
+    "dependency must exist and be placed before the task (use task_move first). Planners only.",
+    {"properties": {
+        "id": {"type": "string"},
+        "set": {"type": "array", "items": {"type": "string"}},
+        "add": {"type": "array", "items": {"type": "string"}},
+        "remove": {"type": "array", "items": {"type": "string"}},
+        "by": {"type": "string"},
+    }, "required": ["id", "by"]},
+)
+def task_depends(args: dict[str, Any]) -> str:
+    argv = ["depends", arg(args, "id")]
+    for key in ("set", "add", "remove"):
+        if arg(args, key) is not None:
+            argv += [f"--{key}", ",".join(arg(args, key))]
+    return bridge.run_cli([*argv, "--by", arg(args, "by")])
+
+
+BUILTIN_GATES = ("tasks",)
+
+
+@tool(
+    "quality_check",
+    "Run quality gates and return a compact JSON report. Gate names come from [quality] in taskgate.toml; the "
+    "built-in gate 'tasks' validates the registry and checks the Markdown view. Without 'checks' every gate runs.",
+    {"properties": {"checks": {"type": "array", "items": {"type": "string"}}}},
+)
+def quality_check(args: dict[str, Any]) -> str:
+    gates = config_mod.load(config_mod.find_root()).quality
+    available = [*gates, *BUILTIN_GATES]
+    requested = arg(args, "checks")
+    if requested is None:
+        requested = available
+    if not requested:
+        raise ValueError("checks must contain at least one gate")
+    unknown = [name for name in requested if name not in available]
+    if unknown:
+        raise ValueError(f"unknown quality checks: {', '.join(unknown)} (available: {', '.join(available)})")
+    results: list[dict[str, Any]] = []
+    ok = True
+    for name in requested:
+        if name in BUILTIN_GATES:
+            for command in (["validate"], ["render", "--check"]):
+                try:
+                    code, output = 0, bridge.run_cli(command)
+                except RuntimeError as exc:
+                    code, output = 1, str(exc)
+                ok = ok and code == 0
+                results.append({"check": name, "command": f"taskgate {' '.join(command)}", "exit": code, "output": output})
+            continue
+        for command in gates[name]:
+            code, output = bridge.run_process(command)
+            ok = ok and code == 0
+            results.append({"check": name, "command": " ".join(command), "exit": code, "output": output})
+    report = json.dumps({"ok": ok, "results": results}, ensure_ascii=False, indent=1)
+    if not ok:
+        raise RuntimeError(report)
+    return report