pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/cli/app_commands.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager, redirect_stdout
+import inspect
+import json
+import sys
+from typing import Any
+
+from pz_core.assembly.cli import AppCliCommand
+from pz_core.cli_options import add_cli_option, resolve_program_name
+from pz_core.core.extensions import CliInvocationContext, CliToolSpec
+from pz_core.runtime.errors import PzError, as_pz_error
+from pz_core.runtime import (
+    RuntimePlan,
+    build_worker_status,
+    compile_runtime_plan,
+    create_application_runtime_from_plan,
+    create_worker_runtime,
+    run_worker_entry,
+)
+from pz_core.runtime.cli._args import PzArgumentParser, json_output_requested, normalize_cli_argv
+
+
+def _read_cli_identifier(raw: object, *, field_name: str, action: str) -> str:
+    if not isinstance(raw, str) or not raw.strip():
+        raise PzError(
+            code="PZ_APP_CLI_IDENTIFIER_INVALID",
+            message=f"{field_name} must be a non-empty string.",
+            stage="cli",
+            owner="runtime.cli",
+            action=action,
+        )
+    return raw.strip()
+
+
+def discover_app_cli_commands(plan: RuntimePlan) -> tuple[AppCliCommand, ...]:
+    return plan.cli_manifest.commands
+
+
+def _find_command(plan: RuntimePlan, app_id: str, tool_name: str) -> AppCliCommand:
+    for command in discover_app_cli_commands(plan):
+        if command.app_id == app_id and command.tool_name == tool_name:
+            return command
+    raise PzError(
+        code="PZ_APP_CLI_COMMAND_NOT_FOUND",
+        message=f"Unknown app CLI command: {app_id} {tool_name}",
+        stage="cli",
+        owner=app_id,
+        action="dispatch_app_cli",
+    )
+
+
+@contextmanager
+def _project_import_context(plan: RuntimePlan):
+    import_roots = [str(plan.project.project_dir.resolve())]
+    for source in plan.resource_manifest.sources:
+        candidate = str(source.package_root.parent.resolve())
+        if candidate not in import_roots:
+            import_roots.append(candidate)
+    inserted: list[str] = []
+    for root in reversed(import_roots):
+        if root in sys.path:
+            continue
+        sys.path.insert(0, root)
+        inserted.append(root)
+    try:
+        yield
+    finally:
+        for root in inserted:
+            try:
+                sys.path.remove(root)
+            except ValueError:
+                pass
+
+
+def _invoke_tool_run(spec: CliToolSpec, *, ctx: CliInvocationContext) -> int:
+    try:
+        result = spec.tool.run(ctx)
+    except SystemExit as exc:
+        code = exc.code
+        if code is None:
+            return 0
+        if isinstance(code, int):
+            return code
+        return 1
+    if inspect.isawaitable(result):
+        result = asyncio.run(result)
+    if isinstance(result, int):
+        return result
+    return 0
+
+
+def _tool_worker_entry(spec: CliToolSpec) -> Any:
+    entry = getattr(spec.tool, "worker_entry", None)
+    if entry is None:
+        return None
+    if not callable(entry):
+        raise PzError(
+            code="PZ_WORKER_CLI_ENTRY_INVALID",
+            message=f"Worker CLI tool '{spec.id}' exposes non-callable worker_entry.",
+            stage="worker",
+            owner=spec.owner_app,
+            action="dispatch_worker_cli",
+        )
+    return entry
+
+
+def _dispatch_worker_cli(
+    *,
+    app_id: str,
+    tool_name: str,
+    spec: CliToolSpec,
+    argv: list[str],
+    plan: RuntimePlan,
+    json_output: bool = False,
+) -> int:
+    entry = _tool_worker_entry(spec)
+    if entry is None:
+        tool_argv = list(argv)
+        if json_output and not json_output_requested(tool_argv):
+            tool_argv.insert(0, "--json")
+        parser = PzArgumentParser(
+            prog=f"{resolve_program_name()} {app_id} {tool_name}",
+            description=spec.summary or f"Run {app_id} {tool_name}.",
+            add_help=True,
+            error_code="PZ_APP_CLI_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=app_id,
+            error_action="dispatch_app_cli",
+        )
+        spec.tool.configure(parser)
+        try:
+            ns, remainder = parser.parse_known_args(tool_argv)
+        except SystemExit as exc:
+            code = exc.code
+            return code if isinstance(code, int) else 1
+        ctx = CliInvocationContext(
+            project=plan.project,
+            args=ns,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+            plan=plan,
+            app_id=app_id,
+            tool_name=tool_name,
+            argv=tuple(tool_argv),
+            remainder=tuple(remainder),
+        )
+        return _invoke_tool_run(spec, ctx=ctx)
+
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} {app_id} {tool_name}",
+        description="Dispatch a worker CLI discovered from <app>/cli/<tool>.py.",
+        add_help=True,
+        error_code="PZ_WORKER_CLI_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner=app_id,
+        error_action="dispatch_worker_cli",
+    )
+    add_cli_option(parser, "--once", action="store_true", dest="once")
+    add_cli_option(parser, "--status", action="store_true", dest="status")
+    add_cli_option(parser, "--replica-slot", type=int, dest="replica_slot")
+    add_cli_option(parser, "--concurrency", type=int, dest="concurrency")
+    add_cli_option(parser, "--poll-interval", type=float, dest="poll_interval")
+    add_cli_option(parser, "--shutdown-timeout", type=float, dest="shutdown_timeout")
+    spec.tool.configure(parser)
+    try:
+        ns, remainder = parser.parse_known_args(argv)
+    except SystemExit as exc:
+        code = exc.code
+        return code if isinstance(code, int) else 1
+    if ns.status:
+        runtime = create_worker_runtime(
+            project_dir=plan.project.project_dir,
+            app_id=app_id,
+            tool_name=tool_name,
+            replica_slot=ns.replica_slot,
+            once=ns.once,
+            concurrency=ns.concurrency,
+            poll_interval_seconds=ns.poll_interval,
+            shutdown_timeout_seconds=ns.shutdown_timeout,
+        )
+        payload = build_worker_status(runtime)
+        print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+        return 0
+    return run_worker_entry(
+        entry,
+        argv=remainder,
+        project_dir=plan.project.project_dir,
+        app_id=app_id,
+        tool_name=tool_name,
+        replica_slot=ns.replica_slot,
+        once=ns.once,
+        concurrency=ns.concurrency,
+        poll_interval_seconds=ns.poll_interval,
+        shutdown_timeout_seconds=ns.shutdown_timeout,
+    )
+
+
+def _dispatch_app_cli_with_runtime(
+    *,
+    app_id: str,
+    tool_name: str,
+    spec: CliToolSpec,
+    argv: list[str],
+    plan: RuntimePlan,
+    json_output: bool = False,
+) -> int:
+    entry = _tool_worker_entry(spec)
+    if entry is not None:
+        return _dispatch_worker_cli(
+            app_id=app_id,
+            tool_name=tool_name,
+            spec=spec,
+            argv=argv,
+            plan=plan,
+            json_output=json_output,
+        )
+
+    if json_output:
+        with redirect_stdout(sys.stderr):
+            runtime = create_application_runtime_from_plan(plan, compile_http_app=False)
+            started = runtime.activate()
+    else:
+        runtime = create_application_runtime_from_plan(plan, compile_http_app=False)
+        started = runtime.activate()
+    try:
+        return _dispatch_worker_cli(
+            app_id=app_id,
+            tool_name=tool_name,
+            spec=spec,
+            argv=argv,
+            plan=started.plan,
+            json_output=json_output,
+        )
+    finally:
+        if json_output:
+            with redirect_stdout(sys.stderr):
+                started.shutdown()
+        else:
+            started.shutdown()
+
+
+def _json_error(error: PzError) -> str:
+    payload = error.to_dict()
+    payload["status"] = "error"
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True)
+
+
+def _write_error(error: PzError, *, json_output: bool) -> None:
+    if json_output:
+        sys.stdout.write(_json_error(error) + "\n")
+        return
+    sys.stderr.write(str(error) + "\n")
+
+
+def _is_help_token(value: object) -> bool:
+    return isinstance(value, str) and value.strip().lower() in {"-h", "--help", "help"}
+
+
+def build_list_payload(plan: RuntimePlan) -> dict[str, Any]:
+    commands = discover_app_cli_commands(plan)
+    return {
+        "status": "ok",
+        "code": "PZ_LIST_OK",
+        "stage": "cli",
+        "owner": "runtime.cli",
+        "action": "list",
+        "installed_apps": [
+            {
+                "app_id": app.app_id,
+                "module_path": app.module_path,
+                "entrypoint": app.entrypoint,
+                "required_pz": app.required_pz,
+            }
+            for app in plan.app_registry.apps
+        ],
+        "app_cli_commands": [
+            {
+                "app_id": command.app_id,
+                "tool_name": command.tool_name,
+                "import_path": command.import_path,
+            }
+            for command in commands
+        ],
+    }
+
+
+def list_main(argv: list[str] | None = None) -> int:
+    raw_argv = list(argv) if argv is not None else None
+    json_output = json_output_requested(raw_argv)
+    try:
+        argv = normalize_cli_argv(
+            raw_argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="runtime.cli",
+            action="list",
+        )
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_LIST_FAILED",
+            stage="cli",
+            owner="runtime.cli",
+            action="list",
+        )
+        _write_error(error, json_output=json_output)
+        return 1
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} list",
+        description="List installed apps and discovered app CLI tools.",
+        error_code="PZ_LIST_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="runtime.cli",
+        error_action="list",
+    )
+    add_cli_option(parser, "--json", action="store_true", dest="json_output")
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    ns = None
+    try:
+        ns = parser.parse_args(argv)
+        plan = compile_runtime_plan(project_dir=ns.project_dir)
+        payload = build_list_payload(plan)
+        if ns.json_output:
+            print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+        else:
+            print(f"installed_apps={len(payload['installed_apps'])}")
+            for item in payload["installed_apps"]:
+                print(f"app {item['app_id']} -> {item['module_path']}")
+            for item in payload["app_cli_commands"]:
+                print(f"cli {item['app_id']} {item['tool_name']}")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_LIST_FAILED",
+            stage="cli",
+            owner="runtime.cli",
+            action="list",
+        )
+        _write_error(error, json_output=ns.json_output if ns is not None else json_output)
+        return 1
+
+
+def dispatch_app_cli(app_id: str, argv: list[str] | None = None) -> int:
+    try:
+        app_id = _read_cli_identifier(app_id, field_name="app_id", action="dispatch_app_cli")
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_APP_CLI_FAILED",
+            stage="cli",
+            owner="runtime.cli",
+            action="dispatch_app_cli",
+        )
+        _write_error(error, json_output=json_output_requested(list(argv) if argv is not None else None))
+        return 1
+    raw_argv = list(argv) if argv is not None else None
+    json_output = json_output_requested(raw_argv)
+    try:
+        argv = normalize_cli_argv(
+            raw_argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=app_id,
+            action="dispatch_app_cli",
+        )
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_APP_CLI_FAILED",
+            stage="cli",
+            owner=app_id,
+            action="dispatch_app_cli",
+        )
+        _write_error(error, json_output=json_output)
+        return 1
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} {app_id}",
+        description="Dispatch an app CLI tool discovered from <app>/cli/<tool>.py.",
+        add_help=False,
+        error_code="PZ_APP_CLI_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner=app_id,
+        error_action="dispatch_app_cli",
+    )
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    add_cli_option(parser, "--json", action="store_true", dest="json_output")
+    parser.add_argument("tool")
+    ns = None
+    try:
+        if not argv or _is_help_token(argv[0]):
+            parser.print_help()
+            return 0
+        ns, remainder = parser.parse_known_args(argv)
+        plan = compile_runtime_plan(project_dir=ns.project_dir)
+        with _project_import_context(plan):
+            command = _find_command(plan, app_id=app_id, tool_name=ns.tool)
+            return _dispatch_app_cli_with_runtime(
+                app_id=app_id,
+                tool_name=ns.tool,
+                spec=command.spec,
+                argv=remainder,
+                plan=plan,
+                json_output=bool(getattr(ns, "json_output", False)),
+            )
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_APP_CLI_FAILED",
+            stage="cli",
+            owner=app_id,
+            action="dispatch_app_cli",
+        )
+        _write_error(error, json_output=ns.json_output if ns is not None else json_output)
+        return 1

