pz-cli 5.0.1__tar.gz → 5.0.3__tar.gz

pz_cli-5.0.3/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: pz-cli
+Version: 5.0.3
+Summary: PZ protocol compiler with bundled authoring and foundation implementations
+Project-URL: Homepage, https://github.com/JiXiangTools/pz
+Project-URL: Repository, https://github.com/JiXiangTools/pz
+Author: pz maintainers
+License-Expression: LicenseRef-Proprietary
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: aiofiles<25.0,>=24.1
+Requires-Dist: boto3<2.0,>=1.38
+Requires-Dist: cloudpickle<4.0,>=3.1
+Requires-Dist: fastapi<0.137,>=0.110
+Requires-Dist: packaging<26,>=24
+Requires-Dist: pydantic<3.0,>=2.10
+Requires-Dist: redis<7,>=5
+Requires-Dist: requests<3.0,>=2.32
+Requires-Dist: tomlkit<1.0,>=0.13
+Requires-Dist: uvicorn<1.0,>=0.35
+Provides-Extra: db
+Requires-Dist: aerich<1.0,>=0.8; extra == 'db'
+Requires-Dist: tortoise-orm<1.0,>=0.25; extra == 'db'
+Provides-Extra: db-mysql
+Requires-Dist: aiomysql<1.0,>=0.3; extra == 'db-mysql'
+Requires-Dist: pymysql<2.0,>=1.1; extra == 'db-mysql'
+Provides-Extra: db-postgres
+Requires-Dist: asyncpg<1,>=0.30; extra == 'db-postgres'
+Requires-Dist: psycopg[binary,pool]<4.0,>=3.2; extra == 'db-postgres'
+Description-Content-Type: text/markdown
+
+# pz-cli
+
+`pz-cli` is the single install and release unit for the PZ protocol compiler and
+its bundled official control-plane/runtime implementations.
+
+The version declared by the root `pyproject.toml` bundles the `pz_core`,
+`pz_authoring`, `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
+```
+
+The source checkout uses one root `pyproject.toml` and one root `uv.lock`.
+Package-specific documentation lives under each bundled Python package's
+`docs/` directory.

pz_cli-5.0.3/README.md

@@ -0,0 +1,19 @@
+# pz-cli
+
+`pz-cli` is the single install and release unit for the PZ protocol compiler and
+its bundled official control-plane/runtime implementations.
+
+The version declared by the root `pyproject.toml` bundles the `pz_core`,
+`pz_authoring`, `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
+```
+
+The source checkout uses one root `pyproject.toml` and one root `uv.lock`.
+Package-specific documentation lives under each bundled Python package's
+`docs/` directory.

pz_cli-5.0.3/conftest.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _isolate_runtime_invocation_id() -> None:
+    name = "PZ_RUNTIME_INVOCATION_ID"
+    missing = object()
+    original_value = os.environ.get(name, missing)
+    os.environ.pop(name, None)
+    try:
+        yield
+    finally:
+        if original_value is missing:
+            os.environ.pop(name, None)
+        else:
+            os.environ[name] = str(original_value)

pz_cli-5.0.3/docs/superpowers/specs/2026-07-13-pz-app-version-resolution-design.md

