pz-cli 5.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (399) hide show
  1. pz_cli-5.0.0.dist-info/METADATA +51 -0
  2. pz_cli-5.0.0.dist-info/RECORD +399 -0
  3. pz_cli-5.0.0.dist-info/WHEEL +4 -0
  4. pz_cli-5.0.0.dist-info/entry_points.txt +5 -0
  5. pz_core/__init__.py +64 -0
  6. pz_core/__main__.py +7 -0
  7. pz_core/app.py +45 -0
  8. pz_core/assembly/__init__.py +17 -0
  9. pz_core/assembly/app_discovery.py +1240 -0
  10. pz_core/assembly/apps/__init__.py +25 -0
  11. pz_core/assembly/apps/compiler.py +824 -0
  12. pz_core/assembly/apps/providers.py +188 -0
  13. pz_core/assembly/cli/__init__.py +9 -0
  14. pz_core/assembly/cli/compiler.py +166 -0
  15. pz_core/assembly/diagnostics/__init__.py +21 -0
  16. pz_core/assembly/diagnostics/checks.py +257 -0
  17. pz_core/assembly/diagnostics/dev_sources.py +569 -0
  18. pz_core/assembly/events/__init__.py +5 -0
  19. pz_core/assembly/events/compiler.py +219 -0
  20. pz_core/assembly/extensions/__init__.py +5 -0
  21. pz_core/assembly/extensions/compiler.py +696 -0
  22. pz_core/assembly/infra/__init__.py +6 -0
  23. pz_core/assembly/infra/compiler.py +272 -0
  24. pz_core/assembly/lifecycle/__init__.py +5 -0
  25. pz_core/assembly/lifecycle/compiler.py +95 -0
  26. pz_core/assembly/middlewares/__init__.py +19 -0
  27. pz_core/assembly/middlewares/compiler.py +508 -0
  28. pz_core/assembly/project/__init__.py +7 -0
  29. pz_core/assembly/project/compiler.py +9 -0
  30. pz_core/assembly/project/context.py +17 -0
  31. pz_core/assembly/project/discovery.py +227 -0
  32. pz_core/assembly/resources/__init__.py +19 -0
  33. pz_core/assembly/resources/compiler.py +310 -0
  34. pz_core/assembly/resources/settings.py +129 -0
  35. pz_core/assembly/routes/__init__.py +7 -0
  36. pz_core/assembly/routes/compiler.py +400 -0
  37. pz_core/assembly/runtime_manifests/__init__.py +13 -0
  38. pz_core/assembly/runtime_manifests/compiler.py +159 -0
  39. pz_core/assembly/settings/__init__.py +17 -0
  40. pz_core/assembly/settings/compiler.py +786 -0
  41. pz_core/assembly/settings/host_project_overrides.py +82 -0
  42. pz_core/assembly/settings/host_runtime_endpoint.py +207 -0
  43. pz_core/authoring/__init__.py +79 -0
  44. pz_core/authoring/app_init_service.py +946 -0
  45. pz_core/authoring/app_versions.py +814 -0
  46. pz_core/authoring/cli.py +192 -0
  47. pz_core/authoring/commands.py +1810 -0
  48. pz_core/authoring/conflicts.py +180 -0
  49. pz_core/authoring/dev_bindings.py +916 -0
  50. pz_core/authoring/dev_git.py +1087 -0
  51. pz_core/authoring/dev_import.py +1061 -0
  52. pz_core/authoring/dev_manifest.py +522 -0
  53. pz_core/authoring/dev_sources.py +1638 -0
  54. pz_core/authoring/env_cli.py +454 -0
  55. pz_core/authoring/files.py +109 -0
  56. pz_core/authoring/ide_projection.py +1129 -0
  57. pz_core/authoring/naming.py +58 -0
  58. pz_core/authoring/official_dev_sources.py +432 -0
  59. pz_core/authoring/official_sources.json +156 -0
  60. pz_core/authoring/orchestration_service.py +558 -0
  61. pz_core/authoring/project_default.jsonc +53 -0
  62. pz_core/authoring/project_defaults.py +88 -0
  63. pz_core/authoring/project_metadata_service.py +199 -0
  64. pz_core/authoring/project_settings_checks.py +51 -0
  65. pz_core/authoring/project_settings_cli.py +299 -0
  66. pz_core/authoring/project_settings_service.py +1700 -0
  67. pz_core/authoring/project_state.py +399 -0
  68. pz_core/authoring/publish_git.py +423 -0
  69. pz_core/authoring/publish_lock.py +188 -0
  70. pz_core/authoring/publish_source.py +195 -0
  71. pz_core/authoring/release.py +1382 -0
  72. pz_core/authoring/repo_keys.py +29 -0
  73. pz_core/authoring/root_cli.py +28 -0
  74. pz_core/authoring/scaffold_service.py +325 -0
  75. pz_core/authoring/sync_service.py +787 -0
  76. pz_core/authoring/templates/app/__init__.py +1 -0
  77. pz_core/authoring/templates/app/api.py +25 -0
  78. pz_core/authoring/templates/app/apps.py +31 -0
  79. pz_core/authoring/templates/app/auth_package_init.py +14 -0
  80. pz_core/authoring/templates/app/auth_readme.py +29 -0
  81. pz_core/authoring/templates/app/configs_package_init.py +14 -0
  82. pz_core/authoring/templates/app/default_env.py +18 -0
  83. pz_core/authoring/templates/app/default_jsonc.py +25 -0
  84. pz_core/authoring/templates/app/locales_readme.py +25 -0
  85. pz_core/authoring/templates/app/migrations_readme.py +19 -0
  86. pz_core/authoring/templates/app/models.py +14 -0
  87. pz_core/authoring/templates/app/package_init.py +8 -0
  88. pz_core/authoring/templates/app/pages_base.py +161 -0
  89. pz_core/authoring/templates/app/pages_readme.py +25 -0
  90. pz_core/authoring/templates/app/public.py +31 -0
  91. pz_core/authoring/templates/app/pyproject.py +77 -0
  92. pz_core/authoring/templates/app/readme.py +74 -0
  93. pz_core/authoring/templates/app/settings.py +46 -0
  94. pz_core/authoring/templates/app/static_app_js.py +24 -0
  95. pz_core/authoring/templates/app/static_readme.py +31 -0
  96. pz_core/authoring/templates/app/template_config_page.py +23 -0
  97. pz_core/authoring/templates/app/template_index_html.py +28 -0
  98. pz_core/authoring/templates/app/templates_readme.py +32 -0
  99. pz_core/authoring/templates/app/urls.py +36 -0
  100. pz_core/authoring/templates/app/views.py +36 -0
  101. pz_core/authoring/templates/project/__init__.py +1 -0
  102. pz_core/authoring/templates/project/agents.py +51 -0
  103. pz_core/authoring/templates/project/apps_container_readme.py +37 -0
  104. pz_core/authoring/templates/project/main_py.py +59 -0
  105. pz_core/authoring/templates/project/project_env.py +19 -0
  106. pz_core/authoring/templates/project/pyproject.py +26 -0
  107. pz_core/authoring/templates/project/pz_env_env.py +65 -0
  108. pz_core/authoring/templates/project/pz_env_jsonc.py +69 -0
  109. pz_core/authoring/templates/project/pz_jsonc.py +12 -0
  110. pz_core/authoring/templates/project/readme.py +94 -0
  111. pz_core/authoring/templates/project/root_gitkeep.py +8 -0
  112. pz_core/authoring/templates/shared/__init__.py +5 -0
  113. pz_core/authoring/templates/shared/text.py +10 -0
  114. pz_core/authoring/venv_service.py +87 -0
  115. pz_core/authoring/workspace.py +167 -0
  116. pz_core/cli.py +291 -0
  117. pz_core/cli_options.py +74 -0
  118. pz_core/core/__init__.py +3 -0
  119. pz_core/core/errors/__init__.py +5 -0
  120. pz_core/core/errors/models.py +117 -0
  121. pz_core/core/events/__init__.py +5 -0
  122. pz_core/core/events/registry.py +54 -0
  123. pz_core/core/extensions/__init__.py +51 -0
  124. pz_core/core/extensions/registry.py +790 -0
  125. pz_core/core/health/__init__.py +6 -0
  126. pz_core/core/health/contracts.py +10 -0
  127. pz_core/core/middlewares/__init__.py +6 -0
  128. pz_core/core/middlewares/models.py +24 -0
  129. pz_core/core/routing/__init__.py +5 -0
  130. pz_core/core/routing/models.py +21 -0
  131. pz_core/core/settings_contracts.py +25 -0
  132. pz_core/docs/README.md +20 -0
  133. pz_core/docs/distribution-README.md +438 -0
  134. pz_core/docs/pz/345/221/275/344/273/244/346/200/273/350/247/210.md +1011 -0
  135. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/00-pz/346/236/266/346/236/204/346/200/273/347/272/262.md +240 -0
  136. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/350/247/204/350/214/203.md +216 -0
  137. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203.md +403 -0
  138. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/03-App/346/234/200/345/260/217/345/255/220/345/214/205/350/247/204/350/214/203.md +571 -0
  139. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/04-Settings/344/270/216/351/205/215/347/275/256/350/247/204/350/214/203.md +1177 -0
  140. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/05-/350/265/204/346/272/220/344/270/216/350/277/220/350/241/214/347/233/256/345/275/225/350/247/204/350/214/203.md +575 -0
  141. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/06-/346/225/260/346/215/256/345/272/223/344/270/216/345/217/257/351/200/211/345/237/272/347/241/200/350/256/276/346/226/275/350/247/204/350/214/203.md +499 -0
  142. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/07-App/346/233/277/346/215/242/350/247/204/350/214/203.md +206 -0
  143. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/08-/345/271/263/345/217/260/347/272/247App/344/270/216/350/277/220/350/241/214/346/227/266/345/215/225/344/276/213/350/247/204/350/214/203.md +445 -0
  144. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/09-CLI/344/270/216Worker/345/205/245/345/217/243/350/247/204/350/214/203.md +950 -0
  145. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/10-/346/265/213/350/257/225/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md +1001 -0
  146. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/11-/344/273/223/345/272/223/347/234/237/347/233/270/346/272/220/345/234/260/345/233/276.md +102 -0
  147. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/12-/346/236/204/345/273/272/344/270/216/345/217/221/345/270/203/346/243/200/346/237/245/346/270/205/345/215/225.md +171 -0
  148. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/13-/346/255/243/345/274/217Facade/346/200/273/350/241/250.md +402 -0
  149. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/14-/345/210/206/345/261/202/344/270/216/346/211/251/345/261/225/350/247/204/350/214/203.md +550 -0
  150. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/15-/345/255/220/345/214/205/345/274/200/345/217/221/344/275/277/347/224/250/346/211/213/345/206/214.md +1004 -0
  151. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/16-/346/211/251/345/261/225/347/202/271/346/255/243/345/274/217/345/215/217/350/256/256/346/270/205/345/215/225.md +352 -0
  152. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/17-pz.protocols.v1/346/255/243/345/274/217/345/215/217/350/256/256.md +266 -0
  153. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/18-/346/211/251/345/261/225/347/202/271/345/206/262/347/252/201/350/243/201/345/206/263/346/200/273/350/241/250.md +131 -0
  154. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/19-/351/224/231/350/257/257/347/240/201/344/270/216/350/257/212/346/226/255/345/215/217/350/256/256.md +176 -0
  155. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/20-/347/247/201/346/234/211/345/214/205/344/273/223/344/270/216/347/273/237/344/270/200/350/256/244/350/257/201/351/203/250/347/275/262/350/247/204/350/214/203.md +243 -0
  156. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/21-contrib/347/272/246/345/256/232/344/270/216Provider/346/216/245/345/205/245/350/247/204/350/214/203.md +365 -0
  157. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/22-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203.md +912 -0
  158. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/23-/351/246/226/345/261/217/345/261/225/347/244/272/344/270/216/351/246/226/345/270/247/347/250/263/345/256/232/350/247/204/350/214/203.md +269 -0
  159. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/24-pz/345/220/257/345/212/250/344/270/216/350/277/220/350/241/214/346/227/266/347/274/226/350/257/221/346/265/201/347/250/213.md +245 -0
  160. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/25-/351/235/242/345/220/221/345/257/271/350/261/241/345/274/200/345/217/221/350/247/204/350/214/203.md +300 -0
  161. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/README.md +98 -0
  162. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/00-legacy_core/346/240/207/345/207/206pip/345/214/205/345/214/226/351/207/215/346/236/204/346/200/273/347/272/262.md +1073 -0
  163. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/351/207/215/346/236/204/346/211/247/350/241/214/346/226/271/346/241/210.md +224 -0
  164. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203-/345/220/253/345/216/206/345/217/262/345/217/243/345/276/204.md +671 -0
  165. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/13-/344/270/200/346/254/241/346/200/247/345/256/236/346/226/275/346/270/205/345/215/225.md +387 -0
  166. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/14-/345/255/220/345/214/205/351/200/202/351/205/215/346/224/271/351/200/240/346/270/205/345/215/225.md +592 -0
  167. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/15-infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/346/270/205/345/215/225.md +81 -0
  168. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/19-core/345/215/225/344/270/200/346/255/243/345/274/217/346/226/271/346/241/210/346/224/266/346/225/233/346/211/247/350/241/214/346/270/205/345/215/225.md +161 -0
  169. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/25-/345/215/217/350/256/256/345/210/260/346/272/220/347/240/201/345/267/256/350/267/235/346/270/205/345/215/225.md +377 -0
  170. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/26-cutover/345/256/214/345/267/245/346/243/200/346/237/245/346/270/205/345/215/225.md +117 -0
  171. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/29-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203-/345/220/253/350/277/201/347/247/273/347/255/226/347/225/245.md +956 -0
  172. pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/archive//344/270/255/351/227/264/346/200/201/99-/350/265/204/346/272/220/346/224/266/345/217/243/345/220/216/347/273/255TODO.md +84 -0
  173. pz_core/docs//345/217/221/347/211/210/345/211/215/346/270/205/345/215/225-4.0.11.md +84 -0
  174. pz_core/docs//346/226/260/346/211/213/346/214/207/345/215/227.md +422 -0
  175. pz_core/infra/__init__.py +17 -0
  176. pz_core/infra/db/__init__.py +23 -0
  177. pz_core/infra/db/contracts.py +73 -0
  178. pz_core/infra/health/__init__.py +5 -0
  179. pz_core/infra/health/contracts.py +8 -0
  180. pz_core/infra/kv/__init__.py +5 -0
  181. pz_core/infra/kv/contracts.py +17 -0
  182. pz_core/infra/observability/__init__.py +23 -0
  183. pz_core/infra/observability/contracts.py +142 -0
  184. pz_core/infra/resilience/__init__.py +5 -0
  185. pz_core/infra/resilience/contracts.py +17 -0
  186. pz_core/infra/resources/__init__.py +5 -0
  187. pz_core/infra/resources/contracts.py +16 -0
  188. pz_core/infra/settings/__init__.py +17 -0
  189. pz_core/infra/settings/models.py +81 -0
  190. pz_core/infra/storage/__init__.py +5 -0
  191. pz_core/infra/storage/ports.py +27 -0
  192. pz_core/project_root_commands.py +282 -0
  193. pz_core/project_runtime_cli.py +344 -0
  194. pz_core/project_sources.py +253 -0
  195. pz_core/pz_launcher.py +209 -0
  196. pz_core/root_cli.py +70 -0
  197. pz_core/runtime/__init__.py +229 -0
  198. pz_core/runtime/access.py +86 -0
  199. pz_core/runtime/adapters/__init__.py +5 -0
  200. pz_core/runtime/adapters/base.py +18 -0
  201. pz_core/runtime/asyncio_bridge.py +18 -0
  202. pz_core/runtime/bindings/__init__.py +5 -0
  203. pz_core/runtime/bindings/container.py +50 -0
  204. pz_core/runtime/cli/__init__.py +5 -0
  205. pz_core/runtime/cli/_args.py +67 -0
  206. pz_core/runtime/cli/app_commands.py +417 -0
  207. pz_core/runtime/cli/check.py +214 -0
  208. pz_core/runtime/cli/db.py +297 -0
  209. pz_core/runtime/cli/main.py +89 -0
  210. pz_core/runtime/cli/resources.py +280 -0
  211. pz_core/runtime/discovery.py +23 -0
  212. pz_core/runtime/environment_integrity.py +157 -0
  213. pz_core/runtime/errors.py +5 -0
  214. pz_core/runtime/events.py +87 -0
  215. pz_core/runtime/facades/__init__.py +38 -0
  216. pz_core/runtime/facades/_capabilities.py +46 -0
  217. pz_core/runtime/facades/cache.py +103 -0
  218. pz_core/runtime/facades/database.py +71 -0
  219. pz_core/runtime/facades/events.py +380 -0
  220. pz_core/runtime/facades/health.py +101 -0
  221. pz_core/runtime/facades/mail.py +121 -0
  222. pz_core/runtime/facades/observability.py +102 -0
  223. pz_core/runtime/facades/providers.py +75 -0
  224. pz_core/runtime/facades/resources.py +52 -0
  225. pz_core/runtime/facades/storage.py +296 -0
  226. pz_core/runtime/health/__init__.py +5 -0
  227. pz_core/runtime/health/service.py +102 -0
  228. pz_core/runtime/host.py +188 -0
  229. pz_core/runtime/host_runner.py +282 -0
  230. pz_core/runtime/http/__init__.py +20 -0
  231. pz_core/runtime/http/app.py +576 -0
  232. pz_core/runtime/http_timing.py +173 -0
  233. pz_core/runtime/invocation.py +29 -0
  234. pz_core/runtime/json_safe.py +47 -0
  235. pz_core/runtime/lifecycle/__init__.py +25 -0
  236. pz_core/runtime/lifecycle/manager.py +533 -0
  237. pz_core/runtime/plan.py +214 -0
  238. pz_core/runtime/plan_context.py +33 -0
  239. pz_core/runtime/plan_snapshot.py +177 -0
  240. pz_core/runtime/registries/__init__.py +27 -0
  241. pz_core/runtime/registries/capabilities.py +101 -0
  242. pz_core/runtime/registries/providers.py +396 -0
  243. pz_core/runtime/resource_assets.py +344 -0
  244. pz_core/runtime/run_cli.py +211 -0
  245. pz_core/runtime/settings.py +888 -0
  246. pz_core/runtime/worker/__init__.py +21 -0
  247. pz_core/runtime/worker/engine.py +921 -0
  248. pz_core/runtime/worker/runtime.py +25 -0
  249. pz_core/testing/__init__.py +15 -0
  250. pz_core/testing/doc_route_contracts.py +305 -0
  251. pz_core/utils/__init__.py +44 -0
  252. pz_core/utils/env.py +65 -0
  253. pz_core/utils/project_jsonc/__init__.py +29 -0
  254. pz_core/utils/project_jsonc/document.py +420 -0
  255. pz_core/utils/project_settings.py +99 -0
  256. pz_foundation/__init__.py +50 -0
  257. pz_foundation/_contracts.py +81 -0
  258. pz_foundation/_errors.py +34 -0
  259. pz_foundation/api.py +14 -0
  260. pz_foundation/apps.py +127 -0
  261. pz_foundation/auth/__init__.py +1 -0
  262. pz_foundation/cache_control.py +233 -0
  263. pz_foundation/cli/__init__.py +2 -0
  264. pz_foundation/cli/workers.py +565 -0
  265. pz_foundation/configs/__init__.py +0 -0
  266. pz_foundation/configs/default.env +15 -0
  267. pz_foundation/configs/default.jsonc +452 -0
  268. pz_foundation/db/__init__.py +94 -0
  269. pz_foundation/db/aerich_executor.py +664 -0
  270. pz_foundation/db/config.py +358 -0
  271. pz_foundation/db/connection_manager.py +689 -0
  272. pz_foundation/db/connection_probe.py +204 -0
  273. pz_foundation/db/database.py +1291 -0
  274. pz_foundation/db/deps.py +47 -0
  275. pz_foundation/db/lifecycle_status.py +85 -0
  276. pz_foundation/db/migrations.py +477 -0
  277. pz_foundation/db/mysql.py +57 -0
  278. pz_foundation/db/postgresql.py +409 -0
  279. pz_foundation/db/production_pool_fallback.py +143 -0
  280. pz_foundation/db/public.py +45 -0
  281. pz_foundation/db/session.py +369 -0
  282. pz_foundation/db/sqlite.py +15 -0
  283. pz_foundation/db/tortoise_manager.py +724 -0
  284. pz_foundation/db/tortoise_psycopg.py +148 -0
  285. pz_foundation/docs/README.md +18 -0
  286. pz_foundation/docs/distribution-README.md +319 -0
  287. pz_foundation/docs/infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/350/257/264/346/230/216.md +39 -0
  288. pz_foundation/docs//345/205/254/345/274/200/345/205/215/350/264/271/346/216/245/345/217/243/351/230/262/346/273/245/347/224/250/344/270/216/344/272/272/346/234/272/346/240/241/351/252/214.md +680 -0
  289. pz_foundation/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +288 -0
  290. pz_foundation/docs//350/267/257/347/224/261/344/270/216URL/345/244/204/347/220/206/350/247/204/350/214/203.md +119 -0
  291. pz_foundation/health.py +105 -0
  292. pz_foundation/host/__init__.py +11 -0
  293. pz_foundation/host/builder.py +34 -0
  294. pz_foundation/host/cache_runtime.py +44 -0
  295. pz_foundation/host/db/__init__.py +17 -0
  296. pz_foundation/host/db/aerich_config.py +36 -0
  297. pz_foundation/host/db/config.py +106 -0
  298. pz_foundation/host/db/connection_manager.py +48 -0
  299. pz_foundation/host/db/deps.py +5 -0
  300. pz_foundation/host/db/orm_retry_patch.py +566 -0
  301. pz_foundation/host/db/request_adapter.py +325 -0
  302. pz_foundation/host/db/router.py +28 -0
  303. pz_foundation/host/db/session.py +284 -0
  304. pz_foundation/host/db/tortoise_manager.py +10 -0
  305. pz_foundation/host/idempotency.py +132 -0
  306. pz_foundation/host/lifespan.py +247 -0
  307. pz_foundation/host/redis_runtime.py +100 -0
  308. pz_foundation/host/web.py +790 -0
  309. pz_foundation/infra_provider.py +236 -0
  310. pz_foundation/kv/__init__.py +25 -0
  311. pz_foundation/kv/cache.py +1166 -0
  312. pz_foundation/kv/deps.py +84 -0
  313. pz_foundation/kv/public.py +25 -0
  314. pz_foundation/kv/redis_manager.py +1531 -0
  315. pz_foundation/lazy_exports.py +43 -0
  316. pz_foundation/lazy_imports.py +124 -0
  317. pz_foundation/lifecycle.py +392 -0
  318. pz_foundation/managed_workers.py +1117 -0
  319. pz_foundation/middlewares/__init__.py +26 -0
  320. pz_foundation/middlewares/_settings.py +250 -0
  321. pz_foundation/middlewares/analytics.py +124 -0
  322. pz_foundation/middlewares/cache_control.py +156 -0
  323. pz_foundation/middlewares/compression.py +202 -0
  324. pz_foundation/middlewares/cors.py +62 -0
  325. pz_foundation/middlewares/geo_country.py +44 -0
  326. pz_foundation/middlewares/inner_router.py +50 -0
  327. pz_foundation/middlewares/rate_limited/__init__.py +3 -0
  328. pz_foundation/middlewares/rate_limited/key_limiter.py +115 -0
  329. pz_foundation/middlewares/request_logging.py +104 -0
  330. pz_foundation/middlewares/route_owner.py +309 -0
  331. pz_foundation/middlewares/security_csrf.py +44 -0
  332. pz_foundation/middlewares/security_headers/__init__.py +4 -0
  333. pz_foundation/middlewares/security_headers/conflicts.py +44 -0
  334. pz_foundation/middlewares/security_headers/csp_nonce.py +200 -0
  335. pz_foundation/middlewares/security_headers/security_headers.py +44 -0
  336. pz_foundation/migrations/__init__.py +1 -0
  337. pz_foundation/migrations/pz_foundation/__init__.py +1 -0
  338. pz_foundation/models.py +22 -0
  339. pz_foundation/notifications/__init__.py +23 -0
  340. pz_foundation/notifications/email.py +542 -0
  341. pz_foundation/notifications/public.py +31 -0
  342. pz_foundation/observability/__init__.py +71 -0
  343. pz_foundation/observability/http.py +34 -0
  344. pz_foundation/observability/logger/__init__.py +49 -0
  345. pz_foundation/observability/logger/_bot_settings.py +126 -0
  346. pz_foundation/observability/logger/bot_message.py +592 -0
  347. pz_foundation/observability/logger/core.py +385 -0
  348. pz_foundation/observability/logger/delivery_audit.py +84 -0
  349. pz_foundation/observability/logger/feishu_bot.py +199 -0
  350. pz_foundation/observability/logger/telegram_bot.py +194 -0
  351. pz_foundation/observability/metrics.py +365 -0
  352. pz_foundation/observability/runtime.py +68 -0
  353. pz_foundation/public.py +405 -0
  354. pz_foundation/resources/__init__.py +12 -0
  355. pz_foundation/resources/builder.py +900 -0
  356. pz_foundation/resources/images.py +363 -0
  357. pz_foundation/root_cli.py +20 -0
  358. pz_foundation/routing/__init__.py +203 -0
  359. pz_foundation/routing/canonical.py +486 -0
  360. pz_foundation/routing/convertors.py +82 -0
  361. pz_foundation/routing/declarations.py +843 -0
  362. pz_foundation/routing/exports.py +148 -0
  363. pz_foundation/routing/loaders.py +138 -0
  364. pz_foundation/routing/manifest.py +215 -0
  365. pz_foundation/routing/manifest_provider.py +47 -0
  366. pz_foundation/routing/mounts.py +101 -0
  367. pz_foundation/routing/ordering.py +172 -0
  368. pz_foundation/routing/registry.py +133 -0
  369. pz_foundation/routing/utils.py +28 -0
  370. pz_foundation/runtime.py +234 -0
  371. pz_foundation/settings.py +253 -0
  372. pz_foundation/settings_normalization.py +130 -0
  373. pz_foundation/storage/__init__.py +25 -0
  374. pz_foundation/storage/local.py +209 -0
  375. pz_foundation/storage/public.py +106 -0
  376. pz_foundation/storage/s3.py +116 -0
  377. pz_foundation/storage/service.py +234 -0
  378. pz_foundation/urls.py +19 -0
  379. pz_foundation/utils/__init__.py +6 -0
  380. pz_foundation/utils/merge.py +160 -0
  381. pz_foundation/worker_replicas.py +55 -0
  382. pz_settings_center/__init__.py +5 -0
  383. pz_settings_center/api/__init__.py +5 -0
  384. pz_settings_center/api/runtime_overrides.py +360 -0
  385. pz_settings_center/apps.py +28 -0
  386. pz_settings_center/configs/__init__.py +0 -0
  387. pz_settings_center/configs/default.env +2 -0
  388. pz_settings_center/configs/default.jsonc +1 -0
  389. pz_settings_center/docs/01-settings_center/350/203/275/345/212/233/350/276/271/347/225/214.md +124 -0
  390. pz_settings_center/docs/README.md +12 -0
  391. pz_settings_center/docs/distribution-README.md +150 -0
  392. pz_settings_center/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +48 -0
  393. pz_settings_center/integration_payload.py +18 -0
  394. pz_settings_center/project_helpers.py +405 -0
  395. pz_settings_center/public.py +139 -0
  396. pz_settings_center/routing_helpers.py +73 -0
  397. pz_settings_center/runtime_override_provider.py +61 -0
  398. pz_settings_center/typed_settings.py +324 -0
  399. pz_settings_center/urls.py +9 -0
