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,172 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any
4
+
5
+ from fastapi import FastAPI
6
+ from fastapi.routing import APIRoute
7
+ from starlette.routing import Mount
8
+
9
+
10
+ def _parse_path_param(segment: str) -> tuple[str, str] | None:
11
+ if not segment.startswith("{") or not segment.endswith("}"):
12
+ return None
13
+ body = segment[1:-1].strip()
14
+ if not body:
15
+ return None
16
+ if ":" in body:
17
+ name, convertor = body.split(":", 1)
18
+ else:
19
+ name, convertor = body, ""
20
+ name = name.strip()
21
+ if not name:
22
+ return None
23
+ return name, convertor.strip()
24
+
25
+
26
+ def _route_path_shape(path: str) -> tuple[tuple[str, ...], tuple[str, ...], int, bool]:
27
+ param_names: list[str] = []
28
+ param_convertors: list[str] = []
29
+ static_count = 0
30
+ has_path_catch_all = False
31
+ for segment in (item for item in str(path or "").strip("/").split("/") if item):
32
+ parsed = _parse_path_param(segment)
33
+ if parsed is None:
34
+ static_count += 1
35
+ continue
36
+ name, convertor = parsed
37
+ param_names.append(name)
38
+ param_convertors.append(convertor)
39
+ if convertor == "path":
40
+ has_path_catch_all = True
41
+ return tuple(param_names), tuple(param_convertors), static_count, has_path_catch_all
42
+
43
+
44
+ def classify_route_type(path: str) -> str:
45
+ normalized_path = str(path or "").rstrip("/") or "/"
46
+ fully_generic_patterns = {
47
+ "/",
48
+ "/{path:path}",
49
+ }
50
+ if normalized_path in fully_generic_patterns:
51
+ return "generic"
52
+
53
+ param_names, param_convertors, static_count, has_path_catch_all = _route_path_shape(normalized_path)
54
+ param_count = len(param_names)
55
+ has_constrained_param = any(convertor and convertor != "path" for convertor in param_convertors)
56
+ if has_path_catch_all:
57
+ return "generic"
58
+ if param_count == 0:
59
+ return "definite"
60
+
61
+ if static_count == 0:
62
+ if has_constrained_param:
63
+ return "single_param"
64
+ return "generic"
65
+
66
+ if param_count == 1:
67
+ if param_names[0] == "lang":
68
+ return "single_param"
69
+ return "definite"
70
+ if param_count == 2 and "lang" in param_names:
71
+ return "single_param"
72
+ if "module" in param_names and not has_constrained_param:
73
+ return "generic"
74
+ return "definite"
75
+
76
+
77
+ def _static_segment_count(path: str) -> int:
78
+ segments = [segment for segment in str(path or "").split("/") if segment]
79
+ count = 0
80
+ for segment in segments:
81
+ if "{" in segment and "}" in segment:
82
+ continue
83
+ count += 1
84
+ return count
85
+
86
+
87
+ def get_route_sort_key(path: str) -> tuple[int, int, int, str]:
88
+ return (-path.count("/"), -_static_segment_count(path), path.count("{"), path)
89
+
90
+
91
+ def _single_param_route_sort_key(path: str) -> tuple[int, int, int, int, str]:
92
+ _param_names, param_convertors, static_count, _has_path_catch_all = _route_path_shape(path)
93
+ has_constrained_param = any(convertor and convertor != "path" for convertor in param_convertors)
94
+ fully_dynamic_constrained_route = static_count == 0 and has_constrained_param
95
+ return (1 if fully_dynamic_constrained_route else 0, *get_route_sort_key(path))
96
+
97
+
98
+ def route_dedup_key(route: APIRoute) -> tuple[str, tuple[str, ...]]:
99
+ return route.path, tuple(sorted(route.methods or ()))
100
+
101
+
102
+ def _unique_routes_by_identity(routes: list[APIRoute]) -> list[APIRoute]:
103
+ out: list[APIRoute] = []
104
+ seen_ids: set[int] = set()
105
+ for route in routes:
106
+ route_id = id(route)
107
+ if route_id in seen_ids:
108
+ continue
109
+ seen_ids.add(route_id)
110
+ out.append(route)
111
+ return out
112
+
113
+
114
+ def clean_and_reorder_routes(app: FastAPI) -> None:
115
+ mount_routes: list[Mount] = []
116
+ other_routes: list[Any] = []
117
+ definite_registry: dict[tuple[str, str], APIRoute] = {}
118
+ single_param_routes: dict[tuple[str, tuple[str, ...]], APIRoute] = {}
119
+ generic_routes: dict[tuple[str, tuple[str, ...]], APIRoute] = {}
120
+ duplicate_count = 0
121
+
122
+ for route in list(getattr(app, "routes", []) or []):
123
+ if isinstance(route, Mount):
124
+ mount_routes.append(route)
125
+ continue
126
+ if not isinstance(route, APIRoute):
127
+ other_routes.append(route)
128
+ continue
129
+
130
+ route_type = classify_route_type(route.path)
131
+ if route_type == "definite":
132
+ for method in route.methods or ():
133
+ key = (route.path, method)
134
+ if key in definite_registry:
135
+ duplicate_count += 1
136
+ definite_registry[key] = route
137
+ continue
138
+
139
+ dedup_key = route_dedup_key(route)
140
+ target = generic_routes if route_type == "generic" else single_param_routes
141
+ if dedup_key in target:
142
+ duplicate_count += 1
143
+ target[dedup_key] = route
144
+
145
+ definite_routes = sorted(
146
+ _unique_routes_by_identity(list(definite_registry.values())),
147
+ key=lambda route: get_route_sort_key(route.path),
148
+ )
149
+ mount_route_list = sorted(
150
+ mount_routes,
151
+ key=lambda route: get_route_sort_key(getattr(route, "path", "") or "/"),
152
+ )
153
+ single_param_route_list = sorted(
154
+ single_param_routes.values(),
155
+ key=lambda route: _single_param_route_sort_key(route.path),
156
+ )
157
+ generic_route_list = sorted(
158
+ generic_routes.values(),
159
+ key=lambda route: get_route_sort_key(route.path),
160
+ )
161
+
162
+ app.router.routes.clear()
163
+ app.router.routes.extend(other_routes)
164
+ app.router.routes.extend(definite_routes)
165
+ app.router.routes.extend(mount_route_list)
166
+ app.router.routes.extend(single_param_route_list)
167
+ app.router.routes.extend(generic_route_list)
168
+
169
+ try:
170
+ app.state.pz_route_duplicates = duplicate_count
171
+ except Exception:
172
+ pass
@@ -0,0 +1,133 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+
6
+ from fastapi import APIRouter
7
+ from fastapi.routing import APIRoute
8
+
9
+ from .loaders import DeclaredUrlSpec
10
+ from .ordering import route_dedup_key
11
+ from .utils import _join_path_prefix, _path_repeats_prefix
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class RouteRegistryEntry:
16
+ owner_app: str
17
+ app_id: str
18
+ namespace: str
19
+ router: APIRouter
20
+ path_prefix: str = ""
21
+ dependencies: tuple[Any, ...] = ()
22
+ replace_target: str = ""
23
+ route_hints: tuple[str, ...] = ()
24
+ conflict_policy: str = "fail"
25
+
26
+
27
+ @dataclass(frozen=True, slots=True)
28
+ class RouteManifest:
29
+ entries: tuple[RouteRegistryEntry, ...]
30
+
31
+
32
+ def _iter_route_keys(router: APIRouter, *, path_prefix: str) -> tuple[tuple[str, tuple[str, ...]], ...]:
33
+ keys: list[tuple[str, tuple[str, ...]]] = []
34
+ for route in getattr(router, "routes", ()) or ():
35
+ if not isinstance(route, APIRoute):
36
+ continue
37
+ mounted_path = _join_path_prefix(path_prefix, str(getattr(route, "path", "") or ""))
38
+ methods = tuple(sorted(getattr(route, "methods", ()) or ()))
39
+ keys.append((mounted_path, methods))
40
+ return tuple(keys)
41
+
42
+
43
+ def _assert_routes_do_not_repeat_path_prefix(entry: RouteRegistryEntry) -> None:
44
+ prefix = str(entry.path_prefix or "").strip()
45
+ if not prefix:
46
+ return
47
+ for route in getattr(entry.router, "routes", ()) or ():
48
+ path = str(getattr(route, "path", "") or "")
49
+ if not _path_repeats_prefix(path, prefix):
50
+ continue
51
+ raise RuntimeError(
52
+ "route declaration repeats its path_prefix before FastAPI mount: "
53
+ f"{entry.namespace} declares path_prefix {prefix!r} and route path {path!r}. "
54
+ "Use Django-style include/mount semantics: declare child router paths relative to the prefix."
55
+ )
56
+
57
+
58
+ def build_route_registry_entry(
59
+ *,
60
+ owner_app: str,
61
+ spec: DeclaredUrlSpec,
62
+ route_hints: tuple[str, ...] = (),
63
+ ) -> RouteRegistryEntry:
64
+ normalized_owner = str(owner_app or "").strip()
65
+ return RouteRegistryEntry(
66
+ owner_app=normalized_owner,
67
+ app_id=normalized_owner,
68
+ namespace=str(spec.namespace or "").strip(),
69
+ router=spec.router,
70
+ path_prefix=str(spec.path_prefix or "").strip(),
71
+ dependencies=tuple(spec.dependencies or ()),
72
+ replace_target=str(spec.replace_target or "").strip(),
73
+ route_hints=tuple(spec.route_hints or ()) + tuple(route_hints or ()),
74
+ conflict_policy=str(spec.conflict_policy or "fail").strip().lower() or "fail",
75
+ )
76
+
77
+
78
+ def compile_route_registry(entries: tuple[RouteRegistryEntry, ...] | list[RouteRegistryEntry]) -> tuple[RouteRegistryEntry, ...]:
79
+ compiled: list[RouteRegistryEntry] = []
80
+ namespace_map: dict[str, RouteRegistryEntry] = {}
81
+ route_key_map: dict[tuple[str, tuple[str, ...]], RouteRegistryEntry] = {}
82
+
83
+ for entry in entries:
84
+ if not isinstance(entry, RouteRegistryEntry):
85
+ raise RuntimeError(f"route registry expects RouteRegistryEntry instances, got {type(entry)!r}.")
86
+ if not entry.owner_app:
87
+ raise RuntimeError("route registry entries must declare owner_app.")
88
+ if not entry.app_id:
89
+ raise RuntimeError("route registry entries must declare app_id.")
90
+ if not entry.namespace:
91
+ raise RuntimeError("route registry entries must declare namespace.")
92
+ if str(entry.conflict_policy or "fail").strip().lower() != "fail":
93
+ raise RuntimeError("route registry entries currently only support conflict_policy='fail'.")
94
+ _assert_routes_do_not_repeat_path_prefix(entry)
95
+
96
+ previous_namespace = namespace_map.get(entry.namespace)
97
+ if previous_namespace is not None:
98
+ raise RuntimeError(
99
+ f"duplicate route namespace {entry.namespace!r}: {previous_namespace.owner_app} and {entry.owner_app}"
100
+ )
101
+
102
+ replace_target = str(entry.replace_target or "").strip()
103
+ if replace_target:
104
+ target = namespace_map.get(replace_target)
105
+ if target is None:
106
+ raise RuntimeError(
107
+ f"route namespace {entry.namespace!r} declares unknown replace_target {replace_target!r}."
108
+ )
109
+ compiled = [item for item in compiled if item.namespace != replace_target]
110
+ namespace_map.pop(replace_target, None)
111
+ for key, value in list(route_key_map.items()):
112
+ if value.namespace == replace_target:
113
+ route_key_map.pop(key, None)
114
+
115
+ current_route_keys = _iter_route_keys(entry.router, path_prefix=entry.path_prefix)
116
+ for route_key in current_route_keys:
117
+ previous_route = route_key_map.get(route_key)
118
+ if previous_route is not None:
119
+ raise RuntimeError(
120
+ "route conflict before FastAPI mount: "
121
+ f"{route_key[0]} {route_key[1]} from {previous_route.namespace} and {entry.namespace}"
122
+ )
123
+
124
+ compiled.append(entry)
125
+ namespace_map[entry.namespace] = entry
126
+ for route_key in current_route_keys:
127
+ route_key_map[route_key] = entry
128
+
129
+ return tuple(compiled)
130
+
131
+
132
+ def compile_route_manifest(entries: tuple[RouteRegistryEntry, ...] | list[RouteRegistryEntry]) -> RouteManifest:
133
+ return RouteManifest(entries=compile_route_registry(entries))
@@ -0,0 +1,28 @@
1
+ from __future__ import annotations
2
+
3
+
4
+ def _join_path_prefix(prefix: str, path: str) -> str:
5
+ normalized_prefix = str(prefix or "").rstrip("/")
6
+ normalized_path = str(path or "").strip()
7
+ if not normalized_prefix and not normalized_path:
8
+ return ""
9
+ normalized_path = normalized_path or "/"
10
+ if not normalized_prefix:
11
+ return normalized_path
12
+ if normalized_path == "/":
13
+ return normalized_prefix or "/"
14
+ if not normalized_path.startswith("/"):
15
+ normalized_path = "/" + normalized_path
16
+ return f"{normalized_prefix}{normalized_path}"
17
+
18
+
19
+ def _path_repeats_prefix(path: str, prefix: str) -> bool:
20
+ normalized_prefix = str(prefix or "").strip().rstrip("/")
21
+ if not normalized_prefix or normalized_prefix == "/":
22
+ return False
23
+ normalized_path = str(path or "").strip()
24
+ if not normalized_path:
25
+ return False
26
+ if not normalized_path.startswith("/"):
27
+ normalized_path = f"/{normalized_path}"
28
+ return normalized_path == normalized_prefix or normalized_path.startswith(f"{normalized_prefix}/")
@@ -0,0 +1,234 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from dataclasses import dataclass
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from pz_core.assembly.project import resolve_project_context
9
+
10
+
11
+ @dataclass(slots=True)
12
+ class FoundationRuntimeState:
13
+ owner: str
14
+ project_dir: Path | None
15
+ capability_statuses: dict[str, str]
16
+ database_status: dict[str, Any]
17
+ kv_status: dict[str, Any]
18
+ mail_status: dict[str, Any]
19
+ storage_status: dict[str, Any]
20
+ observability_status: dict[str, Any]
21
+ health_status: dict[str, Any]
22
+
23
+ @property
24
+ def snapshot_path(self) -> Path | None:
25
+ if self.project_dir is None:
26
+ return None
27
+ return resolve_project_context(self.project_dir).asset_dir / "foundation" / "capabilities.json"
28
+
29
+
30
+ _RUNTIME_STATES: dict[str, FoundationRuntimeState] = {}
31
+ _ACTIVE_RUNTIME_OWNER: str | None = None
32
+ _RUNTIME_CONTEXTS: dict[str, dict[str, Any]] = {}
33
+ _PROJECT_RUNTIME_CONTEXTS: dict[str, dict[str, Any]] = {}
34
+
35
+
36
+ def _active_runtime_state() -> FoundationRuntimeState | None:
37
+ if not _ACTIVE_RUNTIME_OWNER:
38
+ return None
39
+ return _RUNTIME_STATES.get(_ACTIVE_RUNTIME_OWNER)
40
+
41
+
42
+ def bind_runtime_state(
43
+ *,
44
+ capability_statuses: dict[str, str],
45
+ database_status: dict[str, Any] | None = None,
46
+ kv_status: dict[str, Any] | None = None,
47
+ mail_status: dict[str, Any] | None = None,
48
+ storage_status: dict[str, Any] | None = None,
49
+ observability_status: dict[str, Any] | None = None,
50
+ health_status: dict[str, Any] | None = None,
51
+ project_dir: str | Path | None = None,
52
+ owner: str = "foundation",
53
+ ) -> FoundationRuntimeState:
54
+ global _ACTIVE_RUNTIME_OWNER
55
+ state = FoundationRuntimeState(
56
+ owner=owner,
57
+ project_dir=resolve_project_context(project_dir).project_dir.resolve() if project_dir is not None else None,
58
+ capability_statuses=dict(capability_statuses),
59
+ database_status=dict(database_status or {}),
60
+ kv_status=dict(kv_status or {}),
61
+ mail_status=dict(mail_status or {}),
62
+ storage_status=dict(storage_status or {}),
63
+ observability_status=dict(observability_status or {}),
64
+ health_status=dict(health_status or {}),
65
+ )
66
+ if state.snapshot_path is not None:
67
+ state.snapshot_path.parent.mkdir(parents=True, exist_ok=True)
68
+ state.snapshot_path.write_text(
69
+ json.dumps(
70
+ {
71
+ "owner": state.owner,
72
+ "project_dir": str(state.project_dir),
73
+ "capability_statuses": state.capability_statuses,
74
+ "database_status": state.database_status,
75
+ "kv_status": state.kv_status,
76
+ "mail_status": state.mail_status,
77
+ "storage_status": state.storage_status,
78
+ "observability_status": state.observability_status,
79
+ "health_status": state.health_status,
80
+ },
81
+ ensure_ascii=False,
82
+ indent=2,
83
+ ),
84
+ encoding="utf-8",
85
+ )
86
+ _RUNTIME_STATES[owner] = state
87
+ _ACTIVE_RUNTIME_OWNER = owner
88
+ return state
89
+
90
+
91
+ def bind_runtime_context(
92
+ *,
93
+ owner: str,
94
+ project_dir: str | Path | None,
95
+ bindings: Any,
96
+ plan: Any,
97
+ lifecycle_state: Any,
98
+ ) -> None:
99
+ resolved_project_dir = resolve_project_context(project_dir).project_dir.resolve() if project_dir is not None else None
100
+ payload = {
101
+ "owner": owner,
102
+ "project_dir": resolved_project_dir,
103
+ "bindings": bindings,
104
+ "plan": plan,
105
+ "lifecycle_state": lifecycle_state,
106
+ }
107
+ _RUNTIME_CONTEXTS[owner] = payload
108
+ if resolved_project_dir is not None:
109
+ _PROJECT_RUNTIME_CONTEXTS[str(resolved_project_dir)] = payload
110
+
111
+
112
+ def reset_runtime_context(*, owner: str | None = None) -> None:
113
+ if owner is None:
114
+ _RUNTIME_CONTEXTS.clear()
115
+ _PROJECT_RUNTIME_CONTEXTS.clear()
116
+ return
117
+ payload = _RUNTIME_CONTEXTS.pop(owner, None)
118
+ if payload is None:
119
+ return
120
+ project_dir = payload.get("project_dir")
121
+ if project_dir is not None:
122
+ _PROJECT_RUNTIME_CONTEXTS.pop(str(project_dir), None)
123
+
124
+
125
+ def reset_runtime_state(*, owner: str | None = None) -> None:
126
+ global _ACTIVE_RUNTIME_OWNER
127
+ if owner is not None:
128
+ _RUNTIME_STATES.pop(owner, None)
129
+ reset_runtime_context(owner=owner)
130
+ if _ACTIVE_RUNTIME_OWNER == owner:
131
+ _ACTIVE_RUNTIME_OWNER = next(reversed(_RUNTIME_STATES), None) if _RUNTIME_STATES else None
132
+ return
133
+ _RUNTIME_STATES.clear()
134
+ _ACTIVE_RUNTIME_OWNER = None
135
+ reset_runtime_context()
136
+
137
+
138
+ def get_runtime_state(request: Any | None = None) -> FoundationRuntimeState | None:
139
+ if request is not None:
140
+ app = None
141
+ try:
142
+ app = getattr(request, "app", None)
143
+ except Exception:
144
+ try:
145
+ app = getattr(request, "scope", {}).get("app")
146
+ except Exception:
147
+ app = None
148
+ state = getattr(app, "state", None) if app is not None else None
149
+ runtime_state = getattr(state, "pz_foundation_runtime", None) if state is not None else None
150
+ if isinstance(runtime_state, FoundationRuntimeState):
151
+ return runtime_state
152
+ return _active_runtime_state()
153
+
154
+
155
+ def get_runtime_context(*, request: Any | None = None, project_dir: str | Path | None = None) -> dict[str, Any] | None:
156
+ if request is not None:
157
+ app = None
158
+ try:
159
+ app = getattr(request, "app", None)
160
+ except Exception:
161
+ try:
162
+ app = getattr(request, "scope", {}).get("app")
163
+ except Exception:
164
+ app = None
165
+ state = getattr(app, "state", None) if app is not None else None
166
+ bindings = getattr(state, "pz_runtime_bindings", None) if state is not None else None
167
+ plan = getattr(state, "pz_runtime_plan", None) if state is not None else None
168
+ lifecycle_state = getattr(state, "pz_runtime_state", None) if state is not None else None
169
+ if bindings is not None:
170
+ return {
171
+ "owner": getattr(state, "pz_foundation_owner", None),
172
+ "project_dir": resolve_project_context(getattr(state, "project_dir")).project_dir.resolve()
173
+ if getattr(state, "project_dir", None)
174
+ else None,
175
+ "bindings": bindings,
176
+ "plan": plan,
177
+ "lifecycle_state": lifecycle_state,
178
+ }
179
+ if project_dir is not None:
180
+ payload = _PROJECT_RUNTIME_CONTEXTS.get(str(resolve_project_context(project_dir).project_dir.resolve()))
181
+ if payload is not None:
182
+ return payload
183
+ if _ACTIVE_RUNTIME_OWNER:
184
+ return _RUNTIME_CONTEXTS.get(_ACTIVE_RUNTIME_OWNER)
185
+ return None
186
+
187
+
188
+ def require_runtime_bindings(*, request: Any | None = None, project_dir: str | Path | None = None) -> Any:
189
+ payload = get_runtime_context(request=request, project_dir=project_dir)
190
+ if payload is None or payload.get("bindings") is None:
191
+ raise RuntimeError("foundation runtime bindings are unavailable")
192
+ return payload["bindings"]
193
+
194
+
195
+ def describe_runtime_state(request: Any | None = None) -> dict[str, Any]:
196
+ state = get_runtime_state(request)
197
+ if state is None:
198
+ return {
199
+ "owner": None,
200
+ "project_dir": None,
201
+ "snapshot_path": None,
202
+ "capability_statuses": {},
203
+ "database_status": {},
204
+ "kv_status": {},
205
+ "mail_status": {},
206
+ "storage_status": {},
207
+ "observability_status": {},
208
+ "health_status": {},
209
+ }
210
+ return {
211
+ "owner": state.owner,
212
+ "project_dir": str(state.project_dir) if state.project_dir is not None else None,
213
+ "snapshot_path": str(state.snapshot_path) if state.snapshot_path is not None else None,
214
+ "capability_statuses": dict(state.capability_statuses),
215
+ "database_status": dict(state.database_status),
216
+ "kv_status": dict(state.kv_status),
217
+ "mail_status": dict(state.mail_status),
218
+ "storage_status": dict(state.storage_status),
219
+ "observability_status": dict(state.observability_status),
220
+ "health_status": dict(state.health_status),
221
+ }
222
+
223
+
224
+ __all__ = [
225
+ "FoundationRuntimeState",
226
+ "bind_runtime_state",
227
+ "bind_runtime_context",
228
+ "describe_runtime_state",
229
+ "get_runtime_context",
230
+ "get_runtime_state",
231
+ "require_runtime_bindings",
232
+ "reset_runtime_state",
233
+ "reset_runtime_context",
234
+ ]