pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/resource_assets.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import time
+from typing import Any, Iterable, Mapping
+
+
+RESOURCE_ASSET_BUNDLES_MANIFEST_KEY = "resource.asset_bundles"
+
+
+_SITE_JS_BUNDLE = {
+    "output": "default/js/site.min.js",
+    "inputs": ("default/js/base.js",),
+    "suffix": ".js",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AssetBuildPolicy:
+    environment: str
+
+
+@dataclass(frozen=True, slots=True)
+class AssetBuildResult:
+    status: str
+    manifest_path: Path
+    static_root: Path
+    assets_built: int
+    bundles_built: int
+    violations: tuple[str, ...] = ()
+
+
+def build_static_asset_manifest(
+    *,
+    static_root: Path,
+    manifest_path: Path,
+    policy: AssetBuildPolicy,
+    page_bundles: Iterable[Mapping[str, Any]],
+) -> AssetBuildResult:
+    static_root = static_root.resolve()
+    manifest_path = manifest_path.resolve()
+    records: dict[str, dict[str, Any]] = {}
+    violations: list[str] = []
+
+    for source_path in _iter_source_assets(static_root):
+        rel_source = _rel_static_path(static_root, source_path)
+        output_path = static_root / _default_minified_path(rel_source)
+        if not output_path.is_file():
+            violations.append(f"static asset {rel_source} minified output is missing")
+            continue
+        records[rel_source] = _asset_record(static_root, rel_source, output_path)
+
+    bundles_built = 0
+    site_records, site_violations = _build_site_bundles(static_root=static_root)
+    violations.extend(site_violations)
+    if site_records:
+        bundles_built += len(site_records)
+        records.update(site_records)
+
+    for bundle in page_bundles:
+        bundle_records, bundle_violations = _build_page_bundle(static_root=static_root, bundle=bundle)
+        violations.extend(bundle_violations)
+        if bundle_records:
+            bundles_built += 1
+            records.update(bundle_records)
+
+    payload = {
+        "schema_version": "pz_core.resource_assets.v1",
+        "environment": str(policy.environment or "").strip() or "develop",
+        "built_at_unix": time.time(),
+        "static_root": str(static_root),
+        "assets": records,
+        "violations": violations,
+    }
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(
+        json.dumps(payload, ensure_ascii=True, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return AssetBuildResult(
+        status="failed" if violations else "ok",
+        manifest_path=manifest_path,
+        static_root=static_root,
+        assets_built=len(records),
+        bundles_built=bundles_built,
+        violations=tuple(violations),
+    )
+
+
+def validate_static_asset_manifest(
+    *,
+    static_root: Path,
+    manifest_path: Path,
+    policy: AssetBuildPolicy,
+) -> AssetBuildResult:
+    static_root = static_root.resolve()
+    manifest_path = manifest_path.resolve()
+    if not manifest_path.is_file():
+        return AssetBuildResult(
+            status="failed",
+            manifest_path=manifest_path,
+            static_root=static_root,
+            assets_built=0,
+            bundles_built=0,
+            violations=(f"asset manifest is missing at {manifest_path}",),
+        )
+    payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    required_environment = str(policy.environment or "").strip() or "develop"
+    manifest_environment = str(payload.get("environment") or "").strip()
+    violations: list[str] = []
+    if manifest_environment != required_environment:
+        violations.append(
+            f"asset manifest environment {manifest_environment} does not match required {required_environment}"
+        )
+    if Path(str(payload.get("static_root") or "")).resolve() != static_root:
+        violations.append("asset manifest static_root does not match current static root")
+    assets = payload.get("assets") if isinstance(payload, dict) else None
+    if not isinstance(assets, dict):
+        violations.append("asset manifest assets must be an object")
+        assets = {}
+    for source, record in sorted(assets.items()):
+        if not isinstance(record, dict):
+            violations.append(f"asset manifest record for {source} must be an object")
+            continue
+        source_path = static_root / source
+        output_path = static_root / str(record.get("output") or "")
+        if not source_path.is_file():
+            violations.append(f"static asset {source} source file is missing")
+            continue
+        if not output_path.is_file():
+            violations.append(f"static asset {source} output file is missing")
+            continue
+        if _sha256_file(source_path) != str(record.get("source_sha256") or ""):
+            violations.append(f"static asset {source} changed after manifest build")
+        if _sha256_file(output_path) != str(record.get("output_sha256") or ""):
+            violations.append(f"static asset {source} output changed after manifest build")
+    return AssetBuildResult(
+        status="failed" if violations else "ok",
+        manifest_path=manifest_path,
+        static_root=static_root,
+        assets_built=len(assets),
+        bundles_built=0,
+        violations=tuple(violations),
+    )
+
+
+def _iter_source_assets(static_root: Path) -> tuple[Path, ...]:
+    paths: list[Path] = []
+    excluded_parts = {"dist", "src", "third_part", "vendor"}
+    for suffix in ("*.css", "*.js"):
+        for path in sorted(static_root.rglob(suffix)):
+            name = path.name
+            if ".min." in name:
+                continue
+            rel_parts = set(_rel_static_path(static_root, path).split("/"))
+            if excluded_parts & rel_parts:
+                continue
+            if path.stat().st_size == 0:
+                continue
+            if path.is_file():
+                paths.append(path)
+    return tuple(paths)
+
+
+def _rel_static_path(static_root: Path, path: Path) -> str:
+    return path.resolve().relative_to(static_root).as_posix()
+
+
+def _default_minified_path(rel_source: str) -> str:
+    pure = PurePosixPath(rel_source)
+    return str(pure.with_name(f"{pure.stem}.min{pure.suffix}"))
+
+
+def _asset_record(static_root: Path, rel_source: str, output_path: Path) -> dict[str, Any]:
+    source_path = static_root / rel_source
+    rel_output = _rel_static_path(static_root, output_path)
+    return {
+        "source": rel_source,
+        "output": rel_output,
+        "source_sha256": _sha256_file(source_path),
+        "output_sha256": _sha256_file(output_path),
+        "source_size": source_path.stat().st_size,
+        "output_size": output_path.stat().st_size,
+    }
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _build_page_bundle(
+    *,
+    static_root: Path,
+    bundle: Mapping[str, Any],
+) -> tuple[dict[str, dict[str, Any]], tuple[str, ...]]:
+    records: dict[str, dict[str, Any]] = {}
+    violations: list[str] = []
+    css_output = str(bundle.get("css_bundle") or "").strip().lstrip("/")
+    js_output = str(bundle.get("js_bundle") or "").strip().lstrip("/")
+    css_inputs = tuple(str(item or "").strip().lstrip("/") for item in bundle.get("css_inputs") or ())
+    js_inputs = tuple(str(item or "").strip().lstrip("/") for item in bundle.get("js_inputs") or ())
+    if css_output and css_inputs:
+        result = _write_bundle(static_root=static_root, output=css_output, inputs=css_inputs, suffix=".css")
+        if result[1]:
+            violations.extend(result[1])
+        else:
+            records[css_output] = _asset_record(
+                static_root,
+                css_output,
+                static_root / _default_minified_path(css_output),
+            )
+    if js_output and js_inputs:
+        result = _write_bundle(static_root=static_root, output=js_output, inputs=js_inputs, suffix=".js")
+        if result[1]:
+            violations.extend(result[1])
+        else:
+            records[js_output] = _asset_record(
+                static_root,
+                js_output,
+                static_root / _default_minified_path(js_output),
+            )
+    return records, tuple(violations)
+
+
+def _write_bundle(
+    *,
+    static_root: Path,
+    output: str,
+    inputs: tuple[str, ...],
+    suffix: str,
+) -> tuple[Path | None, tuple[str, ...]]:
+    violations: list[str] = []
+    output_path = static_root / output
+    minified_path = static_root / _default_minified_path(output)
+    if not output.endswith(suffix):
+        violations.append(f"bundle output {output} must end with {suffix}")
+    parts: list[str] = []
+    minified_parts: list[str] = []
+    for rel_input in inputs:
+        input_path = static_root / rel_input
+        if not input_path.is_file():
+            violations.append(f"bundle input {rel_input} is missing")
+            continue
+        parts.append(f"/* {rel_input} */\n{input_path.read_text(encoding='utf-8').rstrip()}\n")
+        minified_input_path = static_root / _default_minified_path(rel_input)
+        minified_source_path = minified_input_path if minified_input_path.is_file() else input_path
+        minified_parts.append(
+            f"/* {rel_input} */\n{minified_source_path.read_text(encoding='utf-8').rstrip()}\n"
+        )
+    if violations:
+        return None, tuple(violations)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    source_text = "\n".join(parts).rstrip() + "\n"
+    output_path.write_text(source_text, encoding="utf-8")
+    minified_path.parent.mkdir(parents=True, exist_ok=True)
+    minified_text = "\n".join(minified_parts).rstrip() + "\n"
+    minified_path.write_text(minified_text, encoding="utf-8")
+    return output_path, ()
+
+
+def _build_site_bundles(*, static_root: Path) -> tuple[dict[str, dict[str, Any]], tuple[str, ...]]:
+    records: dict[str, dict[str, Any]] = {}
+    violations: list[str] = []
+    for bundle in (_SITE_JS_BUNDLE,):
+        output = str(bundle["output"])
+        inputs = tuple(str(item) for item in bundle["inputs"])
+        suffix = str(bundle["suffix"])
+        if not _site_bundle_declared(static_root=static_root, output=output, inputs=inputs):
+            continue
+        result = _validate_minified_bundle(static_root=static_root, output=output, inputs=inputs, suffix=suffix)
+        if result[1]:
+            violations.extend(result[1])
+        else:
+            records[output] = _asset_record(static_root, output, static_root / output)
+    return records, tuple(violations)
+
+
+def _site_bundle_declared(*, static_root: Path, output: str, inputs: tuple[str, ...]) -> bool:
+    if (static_root / output).is_file():
+        return True
+    return any((static_root / rel_input).is_file() for rel_input in inputs)
+
+
+def _validate_minified_bundle(
+    *,
+    static_root: Path,
+    output: str,
+    inputs: tuple[str, ...],
+    suffix: str,
+) -> tuple[Path | None, tuple[str, ...]]:
+    violations: list[str] = []
+    output_path = static_root / output
+    if not output.endswith(suffix):
+        violations.append(f"bundle output {output} must end with {suffix}")
+    for rel_input in inputs:
+        input_path = static_root / rel_input
+        if not input_path.is_file():
+            violations.append(f"bundle input {rel_input} is missing")
+    if not output_path.is_file():
+        violations.append(f"bundle output {output} is missing")
+    if violations:
+        return None, tuple(violations)
+    return output_path, ()
+
+
+def _validate_bundle(
+    *,
+    static_root: Path,
+    output: str,
+    inputs: tuple[str, ...],
+    suffix: str,
+) -> tuple[Path | None, tuple[str, ...]]:
+    violations: list[str] = []
+    output_path = static_root / output
+    minified_path = static_root / _default_minified_path(output)
+    if not output.endswith(suffix):
+        violations.append(f"bundle output {output} must end with {suffix}")
+    for rel_input in inputs:
+        input_path = static_root / rel_input
+        if not input_path.is_file():
+            violations.append(f"bundle input {rel_input} is missing")
+    if not output_path.is_file():
+        violations.append(f"bundle source output {output} is missing")
+    if not minified_path.is_file():
+        violations.append(f"bundle minified output {_default_minified_path(output)} is missing")
+    if violations:
+        return None, tuple(violations)
+    return output_path, ()
+
+
+__all__ = [
+    "AssetBuildPolicy",
+    "AssetBuildResult",
+    "RESOURCE_ASSET_BUNDLES_MANIFEST_KEY",
+    "build_static_asset_manifest",
+    "validate_static_asset_manifest",
+]

pz_core/runtime/run_cli.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import sys
+from typing import Any
+
+from pz_core.runtime.cli._args import PzArgumentParser, 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
+from pz_core.utils import PROJECT_JSONC_NAME, load_jsonc_file
+
+
+_OWNER = "pz_core.runtime.run_cli"
+_DEFAULT_ENV = "develop"
+_EXPLICIT_RUN_ENVS = {"test", "product"}
+_DEVELOP_ALIASES = {"develop", "dev"}
+_RUN_ENVS = ("develop", "test", "product")
+
+
+def _resolve_project_dir(raw: str | None) -> Path:
+    path = Path(raw or ".").expanduser().resolve()
+    if not path.exists() or not path.is_dir():
+        raise PzError(
+            code="PZ_RUN_PROJECT_DIR_INVALID",
+            message=f"project directory must exist: {path}",
+            stage="cli",
+            owner=_OWNER,
+            action="run",
+        )
+    return path
+
+
+def _resolve_main_path(project_dir: Path) -> Path:
+    path = project_dir / "main.py"
+    if not path.is_file():
+        raise PzError(
+            code="PZ_RUN_MAIN_MISSING",
+            message=f"project main.py does not exist: {path}",
+            stage="cli",
+            owner=_OWNER,
+            action="run",
+        )
+    return path
+
+
+def _resolve_run_env_name(raw: str | None) -> str:
+    if raw is None:
+        return _DEFAULT_ENV
+    value = str(raw).strip().lower()
+    if value in _DEVELOP_ALIASES:
+        return _DEFAULT_ENV
+    if value in _EXPLICIT_RUN_ENVS:
+        return value
+    raise PzError(
+        code="PZ_RUN_MODE_INVALID",
+        message="run mode must be omitted, `develop`, `dev`, `test`, or `product`.",
+        stage="cli",
+        owner=_OWNER,
+        action="run",
+    )
+
+
+def _deep_merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge(merged[key], value)
+            continue
+        merged[key] = value
+    return merged
+
+
+def _read_run_config(project_dir: Path, env_name: str) -> dict[str, Any]:
+    root_payload = load_jsonc_file(
+        project_dir / PROJECT_JSONC_NAME,
+        code="PZ_RUN_CONFIG_INVALID",
+        owner=_OWNER,
+        action="read_run_environment_config",
+    )
+    env_payload = load_jsonc_file(
+        project_dir / f"pz.{env_name}.jsonc",
+        code="PZ_RUN_CONFIG_INVALID",
+        owner=_OWNER,
+        action="read_run_environment_config",
+    )
+    return _deep_merge(root_payload, env_payload)
+
+
+def _run_environment_enabled(config: dict[str, Any], env_name: str) -> bool:
+    project_config = config.get("project")
+    if not isinstance(project_config, dict):
+        return env_name != "test"
+    if "environments" not in project_config:
+        return env_name != "test"
+    environments = project_config.get("environments")
+    if not isinstance(environments, dict):
+        raise PzError(
+            code="PZ_RUN_ENV_CONFIG_INVALID",
+            message="project.environments must be an object when configured.",
+            stage="cli",
+            owner=_OWNER,
+            action="run",
+        )
+    environment_config = environments.get(env_name)
+    if environment_config is None:
+        return env_name != "test"
+    if not isinstance(environment_config, dict):
+        raise PzError(
+            code="PZ_RUN_ENV_CONFIG_INVALID",
+            message=f"project.environments.{env_name} must be an object when configured.",
+            stage="cli",
+            owner=_OWNER,
+            action="run",
+        )
+    enabled = environment_config.get("enabled")
+    if enabled is None:
+        return env_name != "test"
+    if isinstance(enabled, bool):
+        return enabled
+    raise PzError(
+        code="PZ_RUN_ENV_CONFIG_INVALID",
+        message=f"project.environments.{env_name}.enabled must be a boolean when configured.",
+        stage="cli",
+        owner=_OWNER,
+        action="run",
+    )
+
+
+def _enabled_run_environment_names(config: dict[str, Any]) -> tuple[str, ...]:
+    return tuple(env_name for env_name in _RUN_ENVS if _run_environment_enabled(config, env_name))
+
+
+def _enforce_run_environment_enabled(project_dir: Path, env_name: str) -> None:
+    config = _read_run_config(project_dir, env_name)
+    if _run_environment_enabled(config, env_name):
+        return
+    enabled_names = _enabled_run_environment_names(config)
+    allowed = ", ".join(enabled_names) if enabled_names else "none"
+    raise PzError(
+        code="PZ_RUN_ENV_DISABLED",
+        message=(
+            f"Environment `{env_name}` is disabled by "
+            f"`project.environments.{env_name}.enabled=false`. "
+            f"Currently enabled environments: {allowed}."
+        ),
+        stage="cli",
+        owner=_OWNER,
+        action="run",
+    )
+
+
+def _exec_child_process(argv: list[str], *, project_dir: Path, child_env: dict[str, str]) -> int:
+    original_cwd = Path.cwd()
+    try:
+        os.chdir(project_dir)
+        os.execvpe(argv[0], argv, child_env)
+    finally:
+        os.chdir(original_cwd)
+    return 0
+
+
+def _run_with_local_python(*, project_dir: Path, main_path: Path, child_env: dict[str, str]) -> int:
+    return _exec_child_process(
+        [sys.executable, str(main_path)],
+        project_dir=project_dir,
+        child_env=child_env,
+    )
+
+
+def main(argv: list[object] | None = None) -> int:
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=_OWNER,
+            action="run",
+        )
+        parser = PzArgumentParser(
+            prog=f"{resolve_program_name()} run",
+            description="Start the formal project host through the root main.py entrypoint.",
+            error_code="PZ_RUN_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="run",
+        )
+        parser.add_argument("run_env", nargs="?")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+
+        project_dir = _resolve_project_dir(ns.project_dir)
+        main_path = _resolve_main_path(project_dir)
+        env_name = _resolve_run_env_name(ns.run_env)
+        _enforce_run_environment_enabled(project_dir, env_name)
+
+        child_env = os.environ.copy()
+        child_env["PZ_ENV"] = env_name
+
+        return _run_with_local_python(
+            project_dir=project_dir,
+            main_path=main_path,
+            child_env=child_env,
+        )
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="run", stage="cli")
+        print(str(error), file=sys.stderr)
+        return 1
+
+
+__all__ = ["main"]