pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/project_metadata_service.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import os
+import stat
+import uuid
+from collections.abc import Mapping, MutableMapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+import tomlkit  # type: ignore[import-not-found]
+from tomlkit.exceptions import TOMLKitError  # type: ignore[import-not-found]
+
+from pz_core.runtime.errors import PzError
+
+from .app_init_service import (
+    AppInitSourcePlan,
+    build_app_init_source_plan,
+    reconcile_project_uv_sources,
+)
+
+
+_OWNER = "pz_core.authoring.project_metadata_service"
+_atomic_replace = os.replace
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectUvSourcesUpdateResult:
+    path: Path
+    changed: bool
+    removed_keys: tuple[str, ...]
+    updated_keys: tuple[str, ...]
+    plan: AppInitSourcePlan
+
+
+def _error(
+    code: str,
+    message: str,
+    *,
+    action: str,
+    detail: str | None = None,
+) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="project_metadata",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def _mapping(value: object, *, path: str, action: str) -> MutableMapping[str, object]:
+    if not isinstance(value, MutableMapping):
+        raise _error(
+            "PZ_PROJECT_METADATA_INVALID",
+            f"{path} must be a TOML table.",
+            action=action,
+        )
+    return cast(MutableMapping[str, object], value)
+
+
+def _sources_table(document: object, *, action: str) -> MutableMapping[str, object]:
+    root = _mapping(document, path="$", action=action)
+    tool = root.get("tool")
+    if tool is None:
+        tool = tomlkit.table()
+        root["tool"] = tool
+    tool_table = _mapping(tool, path="$.tool", action=action)
+    uv = tool_table.get("uv")
+    if uv is None:
+        uv = tomlkit.table()
+        tool_table["uv"] = uv
+    uv_table = _mapping(uv, path="$.tool.uv", action=action)
+    sources = uv_table.get("sources")
+    if sources is None:
+        sources = tomlkit.table()
+        uv_table["sources"] = sources
+    return _mapping(sources, path="$.tool.uv.sources", action=action)
+
+
+def _plain_sources(sources: Mapping[str, object]) -> dict[str, object]:
+    plain: dict[str, object] = {}
+    for key, value in sources.items():
+        unwrap = getattr(value, "unwrap", None)
+        plain[str(key)] = unwrap() if callable(unwrap) else value
+    return plain
+
+
+def _source_entry(*, path: str) -> object:
+    entry = tomlkit.inline_table()
+    entry["path"] = path
+    entry["editable"] = True
+    return entry
+
+
+def _fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _write_atomic(
+    path: Path,
+    *,
+    before: bytes,
+    after: bytes,
+    action: str,
+) -> None:
+    mode = stat.S_IMODE(path.stat().st_mode)
+    staged = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        descriptor = os.open(staged, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+        try:
+            with os.fdopen(descriptor, "wb") as handle:
+                handle.write(after)
+                handle.flush()
+                os.fsync(handle.fileno())
+        except BaseException:
+            staged.unlink(missing_ok=True)
+            raise
+        if path.read_bytes() != before:
+            raise _error(
+                "PZ_PROJECT_METADATA_CHANGED",
+                "pyproject.toml changed during uv source reconciliation.",
+                action=action,
+            )
+        _atomic_replace(staged, path)
+        _fsync_directory(path.parent)
+    except PzError:
+        raise
+    except (OSError, RuntimeError) as exc:
+        raise _error(
+            "PZ_PROJECT_METADATA_WRITE_FAILED",
+            "failed to atomically update pyproject.toml uv sources.",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    finally:
+        staged.unlink(missing_ok=True)
+
+
+def update_project_uv_sources(
+    project_dir: Path,
+    *,
+    action: str,
+) -> ProjectUvSourcesUpdateResult:
+    project_root = project_dir.expanduser().resolve(strict=False)
+    path = project_root / "pyproject.toml"
+    try:
+        before = path.read_bytes()
+    except OSError as exc:
+        raise _error(
+            "PZ_PROJECT_METADATA_MISSING",
+            "project pyproject.toml is missing or unreadable.",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    try:
+        document = tomlkit.parse(before.decode("utf-8"))
+    except (UnicodeError, TOMLKitError) as exc:
+        raise _error(
+            "PZ_PROJECT_METADATA_INVALID",
+            "project pyproject.toml is not valid UTF-8 TOML.",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    sources = _sources_table(document, action=action)
+    current_sources = _plain_sources(sources)
+    plan = build_app_init_source_plan(
+        project_root,
+        current_sources=current_sources,
+        action=action,
+    )
+    reconciliation = reconcile_project_uv_sources(current_sources, plan)
+    removed_keys = tuple(
+        key for key in reconciliation.removed_keys if key in current_sources
+    )
+    for key in removed_keys:
+        sources.pop(key, None)
+    for distribution in reconciliation.updated_keys:
+        binding = plan.desired_sources[distribution]
+        sources[distribution] = _source_entry(path=binding.path)
+    after = tomlkit.dumps(document).encode("utf-8")
+    changed = after != before
+    if changed:
+        _write_atomic(path, before=before, after=after, action=action)
+    return ProjectUvSourcesUpdateResult(
+        path=path,
+        changed=changed,
+        removed_keys=removed_keys,
+        updated_keys=reconciliation.updated_keys,
+        plan=plan,
+    )
+
+
+__all__ = ["ProjectUvSourcesUpdateResult", "update_project_uv_sources"]

pz_core/authoring/project_settings_checks.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pz_core.assembly.diagnostics import CheckItem
+
+from .project_settings_service import inspect_settings_update_drift
+
+
+def build_settings_update_check_items(project_dir: str | Path) -> tuple[CheckItem, ...]:
+    try:
+        result = inspect_settings_update_drift(project_dir)
+    except Exception as exc:
+        return (
+            CheckItem(
+                severity="warning",
+                code="PZ_CHECK_SETTINGS_UPDATE_DRIFT_FAILED",
+                owner="pz_core.authoring.project_settings",
+                scope="settings",
+                message=f"Failed to inspect settings update drift: {exc}",
+                ok=False,
+            ),
+        )
+    if result.required:
+        pending = ", ".join(str(path) for path in result.changed_paths)
+        return (
+            CheckItem(
+                severity="warning",
+                code="PZ_CHECK_SETTINGS_UPDATE_REQUIRED",
+                owner="pz_core.authoring.project_settings",
+                scope="settings",
+                message=(
+                    "Project settings are behind the current settings update plan. "
+                    f"Run `{result.command}`. Pending files: {pending}."
+                ),
+                ok=False,
+            ),
+        )
+    return (
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_SETTINGS_UPDATE_CURRENT",
+            owner="pz_core.authoring.project_settings",
+            scope="settings",
+            message="Project settings match the current settings update plan.",
+            ok=True,
+        ),
+    )
+
+
+__all__ = ["build_settings_update_check_items"]

pz_core/authoring/project_settings_cli.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+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, option_shortcuts_help, resolve_program_name
+
+from .scaffold_service import refresh_project_agents_file, reset_project_agents_file
+from .project_settings_service import initialize_settings_file, update_settings_file
+
+
+_OWNER = "pz_core.authoring.project_settings"
+def _usage() -> str:
+    program_name = resolve_program_name()
+    return f"""{program_name} project settings
+
+Usage:
+  {program_name} settings init [--force] [--json] [--project-dir PATH]
+  {program_name} settings update [target] [--reset-middlewares-order] [--json] [--project-dir PATH]
+  {program_name} settings refresh-agents [--json] [--project-dir PATH]
+  {program_name} settings reset-agents [--json] [--project-dir PATH]
+
+{option_shortcuts_help()}
+"""
+
+
+def _prog(*parts: str) -> str:
+    return " ".join((resolve_program_name(), *parts))
+
+
+def _json_payload(
+    *,
+    action: str,
+    code: str,
+    result_path: str,
+    module_paths: tuple[str, ...],
+    created: bool,
+) -> str:
+    return json.dumps(
+        {
+            "status": "ok",
+            "code": code,
+            "stage": "cli",
+            "owner": _OWNER,
+            "action": action,
+            "path": result_path,
+            "module_paths": list(module_paths),
+            "created": created,
+        },
+        ensure_ascii=True,
+        sort_keys=True,
+    )
+
+
+def _json_error(error: PzError) -> str:
+    payload = error.to_dict()
+    payload["status"] = "error"
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True)
+
+
+def _resolve_existing_project_dir(project_dir: str | None) -> Path:
+    path = Path(project_dir or ".").expanduser().resolve()
+    if not path.exists() or not path.is_dir():
+        raise PzError(
+            code="PZ_SETTINGS_PROJECT_DIR_INVALID",
+            message=f"project directory must exist: {path}",
+            stage="cli",
+            owner=_OWNER,
+            action="refresh_agents",
+        )
+    return path
+
+
+def init_settings_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=_OWNER,
+            action="init_settings",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("settings", "init"),
+            description="Scan installed apps under the apps namespace and generate pz.jsonc managed sections.",
+            error_code="PZ_SETTINGS_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="init_settings",
+        )
+        add_cli_option(parser, "--force", action="store_true", dest="force")
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        result = initialize_settings_file(ns.project_dir or ".", force=ns.force)
+        if ns.json_output:
+            print(
+                _json_payload(
+                    action="init_settings",
+                    code="PZ_SETTINGS_INIT_OK",
+                    result_path=str(result.path),
+                    module_paths=result.module_paths,
+                    created=result.created,
+                )
+            )
+        else:
+            verb = "generated" if result.created else "overwritten"
+            print(f"{verb} {result.path}")
+            for module_path in result.module_paths:
+                print(f"app {module_path}")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="init_settings", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def update_settings_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=_OWNER,
+            action="update_settings",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("settings", "update"),
+            description="Refresh managed pz.jsonc sections without overwriting non-managed project values.",
+            error_code="PZ_SETTINGS_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="update_settings",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        parser.add_argument("target", nargs="?", default=None)
+        add_cli_option(
+            parser,
+            "--reset-middlewares-order",
+            action="store_true",
+            dest="reset_middlewares_order",
+            help="Rebuild the managed middlewares block using the current conventional order.",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        result = update_settings_file(
+            ns.project_dir or ".",
+            target=ns.target,
+            reset_middlewares_order=ns.reset_middlewares_order,
+        )
+        if ns.json_output:
+            print(
+                _json_payload(
+                    action="update_settings",
+                    code="PZ_SETTINGS_UPDATE_OK",
+                    result_path=str(result.path),
+                    module_paths=result.module_paths,
+                    created=result.created,
+                )
+            )
+        else:
+            print(f"updated {result.path}")
+            for module_path in result.module_paths:
+                print(f"app {module_path}")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="update_settings", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def refresh_agents_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=_OWNER,
+            action="refresh_agents",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("settings", "refresh-agents"),
+            description="Refresh only the managed pz rules block in the project root AGENTS.md.",
+            error_code="PZ_SETTINGS_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="refresh_agents",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        result = refresh_project_agents_file(_resolve_existing_project_dir(ns.project_dir))
+        if ns.json_output:
+            print(
+                _json_payload(
+                    action="refresh_agents",
+                    code="PZ_SETTINGS_REFRESH_AGENTS_OK",
+                    result_path=str(result.path),
+                    module_paths=(),
+                    created=result.created,
+                )
+            )
+        else:
+            verb = "generated" if result.created else "updated"
+            print(f"{verb} {result.path}")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="refresh_agents", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def reset_agents_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner=_OWNER,
+            action="reset_agents",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("settings", "reset-agents"),
+            description="Reset the project root AGENTS.md to only the current managed pz rules block.",
+            error_code="PZ_SETTINGS_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="reset_agents",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        result = reset_project_agents_file(_resolve_existing_project_dir(ns.project_dir))
+        if ns.json_output:
+            print(
+                _json_payload(
+                    action="reset_agents",
+                    code="PZ_SETTINGS_RESET_AGENTS_OK",
+                    result_path=str(result.path),
+                    module_paths=(),
+                    created=result.created,
+                )
+            )
+        else:
+            verb = "generated" if result.created else "reset"
+            print(f"{verb} {result.path}")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="reset_agents", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def main(argv: list[object] | None = None) -> int:
+    args = list(argv or sys.argv[1:])
+    if not args or str(args[0]).strip().lower() in {"-h", "--help", "help"}:
+        sys.stdout.write(_usage())
+        return 0
+
+    command = str(args.pop(0)).strip().lower()
+    if command == "init":
+        return init_settings_main(args)
+    if command == "update":
+        return update_settings_main(args)
+    if command == "refresh-agents":
+        return refresh_agents_main(args)
+    if command == "reset-agents":
+        return reset_agents_main(args)
+
+    sys.stderr.write(f"Unknown command: {command}\n\n{_usage()}")
+    return 2
+
+
+__all__ = [
+    "init_settings_main",
+    "main",
+    "refresh_agents_main",
+    "reset_agents_main",
+    "update_settings_main",
+]