pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/commands.py

@@ -0,0 +1,1810 @@
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+import shutil
+import subprocess
+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, resolve_program_name
+
+from .dev_sources import (
+    AddDevSourceRequest,
+    BranchDevSourceRequest,
+    DevTransactionResult,
+    add_dev_source,
+    branch_dev_source,
+)
+from .dev_manifest import load_dev_manifest
+from .dev_import import (
+    cache_git_source,
+    find_existing_local_import,
+    import_git_app,
+    import_local_dev_source,
+    load_cached_git_source,
+)
+from .ide_projection import IdeSyncResult, sync_ide_projections
+from .official_dev_sources import resolve_source_locator
+from .app_versions import (
+    declare_app_version,
+    install_declared_app,
+    query_app_versions,
+    reconcile_project_environment,
+    resolve_app_version,
+    undeclare_app_version,
+)
+from .files import append_or_create_file, write_files
+from .naming import build_app_id, normalize_app_slug, resolve_project_dir
+from .orchestration_service import (
+    execute_app_init,
+    execute_dev_init,
+    execute_publish_batch,
+)
+from .project_settings_service import update_settings_file
+from .project_metadata_service import update_project_uv_sources
+from .conflicts import (
+    build_app_binding_conflict_error,
+    ensure_no_app_binding_conflicts,
+)
+from .project_state import (
+    add_declared_app,
+    ensure_project_state,
+    load_installed_apps,
+    normalize_formal_app_id,
+    remove_declared_app,
+)
+from .release import (
+    install_env,
+    load_install_target,
+    publish_app,
+    publish_commit,
+    publish_tag,
+    publish_upload,
+    unpublish_app,
+)
+from .scaffold_service import (
+    app_files,
+    resolve_project_local_pz_docs_root,
+)
+from .sync_service import sync_project_targets
+from .templates.project.apps_container_readme import apps_container_readme_template
+
+
+def json_error(error: PzError) -> str:
+    payload = error.to_dict()
+    payload["status"] = "error"
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True)
+
+
+def _success_payload(**payload: object) -> str:
+    return json.dumps({"status": "ok", **payload}, ensure_ascii=True, sort_keys=True)
+
+
+def _resolve_project_local_pz_docs_root(project_dir: Path) -> Path:
+    return resolve_project_local_pz_docs_root(project_dir)
+
+
+def _handle_command_error(*, exc: Exception, json_mode: bool, action: str) -> int:
+    error = as_pz_error(exc, owner="pz_core.authoring", action=action, stage="cli")
+    if json_mode:
+        print(json_error(error))
+    else:
+        print(str(error), file=sys.stderr)
+    return 1
+
+
+def _incomplete_orchestration_error(
+    exc: Exception,
+    *,
+    code: str,
+    action: str,
+    completed_stages: list[str],
+    next_stage: str,
+    selected_version: str | None = None,
+) -> PzError:
+    original = as_pz_error(
+        exc, owner="pz_core.authoring", action=action, stage="cli"
+    )
+    context: dict[str, object] = {
+        "completed_stages": list(completed_stages),
+        "next_stage": next_stage,
+        "original_code": original.code,
+    }
+    if selected_version is not None:
+        context["selected_version"] = selected_version
+    return PzError(
+        code=code,
+        message="orchestration stopped after one or more atomic stages completed.",
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+        detail=str(original),
+        context=context,
+    )
+
+
+def _print_success(*, json_mode: bool, text: str, **payload: object) -> None:
+    if json_mode:
+        print(_success_payload(message=text, **payload))
+    else:
+        print(text)
+
+
+def _prog(*parts: str) -> str:
+    return " ".join((resolve_program_name(), *parts))
+
+
+def _has_dev_source(project_dir: Path, app_id: str) -> bool:
+    manifest = load_dev_manifest(project_dir)
+    return manifest is not None and app_id in manifest.bindings
+
+
+def _print_dev_transaction(
+    result: DevTransactionResult,
+    *,
+    json_mode: bool,
+    ide_result: IdeSyncResult | None = None,
+) -> None:
+    repos = ", ".join(result.repo_keys) or "direct-link"
+    bindings = ", ".join(result.bindings) or "none"
+    ide_statuses = (
+        {}
+        if ide_result is None
+        else {item.provider: item.status for item in ide_result.providers}
+    )
+    ide_note = (
+        ""
+        if not ide_statuses
+        else " IDE projection: "
+        + ", ".join(f"{provider}={status}" for provider, status in ide_statuses.items())
+        + "."
+    )
+    text = (
+        f"Completed pz dev {result.operation}: repos={repos}; "
+        f"business_branch={result.business_branch}; "
+        f"base_branch={result.base_branch}; bindings={bindings}.{ide_note}"
+    )
+    _print_success(
+        json_mode=json_mode,
+        text=text,
+        operation=result.operation,
+        project_dir=str(result.project_dir),
+        business_branch=result.business_branch,
+        base_branch=result.base_branch,
+        repo_keys=list(result.repo_keys),
+        checkouts=[str(path) for path in result.checkouts],
+        bindings=list(result.bindings),
+        links=[str(path) for path in result.links],
+        updated=result.updated,
+        upstream=result.upstream,
+        checkout_deleted=result.checkout_deleted,
+        ide_providers=ide_statuses,
+    )
+
+
+def dev_ide_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="pz_core.authoring",
+            action="dev_ide_sync_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "ide", "sync"),
+            description="Synchronize PZ-owned IDE projections for visible minimal apps.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_ide_sync_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = sync_ide_projections(project_dir)
+        provider_statuses = {
+            item.provider: item.status for item in result.providers
+        }
+        _print_success(
+            json_mode=json_mode,
+            text=(
+                f"Synchronized IDE projection for {len(result.app_ids)} app(s): "
+                + ", ".join(
+                    f"{provider}={status}"
+                    for provider, status in provider_statuses.items()
+                )
+                + "."
+            ),
+            project_dir=str(result.project_dir),
+            app_ids=list(result.app_ids),
+            providers=provider_statuses,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc,
+            json_mode=json_mode,
+            action="dev_ide_sync_main",
+        )
+
+
+def dev_source_main(argv: list[object] | None = None) -> int:
+    args = list(argv or [])
+    json_mode = json_output_requested(args)
+    action = "dev_source_main"
+    try:
+        if not args:
+            raise PzError(
+                code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+                message="pz dev source requires cache/import/link/branch/update/unlink.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+            )
+        command = str(args.pop(0)).strip().lower()
+        normalized = normalize_cli_argv(
+            args,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "source", command),
+            description=f"Execute the atomic dev source {command} stage.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action=action,
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("source")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        if command in {"cache", "import"}:
+            parser.add_argument("--branch", default="develop")
+        if command == "cache":
+            parser.add_argument("--revision")
+        if command == "import":
+            parser.add_argument("--repo-key")
+            parser.add_argument("--revision")
+        if command in {"link", "branch"}:
+            add_cli_option(
+                parser,
+                "--base-branch",
+                choices=("develop", "main"),
+                default="develop",
+                dest="base_branch",
+            )
+        if command == "unlink":
+            add_cli_option(parser, "--delete-checkout", action="store_true", dest="delete_checkout")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        if command == "cache":
+            resolved = resolve_source_locator(ns.source, project_dir=project_dir, action=action)
+            if resolved.source_kind != "git" or resolved.repo_key is None:
+                raise PzError(
+                    code="PZ_DEV_SOURCE_NOT_GIT",
+                    message="dev source cache 只接受 Git 来源。",
+                    stage="dev",
+                    owner="pz_core.authoring",
+                    action=action,
+                )
+            result = cache_git_source(
+                repo_key=resolved.repo_key,
+                source=resolved.clone_source,
+                branch=ns.branch,
+                revision=ns.revision,
+                action=action,
+            )
+            _print_success(
+                json_mode=json_mode,
+                text=f"Cached {result.repo_key} at {result.commit}.",
+                repo_key=result.repo_key,
+                checkout=str(result.checkout),
+                commit=result.commit,
+                branch=result.branch,
+                resolution_ref=result.resolution_ref,
+            )
+            return 0
+        if command == "import":
+            if (ns.repo_key is None) != (ns.revision is None):
+                raise PzError(
+                    code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+                    message="Git 导入必须同时提供 --repo-key 和 --revision。",
+                    stage="cli",
+                    owner="pz_core.authoring",
+                    action=action,
+                )
+            if ns.repo_key is None:
+                result = import_local_dev_source(
+                    ns.source, project_dir=project_dir, action=action
+                )
+            else:
+                resolved = resolve_source_locator(
+                    ns.source, project_dir=project_dir, action=action
+                )
+                if resolved.source_kind != "git" or resolved.repo_key != ns.repo_key:
+                    raise PzError(
+                        code="PZ_DEV_CACHE_RESOLUTION_MISSING",
+                        message="source locator 与 cache repo key 不匹配。",
+                        stage="dev",
+                        owner="pz_core.authoring",
+                        action=action,
+                    )
+                cache = load_cached_git_source(
+                    repo_key=ns.repo_key,
+                    source=resolved.clone_source,
+                    revision=ns.revision,
+                    branch=ns.branch,
+                    action=action,
+                )
+                result = import_git_app(
+                    ns.source, cache=cache, project_dir=project_dir, action=action
+                )
+            _print_success(
+                json_mode=json_mode,
+                text=f"Imported {result.app_id} into {result.destination}.",
+                app_id=result.app_id,
+                destination=str(result.destination),
+                revision=result.commit,
+                created=result.created,
+            )
+            return 0
+        if command == "link":
+            result = add_dev_source(
+                AddDevSourceRequest(project_dir, (ns.source,), base_branch=ns.base_branch)
+            )
+            result = replace(result, operation="link")
+        elif command == "branch":
+            result = branch_dev_source(
+                BranchDevSourceRequest(project_dir, ns.source, base_branch=ns.base_branch)
+            )
+        elif command == "update":
+            from .dev_sources import UpdateDevSourceRequest, update_dev_source
+
+            result = update_dev_source(UpdateDevSourceRequest(project_dir, ns.source))
+        elif command == "unlink":
+            from .dev_sources import RemoveDevSourceRequest, remove_dev_source
+
+            result = remove_dev_source(
+                RemoveDevSourceRequest(project_dir, ns.source, delete_checkout=bool(ns.delete_checkout))
+            )
+            result = replace(result, operation="unlink")
+        else:
+            raise PzError(
+                code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+                message=f"unknown dev source command: {command}",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+            )
+        _print_dev_transaction(result, json_mode=json_mode)
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action=action)
+
+
+def _publish_result_message(result) -> str:
+    verb = "Built and dry-ran publish for" if result.dry_run else "Built and published"
+    return (
+        f"{verb} {result.app_id} {result.version} "
+        f"using target {result.target.name} from {result.dist_dir}."
+    )
+
+
+def _publish_atom_parser(command: str, argv: list[object] | None) -> tuple[object, Path, bool]:
+    action = f"publish_{command}_main"
+    normalized = normalize_cli_argv(
+        argv,
+        code="PZ_CLI_ARGV_INVALID",
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+    )
+    parser = PzArgumentParser(
+        prog=_prog("pub", command),
+        description=f"Execute the atomic pz pub {command} stage.",
+        error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+        error_stage="cli",
+        error_owner="pz_core.authoring",
+        error_action=action,
+    )
+    add_cli_option(parser, "--json", action="store_true")
+    parser.add_argument("app_id")
+    if command == "upload":
+        add_cli_option(parser, "--target")
+        add_cli_option(parser, "--dry-run", action="store_true")
+        parser.add_argument("--version")
+    add_cli_option(parser, "--project-dir", dest="project_dir")
+    ns = parser.parse_args(normalized)
+    return ns, resolve_project_dir(ns.project_dir), bool(getattr(ns, "json", False))
+
+
+def publish_commit_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        ns, project_dir, json_mode = _publish_atom_parser("commit", argv)
+        result = publish_commit(ns.app_id, project_dir=project_dir, action="publish_commit_main")
+        _print_success(
+            json_mode=json_mode,
+            text=f"Committed {result.source.app_id} {result.version} at {result.commit}.",
+            app_id=result.source.app_id,
+            version=result.version,
+            commit=result.commit,
+            reused=result.reused,
+            package_root=str(result.source.package_root),
+            git_root=str(result.source.git_root),
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="publish_commit_main")
+
+
+def publish_tag_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        ns, project_dir, json_mode = _publish_atom_parser("tag", argv)
+        result = publish_tag(ns.app_id, project_dir=project_dir, action="publish_tag_main")
+        _print_success(
+            json_mode=json_mode,
+            text=f"Tagged {result.commit_result.source.app_id} as {result.tag}.",
+            app_id=result.commit_result.source.app_id,
+            version=result.commit_result.version,
+            commit=result.commit_result.commit,
+            tag=result.tag,
+            reused=result.reused,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="publish_tag_main")
+
+
+def publish_upload_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    try:
+        ns, project_dir, json_mode = _publish_atom_parser("upload", argv)
+        result = publish_upload(
+            ns.app_id,
+            project_dir=project_dir,
+            target_name=ns.target,
+            dry_run=bool(ns.dry_run),
+            version=ns.version,
+            action="publish_upload_main",
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=_publish_result_message(result),
+            app_id=result.app_id,
+            version=result.version,
+            commit=result.commit,
+            tag=result.tag,
+            target=result.target.name,
+            dry_run=result.dry_run,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="publish_upload_main")
+
+
+def _unpublish_result_message(result) -> str:
+    versions = ", ".join(result.removed_versions)
+    verb = "Planned unpublish for" if result.dry_run else "Unpublished"
+    force_suffix = " with force" if result.force else ""
+    return (
+        f"{verb} {result.app_id} ({result.distribution_name}) versions [{versions}] "
+        f"from target {result.target.name}{force_suffix}."
+    )
+
+
+def _require_uv(*, action: str) -> str:
+    uv_binary = shutil.which("uv")
+    if uv_binary:
+        return uv_binary
+    raise PzError(
+        code="PZ_SCAFFOLD_UV_MISSING",
+        message="required dependency backend was not found on PATH.",
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+    )
+
+
+def _install_distribution(
+    app_id: str, *, project_dir: Path, upgrade: bool, action: str
+) -> str:
+    uv_binary = _require_uv(action=action)
+    distribution = app_id.replace("_", "-")
+    argv = [uv_binary, "pip", "install", "--python", sys.executable]
+    if upgrade:
+        argv.append("--upgrade")
+    argv.append(distribution)
+    env = install_env(
+        target=load_install_target(app_id, project_dir=project_dir, action=action),
+        project_dir=project_dir,
+        action=action,
+    )
+    completed = subprocess.run(
+        argv, check=False, capture_output=True, text=True, env=env
+    )
+    if completed.returncode != 0:
+        detail = (
+            completed.stderr or completed.stdout or "dependency install failed"
+        ).strip()
+        raise PzError(
+            code="PZ_SCAFFOLD_INSTALL_FAILED",
+            message=f"failed to install {app_id}.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=detail,
+        )
+    return distribution
+
+
+def startapp_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="pz_core.authoring",
+            action="startapp_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("startapp"),
+            description="Create a formal minimal package under apps/<app_id>/.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="startapp_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("name")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        add_cli_option(
+            parser,
+            "--target-dir",
+            dest="target_dir",
+            help="Directory that will contain <app_id>/; defaults to <project-dir>/apps.",
+        )
+        ns = parser.parse_args(normalized)
+        slug = normalize_app_slug(ns.name, action="startapp_main")
+        app_id = build_app_id(slug)
+        project_dir = resolve_project_dir(ns.project_dir)
+        default_target_dir = (project_dir / "apps").resolve()
+        if ns.target_dir:
+            raw_target_dir = Path(ns.target_dir).expanduser()
+            target_dir = (
+                raw_target_dir
+                if raw_target_dir.is_absolute()
+                else project_dir / raw_target_dir
+            )
+            target_dir = target_dir.resolve()
+        else:
+            target_dir = default_target_dir
+        if target_dir.exists() and not target_dir.is_dir():
+            raise PzError(
+                code="PZ_SCAFFOLD_APPS_DIR_MISSING",
+                message=f"app container path is not a directory: {target_dir}",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="startapp_main",
+            )
+        target_dir.mkdir(parents=True, exist_ok=True)
+        write_files(
+            app_files(project_dir, app_id, target_dir=target_dir),
+            action="startapp_main",
+        )
+        settings_path: Path | None = None
+        if target_dir == default_target_dir:
+            append_or_create_file(
+                target_dir / "README.md", apps_container_readme_template()
+            )
+            add_declared_app(project_dir, app_id, action="startapp_main")
+            settings_path = update_settings_file(project_dir).path
+        if json_mode:
+            print(
+                _success_payload(
+                    message=f"Created app scaffold for {app_id}.",
+                    app_id=app_id,
+                    target_dir=str(target_dir),
+                    settings_path=None if settings_path is None else str(settings_path),
+                    settings_updated=settings_path is not None,
+                )
+            )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="startapp_main"
+        )
+
+
+def app_add_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    version: str | None = None
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="app_add_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "add"),
+            description="Declare a formal minimal app and install its released distribution into the current runtime.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_add_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        parser.add_argument("--version")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        ensure_project_state(project_dir, action="app_add_main")
+        app_id = normalize_formal_app_id(ns.app_id, action="app_add_main")
+        state = query_app_versions(app_id, project_dir=project_dir, action="app_add_main")
+        recovering = (
+            state.declared is not None
+            and (state.locked != state.declared or state.installed != state.declared)
+            and (ns.version is None or ns.version == state.declared)
+        )
+        version = state.declared if recovering else resolve_app_version(
+            state, ns.version, action="app_add_main", project_dir=project_dir
+        )
+        assert version is not None
+        completed_stages.append("versions")
+        installed_apps = load_installed_apps(project_dir, action="app_add_main")
+        if state.declared == version and app_id in installed_apps:
+            declared_apps = tuple(installed_apps)
+        else:
+            declaration = declare_app_version(
+                app_id, version, project_dir=project_dir, action="app_add_main"
+            )
+            declared_apps = declaration.installed_apps
+        completed_stages.append("declare")
+        if state.locked == version and state.installed == version:
+            distribution = state.distribution
+            lock_path = project_dir / "uv.lock"
+        else:
+            installation = install_declared_app(
+                app_id, version, project_dir=project_dir, action="app_add_main"
+            )
+            distribution = installation.distribution
+            lock_path = installation.lock_path
+        completed_stages.append("install")
+        settings_path = update_settings_file(project_dir).path
+        completed_stages.append("settings")
+        _print_success(
+            json_mode=json_mode,
+            text=f"Declared and installed {distribution}=={version} into the project environment.",
+            app_id=app_id,
+            distribution=distribution,
+            version=version,
+            installed_apps=list(declared_apps),
+            lock_path=str(lock_path),
+            settings_path=str(settings_path),
+            completed_stages=completed_stages,
+        )
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("versions", "declare", "install", "settings")
+            next_stage = stages[min(len(completed_stages), len(stages) - 1)]
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_APP_ORCHESTRATION_INCOMPLETE",
+                action="app_add_main",
+                completed_stages=completed_stages,
+                next_stage=next_stage,
+                selected_version=version,
+            )
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="app_add_main"
+        )
+
+
+def app_rm_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="app_rm_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "rm"),
+            description="Remove a formal minimal app from the current project declaration.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_rm_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        ensure_project_state(project_dir, action="app_rm_main")
+        app_id = normalize_formal_app_id(ns.app_id, action="app_rm_main")
+        installed_apps = load_installed_apps(project_dir, action="app_rm_main")
+        if app_id not in installed_apps:
+            raise PzError(
+                code="PZ_SCAFFOLD_APP_NOT_DECLARED",
+                message=f"{app_id} is not declared in project installed_apps.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="app_rm_main",
+            )
+        declaration = undeclare_app_version(
+            app_id, project_dir=project_dir, action="app_rm_main"
+        )
+        completed_stages.append("undeclare")
+        reconcile_project_environment(
+            app_id, project_dir=project_dir, action="app_rm_main"
+        )
+        completed_stages.append("env_sync")
+        settings_path = update_settings_file(project_dir).path
+        completed_stages.append("settings")
+        note = ""
+        if _has_dev_source(project_dir, app_id):
+            note = " Local dev source still exists; run `pz dev unlink <app_id>` to fully stop auto-discovery."
+        _print_success(
+            json_mode=json_mode,
+            text=f"Removed {app_id} from project declaration.{note}",
+            app_id=app_id,
+            installed_apps=list(declaration.installed_apps),
+            has_dev_source=_has_dev_source(project_dir, app_id),
+            settings_path=str(settings_path),
+            completed_stages=completed_stages,
+        )
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("undeclare", "env_sync", "settings")
+            next_stage = stages[min(len(completed_stages), len(stages) - 1)]
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_APP_ORCHESTRATION_INCOMPLETE",
+                action="app_rm_main",
+                completed_stages=completed_stages,
+                next_stage=next_stage,
+            )
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="app_rm_main")
+
+
+def app_update_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    version: str | None = None
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="app_update_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "update"),
+            description="Refresh the installed package for an already-declared formal app.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_update_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        parser.add_argument("--version")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        ensure_project_state(project_dir, action="app_update_main")
+        app_id = normalize_formal_app_id(ns.app_id, action="app_update_main")
+        installed_apps = load_installed_apps(project_dir, action="app_update_main")
+        if app_id not in installed_apps:
+            raise PzError(
+                code="PZ_SCAFFOLD_APP_NOT_DECLARED",
+                message=f"{app_id} is not declared in project installed_apps.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="app_update_main",
+            )
+        state = query_app_versions(app_id, project_dir=project_dir, action="app_update_main")
+        recovering = (
+            state.declared is not None
+            and (state.locked != state.declared or state.installed != state.declared)
+            and (ns.version is None or ns.version == state.declared)
+        )
+        version = state.declared if recovering else resolve_app_version(
+            state, ns.version, action="app_update_main", project_dir=project_dir
+        )
+        assert version is not None
+        completed_stages.append("versions")
+        if state.declared == version:
+            declared_apps = tuple(installed_apps)
+        else:
+            declaration = declare_app_version(
+                app_id, version, project_dir=project_dir, action="app_update_main"
+            )
+            declared_apps = declaration.installed_apps
+        completed_stages.append("declare")
+        if state.locked == version and state.installed == version:
+            distribution = state.distribution
+        else:
+            installation = install_declared_app(
+                app_id, version, project_dir=project_dir, action="app_update_main"
+            )
+            distribution = installation.distribution
+        completed_stages.append("install")
+        settings_path = update_settings_file(project_dir).path
+        completed_stages.append("settings")
+        note = ""
+        if _has_dev_source(project_dir, app_id):
+            note = " Local dev source still has higher precedence than the installed package."
+        _print_success(
+            json_mode=json_mode,
+            text=f"Updated {distribution} to {version}.{note}",
+            app_id=app_id,
+            distribution=distribution,
+            version=version,
+            installed_apps=list(declared_apps),
+            has_dev_source=_has_dev_source(project_dir, app_id),
+            settings_path=str(settings_path),
+            completed_stages=completed_stages,
+        )
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("versions", "declare", "install", "settings")
+            next_stage = stages[min(len(completed_stages), len(stages) - 1)]
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_APP_ORCHESTRATION_INCOMPLETE",
+                action="app_update_main",
+                completed_stages=completed_stages,
+                next_stage=next_stage,
+                selected_version=version,
+            )
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="app_update_main"
+        )
+
+
+def app_versions_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="pz_core.authoring",
+            action="app_versions_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "versions"),
+            description="List published and current project versions for one app.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_versions_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        app_id = normalize_formal_app_id(ns.app_id, action="app_versions_main")
+        state = query_app_versions(app_id, project_dir=project_dir, action="app_versions_main")
+        available = [
+            {
+                "version": item.version,
+                "prerelease": item.prerelease,
+                "yanked": item.yanked,
+                "compatible": item.compatible,
+            }
+            for item in state.available
+        ]
+        if json_mode:
+            print(
+                _success_payload(
+                    app_id=state.app_id,
+                    distribution=state.distribution,
+                    available=available,
+                    latest=state.latest,
+                    declared=state.declared,
+                    locked=state.locked,
+                    installed=state.installed,
+                )
+            )
+        else:
+            print(f"Versions for {state.app_id} ({state.distribution}):")
+            for item in state.available:
+                markers = []
+                if item.version == state.latest:
+                    markers.append("latest")
+                if item.version == state.declared:
+                    markers.append("declared")
+                if item.version == state.locked:
+                    markers.append("locked")
+                if item.version == state.installed:
+                    markers.append("installed")
+                if item.prerelease:
+                    markers.append("prerelease")
+                if item.yanked:
+                    markers.append("yanked")
+                suffix = f" [{', '.join(markers)}]" if markers else ""
+                print(f"  {item.version}{suffix}")
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="app_versions_main")
+
+
+def app_declare_main(argv: list[object] | None = None) -> int:
+    return _app_declaration_main(argv, remove=False)
+
+
+def app_undeclare_main(argv: list[object] | None = None) -> int:
+    return _app_declaration_main(argv, remove=True)
+
+
+def _app_declaration_main(argv: list[object] | None, *, remove: bool) -> int:
+    action = "app_undeclare_main" if remove else "app_declare_main"
+    command = "undeclare" if remove else "declare"
+    json_mode = json_output_requested(argv)
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", command),
+            description=f"Atomically {command} an exact app dependency.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action=action,
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        if not remove:
+            parser.add_argument("--version", required=True)
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        app_id = normalize_formal_app_id(ns.app_id, action=action)
+        result = (
+            undeclare_app_version(app_id, project_dir=project_dir, action=action)
+            if remove
+            else declare_app_version(app_id, ns.version, project_dir=project_dir, action=action)
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=f"{command.title()}d {result.distribution}{'' if result.version is None else '==' + result.version}.",
+            app_id=app_id,
+            distribution=result.distribution,
+            version=result.version,
+            installed_apps=list(result.installed_apps),
+            changed=result.changed,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action=action)
+
+
+def app_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="pz_core.authoring",
+            action="app_install_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "install"),
+            description="Install one already-declared exact app version.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_install_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        parser.add_argument("--version", required=True)
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        app_id = normalize_formal_app_id(ns.app_id, action="app_install_main")
+        result = install_declared_app(
+            app_id, ns.version, project_dir=project_dir, action="app_install_main"
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=f"Installed {result.distribution}=={result.version}.",
+            app_id=app_id,
+            distribution=result.distribution,
+            version=result.version,
+            python=str(result.python),
+            lock_path=str(result.lock_path),
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="app_install_main")
+
+
+def app_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="pz_core.authoring",
+            action="app_init_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("app", "init"),
+            description=(
+                "Initialize project default packages from existing apps/.sources metadata."
+            ),
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="app_init_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        add_cli_option(
+            parser,
+            "--no-sync",
+            action="store_true",
+            dest="no_sync",
+            help="Skip project virtualenv preparation and distribution installation.",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = execute_app_init(
+            project_dir,
+            no_sync=bool(ns.no_sync),
+            action="app_init_main",
+        )
+        discovered_apps = [item.app_id for item in result.source_apps.discovered_apps]
+        if result.project_venv is None:
+            project_venv = None
+            project_venv_created = False
+            text = (
+                f"Declared {len(discovered_apps)} default app(s) from apps/.sources. "
+                "Distribution installation and project virtualenv preparation were skipped."
+            )
+        else:
+            project_venv = str(result.project_venv.path)
+            project_venv_created = result.project_venv.created
+            text = (
+                f"Declared {len(discovered_apps)} default app(s) from apps/.sources "
+                f"and installed {len(result.source_install.distributions)} distribution(s) "
+                f"into project virtualenv {result.project_venv.path}."
+            )
+        _print_success(
+            json_mode=json_mode,
+            text=text,
+            discovered_apps=discovered_apps,
+            declared_apps=list(result.source_apps.declared_apps),
+            installed_apps=list(result.source_apps.installed_apps),
+            project_venv=project_venv,
+            project_venv_created=project_venv_created,
+            install_distributions=list(result.source_install.distributions),
+            install_target=None
+            if result.source_install.install_target is None
+            else result.source_install.install_target.name,
+            install_index_url=None
+            if result.source_install.install_target is None
+            else result.source_install.install_target.index_url,
+            install_targets=[
+                target.name for target in result.source_install.install_targets
+            ],
+            install_index_urls=[
+                target.index_url for target in result.source_install.install_targets
+            ],
+            install_python=None
+            if result.source_install.python is None
+            else str(result.source_install.python),
+            synced_targets=[str(item.path) for item in result.synced_targets],
+            settings_path=None
+            if result.settings_path is None
+            else str(result.settings_path),
+            settings_updated=result.settings_path is not None,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="app_init_main"
+        )
+
+
+def dev_link_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="dev_link_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "link"),
+            description="Bind one Git repository, directory, or app leaf for development.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_link_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("source")
+        add_cli_option(
+            parser,
+            "--base-branch",
+            choices=("develop", "main"),
+            default="develop",
+            dest="base_branch",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = add_dev_source(
+            AddDevSourceRequest(
+                project_dir=project_dir,
+                locators=(ns.source,),
+                base_branch=ns.base_branch,
+            )
+        )
+        result = replace(result, operation="link")
+        completed_stages.append("source_link")
+        update_project_uv_sources(project_dir, action="dev_link_main")
+        completed_stages.append("project_sources")
+        update_settings_file(project_dir)
+        completed_stages.append("settings")
+        sync_project_targets(project_dir, action="dev_link_main")
+        completed_stages.append("env_sync")
+        ide_result = sync_ide_projections(project_dir)
+        completed_stages.append("ide_sync")
+        _print_dev_transaction(result, json_mode=json_mode, ide_result=ide_result)
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("source_link", "project_sources", "settings", "env_sync", "ide_sync")
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_DEV_ORCHESTRATION_INCOMPLETE",
+                action="dev_link_main",
+                completed_stages=completed_stages,
+                next_stage=stages[min(len(completed_stages), len(stages) - 1)],
+            )
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="dev_link_main"
+        )
+
+
+def dev_add_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="dev_add_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "add"),
+            description="Import one formal minimal app into business-owned apps source.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_add_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("source")
+        parser.add_argument("--branch", default="develop")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        resolved = resolve_source_locator(
+            ns.source, project_dir=project_dir, action="dev_add_main"
+        )
+        if resolved.source_kind == "git":
+            assert resolved.repo_key is not None
+            cached = cache_git_source(
+                repo_key=resolved.repo_key,
+                source=resolved.clone_source,
+                branch=ns.branch,
+                action="dev_add_main",
+            )
+            completed_stages.append("source_cache")
+            pinned = load_cached_git_source(
+                repo_key=cached.repo_key,
+                source=cached.source,
+                revision=cached.commit,
+                branch=cached.branch,
+                action="dev_add_main",
+            )
+            result = import_git_app(
+                ns.source,
+                cache=pinned,
+                project_dir=project_dir,
+                action="dev_add_main",
+            )
+        else:
+            result = find_existing_local_import(
+                ns.source, project_dir=project_dir, action="dev_add_main"
+            ) or import_local_dev_source(
+                ns.source, project_dir=project_dir, action="dev_add_main"
+            )
+        completed_stages.append("source_import")
+        settings = update_settings_file(project_dir)
+        completed_stages.append("settings")
+        synced = sync_project_targets(project_dir, action="dev_add_main")
+        completed_stages.append("env_sync")
+        ide_result = sync_ide_projections(project_dir)
+        completed_stages.append("ide_sync")
+        ide_statuses = {
+            item.provider: item.status for item in ide_result.providers
+        }
+        _print_success(
+            json_mode=json_mode,
+            text=f"Imported {result.app_id} into {result.destination} for business ownership.",
+            app_id=result.app_id,
+            destination=str(result.destination),
+            revision=result.commit,
+            created=result.created,
+            settings_path=str(settings.path),
+            synced_targets=[str(item.path) for item in synced],
+            ide_providers=ide_statuses,
+            completed_stages=completed_stages,
+        )
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("source_cache", "source_import", "settings", "env_sync", "ide_sync")
+            if completed_stages[0] != "source_cache":
+                stages = ("source_import", "settings", "env_sync", "ide_sync")
+            next_stage = stages[min(len(completed_stages), len(stages) - 1)]
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_DEV_ORCHESTRATION_INCOMPLETE",
+                action="dev_add_main",
+                completed_stages=completed_stages,
+                next_stage=next_stage,
+            )
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="dev_add_main")
+
+
+def dev_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="pz_core.authoring",
+            action="dev_init_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "init"),
+            description="Initialize a project by importing official apps or explicitly linking sources.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_init_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        add_cli_option(parser, "--app-name")
+        add_cli_option(
+            parser,
+            "--base-branch",
+            choices=("develop", "main"),
+            default="develop",
+            dest="base_branch",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        parser.add_argument("--link", action="store_true")
+        parser.add_argument("--source-dir", dest="source_dir")
+        add_cli_option(
+            parser,
+            "--clone-sources",
+            action="store_true",
+            dest="clone_sources",
+        )
+        add_cli_option(
+            parser,
+            "--no-sync",
+            action="store_true",
+            dest="no_sync",
+            help="Skip the final project environment installation.",
+        )
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        if bool(ns.link) and bool(ns.clone_sources) == bool(ns.source_dir):
+            raise PzError(
+                code="PZ_DEV_INIT_SOURCE_SELECTOR_INVALID",
+                message="pz dev init --link 必须且只能指定 --clone-sources 或 --source-dir。",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="dev_init_main",
+            )
+        if not ns.link and (ns.clone_sources or ns.source_dir):
+            raise PzError(
+                code="PZ_DEV_INIT_SOURCE_SELECTOR_INVALID",
+                message="--clone-sources 和 --source-dir 只能与 --link 一起使用。",
+                stage="cli",
+                owner="pz_core.authoring",
+                action="dev_init_main",
+            )
+        progress_reporter = None if json_mode else print
+        preparation, result = execute_dev_init(
+            project_dir,
+            app_name=ns.app_name,
+            base_branch=ns.base_branch,
+            clone_sources=bool(ns.clone_sources),
+            link=bool(ns.link),
+            source_dir=ns.source_dir,
+            no_sync=bool(ns.no_sync),
+            action="dev_init_main",
+            progress_reporter=progress_reporter,
+        )
+        bootstrap_note = ""
+        if (
+            preparation.scaffold_created
+            and preparation.default_app_created
+            and preparation.default_app_id is not None
+        ):
+            bootstrap_note = f" Created a new project scaffold and default local app `{preparation.default_app_id}` first."
+        elif preparation.scaffold_created:
+            bootstrap_note = " Created a new project scaffold first."
+        elif preparation.default_app_created and preparation.default_app_id is not None:
+            bootstrap_note = (
+                f" Added the default local app `{preparation.default_app_id}`."
+            )
+        project_venv = (
+            None
+            if preparation.project_venv is None
+            else str(preparation.project_venv.path)
+        )
+        project_venv_created = (
+            False
+            if preparation.project_venv is None
+            else preparation.project_venv.created
+        )
+        install_note = (
+            " Initial environment install was skipped. Run `pz env install` before `pz run`."
+            if ns.no_sync
+            else " Initial environment install finished. `pz run` can start directly."
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=(
+                (
+                    "Initialized linked development sources on business branch "
+                    if ns.link
+                    else "Imported official pz_apps source into business ownership for "
+                )
+                + f"{result.business_branch}."
+                f"{bootstrap_note}"
+                f"{install_note}"
+            ),
+            operation=result.operation,
+            business_branch=result.business_branch,
+            base_branch=result.base_branch,
+            repo_keys=list(result.repo_keys),
+            checkouts=[str(path) for path in result.checkouts],
+            bindings=list(result.bindings),
+            links=[str(path) for path in result.links],
+            project_scaffold_created=preparation.scaffold_created,
+            default_app_created=preparation.default_app_created,
+            default_app_id=preparation.default_app_id,
+            project_venv=project_venv,
+            project_venv_created=project_venv_created,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="dev_init_main"
+        )
+
+
+def dev_update_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="dev_update_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "update"),
+            description="Fast-forward a managed checkout on its business branch.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_update_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("repo_or_app")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        from .dev_sources import UpdateDevSourceRequest, update_dev_source
+
+        result = update_dev_source(UpdateDevSourceRequest(project_dir, ns.repo_or_app))
+        completed_stages.append("source_update")
+        sync_project_targets(project_dir, action="dev_update_main")
+        completed_stages.append("env_sync")
+        ide_result = sync_ide_projections(project_dir)
+        completed_stages.append("ide_sync")
+        _print_dev_transaction(result, json_mode=json_mode, ide_result=ide_result)
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("source_update", "env_sync", "ide_sync")
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_DEV_ORCHESTRATION_INCOMPLETE",
+                action="dev_update_main",
+                completed_stages=completed_stages,
+                next_stage=stages[min(len(completed_stages), len(stages) - 1)],
+            )
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="dev_update_main"
+        )
+
+
+def dev_branch_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="dev_branch_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "branch"),
+            description="Prepare an existing managed checkout on the business branch.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_branch_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("repo_or_app")
+        add_cli_option(
+            parser,
+            "--base-branch",
+            choices=("develop", "main"),
+            default="develop",
+            dest="base_branch",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = branch_dev_source(
+            BranchDevSourceRequest(
+                project_dir=project_dir,
+                locator=ns.repo_or_app,
+                base_branch=ns.base_branch,
+            )
+        )
+        completed_stages.append("source_branch")
+        sync_project_targets(project_dir, action="dev_branch_main")
+        completed_stages.append("env_sync")
+        ide_result = sync_ide_projections(project_dir)
+        completed_stages.append("ide_sync")
+        _print_dev_transaction(result, json_mode=json_mode, ide_result=ide_result)
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("source_branch", "env_sync", "ide_sync")
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_DEV_ORCHESTRATION_INCOMPLETE",
+                action="dev_branch_main",
+                completed_stages=completed_stages,
+                next_stage=stages[min(len(completed_stages), len(stages) - 1)],
+            )
+        return _handle_command_error(
+            exc=exc,
+            json_mode=json_mode,
+            action="dev_branch_main",
+        )
+
+
+def dev_unlink_main(argv: list[object] | None = None) -> int:
+    json_mode = json_output_requested(argv)
+    completed_stages: list[str] = []
+    try:
+        normalized = normalize_cli_argv(
+            argv,
+            code="PZ_CLI_ARGV_INVALID",
+            stage="cli",
+            owner="pz_core.authoring",
+            action="dev_unlink_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("dev", "unlink"),
+            description="Remove one managed binding and optionally its safe checkout.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="dev_unlink_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("binding")
+        add_cli_option(
+            parser,
+            "--delete-checkout",
+            action="store_true",
+            dest="delete_checkout",
+        )
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        from .dev_sources import RemoveDevSourceRequest, remove_dev_source
+
+        result = remove_dev_source(
+            RemoveDevSourceRequest(
+                project_dir,
+                ns.binding,
+                delete_checkout=bool(ns.delete_checkout),
+            )
+        )
+        result = replace(result, operation="unlink")
+        completed_stages.append("source_unlink")
+        update_project_uv_sources(project_dir, action="dev_unlink_main")
+        completed_stages.append("project_sources")
+        update_settings_file(project_dir)
+        completed_stages.append("settings")
+        sync_project_targets(project_dir, action="dev_unlink_main")
+        completed_stages.append("env_sync")
+        ide_result = sync_ide_projections(project_dir)
+        completed_stages.append("ide_sync")
+        _print_dev_transaction(result, json_mode=json_mode, ide_result=ide_result)
+        return 0
+    except Exception as exc:
+        if completed_stages:
+            stages = ("source_unlink", "project_sources", "settings", "env_sync", "ide_sync")
+            exc = _incomplete_orchestration_error(
+                exc,
+                code="PZ_DEV_ORCHESTRATION_INCOMPLETE",
+                action="dev_unlink_main",
+                completed_stages=completed_stages,
+                next_stage=stages[min(len(completed_stages), len(stages) - 1)],
+            )
+        return _handle_command_error(exc=exc, json_mode=json_mode, action="dev_unlink_main")
+
+
+# Internal compatibility for callers migrating from the pre-cutover function name.
+dev_rm_main = dev_unlink_main
+
+
+def publish_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="pz_core.authoring",
+            action="publish_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("pub"),
+            description="Build and publish a versioned release artifact for a formal minimal app.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="publish_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        add_cli_option(parser, "--target")
+        add_cli_option(parser, "--dry-run", action="store_true")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = publish_app(
+            ns.app_id,
+            project_dir=project_dir,
+            target_name=ns.target,
+            dry_run=bool(ns.dry_run),
+            action="publish_main",
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=_publish_result_message(result),
+            app_id=result.app_id,
+            version=result.version,
+            package_root=str(result.package_root),
+            dist_dir=str(result.dist_dir),
+            target=result.target.name,
+            dry_run=result.dry_run,
+            commit=result.commit,
+            tag=result.tag,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="publish_main"
+        )
+
+
+def publish_batch_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="pz_core.authoring",
+            action="publish_batch_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("pub", "batch"),
+            description="Publish multiple versioned release artifacts in the explicit order provided.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="publish_batch_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_ids", nargs="+")
+        add_cli_option(parser, "--target")
+        add_cli_option(parser, "--dry-run", action="store_true")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+
+        execution = execute_publish_batch(
+            ns.app_ids,
+            project_dir=project_dir,
+            target_name=ns.target,
+            dry_run=bool(ns.dry_run),
+            action="publish_batch_main",
+        )
+        results = list(execution.results)
+        for result in results:
+            if not json_mode:
+                print(_publish_result_message(result))
+        if json_mode:
+            print(
+                _success_payload(
+                    message=execution.summary_message,
+                    dry_run=bool(ns.dry_run),
+                    target=results[0].target.name
+                    if results
+                    else (ns.target or "default"),
+                    results=[
+                        {
+                            "app_id": result.app_id,
+                            "version": result.version,
+                            "package_root": str(result.package_root),
+                            "dist_dir": str(result.dist_dir),
+                        }
+                        for result in results
+                    ],
+                )
+            )
+        else:
+            print(execution.summary_message)
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="publish_batch_main"
+        )
+
+
+def publish_rm_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="pz_core.authoring",
+            action="publish_rm_main",
+        )
+        parser = PzArgumentParser(
+            prog=_prog("pub", "rm"),
+            description="Remove all published release artifacts for one versioned package from a publish target.",
+            error_code="PZ_SCAFFOLD_ARGUMENTS_INVALID",
+            error_stage="cli",
+            error_owner="pz_core.authoring",
+            error_action="publish_rm_main",
+        )
+        add_cli_option(parser, "--json", action="store_true")
+        parser.add_argument("app_id")
+        add_cli_option(parser, "--target")
+        add_cli_option(parser, "--dry-run", action="store_true")
+        add_cli_option(parser, "--force", action="store_true")
+        add_cli_option(parser, "--project-dir", dest="project_dir")
+        ns = parser.parse_args(normalized)
+        project_dir = resolve_project_dir(ns.project_dir)
+        result = unpublish_app(
+            ns.app_id,
+            project_dir=project_dir,
+            target_name=ns.target,
+            dry_run=bool(ns.dry_run),
+            force=bool(ns.force),
+            action="publish_rm_main",
+        )
+        _print_success(
+            json_mode=json_mode,
+            text=_unpublish_result_message(result),
+            app_id=result.app_id,
+            distribution_name=result.distribution_name,
+            version=result.version,
+            package_root=str(result.package_root),
+            target=result.target.name,
+            removed_versions=list(result.removed_versions),
+            dry_run=result.dry_run,
+            force=result.force,
+        )
+        return 0
+    except Exception as exc:
+        return _handle_command_error(
+            exc=exc, json_mode=json_mode, action="publish_rm_main"
+        )
+
+
+__all__ = [
+    "app_add_main",
+    "app_init_main",
+    "app_rm_main",
+    "app_update_main",
+    "dev_add_main",
+    "dev_branch_main",
+    "dev_ide_sync_main",
+    "dev_init_main",
+    "dev_link_main",
+    "dev_rm_main",
+    "dev_source_main",
+    "dev_unlink_main",
+    "dev_update_main",
+    "json_error",
+    "publish_main",
+    "publish_batch_main",
+    "publish_commit_main",
+    "publish_rm_main",
+    "publish_tag_main",
+    "publish_upload_main",
+    "startapp_main",
+]