prizmkit 1.1.100 → 1.1.101

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

@@ -0,0 +1,193 @@
+"""Argparse command tree for the canonical PrizmKit Python runtime."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from .commands import CommandResult, handle_diagnostics, handle_runtime_command
+from .compat import UnsupportedPythonVersion, ensure_supported_python
+from .paths import resolve_runtime_paths
+
+DESCRIPTION = (
+    "PrizmKit canonical Python runtime CLI.\n"
+    "Runs pipeline, reset, daemon, recovery, status, and diagnostics commands without shell wrappers."
+)
+
+
+def _add_passthrough_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments forwarded to the selected Python runtime command.",
+    )
+
+
+def _set_handler(parser: argparse.ArgumentParser, group: str, action: str, target: str | None = None) -> None:
+    parser.set_defaults(handler="runtime", group=group, action=action, target=target)
+
+
+def _add_action_subparsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    group: str,
+    actions: Sequence[str],
+) -> None:
+    group_parser = subparsers.add_parser(group, help=f"{group} pipeline commands")
+    action_subparsers = group_parser.add_subparsers(dest="action_name", required=True)
+    for action in actions:
+        action_parser = action_subparsers.add_parser(action, help=f"Run {group} {action}")
+        _add_passthrough_options(action_parser)
+        _set_handler(action_parser, group, action)
+
+
+def _add_reset_subparsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    reset_parser = subparsers.add_parser("reset", help="Explicit reset commands")
+    reset_subparsers = reset_parser.add_subparsers(dest="reset_target", required=True)
+    for target in ("feature", "bugfix", "refactor"):
+        target_parser = reset_subparsers.add_parser(target, help=f"Run {target} reset")
+        _add_passthrough_options(target_parser)
+        _set_handler(target_parser, "reset", "reset", target)
+    describe_parser = reset_subparsers.add_parser("describe", help="Describe reset command boundaries")
+    _set_handler(describe_parser, "reset", "describe")
+
+
+def _add_daemon_subparsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    daemon_parser = subparsers.add_parser("daemon", help="Daemon lifecycle commands")
+    target_subparsers = daemon_parser.add_subparsers(dest="daemon_target", required=True)
+    for target in ("feature", "bugfix", "refactor"):
+        target_parser = target_subparsers.add_parser(target, help=f"{target} daemon commands")
+        action_subparsers = target_parser.add_subparsers(dest="daemon_action", required=True)
+        for action in ("start", "stop", "status", "logs", "restart", "describe"):
+            action_parser = action_subparsers.add_parser(action, help=f"Run daemon {target} {action}")
+            _add_passthrough_options(action_parser)
+            _set_handler(action_parser, "daemon", action, target)
+
+
+def _add_status_subparsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    status_parser = subparsers.add_parser("status", help="Status commands")
+    status_subparsers = status_parser.add_subparsers(dest="status_target", required=True)
+    for target in ("feature", "bugfix", "refactor", "all"):
+        target_parser = status_subparsers.add_parser(target, help=f"Show {target} status")
+        _add_passthrough_options(target_parser)
+        _set_handler(target_parser, "status", "status", target)
+
+
+def _add_diagnostics_subparsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    diagnostics_parser = subparsers.add_parser("diagnostics", help="Python runtime diagnostics")
+    diagnostics_subparsers = diagnostics_parser.add_subparsers(dest="diagnostics_action", required=True)
+    for action in ("paths", "entrypoints", "version"):
+        action_parser = diagnostics_subparsers.add_parser(action, help=f"Show {action} diagnostics")
+        action_parser.set_defaults(handler="diagnostics", action=action)
+
+
+_PIPELINE_GROUPS = {"feature", "bugfix", "refactor", "recovery"}
+_GLOBAL_OPTIONS_WITH_VALUES = {"--project-root", "--pipeline-root"}
+
+
+def _split_passthrough_args(argv: Sequence[str]) -> tuple[list[str], tuple[str, ...]]:
+    """Split parser-owned command tokens from legacy args while preserving exact arg order."""
+    tokens = [str(arg) for arg in argv]
+    prefix: list[str] = []
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in _GLOBAL_OPTIONS_WITH_VALUES:
+            prefix.append(token)
+            index += 1
+            if index < len(tokens):
+                prefix.append(tokens[index])
+                index += 1
+            continue
+        if any(token.startswith(f"{option}=") for option in _GLOBAL_OPTIONS_WITH_VALUES):
+            prefix.append(token)
+            index += 1
+            continue
+        break
+
+    if index >= len(tokens):
+        return tokens, ()
+
+    group = tokens[index]
+    if group in _PIPELINE_GROUPS:
+        required_parts = 2
+    elif group in {"reset", "status", "diagnostics"}:
+        required_parts = 2
+    elif group == "daemon":
+        required_parts = 3
+    else:
+        return tokens, ()
+
+    command_end = min(len(tokens), index + required_parts)
+    prefix.extend(tokens[index:command_end])
+    passthrough = tuple(tokens[command_end:])
+    if group == "diagnostics":
+        return tokens, ()
+    return prefix, passthrough
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the standard-library argparse command tree."""
+    parser = argparse.ArgumentParser(
+        prog="prizmkit-runtime",
+        description=DESCRIPTION,
+    )
+    parser.add_argument(
+        "--project-root",
+        help="Optional project root used for path resolution and command execution.",
+    )
+    parser.add_argument(
+        "--pipeline-root",
+        help="Optional dev-pipeline root used for path resolution and command execution.",
+    )
+    subparsers = parser.add_subparsers(dest="command_group", required=True)
+
+    _add_action_subparsers(subparsers, "feature", ("run", "status", "reset", "unskip", "test-cli", "describe"))
+    _add_action_subparsers(subparsers, "bugfix", ("run", "status", "reset", "unskip", "describe"))
+    _add_action_subparsers(subparsers, "refactor", ("run", "status", "reset", "unskip", "describe"))
+    _add_action_subparsers(subparsers, "recovery", ("run", "detect", "describe"))
+    _add_reset_subparsers(subparsers)
+    _add_daemon_subparsers(subparsers)
+    _add_status_subparsers(subparsers)
+    _add_diagnostics_subparsers(subparsers)
+    return parser
+
+
+def _runtime_paths_from_args(args: argparse.Namespace):
+    return resolve_runtime_paths(pipeline_root=args.pipeline_root, project_root=args.project_root)
+
+
+def _dispatch(args: argparse.Namespace) -> CommandResult:
+    paths = _runtime_paths_from_args(args)
+    if args.handler == "diagnostics":
+        return handle_diagnostics(args.action, paths)
+    return handle_runtime_command(
+        args.group,
+        args.action,
+        target=args.target,
+        paths=paths,
+        legacy_args=tuple(getattr(args, "args", ()) or ()),
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the unified runtime CLI."""
+    try:
+        ensure_supported_python()
+    except UnsupportedPythonVersion as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    parser = build_parser()
+    parse_argv = list(sys.argv[1:] if argv is None else argv)
+    parser_argv, passthrough_args = _split_passthrough_args(parse_argv)
+    args = parser.parse_args(parser_argv)
+    if passthrough_args:
+        args.args = tuple(getattr(args, "args", ()) or ()) + passthrough_args
+    result = _dispatch(args)
+    if result.stderr:
+        print(result.stderr, file=sys.stderr)
+    output = result.render()
+    if output:
+        print(output)
+    return result.exit_code

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

@@ -0,0 +1,313 @@
+"""Command contracts for the canonical PrizmKit Python runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .compat import MIN_PYTHON
+from .interoperability import UTILITY_ENTRYPOINTS, describe_existing_entrypoint
+from .paths import RuntimePaths, resolve_runtime_paths
+
+RUNTIME_STATUS = "python-runtime-canonical"
+CANONICAL_RUNTIME_NOTE = "The Python CLI and prizmkit_runtime modules are the canonical runtime."
+PYTHON_CLI = "dev-pipeline/cli.py"
+
+
+@dataclass(frozen=True)
+class RuntimeCommand:
+    """Unified CLI command mapped to the Python behavior provider."""
+
+    group: str
+    action: str
+    target: str | None
+    current_entrypoint: str | None
+    entrypoint_kind: str | None
+    entrypoint_name: str | None
+    transition_status: str = RUNTIME_STATUS
+    notes: tuple[str, ...] = (CANONICAL_RUNTIME_NOTE,)
+
+    @property
+    def key(self) -> tuple[str, str | None, str]:
+        """Return the stable command registry key."""
+        return (self.group, self.target, self.action)
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    """Result returned by runtime command handlers."""
+
+    exit_code: int
+    title: str
+    message: str
+    details: tuple[str, ...] = ()
+    stdout: str | None = None
+    stderr: str | None = None
+
+    def render(self) -> str:
+        """Render a deterministic human-readable result."""
+        if self.stdout is not None:
+            return self.stdout
+        lines = [self.title, self.message]
+        lines.extend(self.details)
+        return "\n".join(line for line in lines if line)
+
+
+def _runtime_invocation(group: str, action: str, target: str | None = None) -> str:
+    if group == "daemon" and target is not None:
+        return f"python3 {PYTHON_CLI} daemon {target} {action}"
+    if group == "reset" and target is not None and action == "reset":
+        return f"python3 {PYTHON_CLI} reset {target}"
+    if group == "status" and target is not None:
+        return f"python3 {PYTHON_CLI} status {target}"
+    return f"python3 {PYTHON_CLI} {group} {action}"
+
+
+def _command(
+    group: str,
+    action: str,
+    *,
+    target: str | None = None,
+    notes: tuple[str, ...] = (CANONICAL_RUNTIME_NOTE,),
+) -> RuntimeCommand:
+    return RuntimeCommand(
+        group=group,
+        target=target,
+        action=action,
+        current_entrypoint=_runtime_invocation(group, action, target),
+        entrypoint_kind="python-cli",
+        entrypoint_name=group if target is None else f"{group}:{target}",
+        notes=notes,
+    )
+
+
+def _pipeline_commands() -> tuple[RuntimeCommand, ...]:
+    commands: list[RuntimeCommand] = []
+    action_matrix = {
+        "feature": ("run", "status", "reset", "unskip", "test-cli", "describe"),
+        "bugfix": ("run", "status", "reset", "unskip", "describe"),
+        "refactor": ("run", "status", "reset", "unskip", "describe"),
+        "recovery": ("run", "detect", "describe"),
+    }
+    for group, actions in action_matrix.items():
+        for action in actions:
+            commands.append(
+                _command(
+                    group,
+                    action,
+                    notes=(
+                        CANONICAL_RUNTIME_NOTE,
+                        "Foreground and recovery behavior is implemented in Python runtime modules.",
+                    ),
+                )
+            )
+    return tuple(commands)
+
+
+def _reset_commands() -> tuple[RuntimeCommand, ...]:
+    commands = [
+        _command(
+            "reset",
+            "reset",
+            target=target,
+            notes=(
+                CANONICAL_RUNTIME_NOTE,
+                "Reset actions are explicit manual operations and are not part of automatic continuation recovery.",
+            ),
+        )
+        for target in ("feature", "bugfix", "refactor")
+    ]
+    commands.append(
+        _command(
+            "reset",
+            "describe",
+            notes=(CANONICAL_RUNTIME_NOTE, "Lists destructive Python reset commands without running them."),
+        )
+    )
+    return tuple(commands)
+
+
+def _daemon_commands() -> tuple[RuntimeCommand, ...]:
+    commands: list[RuntimeCommand] = []
+    for target in ("feature", "bugfix", "refactor"):
+        for action in ("start", "stop", "status", "logs", "restart", "describe"):
+            commands.append(
+                _command(
+                    "daemon",
+                    action,
+                    target=target,
+                    notes=(
+                        CANONICAL_RUNTIME_NOTE,
+                        "Daemon lifecycle behavior is implemented by the Python daemon runtime.",
+                    ),
+                )
+            )
+    return tuple(commands)
+
+
+def _status_commands() -> tuple[RuntimeCommand, ...]:
+    commands = [
+        _command(
+            "status",
+            "status",
+            target=target,
+            notes=(CANONICAL_RUNTIME_NOTE, "Status is resolved by the Python foreground runtime."),
+        )
+        for target in ("feature", "bugfix", "refactor")
+    ]
+    commands.append(
+        _command(
+            "status",
+            "status",
+            target="all",
+            notes=(CANONICAL_RUNTIME_NOTE, "Aggregated status is represented at the Python CLI boundary."),
+        )
+    )
+    return tuple(commands)
+
+
+def _diagnostic_commands() -> tuple[RuntimeCommand, ...]:
+    return tuple(
+        _command(
+            "diagnostics",
+            action,
+            notes=(CANONICAL_RUNTIME_NOTE, "Diagnostic commands are implemented in the Python runtime."),
+        )
+        for action in ("paths", "entrypoints", "version")
+    )
+
+
+COMMAND_REGISTRY: tuple[RuntimeCommand, ...] = (
+    *_pipeline_commands(),
+    *_reset_commands(),
+    *_daemon_commands(),
+    *_status_commands(),
+    *_diagnostic_commands(),
+)
+
+
+def list_runtime_commands() -> tuple[RuntimeCommand, ...]:
+    """Return the unified CLI command inventory."""
+    return COMMAND_REGISTRY
+
+
+def find_runtime_command(group: str, action: str, target: str | None = None) -> RuntimeCommand:
+    """Find one command contract by group/action/target."""
+    for command in COMMAND_REGISTRY:
+        if command.group == group and command.action == action and command.target == target:
+            return command
+    target_text = "" if target is None else f" target={target}"
+    raise KeyError(f"Unknown runtime command: group={group}{target_text} action={action}")
+
+
+def describe_command(command: RuntimeCommand, paths: RuntimePaths | None = None) -> CommandResult:
+    """Describe a Python runtime command contract without running behavior."""
+    _ = paths or resolve_runtime_paths()
+    details = [
+        f"command: {command.group} {command.target or ''} {command.action}".replace("  ", " ").strip(),
+        f"runtime status: {command.transition_status}",
+        f"current entrypoint: {command.current_entrypoint or PYTHON_CLI}",
+    ]
+    details.extend(f"note: {note}" for note in command.notes)
+    return CommandResult(
+        exit_code=0,
+        title="Python runtime command contract",
+        message="This command is available in the canonical PrizmKit Python runtime.",
+        details=tuple(details),
+    )
+
+
+def handle_runtime_command(
+    group: str,
+    action: str,
+    *,
+    target: str | None = None,
+    paths: RuntimePaths | None = None,
+    legacy_args: tuple[str, ...] = (),
+) -> CommandResult:
+    """Handle runtime commands, dispatching ported Python runtime behavior where available."""
+    runtime_paths = paths or resolve_runtime_paths()
+    if group in {"feature", "bugfix", "refactor"} and action in {"run", "status", "unskip", "test-cli"}:
+        from .runners import run_pipeline_command
+
+        return run_pipeline_command(group, action, legacy_args, runtime_paths)
+    if group == "status" and target in {"feature", "bugfix", "refactor"} and action == "status":
+        from .runners import run_pipeline_command
+
+        return run_pipeline_command(target, action, legacy_args, runtime_paths)
+    if group == "recovery" and action in {"run", "detect"}:
+        from .runners import run_recovery_command
+
+        return run_recovery_command(action, legacy_args, runtime_paths)
+    if group == "reset" and target in {"feature", "bugfix", "refactor"} and action == "reset":
+        from .reset import run_reset_command
+
+        return run_reset_command(target, legacy_args, runtime_paths)
+    if group == "daemon" and target in {"feature", "bugfix", "refactor"} and action in {"start", "stop", "status", "logs", "restart", "describe"}:
+        from .daemon import run_daemon_command
+
+        try:
+            return run_daemon_command(target, action, legacy_args, runtime_paths)
+        except ValueError as exc:
+            return CommandResult(1, f"Python {target} daemon", str(exc), stdout="", stderr=str(exc))
+    command = find_runtime_command(group, action, target)
+    return describe_command(command, runtime_paths)
+
+
+def diagnostics_paths(paths: RuntimePaths | None = None) -> CommandResult:
+    """Return path diagnostics for the current runtime layout."""
+    runtime_paths = paths or resolve_runtime_paths()
+    details = (
+        f"layout: {runtime_paths.layout}",
+        f"pipeline_root: {runtime_paths.pipeline_root}",
+        f"project_root: {runtime_paths.project_root}",
+        f"prizmkit_dir: {runtime_paths.prizmkit_dir}",
+        f"plans_dir: {runtime_paths.plans_dir}",
+        f"state_dir: {runtime_paths.state_dir}",
+        f"logs_dir: {runtime_paths.logs_dir}",
+        f"specs_dir: {runtime_paths.specs_dir}",
+    )
+    return CommandResult(
+        exit_code=0,
+        title="Runtime path diagnostics",
+        message="Resolved with pathlib; no shell-specific quoting is required.",
+        details=details,
+    )
+
+
+def diagnostics_entrypoints(paths: RuntimePaths | None = None) -> CommandResult:
+    """Return an inventory of canonical Python runtime and utility entrypoints."""
+    runtime_paths = paths or resolve_runtime_paths()
+    details: list[str] = [
+        f"runtime:cli: {runtime_paths.pipeline_root / 'cli.py'}",
+        f"runtime:module: {runtime_paths.pipeline_root / 'prizmkit_runtime'}",
+    ]
+    for name, relative_path in sorted(UTILITY_ENTRYPOINTS.items()):
+        invocation = describe_existing_entrypoint("utility", name, paths=runtime_paths)
+        details.append(f"utility:{name}: {invocation.script_path if invocation else runtime_paths.pipeline_root / relative_path}")
+    return CommandResult(
+        exit_code=0,
+        title="Python runtime entrypoint inventory",
+        message="Inventory for canonical Python runtime and utility scripts.",
+        details=tuple(details),
+    )
+
+
+def diagnostics_version() -> CommandResult:
+    """Return runtime version contract diagnostics."""
+    return CommandResult(
+        exit_code=0,
+        title="Python runtime version contract",
+        message="Python 3.10+ is required for the canonical PrizmKit Python runtime.",
+        details=(f"minimum_python: {MIN_PYTHON[0]}.{MIN_PYTHON[1]}",),
+    )
+
+
+def handle_diagnostics(action: str, paths: RuntimePaths | None = None) -> CommandResult:
+    """Dispatch diagnostics actions."""
+    if action == "paths":
+        return diagnostics_paths(paths)
+    if action == "entrypoints":
+        return diagnostics_entrypoints(paths)
+    if action == "version":
+        return diagnostics_version()
+    raise KeyError(f"Unknown diagnostics action: {action}")

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

@@ -0,0 +1,32 @@
+"""Python version compatibility guard for the unified runtime."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+MIN_PYTHON = (3, 10)
+
+
+class UnsupportedPythonVersion(RuntimeError):
+    """Raised when the unified runtime starts on an unsupported Python version."""
+
+
+def _major_minor(version_info: Sequence[int] | object) -> tuple[int, int]:
+    """Extract a major/minor tuple from sys.version_info or a tuple-like value."""
+    major = getattr(version_info, "major", None)
+    minor = getattr(version_info, "minor", None)
+    if major is not None and minor is not None:
+        return int(major), int(minor)
+    return int(version_info[0]), int(version_info[1])  # type: ignore[index]
+
+
+def ensure_supported_python(version_info: Sequence[int] | object | None = None) -> None:
+    """Validate that the current interpreter satisfies the Python 3.10+ contract."""
+    candidate = sys.version_info if version_info is None else version_info
+    major, minor = _major_minor(candidate)
+    if (major, minor) < MIN_PYTHON:
+        raise UnsupportedPythonVersion(
+            "PrizmKit unified Python CLI requires Python 3.10+; "
+            f"detected Python {major}.{minor}."
+        )