pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/env_cli.py

@@ -0,0 +1,454 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+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
+
+from .orchestration_service import execute_env_init, execute_env_install, execute_env_sync
+from .naming import resolve_project_dir
+from .sync_service import collect_sync_targets, sync_project_targets
+
+
+_OWNER = "pz_core.authoring.env"
+@dataclass(frozen=True, slots=True)
+class ToolStatus:
+    name: str
+    required: bool
+    found: bool
+    path: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class EnvReport:
+    project_dir: Path
+    initialized_project: bool
+    tools: tuple[ToolStatus, ...]
+
+
+def _program_name() -> str:
+    env_name = os.getenv("PZ_PROGRAM_NAME", "").strip().lower()
+    if env_name in {"pz", "pz"}:
+        return env_name
+    candidate = os.path.basename(str(sys.argv[0] or "")).strip().lower()
+    if candidate in {"pz", "pz"}:
+        return candidate
+    return "pz"
+
+
+def _usage() -> str:
+    program_name = _program_name()
+    return f"""{program_name} env
+
+Usage:
+  {program_name} env doctor [--json] [--project-dir PATH]
+  {program_name} env install [--json] [--project-dir PATH] [--group NAME] [--extra NAME] [--reinstall-package NAME] [--project-only]
+  {program_name} env init [--json] [--no-sync] [--project-dir PATH]
+  {program_name} env sync [--json] [--project-dir PATH] [--group NAME] [--extra NAME] [--reinstall-package NAME] [--project-only]
+
+{option_shortcuts_help()}
+"""
+
+
+def _resolve_existing_project_dir(raw_project_dir: str | None, *, action: str) -> Path:
+    project_dir = resolve_project_dir(raw_project_dir)
+    if not project_dir.exists() or not project_dir.is_dir():
+        raise PzError(
+            code="PZ_ENV_PROJECT_DIR_INVALID",
+            message=f"project directory must exist: {project_dir}",
+            stage="cli",
+            owner=_OWNER,
+            action=action,
+        )
+    return project_dir
+
+
+def _collect_report(project_dir: Path) -> EnvReport:
+    tools = (
+        ToolStatus(name="python", required=True, found=True, path=sys.executable),
+        ToolStatus(
+            name="dependency_backend",
+            required=True,
+            found=bool(shutil.which("uv")),
+            path=shutil.which("uv"),
+        ),
+        ToolStatus(name="git", required=True, found=bool(shutil.which("git")), path=shutil.which("git")),
+    )
+    return EnvReport(
+        project_dir=project_dir,
+        initialized_project=(project_dir / "pz.jsonc").is_file(),
+        tools=tools,
+    )
+
+
+def _report_status(report: EnvReport) -> str:
+    missing_required = [item.name for item in report.tools if item.required and not item.found]
+    return "ok" if not missing_required else "error"
+
+
+def _report_code(report: EnvReport, *, action: str) -> str:
+    if _report_status(report) == "ok":
+        return f"PZ_ENV_{action.upper()}_OK"
+    return "PZ_ENV_PREREQUISITES_MISSING"
+
+
+def _json_payload(
+    report: EnvReport,
+    *,
+    action: str,
+    updated_settings_path: str | None = None,
+    project_venv: str | None = None,
+    project_venv_created: bool = False,
+) -> str:
+    sync_targets = collect_sync_targets(report.project_dir)
+    return json.dumps(
+        {
+            "status": _report_status(report),
+            "code": _report_code(report, action=action),
+            "stage": "cli",
+            "owner": _OWNER,
+            "action": action,
+            "project_dir": str(report.project_dir),
+            "project_initialized": report.initialized_project,
+            "tools": [
+                {
+                    "name": item.name,
+                    "required": item.required,
+                    "found": item.found,
+                    "path": item.path,
+                }
+                for item in report.tools
+            ],
+            "sync_targets": [
+                {
+                    "name": item.name,
+                    "kind": item.kind,
+                    "path": str(item.path),
+                    "exists": item.exists,
+                    "has_pyproject": item.has_pyproject,
+                }
+                for item in sync_targets
+            ],
+            "project_venv": project_venv,
+            "project_venv_created": project_venv_created,
+            "updated_settings_path": updated_settings_path,
+        },
+        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 _print_report(
+    report: EnvReport,
+    *,
+    action: str,
+    updated_settings_path: str | None = None,
+    project_venv: str | None = None,
+) -> None:
+    print(f"env {action} {report.project_dir}")
+    for item in report.tools:
+        if item.found:
+            print(f"{item.name}: ok ({item.path})")
+        else:
+            print(f"{item.name}: missing")
+    project_status = "present" if report.initialized_project else "missing"
+    print(f"pz.jsonc: {project_status}")
+    sync_targets = collect_sync_targets(report.project_dir)
+    if sync_targets:
+        print("sync targets:")
+        for item in sync_targets:
+            pyproject_status = "pyproject" if item.has_pyproject else "no-pyproject"
+            exists_status = "present" if item.exists else "missing"
+            print(f"- {item.kind}:{item.name} {item.path} [{exists_status}, {pyproject_status}]")
+    if updated_settings_path is not None:
+        print(f"settings: updated ({updated_settings_path})")
+    if project_venv is not None:
+        print(f"project venv: ready ({project_venv})")
+    print(f"status: {_report_status(report)}")
+
+
+def doctor_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="doctor",
+        )
+        parser = PzArgumentParser(
+            prog=f"{_program_name()} env doctor",
+            description="Check the local pz authoring prerequisites for this project directory.",
+            error_code="PZ_ENV_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="doctor",
+        )
+        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)
+        report = _collect_report(_resolve_existing_project_dir(ns.project_dir, action="doctor"))
+        if ns.json_output:
+            print(_json_payload(report, action="doctor"))
+        else:
+            _print_report(report, action="doctor")
+        return 0 if _report_status(report) == "ok" else 1
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="doctor", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def init_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",
+        )
+        parser = PzArgumentParser(
+            prog=f"{_program_name()} env init",
+            description="Prepare the formal pz project skeleton and refresh managed settings blocks.",
+            error_code="PZ_ENV_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="init",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--no-sync", action="store_true", dest="no_sync")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = _resolve_existing_project_dir(ns.project_dir, action="init")
+        report = _collect_report(project_dir)
+        if _report_status(report) != "ok":
+            if ns.json_output:
+                print(_json_payload(report, action="init"))
+            else:
+                _print_report(report, action="init")
+            return 1
+        execution = execute_env_init(
+            project_dir,
+            action="init",
+            no_sync=bool(ns.no_sync),
+        )
+        final_report = EnvReport(
+            project_dir=project_dir,
+            initialized_project=((project_dir / "pz.jsonc").is_file()),
+            tools=report.tools,
+        )
+        project_venv = None if execution.project_venv is None else str(execution.project_venv.path)
+        project_venv_created = False if execution.project_venv is None else execution.project_venv.created
+        if ns.json_output:
+            print(
+                _json_payload(
+                    final_report,
+                    action="init",
+                    updated_settings_path=str(execution.settings_path),
+                    project_venv=project_venv,
+                    project_venv_created=project_venv_created,
+                )
+            )
+        else:
+            _print_report(
+                final_report,
+                action="init",
+                updated_settings_path=str(execution.settings_path),
+                project_venv=project_venv,
+            )
+            if execution.initialized_project:
+                print("project scaffold: created")
+            else:
+                print("project scaffold: reused")
+            if ns.no_sync:
+                print("sync: skipped")
+            elif execution.synced_targets:
+                print("synced:")
+                for item in execution.synced_targets:
+                    print(f"- {item.kind}:{item.name} {item.path}")
+            else:
+                print("sync: no pyproject targets found")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="init", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def install_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="install",
+        )
+        parser = PzArgumentParser(
+            prog=f"{_program_name()} env install",
+            description="Prepare the project virtualenv and run the first dependency sync for discovered authoring roots.",
+            error_code="PZ_ENV_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="install",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        add_cli_option(parser, "--group", action="append", default=[], dest="groups")
+        add_cli_option(parser, "--extra", action="append", default=[], dest="extras")
+        add_cli_option(parser, "--reinstall-package", action="append", default=[], dest="reinstall_packages")
+        add_cli_option(parser, "--project-only", action="store_true", dest="project_only")
+        ns = parser.parse_args(normalized)
+        project_dir = _resolve_existing_project_dir(ns.project_dir, action="install")
+        report = _collect_report(project_dir)
+        if _report_status(report) != "ok":
+            if ns.json_output:
+                print(_json_payload(report, action="install"))
+            else:
+                _print_report(report, action="install")
+            return 1
+        execution = execute_env_install(
+            project_dir,
+            action="install",
+            groups=tuple(str(item).strip() for item in ns.groups if str(item).strip()),
+            extras=tuple(str(item).strip() for item in ns.extras if str(item).strip()),
+            reinstall_packages=tuple(
+                str(item).strip() for item in ns.reinstall_packages if str(item).strip()
+            ),
+            project_only=bool(ns.project_only),
+            sync_targets=lambda path, **kwargs: sync_project_targets(path, action="install", **kwargs),
+        )
+        project_venv = str(execution.project_venv.path)
+        if ns.json_output:
+            print(
+                _json_payload(
+                    report,
+                    action="install",
+                    project_venv=project_venv,
+                    project_venv_created=execution.project_venv.created,
+                )
+            )
+        else:
+            _print_report(report, action="install", project_venv=project_venv)
+            if execution.synced_targets:
+                print("synced:")
+                for item in execution.synced_targets:
+                    print(f"- {item.kind}:{item.name} {item.path}")
+            else:
+                print("sync: no pyproject targets found")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="install", stage="cli")
+        if json_mode:
+            print(_json_error(error))
+        else:
+            print(str(error), file=sys.stderr)
+        return 1
+
+
+def sync_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="sync",
+        )
+        parser = PzArgumentParser(
+            prog=f"{_program_name()} env sync",
+            description="Run dependency sync for the formal project root and discovered authoring roots.",
+            error_code="PZ_ENV_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner=_OWNER,
+            error_action="sync",
+        )
+        add_cli_option(parser, "--json", action="store_true", dest="json_output")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        add_cli_option(parser, "--group", action="append", default=[], dest="groups")
+        add_cli_option(parser, "--extra", action="append", default=[], dest="extras")
+        add_cli_option(parser, "--reinstall-package", action="append", default=[], dest="reinstall_packages")
+        add_cli_option(parser, "--project-only", action="store_true", dest="project_only")
+        ns = parser.parse_args(normalized)
+        project_dir = _resolve_existing_project_dir(ns.project_dir, action="sync")
+        report = _collect_report(project_dir)
+        if _report_status(report) != "ok":
+            if ns.json_output:
+                print(_json_payload(report, action="sync"))
+            else:
+                _print_report(report, action="sync")
+            return 1
+        execution = execute_env_sync(
+            project_dir,
+            groups=tuple(str(item).strip() for item in ns.groups if str(item).strip()),
+            extras=tuple(str(item).strip() for item in ns.extras if str(item).strip()),
+            reinstall_packages=tuple(
+                str(item).strip() for item in ns.reinstall_packages if str(item).strip()
+            ),
+            project_only=bool(ns.project_only),
+            sync_targets=lambda path, **kwargs: sync_project_targets(path, action="sync", **kwargs),
+        )
+        if ns.json_output:
+            print(_json_payload(report, action="sync"))
+        else:
+            _print_report(report, action="sync")
+            if execution.synced_targets:
+                print("synced:")
+                for item in execution.synced_targets:
+                    print(f"- {item.kind}:{item.name} {item.path}")
+            else:
+                print("sync: no pyproject targets found")
+        return 0
+    except Exception as exc:
+        error = as_pz_error(exc, owner=_OWNER, action="sync", 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 == "doctor":
+        return doctor_main(args)
+    if command == "install":
+        return install_main(args)
+    if command == "init":
+        return init_main(args)
+    if command == "sync":
+        return sync_main(args)
+
+    sys.stderr.write(f"Unknown command: env {command}\n\n{_usage()}")
+    return 2
+
+
+__all__ = ["doctor_main", "init_main", "install_main", "main", "sync_main"]

pz_core/authoring/files.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from pz_core.runtime.errors import PzError
+
+
+@dataclass(frozen=True, slots=True)
+class ScaffoldFile:
+    path: Path
+    content: str
+
+
+def ensure_writable_target(path: Path, *, action: str) -> None:
+    if path.exists():
+        raise PzError(
+            code="PZ_SCAFFOLD_TARGET_EXISTS",
+            message=f"Refusing to overwrite existing path: {path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+
+def validate_writable_targets(entries: list[ScaffoldFile], *, action: str) -> None:
+    seen: set[Path] = set()
+    for entry in entries:
+        if entry.path in seen:
+            raise PzError(
+                code="PZ_SCAFFOLD_TARGET_DUPLICATE",
+                message=f"duplicate scaffold target declared: {entry.path}",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+            )
+        seen.add(entry.path)
+        ensure_writable_target(entry.path, action=action)
+
+
+def write_files(entries: list[ScaffoldFile], *, action: str) -> None:
+    validate_writable_targets(entries, action=action)
+    for entry in entries:
+        entry.path.parent.mkdir(parents=True, exist_ok=True)
+        entry.path.write_text(entry.content, encoding="utf-8")
+
+
+def append_or_create_file(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        path.write_text(content, encoding="utf-8")
+        return
+    existing = path.read_text(encoding="utf-8")
+    if content.strip() in existing:
+        return
+    suffix = content if existing.endswith("\n\n") or not existing else ("\n\n" + content.lstrip())
+    path.write_text(existing + suffix, encoding="utf-8")
+
+
+def render_upserted_managed_block(
+    existing: str | None,
+    *,
+    start_marker: str,
+    end_marker: str,
+    content: str,
+) -> str:
+    block = f"{start_marker}\n{content.strip()}\n{end_marker}\n"
+    if existing is None:
+        return block
+    start_index = existing.find(start_marker)
+    end_index = existing.find(end_marker)
+    if start_index >= 0 and end_index >= start_index:
+        replaced = existing[:start_index].rstrip()
+        suffix = existing[end_index + len(end_marker) :].lstrip("\n")
+        updated = block if not replaced else f"{replaced}\n\n{block}"
+        if suffix:
+            updated = f"{updated.rstrip()}\n\n{suffix}"
+        return updated
+    suffix = block if existing.endswith("\n\n") or not existing else ("\n\n" + block.lstrip())
+    return existing + suffix
+
+
+def upsert_managed_block(
+    path: Path,
+    *,
+    start_marker: str,
+    end_marker: str,
+    content: str,
+) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existing = path.read_text(encoding="utf-8") if path.exists() else None
+    path.write_text(
+        render_upserted_managed_block(
+            existing,
+            start_marker=start_marker,
+            end_marker=end_marker,
+            content=content,
+        ),
+        encoding="utf-8",
+    )
+
+
+__all__ = [
+    "ScaffoldFile",
+    "append_or_create_file",
+    "render_upserted_managed_block",
+    "upsert_managed_block",
+    "validate_writable_targets",
+    "write_files",
+]