pz-cli 5.0.0__tar.gz → 5.0.2__tar.gz

{pz_cli-5.0.0 → pz_cli-5.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pz-cli
-Version: 5.0.0
+Version: 5.0.2
 Summary: PZ CLI, runtime compiler, settings owner, and foundation runtime
 Project-URL: Homepage, https://github.com/JiXiangTools/pz
 Project-URL: Repository, https://github.com/JiXiangTools/pz
@@ -36,14 +36,14 @@ Description-Content-Type: text/markdown
 
 `pz-cli` is the single install and release unit for the PZ base runtime.
 
-Version 5.0.0 bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
+The version declared by the root `pyproject.toml` bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
 Python packages in one wheel and exposes the formal `pz` command. The retired
 `pz-core`, `pz-contrib`, `pz-settings-center`, and `pz-foundation`
 distributions are no longer built or installed separately. Business packages
 from the `pz_apps` repository remain independent distributions.
 
 ```bash
-pip install pz-cli==5.0.0
+pip install pz-cli
 ```
 
 The source checkout uses one root `pyproject.toml` and one root `uv.lock`.

{pz_cli-5.0.0 → pz_cli-5.0.2}/README.md

@@ -2,14 +2,14 @@
 
 `pz-cli` is the single install and release unit for the PZ base runtime.
 
-Version 5.0.0 bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
+The version declared by the root `pyproject.toml` bundles the `pz_core`, `pz_settings_center`, and `pz_foundation`
 Python packages in one wheel and exposes the formal `pz` command. The retired
 `pz-core`, `pz-contrib`, `pz-settings-center`, and `pz-foundation`
 distributions are no longer built or installed separately. Business packages
 from the `pz_apps` repository remain independent distributions.
 
 ```bash
-pip install pz-cli==5.0.0
+pip install pz-cli
 ```
 
 The source checkout uses one root `pyproject.toml` and one root `uv.lock`.

{pz_cli-5.0.0 → pz_cli-5.0.2}/docs/superpowers/specs/2026-07-13-pz-app-version-resolution-design.md

@@ -2,8 +2,11 @@
 
 ## Status
 
-This document defines the implemented contract for version-aware package
-installation in `pz app`.
+This document defines the original implemented contract for version-aware
+package installation in `pz app`. Source selection, Git package-tag installs,
+and the replacement of the index-only model are now owned by the formal
+`pz_core/pz_core/docs/pz规范与使用/09-CLI与Worker入口规范.md`; the exact-version,
+PEP 440, orchestration, and retry contracts below remain applicable.
 
 ## Goal
 
@@ -13,7 +16,8 @@ reproducible exact installed version.
 
 The normal workflow must be simple:
 
-- `pz app add <app_id>` installs the latest compatible stable version;
+- `pz app add <app_id>` installs the latest compatible stable version from the
+  selected source, defaulting to `internal-pypi`;
 - `pz app add <app_id> --version <version>` installs one exact version;
 - `pz app update <app_id>` resolves the latest compatible stable version;
 - `pz app update <app_id> --version <version>` moves to one exact version;
@@ -26,16 +30,16 @@ PZ retains the explicit atomic-command plus orchestration-command model.
 Orchestration commands are:
 
 - `pz app init`;
-- `pz app add <app_id> [--version <version>]`;
-- `pz app update <app_id> [--version <version>]`;
+- `pz app add <app_id> [--source <source>] [--version <version>]`;
+- `pz app update <app_id> [--source <source>] [--version <version>]`;
 - `pz app rm <app_id>`.
 
 Public atomic commands are:
 
 - `pz app versions <app_id>`;
-- `pz app declare <app_id> --version <version>`;
+- `pz app declare <app_id> --version <version> [--source <source>]`;
 - `pz app undeclare <app_id>`;
-- `pz app install <app_id> --version <version>`.
+- `pz app install <app_id> --version <version> [--source <source>]`.
 
 The orchestrators also reuse atomic `pz settings update` and environment sync
 capabilities. Each command belongs to exactly one layer. Normal human workflows
@@ -63,7 +67,10 @@ minimal apps.
 ## Version Resolution
 
 Without `--version`, `app add`, `app update`, and `app init` resolve the latest
-compatible stable version from the configured formal package index.
+compatible stable version from the configured `AppSourceCatalog` source.
+PyPI sources enumerate releases through the Simple API. Git sources enumerate
+formal `<distribution>@<version>` package tags and resolve the selected tag to
+one full commit and exact leaf subdirectory.
 
 The resolver must:
 
@@ -86,9 +93,9 @@ package dependency metadata, not an ambiguous project installation request.
 
 ## `pz app versions`
 
-`pz app versions <app_id>` is read-only and performs no project, environment,
-or index mutation. It resolves the formal distribution and configured package
-index, then reports:
+`pz app versions <app_id> [--source <source_id>]` is read-only and performs no
+project, environment, Git remote, or index mutation. It resolves the formal
+distribution and selected catalog source, then reports:
 
 - `app_id` and distribution name;
 - all available versions in descending PEP 440 order;
@@ -106,10 +113,19 @@ redacted.
 
 ### `pz app declare`
 
-`pz app declare <app_id> --version <version>` atomically writes the exact
-distribution pin and app identity/load-order declaration. It does not install
-the package or refresh app settings. Repeating an exact matching declaration is
-idempotent; conflicting local source ownership is a hard error.
+`pz app declare <app_id> --version <version> [--source <source>]` atomically
+writes the exact distribution plan and app identity/load-order declaration.
+Before install, a PyPI declaration contains the root identity. With a Git
+source, the command first compiles the complete formal app closure from the root
+package tag's full commit, then writes every member's exact version, the same
+credential-free Git URL/full commit, and its own leaf subdirectory in one
+project transaction; no member may fall back to an index. After `app install`,
+repeating the
+same atomic declaration inspects installed metadata, validates the complete
+formal app dependency closure against hard distribution dependencies and lock
+versions, and reconciles the closure into `installed_apps` in dependency-first
+order. It does not install packages or refresh app settings. Existing explicit
+dev source ownership is preserved and remains higher priority.
 
 ### `pz app undeclare`
 
@@ -119,11 +135,18 @@ or remote package artifacts.
 
 ### `pz app install`
 
-`pz app install <app_id> --version <version>` installs exactly one already
-resolved distribution version into the project environment and converges the
-corresponding `uv.lock` state. It does not choose latest, mutate
-`installed_apps`, or modify source directories. The locked and installed
-metadata must match the requested distribution and version before success.
+`pz app install <app_id> --version <version> [--source <source>]` installs the resolved root
+distribution and its compatible distribution dependency graph into the project
+environment and converges `uv.lock`. Missing formal app dependencies use the
+root app's same install source. A PyPI install does not inherit `UV_INDEX`, uses
+`first-index`, and cannot silently redirect a closure member to another private
+index. A PyPI resolution persists an exact version. A Git resolution consumes
+the exact same-commit closure entries already persisted by `app declare`; the
+explicit source also makes failure recovery reuse the same source. It does not
+choose latest or modify source directories. The
+second atomic `app declare` projects the installed graph into `installed_apps`.
+Locked and installed metadata must match the root request and every formal
+dependency before success.
 
 ## Orchestration
 
@@ -133,16 +156,18 @@ metadata must match the requested distribution and version before success.
 
 ```text
 resolve latest stable or validate --version
-  -> app declare exact version
-  -> app install exact version
+  -> app declare exact same-source plan
+  -> app install exact same-source plan
+  -> app declare installed dependency closure
   -> settings update
 ```
 
-Each successful atomic stage remains committed. If installation fails after
-declaration, the exact declaration remains and retry resumes from install. If
-settings refresh fails after declaration and installation succeed, retry
-resumes from settings refresh. The orchestration always reports completed
-stages, the selected exact version, and the first incomplete stage.
+Each successful atomic stage remains committed. If installation fails after the
+root declaration, that exact declaration remains and retry resumes from install.
+If closure declaration fails after installation, retry repeats `app declare`;
+if settings refresh fails, retry resumes from settings. The orchestration always
+reports completed stages, the selected exact version, and the first incomplete
+stage.
 
 ### `pz app update`
 
@@ -155,8 +180,9 @@ reinstalling.
 
 `pz app init` resolves every selected package first, forms one dependency-safe
 exact plan, then declares and installs in dependency order. A resolver conflict
-fails before project mutation. It never uses versions found in source checkout
-`pyproject.toml` files as production pins.
+fails before project mutation. It never uses a branch, `HEAD`, floating tag, or
+the current version of an arbitrary source checkout as a production pin. A Git
+source is valid only through a formal package tag resolved to a full commit.
 
 ### `pz app rm`
 
@@ -180,7 +206,8 @@ refresh. It does not remove local source or delete remote package versions.
 Publishing and installation remain separate chains. The leaf
 `[project].version`, package tag, wheel metadata, and package-index version must
 match under the Git release orchestration design. `pz app` consumes those
-published versions and never commits, tags, or publishes source.
+published versions from PyPI or a formal Git package tag and never commits,
+tags, or publishes source.
 
 ## Testing
 
@@ -194,12 +221,15 @@ Tests must cover:
 4. `app versions` reports available, latest, declared, locked, and installed
    versions consistently in human and JSON output without mutation;
 5. install validates installed distribution metadata;
-6. add/update/init preserve dependency order and fail before mutation on
-   resolution conflict;
+6. add/update/init install the formal dependency closure from the same source,
+   preserve dependency order, and fail deterministically on resolution conflict;
 7. staged declaration rollback and forward recovery after later-stage failure;
 8. source/distribution identity conflicts remain hard errors;
 9. repository-root version never overrides a leaf package version;
-10. credentials and authenticated index URLs are redacted.
+10. credentials and authenticated index URLs are redacted;
+11. inherited `UV_INDEX` cannot redirect a private formal dependency, while an
+    explicit existing dev source remains higher priority and is never deleted
+    or rewritten by `pz app`.
 
 ## Non-Goals
 
@@ -207,4 +237,6 @@ Tests must cover:
 - Giving every app in one repository the same release version.
 - Persisting floating `latest` dependencies.
 - Automatically selecting or bumping a package's publish version.
-- Installing directly from source checkout in the `pz app` command family.
+- Installing from a mutable branch, `HEAD`, floating tag, dirty checkout, or
+  unversioned local source in the `pz app` command family. Exact Git package-tag
+  installs are formal inputs under the unified source catalog design.

{pz_cli-5.0.0 → pz_cli-5.0.2}/docs/superpowers/specs/2026-07-13-pz-cli-single-wheel-design.md

@@ -140,7 +140,7 @@ The wheel exposes both existing entry-point contracts:
 pz = "pz_core.pz_launcher:main"
 
 [project.entry-points."pz.root_cli"]
-pz_foundation = "pz_foundation.root_cli:get_root_command_handlers"
+workers = "pz_foundation.root_cli:get_root_command_handlers"
 ```
 
 ## Dependency Metadata
@@ -200,13 +200,15 @@ with one dependency:
 pz-cli==5.0.0
 ```
 
-App-to-app dependency relationships remain unchanged; only their exact release
-pins advance with the app release train.
+App-to-app dependency relationships remain unchanged. The cutover artifacts
+start at `5.0.1`, while ongoing package metadata declares compatible `5.x`
+ranges instead of advancing every downstream package with an exact release pin.
 
 Dependency metadata is part of an artifact's identity. Therefore the approved
-`pz_apps` release train moves from `5.0.0` to `5.0.1` in this cutover. Every
-affected app's own version and every exact app-to-app pin are updated to
-`5.0.1`; the base dependency remains `pz-cli==5.0.0`.
+`pz_apps` cutover artifacts move from `5.0.0` to `5.0.1`. After the cutover,
+each app owns an independent version and uses compatibility metadata such as
+`pz-auth>=5.0.1,<6`; the base compatibility dependency is
+`pz-cli>=5.0.0,<6`. Exact versions belong to host projects and `uv.lock`.
 
 Each `[tool.uv.sources]` table removes the old base source entries and uses one
 editable source entry pointing to the PZ repository root:
@@ -228,7 +230,7 @@ its own next unpublished version when changing dependencies.
 ## External Consumer Migration
 
 Any third-party distribution or project that depends directly on a retired
-base distribution must migrate to `pz-cli==5.0.0` before it can consume the
+base distribution must migrate to `pz-cli>=5.0.0,<6` before it can consume the
 single-wheel release. Release notes must list the retired names and the exact
 dependency replacement.
 
@@ -245,7 +247,7 @@ pz-cli = { path = "apps/.sources/pz", editable = true }
 ```
 
 Scaffold, `pz dev init`, project metadata reconciliation, source diagnostics,
-environment sync, provider selection, and installer scripts stop creating or
+environment sync, explicit runtime-target selection, and installer scripts stop creating or
 expecting separate editable bindings for the retired distributions.
 
 The `apps/.sources/pz` Git checkout and manifest identity remain unchanged.
@@ -426,9 +428,10 @@ The cutover is complete only when all of the following pass:
 2. no retired base `pyproject.toml`, lock, build target, publish target, or
    dependency remains;
 3. root `uv lock --check` and the combined PZ test suite pass;
-4. all affected `pz_apps` versions are `5.0.1`, their base dependency is only
-   `pz-cli==5.0.0`, their app-to-app pins and locks are consistent, and their
-   contract tests pass;
+4. the initial affected `pz_apps` artifacts are `5.0.1`, their base dependency
+   is only `pz-cli>=5.0.0,<6`, their app-to-app compatibility ranges and locks
+   are consistent, and their contract tests pass; subsequent app versions are
+   independent and need not remain equal;
 5. a clean build produces one `pz_cli-5.0.0` wheel and one matching sdist;
 6. the wheel contains exactly the intended `pz_core`, `pz_settings_center`, and
    `pz_foundation` package trees plus their declared resources and package docs;
@@ -441,8 +444,9 @@ The cutover is complete only when all of the following pass:
    resources/docs;
 10. an environment with any retired distribution fails the new integrity
     diagnostic with an actionable clean-environment migration message;
-11. source checkout bootstrap and installed-wheel provider paths produce the
-    same CLI and runtime contracts;
+11. the shell-resolved installed `pz-cli` remains the control plane while both
+    source-checkout and installed-wheel project runtime targets produce the same
+    runtime contracts; a project source target never takes over the authoring CLI;
 12. source and installed runtime version checks both resolve exactly
     `pz-cli==5.0.0`, never `pz` or `0.0.0`;
 13. authoring reconciliation emits only the `pz-cli` editable distribution

{pz_cli-5.0.0 → pz_cli-5.0.2}/docs/superpowers/specs/2026-07-13-pz-publish-git-release-orchestration-design.md

@@ -19,12 +19,13 @@ The repository may contain many minimal apps. One app release must not silently
 commit another app's changes.
 
 Publishing first checks whether `project_dir` itself is a Git repository root
-whose root `pyproject.toml` distribution exactly matches the requested app. An
-exact root match is the publish source and gives the whole repository one
-release scope. Only when the root distribution does not match does publishing
-enumerate usable Git repositories under `apps/.sources` and reuse the existing
-workspace-package discovery program inside them. A business-owned copied app is
-not a publish source.
+whose root `pyproject.toml` distribution or `[tool.uv.workspace].members`
+uniquely matches the requested app. A root distribution match gives the whole
+repository one release scope; a workspace-member match gives only that package
+path. Only when the current Git workspace does not match does publishing
+enumerate usable Git repositories under `apps/.sources`. A `tool.uv.sources`
+path is only a dependency source, so a business-owned copied app is not a
+publish source.
 
 This is a constrained reuse of `iter_workspace_packages` /
 `resolve_workspace_package`, not a second package scanner. The shared resolver
@@ -78,22 +79,24 @@ distribution version must match exactly.
 
 The Git root is selected in this order:
 
-1. if `project_dir` resolves to the top level of its Git worktree and the root
-   `pyproject.toml` distribution exactly matches the requested app, select that
-   repository root directly;
+1. if `project_dir` resolves to the top level of its Git worktree, search its
+   root distribution and `[tool.uv.workspace].members`; select the unique root
+   or member match without considering `tool.uv.sources` dependency paths;
 2. otherwise enumerate direct source entries under `apps/.sources`, resolve
    each entry to its canonical Git worktree, and use the existing
    workspace-package discovery program inside each distinct Git root.
 
 Nearest-parent Git discovery from an arbitrary child directory remains
-insufficient. Root publishing is explicit only when `project_dir` is the Git
-top level and its root distribution matches.
+insufficient. Current-workspace publishing is explicit only when `project_dir`
+is the Git top level and its root distribution or formal workspace member
+matches.
 
 Resolution has exactly five outcomes:
 
-1. the project Git root exactly matches the requested distribution: return the
-   repository root as both package root and owning Git root;
-2. no exact root match and no usable Git repository exists under
+1. the project Git root or one formal workspace member exactly matches the
+   requested distribution: return that package root and the current owning Git
+   root;
+2. no current-workspace match and no usable Git repository exists under
    `apps/.sources`: fail with
    `PZ_PUB_GIT_REQUIRED`;
 3. repositories exist but none contains the requested app: fail with
@@ -238,6 +241,26 @@ step. It must not hide an already-created commit or tag when a later step fails.
 build validation, publish-lock validation, and target planning, but performs no
 Git index mutation, commit, tag creation, or remote upload.
 
+## Package Index Boundary
+
+The official app distributions are published only to the configured internal
+PyPI/devpi service. `pz app ...` consumes their released versions from that
+internal service, while `pz dev ...` continues to obtain source from the Git
+cache and either imports a business-owned copy or exposes a managed checkout
+through bindings.
+
+`pz pub` without `--target` must resolve the target source root's explicit
+`tool.pz.publish.default_target` to a configured internal index or upload URL.
+An absent or empty default target is an error; PZ must never fall through to
+the package backend's public default index. `devpi_dev`, `devpi_prod`, and
+`devpi_pub` are all channels of the internal service; `devpi_pub` is the
+internal shared-release channel, not `pypi.org`.
+
+Publishing to `pypi.org` is a separate, explicit exception. It requires
+`--target pypi` (or `-t pypi`) and must pass the project publish lock. The
+default lock allows only the `pz-cli` distribution; a project that authorizes
+another distribution must replace that allowlist explicitly.
+
 ## Failure And Retry Semantics
 
 The workflow is forward-recoverable, not rollback-by-history-rewrite:
@@ -341,8 +364,9 @@ Tests must cover:
 1. commit stages and commits only the selected minimal-app path;
 2. tracked changes, deletions, and untracked source files in the target app are
    included;
-3. an exact matching repository root publishes directly, while a non-matching
-   host root still falls back to `.sources` discovery;
+3. an exact root distribution or formal workspace member publishes directly,
+   while a non-matching host root still falls back to `.sources` discovery and
+   never treats `tool.uv.sources` as publish membership;
 4. no root or `.sources` Git source, no matching app, multiple matching Git roots,
    staged changes, ambiguous shared-root changes, detached HEAD, missing Git
    identity, and non-Git package roots fail before mutation;

{pz_cli-5.0.0 → pz_cli-5.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pz-cli"
-version = "5.0.0"
+version = "5.0.2"
 description = "PZ CLI, runtime compiler, settings owner, and foundation runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,7 +45,7 @@ db-mysql = ["pymysql>=1.1,<2.0"]
 pz = "pz_core.pz_launcher:main"
 
 [project.entry-points."pz.root_cli"]
-pz_foundation = "pz_foundation.root_cli:get_root_command_handlers"
+workers = "pz_foundation.root_cli:get_root_command_handlers"
 
 [dependency-groups]
 dev = [
@@ -81,7 +81,7 @@ norecursedirs = [".git", ".venv", "__pycache__", "build", "dist", ".runtime"]
 package_role = "runtime_bootstrap"
 
 [tool.pz.publish]
-default_target = "devpi_pub"
+default_target = "pypi"
 
 [tool.pz.publish.targets.devpi_dev]
 publish_url = "https://devpi.seobot.cc/packages/dev/"

{pz_cli-5.0.0 → pz_cli-5.0.2}/pz_contrib/pz_foundation/pz_foundation/_contracts.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
 
@@ -10,6 +10,7 @@ class PresignInfo:
     method: str
     url: str
     expires_in_seconds: int
+    headers: dict[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True, slots=True)
@@ -23,6 +24,10 @@ class StoredObject:
 class StoragePort(Protocol):
     def store_bytes(self, object_key: str, payload: bytes, *, content_type: str | None = None) -> StoredObject: ...
 
+    def stat(self, object_key: str) -> StoredObject: ...
+
+    def read_range(self, object_key: str, *, offset: int = 0, length: int) -> bytes: ...
+
     def delete(self, object_key: str) -> None: ...
 
     def presign_get(self, object_key: str, *, expires_in_seconds: int) -> PresignInfo: ...