@@ -0,0 +1,242 @@
+# PZ App Version Resolution Design
+
+## Status
+
+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
+
+Keep all minimal apps in one Git repository when desired while giving each
+distribution an independent release version and giving every host project a
+reproducible exact installed version.
+
+The normal workflow must be simple:
+
+- `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;
+- `pz app versions <app_id>` shows available and current version state.
+
+## Command Layers
+
+PZ retains the explicit atomic-command plus orchestration-command model.
+
+Orchestration commands are:
+
+- `pz app init`;
+- `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> [--source <source>]`;
+- `pz app undeclare <app_id>`;
+- `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
+use orchestration commands; atomic commands exist for deterministic validation,
+retry, CI, and failure recovery.
+
+## Version Truths
+
+Each concern has one truth source:
+
+- package release version: the minimal app's own
+  `pyproject.toml [project].version`;
+- host requested exact version: the host project dependency declaration;
+- host resolved dependency graph: the host `uv.lock`;
+- actually installed version: installed distribution metadata from
+  `importlib.metadata`;
+- runtime declaration compatibility: the app's `required_pz` and
+  `required_protocols`, validated by the runtime compiler after installation.
+
+`pz.jsonc installed_apps` records app identity and load order, not a duplicate
+package version. Repository-root versions do not override leaf distribution
+versions. A Git repository may therefore contain many independently versioned
+minimal apps.
+
+## Version Resolution
+
+Without `--version`, `app add`, `app update`, and `app init` resolve the latest
+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:
+
+- exclude yanked releases;
+- exclude prereleases unless the caller explicitly requests that exact version;
+- respect Python, platform, package dependency, and project constraints through
+  a dry-run `uv` resolution of the complete host graph; `required_pz` and
+  protocol declarations remain runtime compiler checks unless encoded as
+  distribution dependencies;
+- use normalized PEP 440 ordering rather than lexical ordering;
+- return one exact version before any mutation;
+- never persist the word `latest` as a dependency constraint.
+
+After resolution, the orchestration pins the selected exact distribution
+version in the host project and refreshes `uv.lock`. "Latest" is therefore an
+invocation-time selection rule, not a floating runtime dependency.
+
+`--version` accepts one exact normalized PEP 440 version only. Ranges remain
+package dependency metadata, not an ambiguous project installation request.
+
+## `pz app versions`
+
+`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;
+- the latest compatible stable version;
+- the host-declared exact version, if any;
+- the `uv.lock` resolved version, if any;
+- the installed distribution version, if any;
+- prerelease and yanked state for each returned version.
+
+Human output marks `latest`, `declared`, `locked`, and `installed`. `--json`
+returns the same typed fields. Credentials and authenticated index URLs must be
+redacted.
+
+## Atomic Commands
+
+### `pz app declare`
+
+`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`
+
+`pz app undeclare <app_id>` atomically removes the project package pin and app
+identity declaration. It does not delete business-owned source, linked source,
+or remote package artifacts.
+
+### `pz app install`
+
+`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
+
+### `pz app add`
+
+`pz app add` executes:
+
+```text
+resolve latest stable or validate --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 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`
+
+`pz app update` uses the same stages but requires an existing package
+declaration. Without `--version`, it resolves latest compatible stable. If the
+current exact version is already latest, it returns idempotent success without
+reinstalling.
+
+### `pz app init`
+
+`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 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`
+
+`pz app rm` orchestrates undeclaration, environment reconciliation, and settings
+refresh. It does not remove local source or delete remote package versions.
+
+## Failure And Retry
+
+- Index or authentication failure occurs before mutation.
+- An unknown or incompatible requested version is a stable resolution error.
+- Each atomic command uses staged files and rollback-capable replacement for
+  the files it owns.
+- Cross-command orchestration is forward-recoverable; PZ preserves completed
+  atomic stages and reports the selected version and first incomplete stage.
+- A lock, installed metadata, and declaration mismatch is an error surfaced by
+  `pz check`; it is never silently hidden by import precedence.
+- Re-running with the same selected version is idempotent.
+
+## Relationship To Publishing
+
+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 from PyPI or a formal Git package tag and never commits,
+tags, or publishes source.
+
+## Testing
+
+Tests must cover:
+
+1. default add/update selects the latest compatible stable PEP 440 version;
+2. exact `--version` selects only that version and rejects missing,
+   incompatible, prerelease-policy, and yanked conflicts deterministically;
+3. default selection is persisted as an exact project pin and exact lock state,
+   never as `latest`;
+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 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;
+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
+
+- Splitting minimal apps into separate Git repositories.
+- Giving every app in one repository the same release version.
+- Persisting floating `latest` dependencies.
+- Automatically selecting or bumping a package's publish version.
+- 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.