foreman-plane 0.1.0__py3-none-any.whl

foreman/__init__.py

@@ -0,0 +1,13 @@
+"""foreman-plane — a task governance plane that lives *outside* the agent harness.
+
+The plane owns dispatch, two-level dependency gating, objective artefact
+acceptance and an append-only audit ledger.  Any CLI agent (Claude Code,
+Codex, DeepSeek Harness, ...) is just a pluggable execution body.
+
+Zero third-party dependencies: standard library only, Python >= 3.10.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

foreman/acceptance.py

@@ -0,0 +1,140 @@
+"""Objective artefact acceptance (SPEC §5).
+
+The acceptance string is ``path`` or ``path::key=value::key=value``.
+
+Supported criteria:
+
+* ``min_bytes=N``    file size >= N
+* ``sha256=<hex>``   sha256 of the file content equals the digest
+* ``contains=<sub>`` file content contains the substring
+* ``exit_code=N``    execution body exit code equals N
+
+Criteria are ANDed.  An unknown criterion fails closed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .contract import ACCEPT_PATH_RE, split_acceptance
+
+__all__ = ["AcceptanceResult", "verify", "parse_acceptance"]
+
+
+@dataclass
+class AcceptanceResult:
+    """Result of one acceptance verification (SPEC §5)."""
+
+    ok: bool
+    path: str | None = None
+    checks: list[dict] = field(default_factory=list)
+    reason: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "path": self.path,
+            "checks": list(self.checks),
+            "reason": self.reason,
+        }
+
+
+def parse_acceptance(value: str | None) -> tuple[str | None, list[tuple[str, str]]]:
+    """Public alias of the acceptance string parser."""
+    return split_acceptance(value)
+
+
+def _as_int(value: str) -> int | None:
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def verify(
+    acceptance: str | None,
+    exit_code: int | None = None,
+    base_dir: str | os.PathLike[str] | None = None,
+) -> AcceptanceResult:
+    """Verify an artefact against an acceptance string."""
+    if acceptance is None or not str(acceptance).strip():
+        return AcceptanceResult(ok=True, path=None, checks=[], reason=None)
+
+    raw_path, criteria = split_acceptance(acceptance)
+    if not raw_path or not ACCEPT_PATH_RE.match(raw_path):
+        return AcceptanceResult(
+            ok=False,
+            path=raw_path,
+            checks=[],
+            reason="acceptance_invalid",
+        )
+
+    target = Path(raw_path).expanduser()
+    if not target.is_absolute():
+        base = Path(base_dir).expanduser() if base_dir else Path.cwd()
+        target = base / target
+
+    checks: list[dict] = []
+    if not target.exists():
+        checks.append({"name": "exists", "expected": True, "actual": False, "ok": False})
+        return AcceptanceResult(ok=False, path=str(target), checks=checks, reason="artifact_missing")
+    checks.append({"name": "exists", "expected": True, "actual": True, "ok": True})
+    if not target.is_file():
+        return AcceptanceResult(
+            ok=False,
+            path=str(target),
+            checks=checks,
+            reason="artifact_not_a_file",
+        )
+
+    try:
+        data = target.read_bytes()
+    except OSError:
+        return AcceptanceResult(
+            ok=False,
+            path=str(target),
+            checks=checks,
+            reason="artifact_unreadable",
+        )
+    text = data.decode("utf-8", errors="replace")
+
+    ok = True
+    reason: str | None = None
+    for name, expected in criteria:
+        key = name.strip().lower()
+        if key == "min_bytes":
+            wanted = _as_int(expected)
+            actual = len(data)
+            passed = wanted is not None and actual >= wanted
+            record_expected = wanted
+        elif key == "sha256":
+            actual = hashlib.sha256(data).hexdigest()
+            passed = actual.lower() == str(expected).strip().lower()
+            record_expected = str(expected).strip().lower()
+        elif key == "contains":
+            actual = None
+            passed = str(expected) in text
+            record_expected = str(expected)
+        elif key == "exit_code":
+            wanted = _as_int(expected)
+            actual = exit_code
+            passed = wanted is not None and exit_code is not None and int(exit_code) == wanted
+            record_expected = wanted
+        else:
+            checks.append(
+                {"name": key, "expected": str(expected), "actual": None, "ok": False}
+            )
+            ok = False
+            reason = reason or "acceptance_unknown_criterion"
+            continue
+        checks.append(
+            {"name": key, "expected": record_expected, "actual": actual, "ok": bool(passed)}
+        )
+        if not passed:
+            ok = False
+            reason = reason or "acceptance_criterion_failed"
+
+    return AcceptanceResult(ok=ok, path=str(target), checks=checks, reason=reason)

