pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/cli/db.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import argparse
+from dataclasses import asdict, dataclass, replace
+import json
+import sys
+from typing import Any
+
+from pz_core.infra.db import (
+    DatabaseMigrationPort,
+    DatabaseMigrationSnapshot,
+    DbOwner,
+    MigrationSource,
+)
+from pz_core.runtime import RuntimePlan, compile_runtime_bindings, compile_runtime_plan
+from pz_core.runtime.cli._args import PzArgumentParser, json_output_requested, normalize_cli_argv
+from pz_core.runtime.errors import PzError, as_pz_error
+from pz_core.cli_options import add_cli_option, resolve_program_name
+
+
+@dataclass(frozen=True, slots=True)
+class DbCliReport:
+    status: str
+    code: str
+    stage: str
+    owner: str
+    action: str
+    workspace_dir: str
+    manifest_path: str
+    orm_config_path: str
+    lock_path: str
+    database_enabled: bool
+    database_driver: str
+    migration_executor: str | None
+    migration_owners: tuple[DbOwner, ...]
+    migration_sources: tuple[MigrationSource, ...]
+    history_entries: dict[str, tuple[str, ...]]
+    prepared_workspace: bool = False
+    executed: bool = False
+    execution_result: dict[str, Any] | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["migration_owners"] = [asdict(item) for item in self.migration_owners]
+        payload["migration_sources"] = [asdict(item) for item in self.migration_sources]
+        payload["history_entries"] = {
+            key: list(value) for key, value in self.history_entries.items()
+        }
+        return payload
+
+
+def _require_database(plan: RuntimePlan, *, action: str) -> None:
+    if not plan.infra.database.enabled:
+        raise PzError(
+            code="PZ_DB_DISABLED",
+            message="Database capability is disabled for the current project.",
+            stage="db",
+            owner="infra.database",
+            action=action,
+        )
+    if not str(plan.infra.database.get("driver", "") or "").strip():
+        raise PzError(
+            code="PZ_DB_DRIVER_MISSING",
+            message="Database capability is enabled but driver is empty.",
+            stage="db",
+            owner="infra.database",
+            action=action,
+        )
+
+
+def _migration_port(plan: RuntimePlan) -> DatabaseMigrationPort:
+    bindings = compile_runtime_bindings(plan)
+    bindings.providers.activate_declared(plan=plan, bindings=bindings)
+    provider = bindings.providers.require("database.migrations")
+    if not isinstance(provider, DatabaseMigrationPort):
+        raise PzError(
+            code="PZ_DB_PROVIDER_INVALID",
+            message=(
+                "Registered database.migrations provider does not implement "
+                "DatabaseMigrationPort."
+            ),
+            stage="db",
+            owner="runtime.cli.db",
+            action="bind_migration_provider",
+        )
+    return provider
+
+
+def _compile_report(
+    snapshot: DatabaseMigrationSnapshot,
+    *,
+    action: str,
+    message: str | None = None,
+) -> DbCliReport:
+    return DbCliReport(
+        status="ok",
+        code="PZ_DB_OK",
+        stage="db",
+        owner="runtime.cli.db",
+        action=action,
+        workspace_dir=str(snapshot.workspace_dir),
+        manifest_path=str(snapshot.manifest_path),
+        orm_config_path=str(snapshot.orm_config_path),
+        lock_path=str(snapshot.lock_path),
+        database_enabled=snapshot.database_enabled,
+        database_driver=snapshot.database_driver,
+        migration_executor=snapshot.migration_executor,
+        migration_owners=snapshot.migration_owners,
+        migration_sources=snapshot.migration_sources,
+        history_entries=snapshot.history_entries,
+        message=message,
+    )
+
+
+def _print_report(report: DbCliReport, *, json_output: bool) -> int:
+    payload = report.to_dict()
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+    else:
+        print(
+            f"status={payload['status']} code={payload['code']} action={payload['action']} "
+            f"workspace_dir={payload['workspace_dir']}"
+        )
+        for item in payload["migration_owners"]:
+            print(f"owner {item['owner']} -> {item['module_path']}")
+    return 0
+
+
+def _print_error(exc: Exception, *, json_output: bool) -> int:
+    if isinstance(exc, PzError):
+        payload = exc.to_dict()
+    else:
+        payload = as_pz_error(
+            exc,
+            code="PZ_DB_FAILED",
+            stage="db",
+            owner="runtime.cli.db",
+            action="dispatch",
+        ).to_dict()
+    payload["status"] = "error"
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+    else:
+        print(f"[{payload['code']}] {payload['message']}", file=sys.stderr)
+    return 1
+
+
+def _makemigrations(plan: RuntimePlan, *, prepare_workspace: bool) -> DbCliReport:
+    _require_database(plan, action="makemigrations")
+    provider = _migration_port(plan)
+    if prepare_workspace:
+        snapshot = provider.prepare(action="makemigrations")
+        report = _compile_report(
+            snapshot,
+            action="makemigrations",
+            message=(
+                "Migration planning uses the declared database.migrations provider and "
+                "writes workspace/config snapshots under ProjectContext cache_dir."
+            ),
+        )
+        return replace(report, prepared_workspace=True)
+    snapshot, execution_result = provider.execute(action="makemigrations")
+    report = _compile_report(
+        snapshot,
+        action="makemigrations",
+        message=(
+            "Migration execution uses the declared database.migrations provider and its "
+            "explicit migration executor contract."
+        ),
+    )
+    return replace(
+        report,
+        prepared_workspace=True,
+        executed=True,
+        execution_result=execution_result,
+    )
+
+
+def _history(plan: RuntimePlan, *, action: str = "history") -> DbCliReport:
+    _require_database(plan, action=action)
+    snapshot = _migration_port(plan).prepare(action=action)
+    report = _compile_report(snapshot, action=action)
+    return replace(report, prepared_workspace=True, executed=False)
+
+
+def _migrate(plan: RuntimePlan, *, prepare_workspace: bool) -> DbCliReport:
+    _require_database(plan, action="migrate")
+    provider = _migration_port(plan)
+    if prepare_workspace:
+        snapshot = provider.prepare(action="migrate")
+        report = _compile_report(
+            snapshot,
+            action="migrate",
+            message=(
+                "Migration preparation uses the declared database.migrations provider and "
+                "writes workspace/config snapshots without executing migrations."
+            ),
+        )
+        return replace(report, prepared_workspace=True, executed=False)
+    snapshot, execution_result = provider.execute(action="migrate")
+    report = _compile_report(
+        snapshot,
+        action="migrate",
+        message=(
+            "Migration execution uses the declared database.migrations provider and its "
+            "explicit migration executor contract."
+        ),
+    )
+    return replace(
+        report,
+        prepared_workspace=True,
+        executed=True,
+        execution_result=execution_result,
+    )
+
+
+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_DB_ARGV_INVALID",
+            stage="db",
+            owner="runtime.cli.db",
+            action="dispatch",
+        )
+    except Exception as exc:
+        return _print_error(exc, json_output=json_output)
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} db",
+        description="Database CLI built on RuntimePlan and provider-backed migration orchestration.",
+        error_code="PZ_DB_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="runtime.cli.db",
+        error_action="parse_args",
+    )
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    add_cli_option(parser, "--json", action="store_true", dest="json_output")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    showmigrations_parser = subparsers.add_parser(
+        "showmigrations",
+        prog=f"{resolve_program_name()} db showmigrations",
+    )
+    _add_db_common_arguments(showmigrations_parser)
+    makemigrations_parser = subparsers.add_parser(
+        "makemigrations",
+        prog=f"{resolve_program_name()} db makemigrations",
+    )
+    _add_db_common_arguments(makemigrations_parser)
+    add_cli_option(
+        makemigrations_parser,
+        "--prepare-workspace",
+        action="store_true",
+        dest="prepare_workspace",
+    )
+    migrate_parser = subparsers.add_parser("migrate", prog=f"{resolve_program_name()} db migrate")
+    _add_db_common_arguments(migrate_parser)
+    add_cli_option(
+        migrate_parser,
+        "--prepare-workspace",
+        action="store_true",
+        dest="prepare_workspace",
+    )
+
+    ns = None
+    try:
+        ns = parser.parse_args(argv)
+        plan = compile_runtime_plan(project_dir=ns.project_dir)
+        if ns.command == "showmigrations":
+            return _print_report(_history(plan, action="showmigrations"), json_output=ns.json_output)
+        if ns.command == "makemigrations":
+            return _print_report(
+                _makemigrations(plan, prepare_workspace=ns.prepare_workspace),
+                json_output=ns.json_output,
+            )
+        if ns.command == "migrate":
+            return _print_report(
+                _migrate(plan, prepare_workspace=ns.prepare_workspace),
+                json_output=ns.json_output,
+            )
+        raise PzError(
+            code="PZ_DB_UNKNOWN_COMMAND",
+            message=f"Unknown db command: {ns.command}",
+            stage="db",
+            owner="runtime.cli.db",
+            action="dispatch",
+        )
+    except Exception as exc:
+        return _print_error(exc, json_output=ns.json_output if ns is not None else json_output)
+
+
+def _add_db_common_arguments(parser: argparse.ArgumentParser) -> None:
+    add_cli_option(parser, "--project-dir", dest="project_dir", default=argparse.SUPPRESS)
+    add_cli_option(parser, "--json", action="store_true", dest="json_output", default=argparse.SUPPRESS)

