prizmkit 1.1.153 → 1.1.155

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

@@ -9,136 +9,228 @@ 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
-from .runtime_helper import render_result, run_helper_command
 
 DESCRIPTION = (
     "PrizmKit canonical Python runtime CLI.\n"
-    "Runs pipeline, reset, daemon, recovery, status, and diagnostics commands without shell wrappers."
+    "Runs operation-first pipeline, status, reset, daemon, diagnostics, and helper commands."
 )
 
+_FAMILIES = ("feature", "bugfix", "refactor")
+_GLOBAL_OPTIONS_WITH_VALUES = {"--project-root", "--pipeline-root"}
+_LEAF_OPTIONS_WITH_VALUES = {
+    "--env",
+    "--features",
+    "--lines",
+    "-n",
+    "--max-retries",
+    "--max-infra-retries",
+    "--resume-phase",
+}
+
+
+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_passthrough_options(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument(
-        "args",
-        nargs=argparse.REMAINDER,
-        help="Arguments forwarded to the selected Python runtime command.",
-    )
+
+def _non_negative_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("must be non-negative")
+    return parsed
+
+
+def _add_runner_arguments(parser: argparse.ArgumentParser, family: str) -> None:
+    parser.add_argument("operand", nargs="?", help="Optional task ID or family plan path.")
+    parser.add_argument("second_operand", nargs="?", help="Optional family plan path or task ID.")
+    if family == "feature":
+        parser.add_argument("--features", help="Feature ID, range, or comma-separated selection.")
+    parser.add_argument("--max-retries", type=_non_negative_int)
+    parser.add_argument("--max-infra-retries", type=_non_negative_int)
+    parser.add_argument("--resume-phase")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--clean", action="store_true")
+    parser.add_argument("--no-reset", action="store_true")
+
+
+def _add_run_subparsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    run_parser = subparsers.add_parser("run", help="Run a foreground pipeline family")
+    family_subparsers = run_parser.add_subparsers(dest="run_family", required=True)
+    for family in _FAMILIES:
+        family_parser = family_subparsers.add_parser(family, help=f"Run the {family} pipeline")
+        _add_runner_arguments(family_parser, family)
+        _set_handler(family_parser, "run", "run", family)
 
 
-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_status_subparsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    status_parser = subparsers.add_parser("status", help="Inspect pipeline task state")
+    target_subparsers = status_parser.add_subparsers(dest="status_target", required=True)
+    for family in _FAMILIES:
+        family_parser = target_subparsers.add_parser(family, help=f"Show {family} status")
+        _add_runner_arguments(family_parser, family)
+        _set_handler(family_parser, "status", "status", family)
+    all_parser = target_subparsers.add_parser(
+        "all",
+        help="Show read-only status for every configured family",
+    )
+    _set_handler(all_parser, "status", "status", "all")
 
 
-def _add_action_subparsers(
+def _add_reset_subparsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    reset_parser = subparsers.add_parser("reset", help="Apply one explicit reset mode")
+    family_subparsers = reset_parser.add_subparsers(dest="reset_family", required=True)
+    for family in _FAMILIES:
+        family_parser = family_subparsers.add_parser(family, help=f"Reset {family} task state")
+        family_parser.add_argument("operand", nargs="?", help="Task ID, range, or family plan path.")
+        family_parser.add_argument("second_operand", nargs="?", help="Optional family plan path.")
+        family_parser.add_argument("--state-only", action="store_true")
+        family_parser.add_argument("--fresh-checkout", action="store_true")
+        family_parser.add_argument("--clean", action="store_true")
+        family_parser.add_argument("--preserve-runtime", action="store_true")
+        family_parser.add_argument("--all", action="store_true")
+        family_parser.add_argument("--auto-skipped", action="store_true")
+        family_parser.add_argument("--failed", action="store_true")
+        family_parser.add_argument("--stalled", action="store_true")
+        _set_handler(family_parser, "reset", "reset", family)
+
+
+def _add_daemon_start_arguments(parser: argparse.ArgumentParser, family: str) -> None:
+    parser.add_argument("list_path", nargs="?", help="Optional family plan path.")
+    parser.add_argument("--env", help="Quoted KEY=VALUE daemon environment overrides.")
+    if family == "feature":
+        parser.add_argument("--features", help="Feature ID, range, or comma-separated selection.")
+
+
+def _add_daemon_subparsers(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    daemon_parser = subparsers.add_parser("daemon", help="Manage background pipeline processes")
+    family_subparsers = daemon_parser.add_subparsers(dest="daemon_family", required=True)
+    for family in _FAMILIES:
+        family_parser = family_subparsers.add_parser(family, help=f"Manage the {family} daemon")
+        action_subparsers = family_parser.add_subparsers(dest="daemon_action", required=True)
+        for action in ("start", "stop", "status", "logs", "restart"):
+            action_parser = action_subparsers.add_parser(action, help=f"{action.title()} the {family} daemon")
+            if action in {"start", "restart"}:
+                _add_daemon_start_arguments(action_parser, family)
+            elif action == "logs":
+                action_parser.add_argument("--lines", "-n", type=_non_negative_int, default=50)
+                action_parser.add_argument("--follow", "-f", action="store_true")
+            _set_handler(action_parser, "daemon", action, family)
+
+
+def _add_diagnostics_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")
+    diagnostics_parser = subparsers.add_parser("diagnostics", help="Inspect Python runtime configuration")
+    action_subparsers = diagnostics_parser.add_subparsers(dest="diagnostics_action", required=True)
+    for action in ("paths", "entrypoints", "version", "ai-cli"):
+        action_parser = action_subparsers.add_parser(action, help=f"Show {action} diagnostics")
         action_parser.set_defaults(handler="diagnostics", action=action)
 
 
-def _add_helper_subparser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    helper_parser = subparsers.add_parser("helper", help="Cross-platform prompt runtime helper commands")
+def _add_helper_subparser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    helper_parser = subparsers.add_parser("helper", help="Run low-level cross-platform helper commands")
+    helper_parser.add_argument("helper_command", nargs="?", help="Helper command namespace.")
     helper_parser.add_argument(
-        "args",
+        "helper_args",
         nargs=argparse.REMAINDER,
         help="Arguments forwarded to prizmkit-runtime-helper.",
     )
-    helper_parser.set_defaults(handler="helper", group="helper", action="run", target=None)
-
-
-_PIPELINE_GROUPS = {"feature", "bugfix", "refactor", "recovery"}
-_GLOBAL_OPTIONS_WITH_VALUES = {"--project-root", "--pipeline-root"}
+    _set_handler(helper_parser, "helper", "run")
 
 
-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."""
+def _parser_argv(argv: Sequence[str]) -> list[str]:
+    """Normalize interspersed leaf operands for argparse validation only."""
     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
+            index += 2
             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]
+    depth = {"run": 2, "status": 2, "reset": 2, "daemon": 3}.get(group)
+    if depth is None or len(tokens) <= index + depth:
+        return tokens
+
+    command_end = index + depth
+    operands: list[str] = []
+    options: list[str] = []
+    tail = tokens[command_end:]
+    tail_index = 0
+    while tail_index < len(tail):
+        token = tail[tail_index]
+        option_name = token.split("=", 1)[0]
+        if token.startswith("-"):
+            options.append(token)
+            if (
+                "=" not in token
+                and option_name in _LEAF_OPTIONS_WITH_VALUES
+                and tail_index + 1 < len(tail)
+            ):
+                tail_index += 1
+                options.append(tail[tail_index])
+        else:
+            operands.append(token)
+        tail_index += 1
+    return [*tokens[:command_end], *operands, *options]
+
+
+def _runtime_action_args(argv: Sequence[str]) -> tuple[str, ...]:
+    """Return the original validated leaf arguments in their exact order."""
+    tokens = [str(arg) for arg in argv]
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in _GLOBAL_OPTIONS_WITH_VALUES:
+            index += 2
+            continue
+        if any(token.startswith(f"{option}=") for option in _GLOBAL_OPTIONS_WITH_VALUES):
+            index += 1
+            continue
+        break
     if index >= len(tokens):
-        return tokens, ()
+        return ()
 
     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
+    depth = {
+        "run": 2,
+        "status": 2,
+        "reset": 2,
+        "daemon": 3,
+        "diagnostics": 2,
+        "helper": 1,
+    }.get(group)
+    if depth is None:
+        return ()
+    return tuple(tokens[index + depth :])
 
 
 def build_parser() -> argparse.ArgumentParser:
-    """Build the standard-library argparse command tree."""
+    """Build the standard-library operation-first argparse command tree."""
     parser = argparse.ArgumentParser(
         prog="prizmkit-runtime",
         description=DESCRIPTION,
@@ -154,13 +246,10 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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_run_subparsers(subparsers)
+    _add_status_subparsers(subparsers)
     _add_reset_subparsers(subparsers)
     _add_daemon_subparsers(subparsers)
-    _add_status_subparsers(subparsers)
     _add_diagnostics_subparsers(subparsers)
     _add_helper_subparser(subparsers)
     return parser
@@ -174,14 +263,6 @@ def _dispatch(args: argparse.Namespace) -> CommandResult:
     paths = _runtime_paths_from_args(args)
     if args.handler == "diagnostics":
         return handle_diagnostics(args.action, paths)
-    if args.handler == "helper":
-        helper_result = run_helper_command(tuple(getattr(args, "args", ()) or ()))
-        return CommandResult(
-            helper_result.exit_code,
-            "Python runtime helper",
-            "Cross-platform prompt runtime helper result.",
-            stdout=render_result(helper_result, json_output="--json" in tuple(getattr(args, "args", ()) or ())),
-        )
     return handle_runtime_command(
         args.group,
         args.action,
@@ -192,7 +273,7 @@ def _dispatch(args: argparse.Namespace) -> CommandResult:
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    """Run the unified runtime CLI."""
+    """Run the canonical operation-first runtime CLI."""
     try:
         ensure_supported_python()
     except UnsupportedPythonVersion as exc:
@@ -201,10 +282,8 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     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
+    args = parser.parse_args(_parser_argv(parse_argv))
+    args.args = _runtime_action_args(parse_argv)
     result = _dispatch(args)
     if result.stderr:
         print(result.stderr, file=sys.stderr)