foreman/cli.py

@@ -0,0 +1,292 @@
+"""Command line interface (SPEC §8).
+
+``python -m foreman.cli`` or the ``foreman`` console script.
+
+Exit codes: 0 success, 2 blocked by the gate, 3 artefact acceptance failed,
+1 any other error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .acceptance import verify
+from .config import describe, load_config, resolve_default_agent
+from .errors import UnknownTaskError
+from .runner import Dispatcher
+
+__all__ = ["main", "build_parser"]
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_BLOCKED = 2
+EXIT_ACCEPTANCE = 3
+
+_JSON_FLAG = argparse.SUPPRESS
+
+
+def _add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        default=_JSON_FLAG,
+        help="machine readable output (JSON)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="foreman",
+        description="foreman-plane — task governance outside the agent harness",
+    )
+    _add_json(parser)
+    sub = parser.add_subparsers(dest="command")
+
+    dispatch = sub.add_parser("dispatch", help="dispatch a task card file")
+    dispatch.add_argument("--file", required=True, help="path to the task card")
+    dispatch.add_argument("--agent", help="execution body name")
+    dispatch.add_argument("--workdir", help="working directory")
+    dispatch.add_argument("--force", action="store_true", help="override the duplicate check")
+    _add_json(dispatch)
+
+    status = sub.add_parser("status", help="ledger status summary")
+    status.add_argument("--task-id", help="restrict to one task")
+    _add_json(status)
+
+    ledger = sub.add_parser("ledger", help="ledger operations")
+    ledger_sub = ledger.add_subparsers(dest="ledger_command")
+
+    listing = ledger_sub.add_parser("list", help="list all tasks")
+    listing.add_argument("--task-id", help="restrict to one task")
+    _add_json(listing)
+
+    show = ledger_sub.add_parser("show", help="show the events of one task")
+    show.add_argument("task_id")
+    _add_json(show)
+
+    ready = ledger_sub.add_parser("ready", help="tasks whose dependencies are satisfied")
+    _add_json(ready)
+
+    blocked = ledger_sub.add_parser("blocked", help="tasks currently blocked")
+    _add_json(blocked)
+
+    cancel = ledger_sub.add_parser("cancel", help="cancel a task")
+    cancel.add_argument("task_id")
+    cancel.add_argument("--reason", default="")
+    _add_json(cancel)
+
+    replan = ledger_sub.add_parser("replan", help="re-plan a task")
+    replan.add_argument("task_id")
+    replan.add_argument("--reason", default="")
+    replan.add_argument("--new-task-id", default=None)
+    _add_json(replan)
+
+    verify_cmd = sub.add_parser("verify", help="verify an acceptance string")
+    verify_cmd.add_argument("--acceptance", required=True, help="acceptance string")
+    verify_cmd.add_argument("--base-dir", default=None, help="base directory for relative paths")
+    _add_json(verify_cmd)
+
+    sub.add_parser("mcp", help="run the MCP stdio server")
+    sub.add_parser("config", help="print the effective configuration")
+    _add_json(sub.choices["mcp"])
+    _add_json(sub.choices["config"])
+
+    return parser
+
+
+def _emit(payload: Any, as_json: bool, text: str = "") -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(text if text else json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _cmd_dispatch(args: argparse.Namespace, dispatcher: Dispatcher) -> int:
+    try:
+        text = Path(args.file).read_text(encoding="utf-8")
+    except OSError as exc:
+        print(f"cannot read task card: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    payload = dispatcher.dispatch(
+        text,
+        agent=args.agent,
+        workdir=args.workdir,
+        force=bool(args.force),
+    )
+    if payload.get("blocked"):
+        _emit(payload, args.json, _dispatch_text(payload))
+        return EXIT_BLOCKED
+    if payload.get("acceptance_ok") is False:
+        _emit(payload, args.json, _dispatch_text(payload))
+        return EXIT_ACCEPTANCE
+    if not payload.get("ok"):
+        _emit(payload, args.json, _dispatch_text(payload))
+        return EXIT_ERROR
+    _emit(payload, args.json, _dispatch_text(payload))
+    return EXIT_OK
+
+
+def _dispatch_text(payload: dict) -> str:
+    lines = [
+        f"task_id: {payload.get('task_id')}",
+        f"ok: {payload.get('ok')}",
+    ]
+    if payload.get("blocked"):
+        lines.append(f"blocked: {payload.get('reason')}")
+        if payload.get("missing"):
+            lines.append(f"missing: {', '.join(payload['missing'])}")
+        return "\n".join(lines)
+    lines.append(f"verdict: {payload.get('verdict')}")
+    lines.append(f"acceptance_ok: {payload.get('acceptance_ok')}")
+    lines.append(f"exit_code: {payload.get('exit_code')}")
+    if payload.get("needs_api_pending"):
+        lines.append("needs_api_pending: true")
+    return "\n".join(lines)
+
+
+def _cmd_status(args: argparse.Namespace, dispatcher: Dispatcher) -> int:
+    payload = dispatcher.status(args.task_id)
+    if args.json:
+        _emit(payload, True)
+    else:
+        if args.task_id:
+            state = payload.get("task")
+            if not state:
+                print(f"unknown task: {args.task_id}")
+            else:
+                for key in ("task_id", "status", "verdict", "acceptance_ok", "exit_code", "last_ts"):
+                    print(f"{key}: {state.get(key)}")
+        else:
+            for name, count in sorted((payload.get("counts") or {}).items()):
+                print(f"{name}: {count}")
+    return EXIT_OK
+
+
+def _cmd_ledger(args: argparse.Namespace, dispatcher: Dispatcher) -> int:
+    command = getattr(args, "ledger_command", None)
+    if command is None:
+        print("foreman ledger: expected one of list|show|ready|blocked|cancel|replan", file=sys.stderr)
+        return EXIT_ERROR
+    if command == "list":
+        payload = dispatcher.status(getattr(args, "task_id", None))
+        tasks = payload.get("tasks") or {}
+        if getattr(args, "task_id", None):
+            tasks = {args.task_id: tasks.get(args.task_id)} if args.task_id in tasks else {}
+        if args.json:
+            _emit(tasks, True)
+        else:
+            for task_id, state in sorted(tasks.items()):
+                print(f"{task_id}\t{state.get('status')}\t{state.get('verdict')}")
+        return EXIT_OK
+    if command == "show":
+        events = dispatcher.ledger.events(args.task_id)
+        if args.json:
+            _emit(events, True)
+        else:
+            for event in events:
+                print(json.dumps(event, ensure_ascii=False))
+        return EXIT_OK
+    if command == "ready":
+        payload = dispatcher.ready_tasks()
+        _emit(payload, args.json, "\n".join(item["task_id"] for item in payload))
+        return EXIT_OK
+    if command == "blocked":
+        payload = dispatcher.blocked_tasks()
+        _emit(payload, args.json, "\n".join(
+            f"{item['task_id']}\t{item.get('reason')}" for item in payload
+        ))
+        return EXIT_OK
+    if command == "cancel":
+        try:
+            payload = dispatcher.cancel(args.task_id, args.reason)
+        except UnknownTaskError as exc:
+            print(str(exc), file=sys.stderr)
+            return EXIT_ERROR
+        _emit(payload, args.json, f"cancelled: {args.task_id}")
+        return EXIT_OK
+    if command == "replan":
+        try:
+            payload = dispatcher.replan(args.task_id, args.reason, args.new_task_id)
+        except UnknownTaskError as exc:
+            print(str(exc), file=sys.stderr)
+            return EXIT_ERROR
+        _emit(payload, args.json, f"replanned: {args.task_id}")
+        return EXIT_OK
+    print(f"unknown ledger command: {command}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    result = verify(args.acceptance, base_dir=args.base_dir)
+    payload = result.to_dict()
+    if args.json:
+        _emit(payload, True)
+    else:
+        print(f"ok: {result.ok}")
+        print(f"path: {result.path}")
+        if result.reason:
+            print(f"reason: {result.reason}")
+        for check in result.checks:
+            print(f"  {check['name']}: expected={check['expected']} actual={check['actual']} ok={check['ok']}")
+    return EXIT_OK if result.ok else EXIT_ACCEPTANCE
+
+
+def _cmd_config(args: argparse.Namespace) -> int:
+    config = load_config()
+    payload = describe(config)
+    payload["default_agent"] = resolve_default_agent()
+    if args.json:
+        _emit(payload, True)
+    else:
+        print(f"FOREMAN_HOME: {payload['home']}")
+        print(f"ledger: {payload['ledger_path']}")
+        print(f"runs_dir: {payload['runs_dir']}")
+        print(f"timeout_s: {payload['timeout_s']}")
+        print(f"default_agent: {payload['default_agent']}")
+        print(f"agents: {', '.join(payload['agents'])}")
+    return EXIT_OK
+
+
+def _cmd_mcp() -> int:
+    from .mcp_server import main as mcp_main
+
+    return mcp_main()
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "json"):
+        args.json = False
+    as_json = bool(args.json)
+    command = getattr(args, "command", None)
+    if not command:
+        parser.print_help()
+        return EXIT_ERROR
+
+    if command == "mcp":
+        return _cmd_mcp()
+
+    dispatcher = Dispatcher(load_config())
+    if command == "dispatch":
+        return _cmd_dispatch(args, dispatcher)
+    if command == "status":
+        return _cmd_status(args, dispatcher)
+    if command == "ledger":
+        return _cmd_ledger(args, dispatcher)
+    if command == "verify":
+        return _cmd_verify(args)
+    if command == "config":
+        return _cmd_config(args)
+    parser.print_help()
+    return EXIT_ERROR
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

foreman/config.py

@@ -0,0 +1,175 @@
+"""Configuration resolution (SPEC §9).
+
+Every path used by foreman-plane comes from configuration:
+
+1. ``FOREMAN_HOME`` environment variable
+2. ``$HOME/.foreman`` (skipped when ``HOME`` is not set — never crash)
+3. ``<cwd>/.foreman``
+
+No absolute path constant and no host module is referenced anywhere.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping, MutableMapping
+
+DEFAULT_TIMEOUT_S = 900
+DEFAULT_AGENT = "generic"
+
+ENV_HOME = "FOREMAN_HOME"
+ENV_TIMEOUT = "FOREMAN_TIMEOUT"
+ENV_AGENT = "FOREMAN_AGENT"
+ENV_ACTOR = "FOREMAN_ACTOR"
+
+AGENTS_FILE = "agents.json"
+LEDGER_FILE = "ledger.jsonl"
+RUNS_DIR = "runs"
+
+#: Built-in execution bodies.  Every one of them is a generic CLI agent
+#: entry point — none of them depends on the host harness.
+BUILTIN_AGENTS: dict[str, dict] = {
+    "claude": {"command": "claude -p {task}", "description": "Claude Code CLI"},
+    "codex": {"command": "codex exec {task}", "description": "Codex CLI"},
+    "dsh": {"command": "dsh headless {task}", "description": "DeepSeek Harness, headless"},
+    "generic": {"command": "", "description": "custom agent, define it in agents.json"},
+}
+
+
+@dataclass
+class ForemanConfig:
+    """Effective configuration of one foreman-plane instance."""
+
+    home: Path
+    ledger_path: Path
+    runs_dir: Path
+    agents: dict[str, dict] = field(default_factory=dict)
+    timeout_s: int = DEFAULT_TIMEOUT_S
+
+
+def resolve_home(
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Resolve ``FOREMAN_HOME`` following SPEC §3.1."""
+    env = os.environ if env is None else env
+    raw = (env.get(ENV_HOME) or "").strip()
+    if raw:
+        return Path(raw).expanduser()
+    for var in ("HOME", "USERPROFILE"):
+        home = (env.get(var) or "").strip()
+        if home:
+            return Path(home).expanduser() / ".foreman"
+    base = Path(cwd) if cwd else Path.cwd()
+    return base / ".foreman"
+
+
+def load_agents(home: str | os.PathLike[str]) -> dict[str, dict]:
+    """Load ``${FOREMAN_HOME}/agents.json`` merged over the built-in agents.
+
+    The file is optional.  A malformed file never raises: the built-in
+    agents are returned instead.
+    """
+    agents: MutableMapping[str, dict] = {name: dict(spec) for name, spec in BUILTIN_AGENTS.items()}
+    path = Path(home).expanduser() / AGENTS_FILE
+    try:
+        if not path.is_file():
+            return dict(agents)
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return dict(agents)
+    if not isinstance(data, dict):
+        return dict(agents)
+    extra = data.get("agents")
+    if isinstance(extra, dict):
+        for name, spec in extra.items():
+            if not isinstance(spec, dict):
+                continue
+            merged = dict(agents.get(str(name), {}))
+            merged.update(spec)
+            agents[str(name)] = merged
+    return dict(agents)
+
+
+def _resolve_timeout(env: Mapping[str, str]) -> int:
+    raw = (env.get(ENV_TIMEOUT) or "").strip()
+    if raw:
+        try:
+            value = int(raw)
+        except ValueError:
+            value = DEFAULT_TIMEOUT_S
+        if value > 0:
+            return value
+    return DEFAULT_TIMEOUT_S
+
+
+def load_config(
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> ForemanConfig:
+    """Build the effective configuration."""
+    env = os.environ if env is None else env
+    home = resolve_home(env, cwd)
+    return ForemanConfig(
+        home=home,
+        ledger_path=home / LEDGER_FILE,
+        runs_dir=home / RUNS_DIR,
+        agents=load_agents(home),
+        timeout_s=_resolve_timeout(env),
+    )
+
+
+def resolve_default_agent(env: Mapping[str, str] | None = None) -> str:
+    """Name of the execution body used when the caller does not pick one."""
+    env = os.environ if env is None else env
+    return (env.get(ENV_AGENT) or "").strip() or DEFAULT_AGENT
+
+
+def resolve_actor(env: Mapping[str, str] | None = None) -> str:
+    """Name recorded in the ``actor`` field of every ledger event."""
+    env = os.environ if env is None else env
+    return (env.get(ENV_ACTOR) or "").strip() or "foreman"
+
+
+def ensure_dirs(config: ForemanConfig) -> None:
+    """Create the home / runs directories, ignoring filesystem failures."""
+    for directory in (config.home, config.runs_dir):
+        try:
+            directory.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            pass
+
+
+def describe(config: ForemanConfig, env: Mapping[str, str] | None = None) -> dict:
+    """Human/machine readable snapshot of the effective configuration."""
+    env = os.environ if env is None else env
+    return {
+        "home": str(config.home),
+        "ledger_path": str(config.ledger_path),
+        "runs_dir": str(config.runs_dir),
+        "timeout_s": config.timeout_s,
+        "default_agent": resolve_default_agent(env),
+        "agents": sorted(config.agents),
+    }
+
+
+__all__ = [
+    "DEFAULT_TIMEOUT_S",
+    "DEFAULT_AGENT",
+    "ENV_HOME",
+    "ENV_TIMEOUT",
+    "ENV_AGENT",
+    "ENV_ACTOR",
+    "BUILTIN_AGENTS",
+    "ForemanConfig",
+    "resolve_home",
+    "load_agents",
+    "load_config",
+    "resolve_default_agent",
+    "resolve_actor",
+    "ensure_dirs",
+    "describe",
+]