@@ -0,0 +1,950 @@
1
+ # CLI 与 Worker 入口规范
2
+
3
+ ## 1. 目标
4
+
5
+ 收口 `pz` 的入口边界,区分:
6
+
7
+ - 框架级入口
8
+ - 项目级入口
9
+ - app 级 CLI 入口
10
+ - worker 级运行入口
11
+
12
+ 避免继续把 vendored 目录执行、wrapper、隐式 in-process worker 启动混成一层。
13
+
14
+ - `pz` 是唯一正式基础包与唯一可独立启动的包
15
+ - app CLI 必须通过正式 `cli.tool` 扩展对象接入 `pz`
16
+
17
+ ## 2. 框架级标准入口
18
+
19
+ 唯一标准 CLI 入口实现:
20
+
21
+ - `pz`
22
+ - `pz`
23
+
24
+ 保留的 Python 技术入口:
25
+
26
+ - `python -m pz_core`
27
+ - `pz.app:create_app`
28
+ - `pz.app:create_host_app`
29
+ - `pz.app:run_host_main`
30
+
31
+ 要求:
32
+
33
+ - 标准入口必须先解析 `project_dir`
34
+ - 再解析完整配置
35
+ - 再编译唯一的 `RuntimePlan`
36
+ - 最后消费 `RuntimePlan` 启动对应进程
37
+ - `pz` 的正式 CLI 真相源固定为 `pz_core.cli:main`
38
+ - `pz` 的正式入口固定为 `pz_core.pz_launcher:main` launcher facade;它只负责按正式顺序选择 provider,再进入某个 `pz_core.cli:main`
39
+ - `pz.root_cli` 固定为顶层命令 provider entry-point group,只负责注册 handler,不是第二个 CLI 入口
40
+ - `__main__` 只允许复用这一个正式 CLI 真相源,不得再长出第二套 wrapper 或 shim 同步逻辑
41
+ - `create_app` / `create_host_app` / `run_host_main` 这类公开 Python API 也必须复用同一套上下文解析与装配边界
42
+
43
+ `pz` 的 provider 选择顺序是正式 contract:
44
+
45
+ 1. 当前项目本地 `.venv`
46
+ 2. 当前项目 dev manifest 里记录的 `pz` bootstrap runtime path(正式 checkout 位于 `apps/.sources/pz`)
47
+ 3. 当前解释器里的已安装 `site-packages`
48
+ 4. `uv tool run --from pz-cli pz`
49
+
50
+ 约束:
51
+
52
+ - `pz` 是高频基础入口,定型后只允许 bugfix、contract 补齐与明确纳入 contract 的新能力
53
+ - 命令路径不做缩写,不登记 `pz e d`、`pz a i`、`pz b mm` 这类二级 alias,也不按前缀猜测命令,避免高频 CLI 因新增命令产生歧义
54
+ - 高频简写只发生在参数层,例如 `--project-dir` / `-d`、`--json` / `-j`
55
+ - 参数短选项必须通过 `pz_core.cli_options.add_cli_option()` 的同一份公共表注册,不允许各命令私自发明短参数
56
+ - 参数短选项必须同步到 `pz -h` / `pz -h`;各 argparse 子命令的 `-h` 也必须展示同一组选项的长短写法
57
+ - 不得随业务能力变化而改变既有命令语义、provider 顺序、入口函数、安装依赖边界或 `project_dir` 解析规则
58
+ - 这条顺序只属于 `pz` launcher facade,不属于 `pz_core.cli:main` 的运行时主链
59
+ - `pz` 无论命中哪一级 provider,最终都必须进入 `pz_core.cli:main`
60
+ - 不允许因为 provider 选择而长出第二套 CLI 语义、第二套 `RuntimePlan` 或第二套 settings/route/resource 编译规则
61
+
62
+ ## 2.1 入口装配流水线
63
+
64
+ 所有正式入口统一采用以下固定流水线:
65
+
66
+ 1. 解析 `project_dir`
67
+ 2. 读取 `pz.jsonc`、`pz.{PZ_ENV}.jsonc`、`<project_dir>/.env` 与 `<project_dir>/.env.{PZ_ENV}`
68
+ 3. 生成 `SettingsSnapshot`
69
+ 4. 编译 `AppRegistry`
70
+ 5. 编译 `ResourceManifest`
71
+ 6. 编译 `InfraContext`
72
+ 7. 编译 `RouteManifest` / `MiddlewareManifest`
73
+ 8. 组装 `CapabilityRegistry`
74
+ 9. 产出 `RuntimePlan`
75
+ 10. 启动 Web / CLI / worker
76
+
77
+ 要求:
78
+
79
+ - 这条流水线是唯一正式装配链
80
+ - `create_app()`、`create_host_app()`、CLI、worker 不得各自裁剪或重排这条流水线
81
+ - 入口层只负责选择进程类型,不负责重新定义中间产物的规则
82
+ - 入口层若未显式指定 `PZ_ENV`,正式默认环境固定为 `develop`
83
+ - 入口层若要启动 `product`,必须在命令行或进程环境中显式指定 `PZ_ENV=product`
84
+ - `pz run = pz run develop = pz run dev`,都映射到 `PZ_ENV=develop`
85
+ - `pz run test` -> `test`,`pz run product` -> `product`
86
+ - 这三条命令只是正式 CLI 对 `PZ_ENV` 的显式映射,不改变底层唯一 selector 仍为 `PZ_ENV`
87
+ - 第 1-9 步属于编译阶段,只允许产出不可变计划
88
+ - 第 10 步属于执行阶段,才允许发生 framework/client/worker 副作用
89
+
90
+ 边界约束:
91
+
92
+ - CLI 子命令执行前不得重新跑一遍局部 app 扫描或 settings 归一化
93
+ - Web 入口在 FastAPI mutation 前必须先拿到完整 `RouteManifest` / `MiddlewareManifest`
94
+ - worker 入口在启动后台循环前必须先拿到完整 `InfraContext` / `CapabilityRegistry`
95
+ - `pz <app_id> <tool>` 属于正式 app CLI 入口,执行前必须编译完整 `RuntimePlan`;它不是只加载 settings 的快捷脚本入口
96
+ - 只需要读取配置的直接 Python 脚本可以使用 `settings_center.settings` 的 settings lazy autoload;该能力只编译/读取 `SettingsSnapshot` 与 settings provider 输出,不代表 Web / CLI / worker runtime 已启动
97
+
98
+ 约束:
99
+ - 公开 Python API 不应默认隐式回落到全局 `settings`
100
+ - `settings=None` 不属于正式入口心智
101
+ - `register_core()` 不应继续把 event bus 初始化、storage backend 绑定、infra singleton 配置、resources/migrations merge、app settings namespace attach、static/uploads mount 混在一个黑盒流程里
102
+ - 这些步骤必须在本次重构中一次收口为显式、可测试的装配阶段
103
+ - `create_app()` / `create_host_app()` 也不应在注册阶段隐式触发 assets build/deploy
104
+ - 入口层也不应继续通过默认 event bus、默认 Redis config、默认 email/i18n runtime 之类全局 setter 改写 process-wide 单例
105
+
106
+ 不再把以下模式作为主路径:
107
+
108
+ - `python pz`
109
+ - 在项目根搜索历史包入口后执行 wrapper
110
+ - 通过根 `pz init` 写 shell rc 和 wrapper 才能正常用框架
111
+
112
+ 约束:
113
+ - help 文案、错误提示、示例命令只使用 `pz ...`
114
+ - `__main__` 不应再通过修改 `sys.path` 来优先处理 vendored/symlink 目录执行
115
+ - `settings_center.settings` 与 `CliManager` 不应在 import/构造阶段直接抓取错误的项目上下文或隐式全局单例
116
+ - `register_core()` / `create_app()` 不应在入口完成后顺手触发 asset build / preflight build
117
+ - 入口帮助文案也不应继续以 `python pz git_plugins`、根 `python pz init`、`python pz run` 为主路径
118
+
119
+ ## 2.2 Python API 与 CLI 的同构约束
120
+
121
+ 公开 Python API 不是第二套入口模型,只是同一入口流水线的程序化入口。
122
+
123
+ 正式要求:
124
+
125
+ - `pz` CLI 与 `create_app()` / `create_host_app()` / `run_host_main()` 必须共享同一编译链
126
+ - Python API 不得跳过 `project_dir` 解析、settings 编译、app registry 编译、`RuntimePlan` 产出
127
+ - Python API 不得接受“半成品 settings 对象”并直接进入正式主链
128
+ - CLI 与 Python API 的错误分层必须一致:
129
+ - project context 错误
130
+ - settings 错误
131
+ - app registry 错误
132
+ - infra/capability 错误
133
+
134
+ 结论:
135
+
136
+ - CLI 是标准用户入口
137
+ - Python API 是标准程序化入口
138
+ - 两者不是两套架构,只是同一条装配链的两个入口形态
139
+
140
+ ## 2.3 非正式入口处理规则
141
+
142
+ 下列路径不是正式入口:
143
+
144
+ - `python pz`
145
+ - `git_plugins`
146
+ - `init`
147
+ - 依赖 vendored/symlink 目录执行的路径
148
+
149
+ 正式要求:
150
+
151
+ - `pz --help` 的主帮助文案只展示正式入口
152
+ - 帮助文案、报错建议、README 示例只使用 `pz ...`
153
+ - CLI 入口不得为了旧路径而修改 `sys.path`、优先注入 repo-root 或推断 vendored `app/`
154
+ - 已安装 global `pz` / `pz` 若在 `pz` 源码根目录内执行,解释器可能因默认 import 优先级先命中当前目录下的 `pz/` 包;这属于 Python 原生遮蔽行为,不属于正式 CLI 安装语义
155
+ - 正式安装验证、发布 smoke、`pz-cli` 冷启动检查必须在 `pz` 源码树外执行;当前目录只能决定 project context,不得被依赖为 CLI 实现选择器
156
+ - CLI 入口不得再生成、回写或同步第二套全局 shell shim
157
+ - 包内 `plugins` 目录不作为正式工作目录
158
+
159
+ ## 3. 项目级入口
160
+
161
+ 项目内部可以有自己的宿主入口文件,但这些文件不构成框架契约。
162
+
163
+ 但这些入口都应复用统一的:
164
+
165
+ - 项目目录发现
166
+ - 配置解析
167
+ - app 装配
168
+
169
+ 项目入口只负责:
170
+
171
+ - 选择要启动的进程类型
172
+ - 选择端口/并发/部署参数
173
+ - 组合项目自有 app
174
+
175
+ 不负责重复实现 `pz` 的核心配置逻辑。
176
+
177
+ 正式约束补充:
178
+
179
+ - 宿主项目正式只保留一个根 `main.py`
180
+ - `main.py` 只保留两个正式入口函数:`create_app()` 与 `main()`
181
+ - `create_app()` 只负责调用统一 host builder,例如 `create_host_app(project_dir=resolve_project_dir(__file__))`
182
+ - `main()` 只负责读取少量启动快捷参数并调用 `uvicorn.run(...)`
183
+ - 项目入口不得再声明 `_resolve_project_dir()`、`PROJECT_DIR = ...`、`_project_*()`、本地 snapshot cache 或其它宿主私有 settings wrapper
184
+ - grouped init 命令生成的新项目 `main.py` 必须遵循同一形态
185
+
186
+ 项目入口允许的快捷配置范围固定为:
187
+
188
+ - `project.app_host`
189
+ - `project.app_port`
190
+ - `project.app_workers`
191
+ - `project.app_reload`
192
+
193
+ 项目入口允许读取的进程环境变量固定为:
194
+
195
+ - `APP_HOST`
196
+ - `APP_PORT`
197
+ - `APP_RELOAD`
198
+ - `APP_WORKERS`
199
+ - `UVICORN_LOOP`
200
+ - `UVICORN_HTTP_IMPL`
201
+ - `UVICORN_LOG_LEVEL`
202
+ - `UVICORN_PROXY_HEADERS`
203
+ - `UVICORN_FORWARDED_ALLOW_IPS`
204
+ - `UVICORN_ACCESS_LOG`
205
+
206
+ 补充说明:
207
+
208
+ - 上述变量是宿主根 `main.py` 的启动快捷入口,正式使用大写命名
209
+ - 它们不改变 settings 体系“项目字段走 section path、小写字段名”的主约定
210
+ - `BASE_URL`、`STATIC_TARGET_PATH`、`STATIC_TARGET_OWNER` 虽不直接传给 `uvicorn.run(...)`,但会在 settings 编译链中作为同一类宿主启动特例处理
211
+
212
+ 约束补充:
213
+
214
+ - `pz.runtime.host_runner` 只读取正式大写 host env,不再兼容小写 `app_host` / `app_port` / `app_reload` / `app_workers`
215
+ - 宿主项目 `main.py`、settings override 与 `host_runner` 保持同一套单轨入口,不扩散双轨读取
216
+
217
+ 优先级规则:
218
+
219
+ - 若大写入口环境变量与 `project` 中的小写快捷字段语义相同,则大写环境变量优先级最高
220
+ - 当前正式映射固定为:
221
+ - `APP_HOST -> project.app_host`
222
+ - `APP_PORT -> project.app_port`
223
+ - `APP_WORKERS -> project.app_workers`
224
+ - `APP_RELOAD -> project.app_reload`
225
+ - `BASE_URL -> project.base_url`
226
+ - `STATIC_TARGET_PATH -> project.static_target_path`
227
+ - `STATIC_TARGET_OWNER -> project.static_target_owner`
228
+ - `project.base_url` 是唯一服务 URL 配置入口:开发环境通常配置本地/IP URL,生产环境配置线上域名
229
+ - settings 编译层必须通过统一 `HostRuntimeEndpointResolver` 解析 `base_url`、`APP_HOST`、`APP_PORT`,并同时产出编译后的 `project.app_host`、`project.app_port`、`project.base_url`
230
+ - 当 `base_url` 的 host 是 `localhost`、`127.0.0.1`、`0.0.0.0`、IPv4 或 IPv6 地址时,显式 `APP_HOST` / `APP_PORT` 可以改写编译后的本地 `project.base_url`;例如 `APP_PORT=8005 pz run -d .` 会把本地服务 URL 编译为 `http://127.0.0.1:8005`
231
+ - 当 `base_url` 的 host 是线上域名时,显式 `APP_HOST` / `APP_PORT` 只作为运行监听覆盖,不得改写编译后的 canonical `project.base_url`
232
+ - 当没有显式 `APP_HOST` / `APP_PORT` 时,启动监听参数必须从 `base_url` 反推;这样开发只需要写本地/IP `base_url`,生产只需要写域名 `base_url`
233
+
234
+ 运行约束补充:
235
+
236
+ - `manga-translate-web` 这类 console script 最终会导入当前项目根的 `main.py`
237
+ - `pz run` / `pz run` 的正式行为是直接 handoff 到项目根 `main.py`,而不是在外层长期保留一个包装父进程
238
+ - 因此必须在目标项目根目录执行,不能把上层工作区目录当成长期正式启动 cwd
239
+
240
+ 开发态 reload 规则:
241
+
242
+ - 宿主入口不应让 `uvicorn --reload` 直接监控整个项目根目录
243
+ - 正式做法是只监控 `apps/` 下的可见最小子包目录
244
+ - 隐藏目录例如 `apps/.sources/` 与 `__pycache__` 必须排除在 reload watch 之外
245
+
246
+ ## 3.1 正式命令三层边界摘要
247
+
248
+ 命令分类的唯一正式真相表见 [`pz命令总览.md`](../pz命令总览.md)。本规范只固定与入口边界相关的一致摘要:
249
+
250
+ - 编排命令:`pz dev init`、`pz dev add`、`pz dev link`、`pz dev branch`、`pz dev update`、`pz dev unlink`、`pz env init`、`pz app init`、`pz app add`、`pz app update`、`pz app rm`、`pz pub`、`pz pub batch`
251
+ - 原子命令:`pz env doctor`、`pz env install`、`pz env sync`、`pz settings init`、`pz settings update`、`pz settings refresh-agents`、`pz settings reset-agents`、`pz startapp`、`pz app versions`、`pz app declare`、`pz app undeclare`、`pz app install`、`pz dev source cache`、`pz dev source import`、`pz dev source link`、`pz dev source branch`、`pz dev source update`、`pz dev source unlink`、`pz dev ide sync`、`pz pub commit`、`pz pub tag`、`pz pub upload`、`pz pub rm`
252
+ - 运行时命令:`pz run`、`pz list`、`pz check`、`pz db ...`、`pz workers ...`、`pz resources ...`、`pz <app_id> <tool>`
253
+
254
+ 每个命令只能属于一层。`env install` / `env sync` 是原子命令,`pub rm` 是原子命令;它们不得再列入编排层。编排命令可以调用原子命令,但不得改变 `installed_apps` 与 `RuntimePlan` 的唯一真相源地位。
255
+
256
+ ### 3.1.0 `pz env doctor` / `pz env install` / `pz env init` / `pz env sync`
257
+
258
+ `env` 组命令的正式职责是项目作者面环境管理。其中 `env init` 属于编排层,`env doctor` / `env install` / `env sync` 属于原子层。
259
+
260
+ 它们的语义固定如下:
261
+
262
+ - `pz env doctor`
263
+ - 检查当前项目目录上的作者面前置条件是否齐备
264
+ - 当前正式检查项至少包括 `python`、`uv`、`git` 与项目目录有效性
265
+ - `pz env install`
266
+ - 创建或复用当前项目根 `.venv`
267
+ - 再对当前项目根和已发现的本地作者面 checkout 委托执行首轮依赖同步
268
+ - 它是正式初始环境安装入口,不要求用户手工分开执行 `.venv` 准备与第一次 `uv sync`
269
+ - `pz env init`
270
+ - 对空项目目录补齐正式项目骨架
271
+ - 然后统一执行 settings 托管区刷新
272
+ - 再委托 `pz env install` 完成当前项目根和已发现本地作者面 checkout 的初始环境安装
273
+ - 它是对既有正式原子动作的编排,不引入第二套骨架或第二套 settings 主链
274
+ - `pz env sync`
275
+ - 不改项目骨架与 settings
276
+ - 只对当前项目根和已发现的本地作者面 checkout 委托执行依赖同步
277
+ - source-root workspace overlay 必须排除 `.venv`、`.pytest_cache`、`__pycache__`、`*.egg-info` 与 Python 包根 `dist` 等生成目录,只允许源码真相进入 editable build;不得删除依赖目录内部的同名资源目录,生成目录符号链接只允许解除链接,不得跟随删除外部目标
278
+ - 它是正式依赖同步入口,不要求用户裸跑 `uv sync`
279
+
280
+ 边界:
281
+
282
+ - `env doctor` 只做诊断,不做副作用安装
283
+ - `env install` 只负责 `.venv` 准备与首轮依赖同步
284
+ - `env init` 只复用底层 scaffold service、`pz settings update` 与 `pz env install` 的正式语义
285
+ - `env sync` 只负责依赖同步,不替代 `env init`
286
+ - `env init` 不替代 `app add` / `dev add` / `dev link` / `publish`
287
+ - `env` 组命令不维护第二套项目配置入口,不额外生成不同命名的 settings 文件
288
+
289
+ 一句话:
290
+
291
+ - `env` 组命令管理“当前项目作者面环境是否就绪”
292
+ - `app` 组命令管理“项目装了谁”
293
+ - `dev` 组命令管理“本地拉了谁的源码”
294
+ - `publish` / `pub` 管理“谁被正式发布”
295
+
296
+ ### 3.1.1 `pz startapp`
297
+
298
+ `pz startapp` 的正式语义是:
299
+
300
+ - 在当前项目 `apps/` 下创建一个正式最小子包骨架
301
+ - 目录名、import 包名、`app_id` 与 distribution 约定统一按正式命名规则展开
302
+ - 默认把新建 app 写入项目声明,并执行一次托管 settings 刷新
303
+ - 传 `--target-dir` 时只生成 `<target-dir>/<app_id>/` 源码骨架,不改项目 `installed_apps`,也不刷新项目 settings
304
+
305
+ 边界:
306
+
307
+ - 只负责本地最小子包脚手架
308
+ - 不修改项目解释器环境中的 distribution 安装状态
309
+ - 不替代 `pz app add`
310
+ - 不进入发布链
311
+
312
+ ### 3.1.2 `pz dev init`
313
+
314
+ `pz dev init` 的正式语义是:
315
+
316
+ - 作为新建开发项目的唯一正式编排入口
317
+ - 创建或复用项目骨架
318
+ - 创建或复用默认本地 app
319
+ - 默认先通过 `dev source cache` 固定官方 `pz_apps` revision,再对其中每个正式最小叶子执行 `dev source import`,源码落在 `apps/<app_id>` 并由业务仓拥有
320
+ - 所有叶子预检和导入成功后,只执行一次 `settings update`、一次 `env install` 与一次 `dev ide sync`
321
+ - `--no-sync` 只跳过 `env install`,因此不会创建项目根 `.venv`;IDE 同步仍执行
322
+ - 旧 linked bootstrap 行为只通过 `--link --clone-sources` 或 `--link --source-dir <path>` 显式进入,两个 selector 必须且只能出现一个
323
+ - `--clone-sources` / `--source-dir` 不带 `--link` 时直接失败;linked 模式默认从 `develop` 创建业务分支,显式替代基础分支只有 `main`
324
+ - linked 模式保留原 bootstrap scope,不隐式暴露完整 `pz_apps` 仓
325
+
326
+ 边界:
327
+
328
+ - 它是编排命令,不替代 `pz run`
329
+ - 它只组合 scaffold、source cache/import 或 source link、settings update、env install 与 IDE sync 原子能力
330
+ - 它不负责运行时 settings 编译、app 导入校验或 host 启动
331
+ - 它不替代后续按需使用的 `pz dev add`、`pz dev link`、`pz app add`、`pz settings update`
332
+
333
+ ### 3.1.3 `pz app init` / `pz app add` / `pz app rm` / `pz app update`
334
+
335
+ `app` 组命令的正式职责是维护项目级 app 声明,也就是维护当前项目的 `installed_apps` 与相关项目装配信息。
336
+
337
+ 它们的语义固定如下:
338
+
339
+ - `pz app init`
340
+ - 扫描当前项目已有 `apps/.sources` checkout
341
+ - 从 `.sources` 中读取默认包名与内部 PyPI / devpi 安装位置
342
+ - 把 `.sources` 中所有正式最小 app 子包加入当前项目声明
343
+ - 默认创建或复用项目根 `.venv`
344
+ - 刷新托管 settings 区块
345
+ - 默认把单一基础 distribution `pz-cli` 与已发现正式最小 app 的已发布 distribution 安装进项目 `.venv`
346
+ - 安装必须走内部 PyPI / devpi,不得从源码 editable 安装
347
+ - `pz app add <app_id> [--version <version>]`
348
+ - 编排版本解析、exact declaration、exact install 与 settings refresh
349
+ - 未传版本时选择正式 index 中最新兼容稳定版
350
+ - `pz app update <app_id> [--version <version>]`
351
+ - 对已声明 app 编排同一版本链;未传版本时更新到最新兼容稳定版
352
+ - `pz app rm <app_id>`
353
+ - 编排 `app undeclare`、环境 reconciliation 与 settings refresh
354
+ - `pz app versions <app_id>`
355
+ - 只读列出可用版本,并标记 latest、declared、locked 与 installed
356
+ - `pz app declare <app_id> --version <version>` / `pz app undeclare <app_id>`
357
+ - 原子维护 exact distribution pin 与 app identity/load-order declaration
358
+ - `pz app install <app_id> --version <version>`
359
+ - 原子安装已经解析出的精确版本并验证 installed metadata
360
+
361
+ 边界:
362
+
363
+ - `app init` 是生产装配模型下的编排命令;默认只复用 `.sources` 包清单发现、项目声明、settings update、项目 `.venv` 准备和 distribution 安装原子能力
364
+ - `app init` 默认安装位置来自 `.sources` 中各包最近 source-root 的 `tool.pz.publish.default_target` 与对应 `targets.<target>.check_url`;若默认包清单跨多个内部 PyPI / devpi index,`app init` 会把这些 index 去重后交给同一次安装解析
365
+ - `app init` 安装项使用 `.sources` 中各包 `pyproject.toml` 的 distribution 名,具体版本由内部 PyPI / devpi 与项目锁仓策略解析;`app init` 不把源码 checkout 的当前 version 当作生产安装 pin
366
+ - `app init` 必须先为全部目标解析最新兼容稳定版,形成依赖安全的 exact-version plan;冲突在项目 mutation 前失败
367
+ - `app init --no-sync` / `app init -S` 同时跳过项目根 `.venv` 准备与 distribution 安装;项目声明与 settings 刷新仍会完成
368
+ - `app init` 不 clone 或导入源码,不替代 `dev add` / `dev link` / `dev init`
369
+ - `app init` 不发布 package,不替代 `pub`
370
+ - `app init` 安装 `pz-cli` distribution,但只把正式最小 app 子包写入 `installed_apps`
371
+ - `app init` 跳过 `pz-cli` 与没有 `apps.py` 的集合包,避免把非 app distribution 写进运行时声明
372
+ - `app init` 写入 `installed_apps` 时必须尊重 source app 的 `requires_apps` 依赖顺序,不能生成运行时 compiler 会拒绝的显式顺序
373
+ - `app add` / `app update` / `app rm` 属于编排层;`app versions` / `app declare` / `app undeclare` / `app install` 属于原子层
374
+ - 默认 latest 只作为调用时选择规则;选中后必须写入 exact project pin 与 `uv.lock`,不得持久化浮动 `latest`
375
+ - `--version` 只接受一个精确 PEP 440 版本;range 属于 package dependency metadata,不属于项目安装选择
376
+ - `app versions` 必须使用 PEP 440 排序并排除默认选择中的 yanked/prerelease,且不得修改项目、环境、lock 或 index
377
+ - `app update` 只作用于已声明 app 的 distribution 安装刷新,不创建第二套源码装配模型
378
+ - 不直接承担源码拉取
379
+ - 不直接承担发布
380
+ - 不替代后续按需使用的 `settings init` / `settings update`;它只负责初始化时的托管区块同步
381
+ - `app add` / `app update` 永远按 distribution 名称与已解析 exact version 安装到当前项目解释器环境,不回退为源码仓 `editable` 安装
382
+ - `app declare` / `app add` 不接管 `apps/<app_id>` 中业务拥有的真实源码;存在同名真实目录时返回 `PZ_APP_SOURCE_OWNERSHIP_CONFLICT`
383
+ - `app rm` 只允许移除已声明 app;若目标 app 未声明,命令必须报错,不得返回误导性的成功提示
384
+ - 若能从项目 `publish` 或对应 source-root 的 `tool.pz.publish.targets.<name>.check_url` 解析出正式私有索引,安装命令可以只复用这份索引元数据补全 `uv sync` 的索引与认证环境;这不改变“按 distribution 安装”的正式语义
385
+ - `app add` / `dev add` / `dev link` 完成后必须检查结果状态;若多个项目本地源码位置同时暴露同一 `app_id`,命令直接报错,同时提示标准人工处理方式
386
+ - `dev add` 可以把已声明 distribution 切换为指向业务目录的 local source;此时项目源码优先。反方向切回 package 模式必须先由业务 Git 工作流移除或迁出同名真实源码,再执行 `app add` / `app declare`
387
+
388
+ 一句话:
389
+
390
+ - `app` 组命令管理“项目装了谁”
391
+ - `dev` 组命令管理“本地拉了谁的源码”
392
+ - `publish` / `pub` 管理“谁被正式发布”
393
+
394
+ ### 3.1.4 `pz dev add`
395
+
396
+ `pz dev add` 是 `dev source cache -> dev source import -> settings update -> env sync -> dev ide sync` 编排命令;非 Git 本地输入跳过 cache。
397
+
398
+ `pz dev source cache` 的正式原子语义是:
399
+
400
+ - 使用当前用户隔离的 `<system-temp>/pz/users/<user-key>/git/<repo_key>` 作为可丢弃 Git cache;POSIX 的 `<user-key>` 为 `uid-<uid>`
401
+ - cache root、repo lock、checkout 与 `.pz-cache-owner.json` 必须通过当前用户 owner、限制权限、非符号链接与 canonical remote 校验
402
+ - 默认分支是 `develop`;只有显式 `--branch` 才选择其他分支
403
+ - cache 不存在时在 sibling staging clone、校验无凭据 canonical remote 与 branch 后原子落位
404
+ - matching cache 存在时先 fetch/update,再返回 exact commit;更新失败不得静默使用旧 revision
405
+ - 返回 canonical `repo_key`、full commit 与不可变 resolution ref;已有 resolution ref 不得移动
406
+ - `--revision <full-commit>` 用于失败续跑时验证已有不可变 resolution ref,不得重新选择 branch head;cache/ref 丢失时明确失败,不接受任意 Git object 作为替代
407
+ - clone/update 按 repo lock 串行;损坏、symlink redirect、remote mismatch 或无法证明 PZ 所有权的 entry 不得被信任或递归删除
408
+ - cache 不是 runtime source、项目 binding 或第二源码真相;其持久性只是一项优化
409
+
410
+ `pz dev source import` 的正式原子语义是:
411
+
412
+ - Git 输入必须显式接收 `--repo-key <repo_key> --revision <full-commit>`,并在同一 repo lock 下验证 resolution ref 精确指向该 commit
413
+ - 不得读取可移动 branch、`HEAD` 或 cache 当前最新状态;revision 无法证明时必须失败
414
+ - 接受可唯一解析到一个正式最小子包的 app 身份、显式 Git URL、本地 Git 路径或非 Git 本地目录
415
+ - Git 来源只读取 `source cache` 固定的 exact commit,不执行网络或 cache 更新;最终 `apps/<app_id>` 不保留 `.git`
416
+ - 导入源码由业务仓拥有,PZ 不再对其执行 branch、update、覆盖或自动删除
417
+ - 导出内容先进入 `apps/` 下隐藏 staging 目录,完成 app 声明、distribution、身份和冲突校验后原子落位
418
+ - 输入解析到零个或多个最小子包时直接失败,不按目录顺序猜测
419
+ - 任意真实本地 app、linked binding 或其他项目本地路径已暴露相同 `app_id` 时直接失败;冲突按解析后的 app 身份判断,不按路径名称判断
420
+ - 重复执行不得覆盖业务仓已有修改
421
+
422
+ 导入规则:
423
+
424
+ - Git 输入优先使用固定 commit 的结构化导出,不递归复制 checkout 元数据
425
+ - `.git`、`.venv`、cache、build、dist、egg-info 等生成或仓库元数据不得进入业务源码目录
426
+ - 非 Git 本地目录遵守同一排除、唯一叶子解析和校验合同
427
+ - 项目 `apps.<app_id>.sources.source_mode` 必须收敛为 `local`;Git provenance 写入无凭据 canonical source、full revision 与 leaf subpath;本地目录 provenance 写入 `source = "local"`、不可逆 source identity 与 leaf subpath,不落本机绝对路径
428
+ - 宿主 `pyproject.toml` 必须在同一原子事务中声明 app dependency 与指向 `apps/<app_id>` 的精确 editable `tool.uv.sources`;app 目录、source mode、provenance 或宿主依赖任一步失败时整体回滚
429
+ - 原子导入不刷新 settings、环境或 IDE 投影;这些阶段只由 `dev add` 编排,不新增第二套 manifest
430
+
431
+ 约束:
432
+
433
+ - per-operation staging 必须在成功、失败和中断路径清理;已验证 Git cache 允许保留复用
434
+ - transaction 失败时不得留下目标目录、半成品项目元数据或可见 app
435
+ - 不自动把业务改动合并回上游,也不自动把上游更新覆盖到业务源码
436
+ - 业务仓源码的删除、回退和历史管理统一走业务仓 Git 工作流
437
+
438
+ ### 3.1.5 `pz dev link`
439
+
440
+ `pz dev link` 是 `dev source link -> settings update -> env sync -> dev ide sync` 编排命令。`pz dev source link` 的正式原子语义是保留上游 Git 生命周期并建立可见 binding:
441
+
442
+ - 接受已有 manifest 身份、显式 Git URL、本地 Git 路径或非 Git 本地目录
443
+ - Git checkout 的唯一项目入口是 `apps/.sources/<repo_key>`;该入口允许是指向项目外共享 Git checkout 的符号链接
444
+ - 根据输入粒度在 `apps/` 建立一个受管相对快捷方式:目录输入建立目录 binding,叶子输入建立叶子 binding
445
+ - 默认基础分支是 `develop`;显式替代值只有 `main`
446
+ - PZ 管理 checkout 的目标分支固定为 manifest 的 `business_app_id`,命令不接受任意目标分支
447
+ - 相同 Git source 只维护一个 checkout;同仓后续 binding 必须复用它
448
+ - 本地 Git 路径也 clone 进当前项目,不切换调用方原目录
449
+ - 已存在的共享 checkout 链接可以被复用,但 PZ 只校验 Git 身份和 remote,不 fetch、不 switch、不创建业务分支
450
+ - 非 Git 本地目录记录为 `source_kind=link`,不进入 Git 分支协议
451
+ - 物理 `apps/.sources` 不贡献运行时 app;运行时只发现 `apps/` 下的真实本地 app 和可见 binding
452
+ - checkout、branch/ref、manifest 与 binding 作为一个可回滚事务更新
453
+ - 目录 binding 与其内部叶子 binding 不得重叠
454
+ - 任意业务仓真实目录或其他 binding 已暴露相同 `app_id` 时直接失败,不允许一个 app 身份同时拥有两条本地源码真相
455
+
456
+ ### 3.1.6 `pz dev branch`
457
+
458
+ `pz dev branch` 是 `dev source branch -> env sync -> dev ide sync` 编排命令。`pz dev source branch` 是已有受管 checkout 的原子分支命令:
459
+
460
+ - `<repo-or-app>` 只用于从 manifest 定位 checkout
461
+ - worktree 必须 clean
462
+ - 当前分支只允许业务分支、`develop` 或 `main`;其他功能分支和 detached HEAD 直接失败
463
+ - 本地业务分支存在时直接切换;只有远端业务分支时建立 tracking;两者都不存在时从选定 base 创建
464
+ - `--base-branch` 只决定首次创建点,不改变已经存在的业务分支
465
+ - direct-link binding 不是 Git checkout,必须稳定失败
466
+ - 业务仓拥有的 `apps/<app_id>` 不属于 linked checkout,必须稳定失败
467
+
468
+ ### 3.1.7 `pz dev update`
469
+
470
+ `pz dev update` 是 `dev source update -> env sync -> dev ide sync` 编排命令。`pz dev source update` 只更新受管业务分支:
471
+
472
+ - 要求当前分支等于 manifest 业务分支且 worktree clean
473
+ - 有 upstream 时只允许 fast-forward-only
474
+ - 没有 upstream 时只 fetch 并报告未应用更新
475
+ - 不从 base merge/rebase,也不改变 binding 粒度
476
+ - 共享 checkout 返回 `PZ_DEV_SHARED_CHECKOUT_READ_ONLY`
477
+ - 业务仓拥有的 `apps/<app_id>` 不进入自动上游更新协议
478
+
479
+ ### 3.1.8 `pz dev unlink`
480
+
481
+ `pz dev unlink` 是 `dev source unlink -> settings update -> env sync -> dev ide sync` 编排命令。`pz dev source unlink` 删除精确 binding 与对应 `apps/` 符号链接:
482
+
483
+ - 同仓还有其他 binding 时保留 checkout
484
+ - 删除最后一个 binding 后默认仍保留 checkout
485
+ - 只有显式 `--delete-checkout`、worktree clean、upstream 可验证且没有未推送提交时才删除 checkout
486
+ - bootstrap `pz` repo 不会因删除 app binding 被删除
487
+ - 不改变项目已发布 app 声明,不触碰远端仓库
488
+ - 不删除 `pz dev add` 导入的业务仓真实目录
489
+ - checkout 条目若为共享符号链接,`--delete-checkout` 最多只解除项目内链接,不跟随删除外部目标
490
+
491
+ ### 3.1.9 `pz dev ide sync`
492
+
493
+ `pz dev ide sync` 是所有 IDE 影子投影的唯一原子 owner。它只编译一次可见 app 投影,再委托给独立 provider:
494
+
495
+ - `.idea/` 存在时维护 `.idea/pz.generated.sources.iml`,并在 `.idea/modules.xml` 中只维护一个 PZ-owned module entry
496
+ - `.vscode/` 存在时以 JSONC 方式维护 `.vscode/settings.json` 中由 PZ 插入的 `python.analysis.extraPaths`,状态账本固定为 `.vscode/pz.generated.sources.json`
497
+ - PyCharm 对业务仓 app 登记项目相对 root,对 linked app 登记 canonical 叶子 root
498
+ - VS Code 对两种 app 都登记 `${workspaceFolder}/apps/<visible-leaf-path>`;不得登记整个 checkout、隐藏 `.sources`、未绑定叶子或外部绝对路径
499
+ - 影子资产只包含 IDE module metadata,不复制源码,不进入运行时发现、import precedence、打包、资源编译或发布
500
+ - 使用结构化 XML / JSONC API 保留用户内容;VS Code 只移除状态账本记录的旧 PZ entries
501
+ - 对应 IDE 目录不存在时 provider 返回 `not_applicable`,不创建 `.idea/` 或 `.vscode/`
502
+ - VS Code 双文件替换使用事务 journal;受控失败恢复旧 pair,中断由下一次 sync 先恢复或完成
503
+ - `pz check` 诊断 stale、broken、duplicate、escaping 或不可写的 PZ projection,并以 `pz dev ide sync` 作为唯一修复入口
504
+
505
+ dev 编排跨原子阶段保留已完成源码状态,并统一报告 `completed_stages`、`next_stage` 与原始稳定错误码。`dev add` 在 exact Git provenance 或本地不可逆 source identity 能证明既有导入时可自动跳过 source mutation;其他 dev 编排按 `next_stage` 显式调用公开原子命令继续,不依赖隐式跨命令 journal。任何路径都不得删除业务源码、reset checkout 或覆盖用户 `.idea` / `.vscode` 内容伪装回滚。
506
+
507
+ ### 3.1.10 顶层源码同步命令收敛
508
+
509
+ 顶层不再保留单独的 `pz sync`。
510
+
511
+ 当前正式口径固定为:
512
+
513
+ - 业务仓源码导入使用 `pz dev add`
514
+ - 上游源码 checkout 与 binding 使用 `pz dev link`
515
+ - linked checkout 更新使用 `pz dev update`
516
+ - linked binding 移除使用 `pz dev unlink`
517
+ - 业务仓真实源码的删除和回退使用业务仓 Git 工作流
518
+ - 推送源码到远端仍属于 git 工作流
519
+
520
+ 结论:
521
+
522
+ - 不再设计顶层 `pz sync`
523
+ - 不应把 `git push` 折叠进 `pz` 项目编排命令
524
+
525
+ ### 3.1.11 `pz pub`
526
+
527
+ `pz pub` 的正式语义是:
528
+
529
+ - 对一个已经显式设置 `project.version` 的最小子包,顺序编排 `pub commit`、`pub tag` 与 `pub upload`
530
+ - 若 `project_dir` 自身是 Git root 且根 distribution 精确匹配目标,直接返回仓库根;否则枚举 `apps/.sources` 并复用 `iter_workspace_packages` / `resolve_workspace_package` 的共享发现能力,不回退业务复制目录
531
+ - 非根目标搜索必须唯一返回 package root 与 owning Git root;没有可用 Git 仓库、未找到目标子包、多个仓库重复命中分别失败
532
+ - 外部共享只读 checkout 可以参与发现,但 `pub commit/tag/upload` 必须在 commit 或 ref mutation 前返回 `PZ_PUB_SHARED_CHECKOUT_READ_ONLY`
533
+ - commit 前检查目标 index 的 distribution/version;远端已存在但本地 release commit/tag/artifact 不精确匹配时直接失败
534
+ - 根 distribution 提交显式 `.` 整仓 scope;嵌套子包只提交目标路径,不提交同仓其他最小子包修改
535
+ - 创建 `<distribution-name>@<version>` annotated tag
536
+ - 不自动升级版本号,不自动生成 changelog,不执行 `git push`
537
+
538
+ `pz pub commit` 的正式语义是:
539
+
540
+ - 独立执行同一份“仓库根精确匹配优先,否则 `.sources` 搜索”的约束解析
541
+ - 在目标 package 所属 Git worktree 中,只 stage 并 commit 目标 package path
542
+ - index 必须预先 clean;其他正式最小子包中的 unstaged 修改允许保留且不得进入 commit
543
+ - 未归属任何最小子包的 shared-root 未提交修改阻止单包 release
544
+ - commit subject 固定为 `release(<app_id>): <version>`
545
+
546
+ `pz pub tag` 的正式语义是:
547
+
548
+ - 只为已经验证的 release commit 创建目标 package annotated tag
549
+ - tag 不存在时必须指向 `pub commit` 返回的精确 release commit;重试时该 commit 可以是当前分支可到达的历史 commit,不得误标当前无关 HEAD
550
+ - annotation 固定为 `release(<app_id>): <distribution-name> <version>`
551
+ - 已存在 tag 的 annotation 与 release commit 精确匹配、且 commit 可从当前分支到达时幂等复用,即使 HEAD 已前进;任何不匹配都直接失败
552
+
553
+ `pz pub upload` 的正式语义是:
554
+
555
+ - 要求当前 index/worktree clean 且 HEAD 精确等于 package tag commit,从当前 package root 直接构建,验证 `project.version` 与 wheel metadata,并在 clean-environment wheel smoke 通过后执行 upload
556
+ - `--version` 必须与当前 `project.version` 一致;HEAD 已进入下一版本时不得续传旧 tag
557
+ - 不 commit、不打 tag、不 push、不修改源码
558
+
559
+ `pz pub rm` 的正式语义是:
560
+
561
+ - 对一个已经发布过的最小子包执行正式删除链
562
+ - 只操作 package index,不要求 `.sources` Git 仓库,也不复用发布 source gate
563
+ - 当前正式只支持 devpi target
564
+ - 删除整个 distribution 在目标索引中的全部版本,而不是只删某一个文件
565
+
566
+ `pz pub batch` 的正式语义是:
567
+
568
+ - 对一组已经版本化的最小子包按显式给定顺序串行执行 `pub`
569
+ - 它是上层编排命令,按顺序为每个 app 执行完整单包 `pub` 编排
570
+ - 不允许根据 workspace 扫描结果隐式猜测依赖顺序
571
+ - 若同批次存在依赖链,顺序必须由调用方显式给出
572
+
573
+ 约束:
574
+
575
+ - 发布前必须已有明确版本号
576
+ - `pub --dry-run` 不修改 index、不 commit、不创建 tag、不上传,只完成 scope/build/target 验证与计划输出
577
+ - 不允许把未版本化的本地源码 checkout 直接视为正式发布物
578
+ - `pub` 与 `dev add` / `dev link` / `dev update` / `dev unlink` 必须是两条独立主链
579
+ - `pub rm` 与 `pub` 共用同一份 target 解析与发布凭据来源
580
+ - `pub batch` 只负责顺序编排,不新增第二套发布协议;每个 app 仍有独立 release commit 与 tag
581
+ - commit/tag/upload 任一后续阶段失败时保留已完成状态;重跑只复用精确匹配状态并继续,不 reset、amend、删 tag 或改写历史
582
+ - 凭据正式仍然是环境变量;`pz pub` 允许优先使用当前进程环境,并在当前项目根存在 `.env` 时把其中的发布凭据补入子进程环境,但不覆盖已经显式导出的环境变量
583
+ - 对 non-volatile 的 devpi index,调用方必须显式传 `--force`
584
+
585
+ 一句话:
586
+
587
+ - `dev add` 解决业务仓源码接管;`dev link` / `dev update` / `dev unlink` 解决 linked checkout 管理
588
+ - `pub` 解决子包 Git release 与对外交付编排;`pub rm` 解决已发布产物回收
589
+
590
+ ## 4. app CLI 入口
591
+
592
+ 每个 app 的 CLI 工具统一放在:
593
+
594
+ ```text
595
+ <app>/cli/<tool>.py
596
+ ```
597
+
598
+ 由框架统一发现并暴露为:
599
+
600
+ - `pz <app_id> <tool>`
601
+
602
+ 要求:
603
+
604
+ - tool 在运行前拿到同一份解析后的 settings
605
+ - tool 不得绕过主配置解析器自己再做一套 repo-root 推断
606
+ - app CLI 的正式调用路径是 `pz <app_id> <tool>`
607
+ - 类似 `git_plugins` 这类工具,不得默认反推框架包内目录作为插件仓库根目录
608
+ - CLI manager 不应默认绑定进程级全局 settings 单例
609
+ - `db` 这类框架工具也必须消费显式 project context,不得靠 `_repo_root()`、包内 merged 目录、`PYTHONPATH` 注入来兜底
610
+ - `db` CLI 的帮助文案、`prog`、example 也不应继续以 `python pz db` 和 `pz/merged/aerich.ini` 为中心
611
+
612
+ ## 4.1 `cli.tool` 正式协议
613
+
614
+ app CLI 必须通过正式 `cli.tool` 扩展对象暴露,不再允许自由函数、隐式注册器或动态脚本猜测。
615
+
616
+ 每个 `cli.tool` 至少应包含:
617
+
618
+ - `kind = "cli.tool"`
619
+ - `id`
620
+ - `owner_app`
621
+ - `api_version`
622
+ - `priority`
623
+ - `command`
624
+ - `summary`
625
+ - `tool`
626
+
627
+ `tool` 必须实现:
628
+
629
+ - `configure(parser) -> None`
630
+ - `run(ctx) -> int`
631
+
632
+ 当前正式文件形态:
633
+
634
+ - `<app>/cli/<tool>.py` 必须暴露模块级 `tool = CliToolSpec(...)`
635
+ - `pz` 在 `compile_runtime_plan()` 阶段通过 `compile_cli_manifest()` 加载并校验这个正式对象
636
+ - CLI / worker 执行阶段只消费 `RuntimePlan.cli_manifest`,不得重新扫描 app 目录或重新 import CLI 模块来生成局部命令图
637
+ - 不再把模块级 `main()`、`worker_main()` 或其它自由函数作为正式 dispatch 入口
638
+ - worker 型工具仍通过 `CliToolSpec` 暴露;需要正式 worker runtime 时,由 `tool.tool.worker_entry(...)` 作为 worker 入口函数
639
+
640
+ `ctx` 至少应包含:
641
+
642
+ - `project`
643
+ - `args`
644
+ - `stdout`
645
+ - `stderr`
646
+
647
+ 约束:
648
+
649
+ - `command` 必须是稳定命令路径
650
+ - `configure()` 只配置参数,不执行副作用
651
+ - `run()` 必须返回稳定 exit code
652
+ - 命令冲突按 `priority` 裁决;同优先级冲突直接报错
653
+ - CLI 发现只基于正式 `cli/` 目录与扩展注册
654
+
655
+ ## 4.2 app CLI 发现的单一路径原则
656
+
657
+ 命令发现也必须坚持单一路径。
658
+
659
+ 正式要求:
660
+
661
+ - app CLI 只通过 `<app>/cli/<tool>.py` 目录约定发现
662
+ - 发现结果必须先编译成唯一 `RuntimePlan.cli_manifest`
663
+ - `pz` 不再额外支持:
664
+ - entry points 动态发现 app 子命令
665
+ - import-time registry 注册子命令
666
+ - 运行时扫描任意模块名猜命令
667
+
668
+ 结论:
669
+
670
+ - CLI 命令树的源码真相源是 app 包内 `cli/` 目录
671
+ - CLI 命令树的运行期真相源是编译后的 `RuntimePlan.cli_manifest`
672
+ - 入口层只执行已编译 manifest,不做命令模型扩展裁决
673
+
674
+ ## 4.1 CLI 工程化约束
675
+
676
+ 从可运维和可自动化角度,CLI 还需要满足以下约束:
677
+
678
+ - 非交互命令必须可在 CI / cron / supervisor 中稳定运行
679
+ - stdout 应优先输出正式结果,stderr 输出诊断和错误
680
+ - exit code 必须稳定:
681
+ - `0` 成功
682
+ - 非 `0` 失败
683
+ - 错误信息必须可定位到:
684
+ - project context 问题
685
+ - 配置问题
686
+ - app 装配问题
687
+ - 基础设施缺失问题
688
+
689
+ 要求:
690
+
691
+ - 必须支持 `--json` 作为唯一正式机器可读输出开关,用于自动化与运维集成
692
+ - 帮助文案示例统一使用标准入口,不再出现 vendored/wrapper 心智
693
+
694
+ 边界约束:
695
+
696
+ - `--json` 输出中的错误对象必须带稳定 `code`
697
+ - 成功输出、失败输出、`CheckReport` 输出使用同一错误/诊断编码体系
698
+ - 非 `--json` 模式可以更易读,但不得改变正式 code 语义
699
+
700
+ ## 4.3 系统检查的唯一正式入口
701
+
702
+ system checks 必须有唯一正式入口,不再让 preflight、debug、启动链各自提供一套检查逻辑。
703
+
704
+ 唯一正式入口:
705
+
706
+ - `pz check`
707
+
708
+ 正式要求:
709
+
710
+ - `pz check` 必须先编译 `RuntimePlan`
711
+ - 默认运行时检查只消费 `RuntimePlan`、manifest、snapshot、registry
712
+ - `pz check` 可以追加正式 authoring 诊断;settings update drift 诊断必须复用 `pz settings update` 的同源 dry-run planner,只判断 update 是否会产生配置同步变更,并以 `CheckReport` 项输出修复建议
713
+ - 每个非平凡检查必须先在所属领域落成无副作用原子诊断能力,再由 `pz check` 编排调用;`pz check` 只负责编译上下文、调用诊断项、合并 `CheckItem` / `CheckReport`,不承载 settings、resources、routes、db、发布等领域规则
714
+ - 原子诊断能力返回正式 `CheckItem` 或可无损映射为 `CheckItem` 的稳定结果;诊断项 owner/scope/code 必须能定位到所属领域,不得全部写成 `runtime.check`
715
+ - `pz check --json` 输出唯一正式机器可读 `CheckReport`
716
+ - Web startup、worker startup、debug 页面若要暴露检查结果,也只允许复用同一份 `CheckReport`
717
+
718
+ 不允许:
719
+
720
+ - Web 启动时顺手再跑一套 best-effort 检查链
721
+ - debug 页面自己重扫目录/重连依赖生成另一份检查结果
722
+ - preflight app 自己定义独立输出协议替代正式 `CheckReport`
723
+ - 在 `pz check` CLI 模块内直接实现具体领域检查逻辑;CLI 模块只能做诊断编排、错误收敛和输出
724
+ - 为 settings update drift 另写一套 mtime/hash/raw diff 规则,绕开 `pz settings update` 的正式 merge、normalizer、routing 提升与 env 模板规则
725
+
726
+ 结论:
727
+
728
+ - `pz check` 是系统检查唯一正式入口
729
+ - 其它入口只能复用其检查引擎和结果模型
730
+
731
+ ## 4.4 `db` CLI 工作空间契约
732
+
733
+ 数据库迁移与 schema 管理也必须遵守正式项目边界,不能继续依赖源码仓临时工作区模型。
734
+
735
+ 正式要求:
736
+
737
+ - `pz db ...` 的工作目录、临时配置文件、聚合迁移目录都必须来自当前 `ProjectContext`
738
+ - `db` CLI 只能消费正式 app registry、正式迁移 owner 规则和当前 `RuntimePlan`
739
+ - `db` CLI 不得通过 `_repo_root()`、包内 merged 目录、包内 `aerich.ini`、`PYTHONPATH` 注入来弥补目录边界缺口
740
+ - 正式命令面收敛为 Django 风格:
741
+ - `pz db makemigrations`
742
+ - `pz db migrate`
743
+ - `pz db showmigrations`
744
+ - 迁移文件格式修复若需要存在,只能作为显式子命令或显式 repair/check 流程
745
+
746
+ 禁止:
747
+
748
+ - 在正式 `makemigrations/migrate/showmigrations` 主路径里自动写 repo-root 工作目录
749
+ - 在正式主路径里偷偷执行 best-effort migration patch
750
+ - 通过 suffix match、历史 `app` 路径猜测或第二套 app 扫描规则来决定 migration owner
751
+
752
+ ## 5. worker 入口边界
753
+
754
+ worker 必须是显式入口,不应依赖:
755
+
756
+ - import-time 启动
757
+ - 某个 app `startup()` 钩子偷偷启动
758
+ - 通过全局单例隐式注册后台循环
759
+
760
+ 正式模式:
761
+
762
+ - `pz <app_id> <worker-tool>`
763
+
764
+ 部署系统通过该标准入口显式拉起 worker。
765
+
766
+ `worker.role` 的正式分类由 `WorkerRoleSpec.worker_kind` 承载。分类只描述进程职责和启动治理边界,不替业务包做领域决策:
767
+
768
+ - `infrastructure_worker`:基础设施、队列消费、心跳、清理、调度或领域后台推进 worker。
769
+ - `operator_ingress_worker`:外部操作入口 adapter,例如 Telegram / Discord / Webhook control surface。
770
+ - `resident_actor_worker`:随系统常驻的 Agent actor / role 载具进程。
771
+ - `task_driven_actor_worker`:由任务需求触发的 Agent actor / role 载具进程。
772
+
773
+ `pz` 与 `pz_foundation` 只保存并投影该分类,不解释“谁该执行任务”。是否允许某类 Agent actor worker 随系统启动,归对应 Agent 支持包或领域 owner 的设计合同约束。
774
+
775
+ `worker.role` 的副本数由 `WorkerRoleSpec.replica_count_setting` 绑定到 owner app settings。正常每个 worker 都应声明自己的 count setting,并由 owner app 在 settings schema 与 `configs/default.jsonc` 模板中给出默认值;新增默认键后必须通过 `pz settings update --project-dir <project>` 同步到项目 settings。worker 运行时只能消费 settings center 编译后的 `RuntimePlan` / `SettingsSnapshot`,不得直接读取包内 `default.jsonc`。已声明 count setting 但 settings center 投影中该值缺失 / 非正数时,supervisor 使用 `pz_foundation.managed_workers.default_replica_count`,默认 `1`;未声明 count setting 的冻结 / legacy worker 固定为 singleton,不受全局 fallback 扩容。副本数解析必须统一委托 `pz_foundation.worker_replicas.WorkerReplicaCountResolver`,不得在 Task Center、CLI 或其它调用点手工拼接数量配置。
776
+
777
+ 补充说明:
778
+ - 这里的 `<app_id>` 指正式 app registry 中的叶子 app
779
+ - `installed_apps` 的唯一正式语法是目录名;目录名可以是最小子包,也可以是容器目录
780
+ - 若宿主在 `installed_apps` 中声明的是文件夹/容器目录,则框架会先自动展开到嵌套最小子包,再决定 CLI/worker 的可发现 app 集合
781
+ - 不要求宿主为了 CLI/worker 发现而手工把容器内所有最小子包逐个列出
782
+ - CLI/worker 的 app 发现顺序必须与正式发现算法保持一致:先按 `installed_apps` 条目顺序,再按容器内目录名字典序深度优先展开
783
+ - 若宿主配置声明 `apps` 扫描目录,CLI/worker app 发现只识别 `apps/` 下业务仓真实目录与经过 manifest 校验的可见 binding;`apps/.sources/` 是 linked checkout 承载区,不直接贡献 app
784
+ - 同一 `app_id` 的源码 checkout 与已安装 distribution 同时存在时,CLI/worker app 发现必须使用源码 checkout;不得因为当前解释器能 import 到 distribution 就绕过本地源码
785
+
786
+ 边界约束:
787
+ - task dispatch owner 的 scheduler / reclaimer / cleanup 这类后台循环,应视为独立 worker 角色,而不是默认附着在 Web app `startup()`
788
+ - mail/auth owner 这类 app 的 email worker 也不应继续在 `startup()` 里默认调度
789
+ - `pz run` 自动托管可以拉起 `infrastructure_worker` 和 `operator_ingress_worker`;它们是支撑进程,不等价于 Agent 角色实例已经随系统启动。
790
+ - `pz run` 对 `resident_actor_worker` / `task_driven_actor_worker` 不做通用智能裁决;这类 worker 的默认启动边界必须由声明该 worker 的 Agent 支持包文档和 settings 明确规定。
791
+ - 后台循环内部不应持续依赖进程级 `settings + ensure_full_settings()` 补挂配置命名空间
792
+ - worker 热路径上的拉取、心跳、注册响应,也不应继续从旧全局 settings 单例动态取配置并回退根级历史字段;运行时代码统一只读 `settings_center.settings`
793
+
794
+ ## 6. in-process worker 策略
795
+
796
+ 不保留 in-process worker 作为正式方案。
797
+
798
+ 要求:
799
+
800
+ - worker 统一通过显式独立入口运行
801
+ - Web app `startup()` 不承担 worker 启动职责
802
+ - 不再为开发态、演示态、生产态维护多套 worker 运行模型
803
+
804
+ 禁止模式:
805
+
806
+ - app `startup()` 中注册 `infra.ports`
807
+ - app `startup()` 中订阅事件总线
808
+ - app `startup()` 中直接 `create_task()` 拉起邮件、调度、清理等后台循环
809
+
810
+ 这些行为不能视为正式 worker 运行模型。
811
+
812
+ 补充约束:
813
+
814
+ - 不允许继续用“裸 `create_task()` + `while True` + `except Exception: pass`”作为正式后台任务模型
815
+ - 事件投递、邮件发送、清理循环若需要 fire-and-forget,只能通过显式 runtime scheduler 执行,不得在入口层偷偷改写为同步执行或 `asyncio.run()` 回退
816
+
817
+ ## 7. worker 配置边界
818
+
819
+ worker 与 HTTP 主进程必须共享同一配置真相源:
820
+
821
+ - 同一 `project_dir`
822
+ - 同一配置解析器
823
+ - 同一 `settings_center.settings.<app_id>` 命名空间语义
824
+
825
+ worker 自有运行参数固定分为两类:
826
+
827
+ - 项目配置
828
+ - 队列名
829
+ - 并发数默认值
830
+ - 功能开关
831
+ - 进程启动参数
832
+ - `--once`
833
+ - `--concurrency`
834
+ - `--poll-interval`
835
+
836
+ ## 7.1 worker 运行时工程约束
837
+
838
+ worker 作为长期运行进程,还应满足:
839
+
840
+ - 支持优雅退出
841
+ - 支持显式 shutdown timeout
842
+ - 支持重复启动时的锁/租约冲突诊断
843
+ - 运行态文件、心跳、pid、socket 都必须带 owner/project scope
844
+
845
+ 要求:
846
+
847
+ - 接收 `SIGTERM` / `SIGINT` 时优先执行有序 drain / cleanup
848
+ - worker 不应把“收到停止信号后直接中断”当作正式关闭语义
849
+ - 由 `pz run` 自动托管的 detached worker supervisor 必须绑定当前 host 进程 pid;owner 进程退出后,supervisor 必须主动收口并停止继续拉起 worker
850
+ - worker supervisor、host autostart 与 app 自有后台子进程必须统一解析项目级正式 `pz` 入口;不得再手写 `python -m pz_core`、`sys.executable -m pz_core` 或等价 wrapper
851
+ - 这类子进程的环境必须优先原样继承外层宿主已选定的 `PZ_ENV`,缺失时才允许回退到入口期冻结的 `RuntimePlan.project.pz_env`,并显式携带 `PZ_PROJECT_DIR`
852
+ - runtime / app / worker 代码若只需要知道“当前是 develop 还是 product”,必须消费入口期冻结的 settings snapshot 或正式 helper `current_pz_env(...)`;不得各自直接读取 `os.environ["PZ_ENV"]`、`os.getenv("PZ_ENV")` 或等价私有 wrapper
853
+ - 若存在 once/batch 模式与 daemon 模式,两者行为差异必须明确
854
+ - 首次停止信号进入正式 shutdown 流程;若超过显式 timeout 仍未退出,应以明确错误结束而不是无限挂起
855
+ - 重复停止信号可以升级为强制退出,但不得跳过已登记的 cleanup/诊断输出
856
+
857
+ ## 8. readiness 与入口关系
858
+
859
+ readiness 不应假设所有 worker 与所有基础设施都跟着主 Web 进程启动。
860
+
861
+ 要求:
862
+
863
+ - Web readiness 只覆盖本进程声明负责的能力
864
+ - 独立 worker 需要自己的健康探针或自检命令
865
+ - task dispatch 之类平台 app 的 readiness 应只在其启用时暴露
866
+ - task dispatch worker client 不应把“loopback socket 已监听”当作标准跨部署前置条件
867
+ - worker 侧 readiness 不应仅通过 Web `/ready` 固定返回值推断系统已可调度
868
+ - worker 与 Web 的启动链都不应把 settings overrides reload、L2 client 注册、default redis config 注入这类全局副作用隐藏在 lifespan 内部
869
+
870
+ 约束:
871
+ - worker register / heartbeat / pull 所返回的 server 参数,不应继续依赖运行中的全局 settings 现取现算
872
+ - 应来自入口期确定好的 settings snapshot 或 worker capability contract
873
+ - task dispatch owner 这类平台 app 的 Web `/ready` 不应固定返回成功并让 worker SDK 把它当作系统可调度证明
874
+ - worker SDK 不应在 `start()` 里默认对 loopback `base_url` 做 local socket preflight
875
+ - worker SDK 也不应把某个 owner 私有 readiness URL 的任意“非 404 / 非 5xx”响应都视为 ready
876
+ - `401 -> 自动 re-register` 不得继续充当正式 worker session 协议
877
+
878
+ ## 8.1 启动诊断与错误处理约束
879
+
880
+ 入口层是生产故障定位的第一现场,不能继续容忍大面积 `except Exception: pass` 的 best-effort 主链。
881
+
882
+ 正式要求:
883
+
884
+ - settings 编译、app registry 编译、resource 编译、infra 编译、worker 启动、Web startup 都必须产出稳定诊断
885
+ - 结构性失败必须带正式 `code`、`stage`、`owner`、`action`
886
+ - 主链上的异常不得通过宽泛 `except Exception: pass` 吞掉后继续进入半初始化状态
887
+ - 若某能力允许降级,必须在诊断里显式说明是 `disabled`、`degraded` 还是 `unavailable`
888
+ - HTTP error envelope 必须带稳定 request correlation id;若已启用 tracing,也应能关联到 trace/span 标识
889
+ - 对外错误消息、内部诊断 detail、日志 traceback 必须分层,不得把底层异常字符串直接当作公共 API message
890
+
891
+ 推荐最小字段:
892
+
893
+ - `code`
894
+ - `stage`
895
+ - `owner`
896
+ - `summary`
897
+ - `action`
898
+ - `request_id`
899
+
900
+ 禁止:
901
+
902
+ - 因导入失败、依赖缺失、probe 缺失而静默回退成功
903
+ - 通过 `print()` 或自由文本 warning 充当正式故障协议
904
+ - 让不同入口对同一类启动错误输出不同结构
905
+ - 在日志、HTTP error envelope、validation detail 中直接暴露密码、token、DSN、绝对宿主机路径等敏感信息
906
+
907
+ ## 8.2 startup 副作用约束
908
+
909
+ 生产入口的 `startup()` 必须保持可预测和可回滚,不能继续承载混杂的辅助任务。
910
+
911
+ 正式要求:
912
+
913
+ - `startup()` 只负责激活当前 `RuntimePlan` 中已经声明的运行期资源
914
+ - `startup()` 不得承担 asset build、图片预生成、静态优化、迁移修补、配置自动修复
915
+ - `preflight` 类 app 若保留 `startup()`,其中阻断型检查与优化型任务必须分层,不得混在一条 best-effort 主链
916
+ - app `startup()` 中新增的副作用必须具备对应的 `shutdown()` 对称清理或显式 owner
917
+
918
+ 禁止:
919
+
920
+ - 在 `startup()` 中顺手触发 `run_assets_build()`、图片生成、bundle/minify
921
+ - 在 `startup()` 中把“优化失败但不阻断”与“检查失败必须阻断”混成同一个结果语义
922
+ - 在 `startup()` 中引入与当前进程职责无关的后台准备任务
923
+
924
+ ## 9. 配置边界
925
+
926
+ - 入口边界负责“启动哪类进程”
927
+ - 配置边界负责“所有进程共享同一份配置解析规则”
928
+
929
+ ## 10. 禁止事项
930
+
931
+ 不允许:
932
+
933
+ - CLI 自行写 wrapper 作为主入口
934
+ - worker 默认锁到系统临时目录
935
+ - app 在 import 时启动后台循环
936
+ - worker 代码自己直接拼接 `BASE_URL` / `cwd` / repo root 做配置发现
937
+ - HTTP 主进程和 worker 使用两套 settings 解析逻辑
938
+ - CLI 默认把框架包内目录当作项目插件目录或业务仓库目录
939
+ - 通过根 `pz init` 生成 wrapper 并修改 shell rc 作为框架标准安装路径
940
+ - `db` CLI 继续默认把 repo-root `pz/merged` 当作核心工作目录
941
+ - `create_app()` / `create_host_app()` / `register_core()` 默认回退到进程级全局 settings 并顺带重配一串全局单例
942
+ - `__main__` 或 `db` CLI 通过修改 `sys.path` / `PYTHONPATH` 来弥补项目边界不清晰
943
+ - `CliManager()` 构造时隐式 `ensure_full_settings(global_settings)` 并把它当默认入口上下文
944
+ - app `startup()` 同时承担 provider binding / capability 激活、事件订阅、worker 调度、router/event_handler 二次挂载这类多重副作用职责
945
+ - worker client 在默认启动链里隐式依赖:
946
+ - loopback socket 已监听
947
+ - Web `/ready` 可访问
948
+ 这类宿主部署前置条件
949
+ - Web 入口在 `register_core()` 或 `preflight` startup 中默认触发 assets build/bundle/minify
950
+ - CLI 在正常路径下输出需要人工 grep 才能消费的非结构化“调试日志流”作为唯一结果