pz_core/runtime/cli/check.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from importlib import import_module
+from pathlib import Path
+
+from pz_core.assembly.diagnostics import (
+    CheckItem,
+    CheckReport,
+    build_check_report,
+    build_dev_source_check_items,
+    build_source_preflight_report,
+    extend_check_report,
+    has_blocking_dev_source_failures,
+)
+from pz_core.cli_options import add_cli_option, resolve_program_name
+from pz_core.authoring.ide_projection import build_ide_projection_check_items
+from pz_core.runtime.errors import as_pz_error
+from pz_core.runtime import RuntimePlan, compile_runtime_plan
+from pz_core.runtime.cli._args import (
+    PzArgumentParser,
+    json_output_requested,
+    normalize_cli_argv,
+)
+
+
+def run_check(*, project_dir: str | None = None) -> CheckReport:
+    source_project_dir = (
+        Path(project_dir or os.getenv("PZ_PROJECT_DIR") or Path.cwd())
+        .expanduser()
+        .resolve(strict=False)
+    )
+    source_checks = build_dev_source_check_items(source_project_dir)
+    if has_blocking_dev_source_failures(source_checks):
+        return build_source_preflight_report(source_checks)
+    ide_checks = build_ide_projection_check_items(source_project_dir)
+    plan: RuntimePlan = compile_runtime_plan(project_dir=project_dir)
+    report = build_check_report(plan)
+    report = extend_check_report(report, source_checks)
+    report = extend_check_report(report, ide_checks)
+    report = extend_check_report(report, _load_authoring_check_items(plan))
+    return _merge_external_check_report(report, plan=plan)
+
+
+def _check_code_from_task(task: str) -> str:
+    normalized = "".join(
+        ch if ch.isalnum() else "_" for ch in str(task or "").strip().upper()
+    ).strip("_")
+    return f"PZ_CHECK_{normalized or 'UNKNOWN'}"
+
+
+def _load_app_check_items(plan: RuntimePlan) -> tuple[CheckItem, ...]:
+    items: list[CheckItem] = []
+    apps = tuple(getattr(getattr(plan, "app_registry", None), "apps", ()) or ())
+    for app in apps:
+        app_id = str(getattr(app, "app_id", "") or "").strip()
+        module_path = str(getattr(app, "module_path", "") or "").strip()
+        if not app_id or not module_path:
+            continue
+        public_module_path = f"{module_path}.public"
+        try:
+            public_mod = import_module(public_module_path)
+        except ModuleNotFoundError as exc:
+            if exc.name in {module_path, public_module_path}:
+                continue
+            raise
+        get_facade = getattr(public_mod, "get_check_facade", None)
+        if not callable(get_facade):
+            continue
+        try:
+            facade = get_facade()
+            report = facade.run_blocking(project_dir=str(plan.project.project_dir))
+        except Exception as exc:
+            items.append(
+                CheckItem(
+                    severity="warning",
+                    code="PZ_CHECK_APP_INTEGRATION_FAILED",
+                    owner="runtime.check",
+                    scope=app_id,
+                    message=f"Failed to run app check facade for '{app_id}': {exc}",
+                    ok=False,
+                )
+            )
+            continue
+        for result in getattr(report, "results", ()):
+            items.append(
+                CheckItem(
+                    severity="info"
+                    if result.status in {"passed", "skipped", "disabled"}
+                    else "warning",
+                    code=_check_code_from_task(result.task),
+                    owner="runtime.check",
+                    scope=app_id,
+                    message=result.summary,
+                    ok=result.status in {"passed", "skipped", "disabled"},
+                )
+            )
+    return tuple(items)
+
+
+def _load_external_check_items(plan: RuntimePlan) -> tuple[CheckItem, ...]:
+    try:
+        return _load_app_check_items(plan)
+    except Exception as exc:
+        return (
+            CheckItem(
+                severity="warning",
+                code="PZ_CHECK_EXTERNAL_INTEGRATION_FAILED",
+                owner="runtime.check",
+                scope="external",
+                message=f"Failed to run external app checks: {exc}",
+                ok=False,
+            ),
+        )
+
+
+def _load_authoring_check_items(plan: RuntimePlan) -> tuple[CheckItem, ...]:
+    from pz_core.authoring.project_settings_checks import (
+        build_settings_update_check_items,
+    )
+
+    return build_settings_update_check_items(plan.project.project_dir)
+
+
+def _merge_external_check_report(
+    report: CheckReport, *, plan: RuntimePlan
+) -> CheckReport:
+    extra_checks = _load_external_check_items(plan)
+    return extend_check_report(report, extra_checks)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} check",
+        description="Compile RuntimePlan and run system checks.",
+        error_code="PZ_CHECK_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="runtime.check",
+        error_action="parse_args",
+    )
+    add_cli_option(parser, "--json", action="store_true", dest="json_output")
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    return parser
+
+
+def _print_human_report(report: CheckReport) -> None:
+    print(f"status={report.status} code={report.code}")
+    print(f"installed_apps={len(report.installed_apps)}")
+    for item in report.checks:
+        state = "OK" if item.ok else "FAIL"
+        print(f"{state} {item.code} {item.scope} {item.message}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw_argv = list(argv) if argv is not None else None
+    json_output = json_output_requested(raw_argv)
+    try:
+        argv = normalize_cli_argv(
+            raw_argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="runtime.check",
+            action="compile_runtime_plan",
+        )
+    except Exception as exc:
+        error = as_pz_error(
+            exc,
+            code="PZ_CHECK_FAILED",
+            stage="check",
+            owner="runtime.check",
+            action="compile_runtime_plan",
+        ).to_dict()
+        error["status"] = "error"
+        if json_output:
+            print(json.dumps(error, ensure_ascii=True, sort_keys=True))
+        else:
+            print(
+                f"status=error code={error['code']} stage={error['stage']} message={error['message']}",
+                file=sys.stderr,
+            )
+        return 1
+    ns = None
+    try:
+        parser = _build_parser()
+        ns = parser.parse_args(argv)
+        report = run_check(project_dir=ns.project_dir)
+        if ns.json_output:
+            print(json.dumps(report.to_dict(), ensure_ascii=True, sort_keys=True))
+        else:
+            _print_human_report(report)
+        return 0 if report.status == "ok" else 1
+    except Exception as exc:  # pragma: no cover
+        error = as_pz_error(
+            exc,
+            code="PZ_CHECK_FAILED",
+            stage="check",
+            owner="runtime.check",
+            action="compile_runtime_plan",
+        ).to_dict()
+        error["status"] = "error"
+        if (ns is not None and ns.json_output) or (ns is None and json_output):
+            print(json.dumps(error, ensure_ascii=True, sort_keys=True))
+        else:
+            print(
+                f"status=error code={error['code']} stage={error['stage']} message={error['message']}",
+                file=sys.stderr,
+            )
+        return 1
+
+
+__all__ = ["CheckReport", "run_check", "main"]