prizmkit 1.1.100 → 1.1.101

package/bundled/dev-pipeline/prizmkit_runtime/daemon.py

@@ -0,0 +1,478 @@
+"""Daemon lifecycle commands for the unified Python runtime."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .commands import CommandResult  # type: ignore  # runtime boundary import
+from .processes import ProcessSpec, is_pid_running, launch_process, terminate_pid_tree
+from .runner_models import RunnerFamily, family_for
+
+
+LOG_ROTATE_BYTES = 50 * 1024 * 1024
+START_VERIFY_SECONDS = 2.0
+
+
+@dataclass(frozen=True)
+class DaemonPaths:
+    """Filesystem contract for one pipeline daemon."""
+
+    state_dir: Path
+    pid_file: Path
+    log_file: Path
+    meta_file: Path
+
+
+@dataclass(frozen=True)
+class DaemonStartOptions:
+    """Parsed daemon start/restart arguments."""
+
+    list_path: Path
+    env_overrides: str = ""
+    mode: str = ""
+    features_filter: str = ""
+    critic: bool | None = None
+    help_requested: bool = False
+
+
+@dataclass(frozen=True)
+class DaemonLogOptions:
+    """Parsed daemon log arguments."""
+
+    lines: int = 50
+    follow: bool = False
+
+
+LIST_META_KEY_BY_KIND = {
+    "feature": "feature_list",
+    "bugfix": "bug_list",
+    "refactor": "refactor_list",
+}
+
+ITEMS_KEY_BY_KIND = {
+    "feature": "features",
+    "bugfix": "bugs",
+    "refactor": "refactors",
+}
+
+ID_KEY_BY_KIND = {
+    "feature": "id",
+    "bugfix": "id",
+    "refactor": "id",
+}
+
+PROGRESS_COUNTS_BY_KIND = {
+    "feature": ("completed", "in_progress", "failed", "pending", "skipped", "auto_skipped"),
+    "bugfix": ("completed", "in_progress", "failed", "pending", "needs_info", "skipped"),
+    "refactor": ("completed", "in_progress", "failed", "pending", "skipped", "auto_skipped"),
+}
+
+
+def run_daemon_command(kind: str, action: str, legacy_args: tuple[str, ...], paths) -> CommandResult:
+    """Run a daemon lifecycle command for feature, bugfix, or refactor."""
+    family = family_for(kind, paths)
+    daemon_paths = _daemon_paths(family)
+    if action == "describe":
+        return CommandResult(0, f"Python {kind} daemon", _help_text(family))
+    if action == "start":
+        return _start(family, daemon_paths, legacy_args, paths)
+    if action == "status":
+        return _status(family, daemon_paths)
+    if action == "stop":
+        return _stop(family, daemon_paths)
+    if action in {"logs", "log"}:
+        return _logs(family, daemon_paths, legacy_args)
+    if action == "restart":
+        stop_result = _stop(family, daemon_paths)
+        start_result = _start(family, daemon_paths, legacy_args, paths)
+        stderr = "\n".join(part for part in (stop_result.stderr, start_result.stderr) if part)
+        return CommandResult(start_result.exit_code, start_result.title, start_result.message, stdout=start_result.render(), stderr=stderr)
+    return CommandResult(1, f"Python {kind} daemon", f"Unsupported daemon action: {action}")
+
+
+def _daemon_paths(family: RunnerFamily) -> DaemonPaths:
+    return DaemonPaths(
+        state_dir=family.state_dir,
+        pid_file=family.state_dir / ".pipeline.pid",
+        log_file=family.state_dir / "pipeline-daemon.log",
+        meta_file=family.state_dir / ".pipeline-meta.json",
+    )
+
+
+def _start(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[str, ...], paths) -> CommandResult:
+    options = _parse_start_args(family, legacy_args)
+    if options.help_requested:
+        return CommandResult(0, f"Python {family.kind} daemon", _help_text(family))
+    list_path = options.list_path if options.list_path.is_absolute() else (paths.project_root / options.list_path).resolve()
+    if not list_path.is_file():
+        stderr = f"{family.kind} list not found: {list_path}"
+        return CommandResult(2, f"Python {family.kind} daemon", stderr, stdout="", stderr=stderr)
+
+    daemon_paths.state_dir.mkdir(parents=True, exist_ok=True)
+    stale_warning = _clean_stale_pid(daemon_paths)
+    stderr_lines = [stale_warning] if stale_warning else []
+    running_pid = _read_pid(daemon_paths.pid_file)
+    if is_pid_running(running_pid):
+        message = f"Pipeline is already running (PID: {running_pid})"
+        return CommandResult(1, f"Python {family.kind} daemon", message, stdout="", stderr=message)
+
+    rotated = _rotate_log_if_needed(daemon_paths.log_file)
+    if rotated:
+        stderr_lines.append(f"Log rotated: {rotated}")
+
+    started_at = _utc_iso()
+    _write_log_separator(family, daemon_paths.log_file, list_path, started_at, options)
+    command = _payload_command(family, paths, list_path, options)
+    env = _daemon_env(options)
+    spec = ProcessSpec(
+        command=tuple(command),
+        cwd=paths.project_root,
+        environment_overrides=env,
+        environment_unsets=("CLAUDECODE",),
+        pid_file=daemon_paths.pid_file,
+    )
+    log_handle = daemon_paths.log_file.open("a", encoding="utf-8")
+    try:
+        handle = launch_process(spec, stdout=log_handle, stderr=subprocess.STDOUT, stdin=subprocess.DEVNULL, text=True)
+    finally:
+        log_handle.close()
+
+    pid = int(handle.pid or 0)
+    _write_meta(family, daemon_paths.meta_file, pid, started_at, list_path, options, daemon_paths.log_file)
+    time.sleep(_start_verify_seconds())
+    if not is_pid_running(pid):
+        daemon_paths.pid_file.unlink(missing_ok=True)
+        message = f"Pipeline process died immediately after launch. Check log for errors: {daemon_paths.log_file}"
+        return CommandResult(1, f"Python {family.kind} daemon", message, stdout="", stderr="\n".join([*stderr_lines, message]))
+
+    stderr_lines.extend(
+        [
+            f"Launching {family.kind} pipeline...",
+            f"{family.kind} list: {list_path}",
+            f"Log file: {daemon_paths.log_file}",
+            f"Pipeline started successfully (PID: {pid})",
+        ]
+    )
+    payload = {"success": True, "pid": pid, "log_file": str(daemon_paths.log_file), "started_at": started_at}
+    return CommandResult(0, f"Python {family.kind} daemon", "started", stdout=json.dumps(payload), stderr="\n".join(stderr_lines))
+
+
+def _status(family: RunnerFamily, daemon_paths: DaemonPaths) -> CommandResult:
+    daemon_paths.state_dir.mkdir(parents=True, exist_ok=True)
+    stderr_lines: list[str] = []
+    stale_warning = _clean_stale_pid(daemon_paths)
+    if stale_warning:
+        stderr_lines.append(stale_warning)
+
+    pid = _read_pid(daemon_paths.pid_file)
+    meta = _read_meta(daemon_paths.meta_file)
+    if not is_pid_running(pid):
+        stderr_lines.append("Pipeline is not running")
+        if daemon_paths.log_file.is_file():
+            stderr_lines.append(f"Last log: {daemon_paths.log_file} ({daemon_paths.log_file.stat().st_size // 1024}KB)")
+        return CommandResult(1, f"Python {family.kind} daemon status", "not running", stdout=json.dumps({"running": False}), stderr="\n".join(stderr_lines))
+
+    list_key = LIST_META_KEY_BY_KIND[family.kind]
+    list_path = str(meta.get(list_key) or "")
+    log_size_kb = daemon_paths.log_file.stat().st_size // 1024 if daemon_paths.log_file.is_file() else 0
+    started_at = str(meta.get("started_at") or "")
+    payload: dict[str, object] = {
+        "running": True,
+        "pid": pid,
+        "log_file": str(daemon_paths.log_file),
+        "log_size_kb": log_size_kb,
+        "started_at": started_at,
+        list_key: list_path,
+    }
+    if family.kind != "feature":
+        payload["pipeline_type"] = family.kind
+    progress = _progress_summary(family, Path(list_path) if list_path else None)
+    if progress:
+        payload["progress"] = progress
+
+    stderr_lines.append(f"Pipeline is running (PID: {pid})")
+    if started_at:
+        stderr_lines.append(f"Started at: {started_at}")
+    stderr_lines.append(f"Log file: {daemon_paths.log_file} ({log_size_kb}KB)")
+    tail = _tail_lines(daemon_paths.log_file, 5)
+    if tail:
+        stderr_lines.append("--- Last 5 log lines ---")
+        stderr_lines.extend(tail)
+    return CommandResult(0, f"Python {family.kind} daemon status", "running", stdout=json.dumps(payload), stderr="\n".join(stderr_lines))
+
+
+def _stop(family: RunnerFamily, daemon_paths: DaemonPaths) -> CommandResult:
+    if not daemon_paths.pid_file.is_file():
+        message = "Pipeline is not running (no PID file)"
+        return CommandResult(0, f"Python {family.kind} daemon stop", message, stdout=json.dumps({"success": True, "message": "not running"}), stderr=message)
+    pid = _read_pid(daemon_paths.pid_file)
+    if pid is None:
+        daemon_paths.pid_file.unlink(missing_ok=True)
+        message = "Pipeline is not running (empty PID file)"
+        return CommandResult(0, f"Python {family.kind} daemon stop", message, stdout=json.dumps({"success": True, "message": "not running"}), stderr=message)
+    if not is_pid_running(pid):
+        daemon_paths.pid_file.unlink(missing_ok=True)
+        message = f"Pipeline is not running (process {pid} already exited)"
+        return CommandResult(0, f"Python {family.kind} daemon stop", message, stdout=json.dumps({"success": True, "message": "already exited"}), stderr=message)
+
+    termination = terminate_pid_tree(pid, "daemon_stop", grace_seconds=30.0)
+    if termination.terminated:
+        daemon_paths.pid_file.unlink(missing_ok=True)
+        payload = {"success": True, "pid": pid, "message": "stopped"}
+        return CommandResult(0, f"Python {family.kind} daemon stop", "stopped", stdout=json.dumps(payload), stderr=f"Pipeline stopped (PID: {pid})")
+    payload = {"success": False, "pid": pid, "message": "failed to stop"}
+    return CommandResult(1, f"Python {family.kind} daemon stop", "failed", stdout=json.dumps(payload), stderr=f"Failed to stop pipeline (PID: {pid})")
+
+
+def _logs(family: RunnerFamily, daemon_paths: DaemonPaths, legacy_args: tuple[str, ...]) -> CommandResult:
+    options = _parse_log_args(legacy_args)
+    if not daemon_paths.log_file.is_file():
+        message = f"No log file found at {daemon_paths.log_file}\nPipeline has not been started yet"
+        return CommandResult(0, f"Python {family.kind} daemon logs", message, stdout="", stderr=message)
+    if options.follow:
+        return _follow_log(family, daemon_paths.log_file)
+    return CommandResult(0, f"Python {family.kind} daemon logs", "logs", stdout="\n".join(_tail_lines(daemon_paths.log_file, options.lines)))
+
+
+def _parse_start_args(family: RunnerFamily, legacy_args: tuple[str, ...]) -> DaemonStartOptions:
+    list_path = family.plan_path
+    env_overrides = ""
+    mode = ""
+    features_filter = ""
+    critic: bool | None = None
+    help_requested = False
+    positional: list[str] = []
+    index = 0
+    while index < len(legacy_args):
+        arg = legacy_args[index]
+        if arg in {"--help", "-h", "help"}:
+            help_requested = True
+        elif arg == "--env" and index + 1 < len(legacy_args):
+            index += 1
+            env_overrides = legacy_args[index]
+        elif arg == "--mode" and index + 1 < len(legacy_args):
+            index += 1
+            mode = legacy_args[index]
+            if mode not in {"lite", "standard", "full"}:
+                raise ValueError(f"Invalid mode: {mode} (must be lite, standard, or full)")
+        elif arg == "--features" and index + 1 < len(legacy_args):
+            index += 1
+            features_filter = legacy_args[index]
+        elif arg == "--critic":
+            critic = True
+        elif arg == "--no-critic":
+            critic = False
+        else:
+            positional.append(arg)
+        index += 1
+    if positional:
+        list_path = Path(positional[0]).expanduser()
+    return DaemonStartOptions(list_path=list_path, env_overrides=env_overrides, mode=mode, features_filter=features_filter, critic=critic, help_requested=help_requested)
+
+
+def _parse_log_args(legacy_args: tuple[str, ...]) -> DaemonLogOptions:
+    lines = 50
+    follow = False
+    index = 0
+    while index < len(legacy_args):
+        arg = legacy_args[index]
+        if arg in {"--follow", "-f"}:
+            follow = True
+        elif arg in {"--lines", "-n"} and index + 1 < len(legacy_args):
+            index += 1
+            try:
+                lines = max(0, int(legacy_args[index]))
+            except ValueError:
+                lines = 50
+        index += 1
+    return DaemonLogOptions(lines=lines, follow=follow)
+
+
+def _payload_command(family: RunnerFamily, paths, list_path: Path, options: DaemonStartOptions) -> list[str]:
+    command = [
+        sys.executable,
+        str(paths.pipeline_root / "cli.py"),
+        "--project-root",
+        str(paths.project_root),
+        "--pipeline-root",
+        str(paths.pipeline_root),
+        family.kind,
+        "run",
+        str(list_path),
+    ]
+    if family.kind == "feature" and options.features_filter:
+        command.extend(["--features", options.features_filter])
+    if options.mode:
+        command.extend(["--mode", options.mode])
+    if options.critic is True:
+        command.append("--critic")
+    elif options.critic is False:
+        command.append("--no-critic")
+    return command
+
+
+def _daemon_env(options: DaemonStartOptions) -> dict[str, str]:
+    env: dict[str, str] = {}
+    for token in shlex.split(options.env_overrides):
+        if "=" in token:
+            key, value = token.split("=", 1)
+            if key:
+                env[key] = value
+    if options.mode:
+        env["PIPELINE_MODE"] = options.mode
+    if options.critic is not None:
+        env["ENABLE_CRITIC"] = "true" if options.critic else "false"
+    return env
+
+
+def _clean_stale_pid(daemon_paths: DaemonPaths) -> str:
+    if not daemon_paths.pid_file.is_file():
+        return ""
+    pid = _read_pid(daemon_paths.pid_file)
+    if pid is not None and not is_pid_running(pid):
+        daemon_paths.pid_file.unlink(missing_ok=True)
+        return f"Cleaned stale PID file (process {pid} no longer running)"
+    return ""
+
+
+def _read_pid(path: Path) -> int | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = path.read_text(encoding="utf-8").strip()
+        return int(raw) if raw else None
+    except (OSError, ValueError):
+        return None
+
+
+def _write_meta(family: RunnerFamily, path: Path, pid: int, started_at: str, list_path: Path, options: DaemonStartOptions, log_file: Path) -> None:
+    data: dict[str, object] = {
+        "pid": pid,
+        "pipeline_type": family.kind,
+        "started_at": started_at,
+        LIST_META_KEY_BY_KIND[family.kind]: str(list_path),
+        "env_overrides": options.env_overrides,
+        "mode": options.mode,
+        "log_file": str(log_file),
+    }
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    tmp.replace(path)
+
+
+def _read_meta(path: Path) -> dict[str, object]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _progress_summary(family: RunnerFamily, list_path: Path | None) -> dict[str, object]:
+    if list_path is None or not list_path.is_file():
+        return {}
+    try:
+        data = json.loads(list_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    items = data.get(ITEMS_KEY_BY_KIND[family.kind], [])
+    if not isinstance(items, list):
+        items = []
+    counts = {key: 0 for key in PROGRESS_COUNTS_BY_KIND[family.kind]}
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        item_id = str(item.get(ID_KEY_BY_KIND[family.kind]) or "")
+        status = str(item.get("status") or "pending")
+        status_file = family.state_dir / item_id / "status.json"
+        if status_file.is_file():
+            try:
+                status_data = json.loads(status_file.read_text(encoding="utf-8"))
+                status = str(status_data.get("status") or status)
+            except (OSError, json.JSONDecodeError):
+                pass
+        counts[status if status in counts else "pending"] += 1
+    total = len(items)
+    percent = round(counts.get("completed", 0) / total * 100, 1) if total else 0
+    return {"total": total, **counts, "percent": percent}
+
+
+def _write_log_separator(family: RunnerFamily, log_file: Path, list_path: Path, started_at: str, options: DaemonStartOptions) -> None:
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "",
+        "================================================================",
+        f"  {family.kind.title()} Pipeline Daemon Started: {started_at}",
+        f"  {family.kind.title()} list: {list_path}",
+    ]
+    if options.features_filter:
+        lines.append(f"  Features filter: {options.features_filter}")
+    if options.mode:
+        lines.append(f"  Mode: {options.mode}")
+    if options.env_overrides:
+        lines.append(f"  Environment: {options.env_overrides}")
+    lines.extend(["================================================================", ""])
+    with log_file.open("a", encoding="utf-8") as handle:
+        handle.write("\n".join(lines) + "\n")
+
+
+def _rotate_log_if_needed(log_file: Path) -> Path | None:
+    if not log_file.is_file() or log_file.stat().st_size <= LOG_ROTATE_BYTES:
+        return None
+    rotated = log_file.with_name(f"{log_file.name}.{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S')}.bak")
+    log_file.replace(rotated)
+    return rotated
+
+
+def _tail_lines(path: Path, count: int) -> list[str]:
+    if count <= 0 or not path.is_file():
+        return []
+    try:
+        return path.read_text(encoding="utf-8", errors="replace").splitlines()[-count:]
+    except OSError:
+        return []
+
+
+def _follow_log(family: RunnerFamily, log_file: Path) -> CommandResult:
+    try:
+        with log_file.open("r", encoding="utf-8", errors="replace") as handle:
+            handle.seek(0, os.SEEK_END)
+            while True:
+                line = handle.readline()
+                if line:
+                    print(line, end="")
+                else:
+                    time.sleep(0.5)
+    except KeyboardInterrupt:
+        return CommandResult(0, f"Python {family.kind} daemon logs", "follow stopped", stdout="")
+
+
+def _utc_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _start_verify_seconds() -> float:
+    raw = os.environ.get("PRIZMKIT_DAEMON_VERIFY_SECONDS")
+    if raw is None:
+        return START_VERIFY_SECONDS
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return START_VERIFY_SECONDS
+
+
+def _help_text(family: RunnerFamily) -> str:
+    return (
+        f"Usage: prizmkit-runtime daemon {family.kind} <start|stop|status|logs|restart> [options]\n"
+        "Commands preserve .pipeline.pid, pipeline-daemon.log, and .pipeline-meta.json contracts."
+    )