pz_core/runtime/cli/main.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Sequence
+
+from pz_core.cli_options import option_shortcuts_help, resolve_program_name
+
+from . import app_commands as app_cli
+from . import check as check_cli
+from . import db as db_cli
+from . import resources as resources_cli
+
+def _usage() -> str:
+    program_name = resolve_program_name()
+    return f"""{program_name} CLI
+
+Usage:
+  {program_name} --help
+  {program_name} list [--json] [--project-dir PATH]
+  {program_name} check [--json] [--project-dir PATH]
+  {program_name} db <makemigrations|migrate|showmigrations> [--json] [--project-dir PATH]
+  {program_name} resources images [--force] [--json] [--project-dir PATH]
+  {program_name} <app_id> <tool> [--project-dir PATH]
+
+{option_shortcuts_help()}
+"""
+
+
+def _is_help(value: str | None) -> bool:
+    return isinstance(value, str) and value.strip().lower() in {"-h", "--help", "help"}
+
+
+def _json_mode(args: Sequence[object]) -> bool:
+    return any(isinstance(item, str) and item in {"--json", "-j"} for item in args)
+
+
+def _json_error(message: str, *, code: str) -> str:
+    return json.dumps(
+        {
+            "status": "error",
+            "code": code,
+            "stage": "cli",
+            "owner": "runtime.cli",
+            "action": "dispatch",
+            "summary": message,
+            "message": message,
+        },
+        ensure_ascii=True,
+        sort_keys=True,
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = list(argv or sys.argv[1:])
+    json_mode = _json_mode(args)
+    if not args or _is_help(args[0]):
+        sys.stdout.write(_usage())
+        return 0
+
+    raw_command = args.pop(0)
+    if not isinstance(raw_command, str) or not raw_command.strip():
+        message = "CLI command must be a non-empty string."
+        if json_mode:
+            sys.stdout.write(_json_error(message, code="PZ_CLI_COMMAND_INVALID") + "\n")
+        else:
+            sys.stderr.write(message + "\n\n" + _usage())
+        return 2
+    command = raw_command.strip().lower()
+    if command == "list":
+        return app_cli.list_main(args)
+    if command == "check":
+        return check_cli.main(args)
+    if command == "db":
+        return db_cli.main(args)
+    if command == "resources":
+        return resources_cli.main(args)
+    if args:
+        return app_cli.dispatch_app_cli(command, args)
+
+    message = f"Unknown command: {command}"
+    if json_mode:
+        sys.stdout.write(_json_error(message, code="PZ_CLI_UNKNOWN_COMMAND") + "\n")
+    else:
+        sys.stderr.write(message + "\n\n" + _usage())
+    return 2
+
+
+__all__ = ["main"]

pz_core/runtime/cli/resources.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+import json
+from pathlib import Path
+import sys
+from typing import Any
+
+from pz_core.cli_options import add_cli_option, resolve_program_name
+from pz_core.runtime import compile_runtime_bindings, compile_runtime_plan
+from pz_core.runtime.cli._args import PzArgumentParser, json_output_requested, normalize_cli_argv
+from pz_core.runtime.errors import PzError, as_pz_error
+from pz_core.runtime.resource_assets import (
+    RESOURCE_ASSET_BUNDLES_MANIFEST_KEY,
+    AssetBuildPolicy,
+    build_static_asset_manifest,
+    validate_static_asset_manifest,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceCliReport:
+    status: str
+    code: str
+    stage: str
+    owner: str
+    action: str
+    manifest_path: str
+    output_dir: str
+    forced: bool
+    message: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceAssetCliReport:
+    status: str
+    code: str
+    stage: str
+    owner: str
+    action: str
+    environment: str
+    manifest_path: str
+    output_dir: str
+    assets_built: int
+    bundles_built: int
+    violations: tuple[str, ...]
+    message: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _print_report(report: ResourceCliReport | ResourceAssetCliReport, *, json_output: bool) -> int:
+    payload = report.to_dict()
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+    else:
+        parts = [
+            f"status={payload['status']}",
+            f"code={payload['code']}",
+            f"action={payload['action']}",
+        ]
+        if "forced" in payload:
+            parts.append(f"forced={str(payload['forced']).lower()}")
+        if "environment" in payload:
+            parts.append(f"environment={payload['environment']}")
+        parts.append(f"output_dir={payload['output_dir']}")
+        print(" ".join(parts))
+        for violation in payload.get("violations") or ():
+            print(f"- {violation}", file=sys.stderr)
+    return 0 if payload["status"] == "ok" else 1
+
+
+def _print_error(exc: Exception, *, json_output: bool) -> int:
+    if isinstance(exc, PzError):
+        payload = exc.to_dict()
+    else:
+        payload = as_pz_error(
+            exc,
+            code="PZ_RESOURCES_FAILED",
+            stage="resources",
+            owner="runtime.cli.resources",
+            action="dispatch",
+        ).to_dict()
+    payload["status"] = "error"
+    if json_output:
+        print(json.dumps(payload, ensure_ascii=True, sort_keys=True))
+    else:
+        print(f"[{payload['code']}] {payload['message']}", file=sys.stderr)
+    return 1
+
+
+def _build_resources(*, project_dir: str | None, force: bool) -> ResourceCliReport:
+    plan = compile_runtime_plan(project_dir=project_dir)
+    effective_force = bool(force) or _resource_images_force_enabled(plan)
+    bindings = compile_runtime_bindings(plan)
+    bindings.providers.activate_declared(plan=plan, bindings=bindings)
+    result = bindings.resources.build(force=effective_force)
+    return ResourceCliReport(
+        status="ok",
+        code="PZ_RESOURCES_IMAGES_OK",
+        stage="resources",
+        owner="runtime.cli.resources",
+        action="images",
+        manifest_path=str(result.manifest_path),
+        output_dir=str(result.output_dir),
+        forced=effective_force,
+        message=(
+            "Resource image derivatives were built through the formal resources provider. "
+            "Existing derivative files are preserved unless the CLI flag or settings force is true."
+        ),
+    )
+
+
+def _build_assets(*, project_dir: str | None, environment: str | None, validate_only: bool) -> ResourceAssetCliReport:
+    plan = compile_runtime_plan(project_dir=project_dir)
+    output_root = Path(plan.resource_manifest.output_root)
+    static_root = output_root / "static"
+    manifest_path = output_root / "asset-manifest.json"
+    env_name = str(environment or _runtime_plan_environment(plan) or "develop").strip() or "develop"
+    policy = AssetBuildPolicy(environment=env_name)
+    bundles_built = 0
+
+    if validate_only:
+        result = validate_static_asset_manifest(static_root=static_root, manifest_path=manifest_path, policy=policy)
+    else:
+        bindings = compile_runtime_bindings(plan)
+        bindings.providers.activate_declared(plan=plan, bindings=bindings)
+        bindings.resources.build(force=True)
+        result = build_static_asset_manifest(
+            static_root=static_root,
+            manifest_path=manifest_path,
+            policy=policy,
+            page_bundles=_collect_page_asset_bundles(plan),
+        )
+        bundles_built = result.bundles_built
+        if result.status == "ok":
+            result = validate_static_asset_manifest(static_root=static_root, manifest_path=manifest_path, policy=policy)
+    return ResourceAssetCliReport(
+        status=result.status,
+        code="PZ_RESOURCES_ASSETS_OK" if result.status == "ok" else "PZ_RESOURCES_ASSETS_INVALID",
+        stage="resources",
+        owner="runtime.cli.resources",
+        action="assets",
+        environment=env_name,
+        manifest_path=str(result.manifest_path),
+        output_dir=str(result.static_root.parent),
+        assets_built=result.assets_built,
+        bundles_built=bundles_built,
+        violations=result.violations,
+        message=(
+            "Resource CSS/JS assets were validated."
+            if validate_only
+            else "Resource CSS/JS assets were rebuilt through the formal resources provider and validated."
+        ),
+    )
+
+
+def _runtime_plan_environment(plan: object) -> str:
+    settings = getattr(plan, "settings", None)
+    return str(getattr(settings, "pz_env", "") or "")
+
+
+def _collect_page_asset_bundles(plan: object) -> tuple[dict[str, Any], ...]:
+    manifests = getattr(plan, "runtime_manifests", None)
+    if not isinstance(manifests, Mapping):
+        return ()
+    raw_bundles = manifests.get(RESOURCE_ASSET_BUNDLES_MANIFEST_KEY, ())
+    if not isinstance(raw_bundles, (list, tuple)):
+        return ()
+    return tuple(dict(item) for item in raw_bundles if isinstance(item, Mapping))
+
+
+def _resource_images_force_enabled(plan: object) -> bool:
+    settings_snapshot = getattr(plan, "settings", None)
+    app_settings = getattr(settings_snapshot, "app_settings", None)
+    if not callable(app_settings):
+        return False
+    try:
+        app_payload = app_settings("pz_foundation")
+    except Exception:
+        return False
+    if not isinstance(app_payload, dict):
+        try:
+            app_payload = dict(app_payload)
+        except Exception:
+            return False
+    resources = app_payload.get("resources")
+    if not isinstance(resources, dict):
+        return False
+    images = resources.get("images")
+    if not isinstance(images, dict):
+        return False
+    return _coerce_bool(images.get("force", False))
+
+
+def _coerce_bool(value: object) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    if isinstance(value, (int, float)):
+        return bool(value)
+    return False
+
+
+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_RESOURCES_ARGV_INVALID",
+            stage="resources",
+            owner="runtime.cli.resources",
+            action="dispatch",
+        )
+    except Exception as exc:
+        return _print_error(exc, json_output=json_output)
+
+    parser = PzArgumentParser(
+        prog=f"{resolve_program_name()} resources",
+        description="Resource CLI built on RuntimePlan and the formal resources provider.",
+        error_code="PZ_RESOURCES_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="runtime.cli.resources",
+        error_action="parse_args",
+    )
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    add_cli_option(parser, "--json", action="store_true", dest="json_output")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    images_parser = subparsers.add_parser("images", prog=f"{resolve_program_name()} resources images")
+    _add_resource_common_arguments(images_parser)
+    add_cli_option(images_parser, "--force", action="store_true", dest="force")
+
+    assets_parser = subparsers.add_parser("assets", prog=f"{resolve_program_name()} resources assets")
+    _add_resource_common_arguments(assets_parser)
+    assets_parser.add_argument("--environment", dest="environment", default=None)
+    assets_parser.add_argument("--check", action="store_true", dest="validate_only")
+
+    ns = None
+    try:
+        ns = parser.parse_args(argv)
+        if ns.command == "images":
+            return _print_report(
+                _build_resources(project_dir=ns.project_dir, force=bool(getattr(ns, "force", False))),
+                json_output=ns.json_output,
+            )
+        if ns.command == "assets":
+            return _print_report(
+                _build_assets(
+                    project_dir=getattr(ns, "project_dir", None),
+                    environment=getattr(ns, "environment", None),
+                    validate_only=bool(getattr(ns, "validate_only", False)),
+                ),
+                json_output=ns.json_output,
+            )
+        raise PzError(
+            code="PZ_RESOURCES_UNKNOWN_COMMAND",
+            message=f"Unknown resources command: {ns.command}",
+            stage="resources",
+            owner="runtime.cli.resources",
+            action="dispatch",
+        )
+    except Exception as exc:
+        return _print_error(exc, json_output=ns.json_output if ns is not None else json_output)
+
+
+def _add_resource_common_arguments(parser: argparse.ArgumentParser) -> None:
+    add_cli_option(parser, "--project-dir", dest="project_dir", default=argparse.SUPPRESS)
+    add_cli_option(parser, "--json", action="store_true", dest="json_output", default=argparse.SUPPRESS)
+
+
+__all__ = ["main"]

pz_core/runtime/discovery.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pz_core.assembly.app_discovery import (
+    discover_declared_app_references,
+    discover_leaf_app_packages,
+    import_app_settings_module,
+    read_static_app_declaration,
+    resolve_declared_app_import_roots,
+    resolve_declared_app_id,
+    resolve_import_roots_for_app_references,
+    resolve_package_root,
+)
+
+__all__ = [
+    "discover_declared_app_references",
+    "discover_leaf_app_packages",
+    "import_app_settings_module",
+    "read_static_app_declaration",
+    "resolve_declared_app_import_roots",
+    "resolve_declared_app_id",
+    "resolve_import_roots_for_app_references",
+    "resolve_package_root",
+]