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,1129 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+ import hashlib
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import shutil
9
+ import subprocess
10
+ from typing import Literal
11
+ from uuid import uuid4
12
+ import xml.etree.ElementTree as ET
13
+
14
+ from pz_core.assembly.app_discovery import (
15
+ VisibleAppProjection,
16
+ iter_visible_app_projections,
17
+ )
18
+ from pz_core.runtime.errors import PzError
19
+ from pz_core.utils.project_jsonc import load_jsonc_text
20
+
21
+
22
+ _OWNER = "pz_core.authoring.ide_projection"
23
+ _PYCHARM_MODULE = "pz.generated.sources.iml"
24
+ _VSCODE_LEDGER = "pz.generated.sources.json"
25
+ _VSCODE_JOURNAL = ".pz.ide-sync.transaction.json"
26
+ _VSCODE_START = "// @pz:managed:start ide-extra-paths"
27
+ _VSCODE_END = "// @pz:managed:end ide-extra-paths"
28
+ _VSCODE_SETTING = "python.analysis.extraPaths"
29
+
30
+
31
+ @dataclass(frozen=True, slots=True)
32
+ class IdeProviderResult:
33
+ provider: Literal["pycharm", "vscode"]
34
+ status: Literal["updated", "unchanged", "not_applicable", "failed"]
35
+ assets: tuple[Path, ...] = ()
36
+
37
+
38
+ @dataclass(frozen=True, slots=True)
39
+ class IdeSyncResult:
40
+ project_dir: Path
41
+ app_ids: tuple[str, ...]
42
+ providers: tuple[IdeProviderResult, ...]
43
+
44
+
45
+ def _error(
46
+ code: str,
47
+ message: str,
48
+ *,
49
+ action: str,
50
+ detail: str | None = None,
51
+ ) -> PzError:
52
+ return PzError(
53
+ code=code,
54
+ message=message,
55
+ stage="dev",
56
+ owner=_OWNER,
57
+ action=action,
58
+ detail=detail,
59
+ )
60
+
61
+
62
+ def _project_root(project_dir: str | Path, *, action: str) -> Path:
63
+ root = Path(project_dir).expanduser().resolve(strict=False)
64
+ if not root.is_dir():
65
+ raise _error(
66
+ "PZ_DEV_IDE_PROJECT_INVALID",
67
+ f"project directory does not exist: {root}",
68
+ action=action,
69
+ )
70
+ return root
71
+
72
+
73
+ def _app_projections(project_dir: Path) -> tuple[VisibleAppProjection, ...]:
74
+ projections = iter_visible_app_projections(project_dir)
75
+ apps_root = project_dir / "apps"
76
+ seen_paths: set[Path] = set()
77
+ for projection in projections:
78
+ visible = projection.visible_root.absolute()
79
+ try:
80
+ relative = visible.relative_to(apps_root)
81
+ except ValueError as exc:
82
+ raise _error(
83
+ "PZ_DEV_IDE_PROJECTION_INVALID",
84
+ f"visible app escapes apps/: {projection.app_id}",
85
+ action="compile_ide_projection",
86
+ ) from exc
87
+ if not relative.parts or any(part.startswith(".") for part in relative.parts):
88
+ raise _error(
89
+ "PZ_DEV_IDE_PROJECTION_INVALID",
90
+ f"visible app uses a hidden or empty path: {projection.app_id}",
91
+ action="compile_ide_projection",
92
+ )
93
+ canonical = projection.source_root.resolve(strict=True)
94
+ if canonical in seen_paths:
95
+ raise _error(
96
+ "PZ_DEV_IDE_PROJECTION_INVALID",
97
+ f"multiple visible apps resolve to the same source root: {projection.app_id}",
98
+ action="compile_ide_projection",
99
+ )
100
+ seen_paths.add(canonical)
101
+ return projections
102
+
103
+
104
+ def _atomic_write(path: Path, content: bytes) -> None:
105
+ path.parent.mkdir(parents=True, exist_ok=True)
106
+ staged = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
107
+ try:
108
+ with staged.open("wb") as handle:
109
+ handle.write(content)
110
+ handle.flush()
111
+ os.fsync(handle.fileno())
112
+ if path.exists():
113
+ staged.chmod(path.stat().st_mode)
114
+ os.replace(staged, path)
115
+ _fsync_dir(path.parent)
116
+ finally:
117
+ staged.unlink(missing_ok=True)
118
+
119
+
120
+ def _durable_write(path: Path, content: bytes) -> None:
121
+ with path.open("wb") as handle:
122
+ handle.write(content)
123
+ handle.flush()
124
+ os.fsync(handle.fileno())
125
+
126
+
127
+ def _fsync_file(path: Path) -> None:
128
+ with path.open("rb") as handle:
129
+ os.fsync(handle.fileno())
130
+
131
+
132
+ def _sha256_bytes(content: bytes) -> str:
133
+ return hashlib.sha256(content).hexdigest()
134
+
135
+
136
+ def _sha256_file(path: Path) -> str:
137
+ return _sha256_bytes(path.read_bytes())
138
+
139
+
140
+ def _restore_from_backup(backup: Path, destination: Path) -> None:
141
+ staged = destination.with_name(f".{destination.name}.{uuid4().hex}.restore")
142
+ try:
143
+ shutil.copy2(backup, staged)
144
+ _fsync_file(staged)
145
+ os.replace(staged, destination)
146
+ _fsync_dir(destination.parent)
147
+ finally:
148
+ staged.unlink(missing_ok=True)
149
+
150
+
151
+ def _fsync_dir(path: Path) -> None:
152
+ descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
153
+ try:
154
+ os.fsync(descriptor)
155
+ finally:
156
+ os.close(descriptor)
157
+
158
+
159
+ def _replace_with_rollback(updates: dict[Path, bytes]) -> bool:
160
+ changed = {
161
+ path: content
162
+ for path, content in updates.items()
163
+ if not path.is_file() or path.read_bytes() != content
164
+ }
165
+ if not changed:
166
+ return False
167
+ staged: dict[Path, Path] = {}
168
+ backups: dict[Path, Path | None] = {}
169
+ replaced: list[Path] = []
170
+ try:
171
+ for path, content in changed.items():
172
+ path.parent.mkdir(parents=True, exist_ok=True)
173
+ temp = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
174
+ temp.write_bytes(content)
175
+ staged[path] = temp
176
+ if path.exists():
177
+ backup = path.with_name(f".{path.name}.{uuid4().hex}.bak")
178
+ shutil.copy2(path, backup)
179
+ backups[path] = backup
180
+ else:
181
+ backups[path] = None
182
+ for path, temp in staged.items():
183
+ os.replace(temp, path)
184
+ replaced.append(path)
185
+ _fsync_dir(path.parent)
186
+ return True
187
+ except Exception:
188
+ for path in reversed(replaced):
189
+ backup = backups[path]
190
+ if backup is None:
191
+ path.unlink(missing_ok=True)
192
+ elif backup.exists():
193
+ os.replace(backup, path)
194
+ raise
195
+ finally:
196
+ for temp in staged.values():
197
+ temp.unlink(missing_ok=True)
198
+ for backup in backups.values():
199
+ if backup is not None:
200
+ backup.unlink(missing_ok=True)
201
+
202
+
203
+ def _safe_provider_dir(path: Path, *, provider: str) -> bool:
204
+ if not path.exists():
205
+ return False
206
+ if path.is_symlink() or not path.is_dir():
207
+ raise _error(
208
+ "PZ_DEV_IDE_PROJECT_INVALID",
209
+ f"{provider} configuration path is not a real directory: {path.name}",
210
+ action="sync_ide_projections",
211
+ )
212
+ return True
213
+
214
+
215
+ def _validate_asset_path(path: Path, *, provider: str) -> None:
216
+ if path.exists() and (path.is_symlink() or not path.is_file()):
217
+ raise _error(
218
+ "PZ_DEV_IDE_PROJECT_INVALID",
219
+ f"{provider} asset path is not a real file: {path.name}",
220
+ action="sync_ide_projections",
221
+ )
222
+
223
+
224
+ def _xml_parser() -> ET.XMLParser:
225
+ return ET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
226
+
227
+
228
+ def _pycharm_url(project_dir: Path, projection: VisibleAppProjection) -> str:
229
+ if projection.binding_key is None:
230
+ relative = projection.visible_root.absolute().relative_to(project_dir)
231
+ return f"file://$PROJECT_DIR$/{relative.as_posix()}"
232
+ return projection.source_root.resolve(strict=True).as_uri()
233
+
234
+
235
+ def _render_pycharm_module(
236
+ project_dir: Path,
237
+ projections: tuple[VisibleAppProjection, ...],
238
+ ) -> bytes:
239
+ module = ET.Element("module", {"type": "PYTHON_MODULE", "version": "4"})
240
+ component = ET.SubElement(
241
+ module,
242
+ "component",
243
+ {"name": "NewModuleRootManager", "inherit-compiler-output": "true"},
244
+ )
245
+ ET.SubElement(component, "exclude-output")
246
+ for projection in projections:
247
+ url = _pycharm_url(project_dir, projection)
248
+ content = ET.SubElement(component, "content", {"url": url})
249
+ ET.SubElement(
250
+ content,
251
+ "sourceFolder",
252
+ {"url": url, "isTestSource": "false"},
253
+ )
254
+ ET.SubElement(component, "orderEntry", {"type": "inheritedJdk"})
255
+ ET.SubElement(component, "orderEntry", {"type": "sourceFolder", "forTests": "false"})
256
+ ET.indent(module, space=" ")
257
+ return ET.tostring(module, encoding="utf-8", xml_declaration=True) + b"\n"
258
+
259
+
260
+ def _merge_modules_xml(path: Path) -> bytes:
261
+ if path.is_file():
262
+ try:
263
+ root = ET.fromstring(path.read_bytes(), parser=_xml_parser())
264
+ except (ET.ParseError, OSError) as exc:
265
+ raise _error(
266
+ "PZ_DEV_IDE_PROJECT_INVALID",
267
+ "PyCharm modules.xml is not valid XML.",
268
+ action="sync_ide_projections",
269
+ detail=str(exc),
270
+ ) from exc
271
+ if root.tag != "project":
272
+ raise _error(
273
+ "PZ_DEV_IDE_PROJECT_INVALID",
274
+ "PyCharm modules.xml must have a project root.",
275
+ action="sync_ide_projections",
276
+ )
277
+ else:
278
+ root = ET.Element("project", {"version": "4"})
279
+ manager_components = tuple(
280
+ item
281
+ for item in root.findall("component")
282
+ if item.get("name") == "ProjectModuleManager"
283
+ )
284
+ component = manager_components[0] if manager_components else None
285
+ if component is None:
286
+ component = ET.SubElement(root, "component", {"name": "ProjectModuleManager"})
287
+ module_path = f"$PROJECT_DIR$/.idea/{_PYCHARM_MODULE}"
288
+ for manager in manager_components or (component,):
289
+ manager_modules = manager.find("modules")
290
+ if manager_modules is None:
291
+ continue
292
+ for child in tuple(manager_modules.findall("module")):
293
+ if child.get("filepath") == module_path or child.get("fileurl") == f"file://{module_path}":
294
+ manager_modules.remove(child)
295
+ modules = component.find("modules")
296
+ if modules is None:
297
+ modules = ET.SubElement(component, "modules")
298
+ ET.SubElement(
299
+ modules,
300
+ "module",
301
+ {"fileurl": f"file://{module_path}", "filepath": module_path},
302
+ )
303
+ ET.indent(root, space=" ")
304
+ return ET.tostring(root, encoding="utf-8", xml_declaration=True) + b"\n"
305
+
306
+
307
+ def _sync_pycharm(
308
+ project_dir: Path,
309
+ projections: tuple[VisibleAppProjection, ...],
310
+ ) -> IdeProviderResult:
311
+ idea = project_dir / ".idea"
312
+ if not _safe_provider_dir(idea, provider="PyCharm"):
313
+ return IdeProviderResult(provider="pycharm", status="not_applicable")
314
+ module_path = idea / _PYCHARM_MODULE
315
+ modules_path = idea / "modules.xml"
316
+ _validate_asset_path(module_path, provider="PyCharm")
317
+ _validate_asset_path(modules_path, provider="PyCharm")
318
+ _ensure_git_excludes(project_dir, (f".idea/{_PYCHARM_MODULE}",))
319
+ changed = _replace_with_rollback(
320
+ {
321
+ module_path: _render_pycharm_module(project_dir, projections),
322
+ modules_path: _merge_modules_xml(modules_path),
323
+ }
324
+ )
325
+ return IdeProviderResult(
326
+ provider="pycharm",
327
+ status="updated" if changed else "unchanged",
328
+ assets=(module_path, modules_path),
329
+ )
330
+
331
+
332
+ def _skip_space_and_comments(text: str, index: int) -> int:
333
+ length = len(text)
334
+ while index < length:
335
+ if text[index].isspace():
336
+ index += 1
337
+ continue
338
+ if text.startswith("//", index):
339
+ newline = text.find("\n", index + 2)
340
+ return length if newline < 0 else _skip_space_and_comments(text, newline + 1)
341
+ if text.startswith("/*", index):
342
+ end = text.find("*/", index + 2)
343
+ return length if end < 0 else _skip_space_and_comments(text, end + 2)
344
+ break
345
+ return index
346
+
347
+
348
+ def _string_end(text: str, start: int) -> int:
349
+ escaped = False
350
+ for index in range(start + 1, len(text)):
351
+ char = text[index]
352
+ if escaped:
353
+ escaped = False
354
+ elif char == "\\":
355
+ escaped = True
356
+ elif char == '"':
357
+ return index + 1
358
+ raise ValueError("unterminated JSON string")
359
+
360
+
361
+ def _container_end(text: str, start: int) -> int:
362
+ pairs = {"[": "]", "{": "}"}
363
+ stack = [pairs[text[start]]]
364
+ index = start + 1
365
+ while index < len(text):
366
+ if text.startswith("//", index):
367
+ newline = text.find("\n", index + 2)
368
+ index = len(text) if newline < 0 else newline + 1
369
+ continue
370
+ if text.startswith("/*", index):
371
+ end = text.find("*/", index + 2)
372
+ index = len(text) if end < 0 else end + 2
373
+ continue
374
+ char = text[index]
375
+ if char == '"':
376
+ index = _string_end(text, index)
377
+ continue
378
+ if char in pairs:
379
+ stack.append(pairs[char])
380
+ elif stack and char == stack[-1]:
381
+ stack.pop()
382
+ if not stack:
383
+ return index + 1
384
+ index += 1
385
+ raise ValueError("unterminated JSON container")
386
+
387
+
388
+ def _root_object_end(text: str) -> int:
389
+ start = _skip_space_and_comments(text, 0)
390
+ if start >= len(text) or text[start] != "{":
391
+ raise ValueError("settings root is not an object")
392
+ return _container_end(text, start) - 1
393
+
394
+
395
+ def _last_significant_json_char(text: str) -> str | None:
396
+ last: str | None = None
397
+ index = 0
398
+ while index < len(text):
399
+ if text.startswith("//", index):
400
+ newline = text.find("\n", index + 2)
401
+ index = len(text) if newline < 0 else newline + 1
402
+ continue
403
+ if text.startswith("/*", index):
404
+ end = text.find("*/", index + 2)
405
+ index = len(text) if end < 0 else end + 2
406
+ continue
407
+ char = text[index]
408
+ if char == '"':
409
+ index = _string_end(text, index)
410
+ last = '"'
411
+ continue
412
+ if not char.isspace():
413
+ last = char
414
+ index += 1
415
+ return last
416
+
417
+
418
+ def _top_level_value_span(text: str, key: str) -> tuple[int, int] | None:
419
+ start = _skip_space_and_comments(text, 0)
420
+ if start >= len(text) or text[start] != "{":
421
+ return None
422
+ depth = 1
423
+ index = start + 1
424
+ found: tuple[int, int] | None = None
425
+ while index < len(text) and depth:
426
+ index = _skip_space_and_comments(text, index)
427
+ if index >= len(text):
428
+ break
429
+ char = text[index]
430
+ if char == '"':
431
+ end = _string_end(text, index)
432
+ token = json.loads(text[index:end])
433
+ after = _skip_space_and_comments(text, end)
434
+ if depth == 1 and after < len(text) and text[after] == ":" and token == key:
435
+ if found is not None:
436
+ raise ValueError(f"duplicate top-level setting: {key}")
437
+ value_start = _skip_space_and_comments(text, after + 1)
438
+ if value_start >= len(text):
439
+ raise ValueError("setting value is missing")
440
+ if text[value_start] in "[{":
441
+ value_end = _container_end(text, value_start)
442
+ elif text[value_start] == '"':
443
+ value_end = _string_end(text, value_start)
444
+ else:
445
+ value_end = value_start
446
+ while value_end < len(text) and text[value_end] not in ",}":
447
+ value_end += 1
448
+ found = (value_start, value_end)
449
+ index = value_end
450
+ continue
451
+ index = end
452
+ continue
453
+ if char in "[{":
454
+ depth += 1
455
+ elif char in "]}":
456
+ depth -= 1
457
+ index += 1
458
+ return found
459
+
460
+
461
+ def _load_vscode_settings(path: Path) -> tuple[str, dict[str, object]]:
462
+ text = path.read_text(encoding="utf-8") if path.is_file() else "{}\n"
463
+ try:
464
+ payload = load_jsonc_text(
465
+ text,
466
+ code="PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
467
+ owner=_OWNER,
468
+ action="sync_ide_projections",
469
+ source_name=".vscode/settings.json",
470
+ source_path=path,
471
+ )
472
+ except PzError as exc:
473
+ raise _error(
474
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
475
+ "VS Code settings are not valid JSONC.",
476
+ action="sync_ide_projections",
477
+ detail=exc.message,
478
+ ) from exc
479
+ except (OSError, UnicodeError) as exc:
480
+ raise _error(
481
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
482
+ "VS Code settings cannot be read.",
483
+ action="sync_ide_projections",
484
+ detail=f"settings.json: {type(exc).__name__}",
485
+ ) from exc
486
+ raw_paths = payload.get(_VSCODE_SETTING, [])
487
+ if not isinstance(raw_paths, list) or not all(isinstance(item, str) for item in raw_paths):
488
+ raise _error(
489
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
490
+ f"{_VSCODE_SETTING} must be an array of strings.",
491
+ action="sync_ide_projections",
492
+ )
493
+ return text, payload
494
+
495
+
496
+ def _load_vscode_ledger(path: Path) -> tuple[str, ...]:
497
+ if not path.exists():
498
+ return ()
499
+ try:
500
+ payload = json.loads(path.read_text(encoding="utf-8"))
501
+ except (OSError, UnicodeError, json.JSONDecodeError) as exc:
502
+ raise _error(
503
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
504
+ "VS Code PZ projection ledger is invalid.",
505
+ action="sync_ide_projections",
506
+ detail=f"{_VSCODE_LEDGER}: {type(exc).__name__}",
507
+ ) from exc
508
+ if not isinstance(payload, dict) or payload.get("version") != 1:
509
+ raise _error(
510
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
511
+ "VS Code PZ projection ledger has an unsupported shape.",
512
+ action="sync_ide_projections",
513
+ )
514
+ entries = payload.get("entries")
515
+ if not isinstance(entries, list) or not all(isinstance(item, str) for item in entries):
516
+ raise _error(
517
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
518
+ "VS Code PZ projection ledger entries must be strings.",
519
+ action="sync_ide_projections",
520
+ )
521
+ normalized = tuple(dict.fromkeys(entries))
522
+ if len(normalized) != len(entries):
523
+ raise _error(
524
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
525
+ "VS Code PZ projection ledger contains duplicate entries.",
526
+ action="sync_ide_projections",
527
+ )
528
+ return normalized
529
+
530
+
531
+ def _managed_block_span(array_text: str) -> tuple[int, int] | None:
532
+ starts = array_text.count(_VSCODE_START)
533
+ ends = array_text.count(_VSCODE_END)
534
+ if starts == 0 and ends == 0:
535
+ return None
536
+ if starts != 1 or ends != 1:
537
+ raise _error(
538
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
539
+ "VS Code settings contain invalid PZ managed markers.",
540
+ action="sync_ide_projections",
541
+ )
542
+ start = array_text.index(_VSCODE_START)
543
+ end = array_text.index(_VSCODE_END, start) + len(_VSCODE_END)
544
+ line_start = array_text.rfind("\n", 0, start) + 1
545
+ suffix = array_text[end:]
546
+ if suffix.strip() != "]":
547
+ raise _error(
548
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
549
+ "PZ managed VS Code paths must be the final array entries.",
550
+ action="sync_ide_projections",
551
+ )
552
+ return line_start, end
553
+
554
+
555
+ def _validate_managed_block(array_text: str, ledger: tuple[str, ...]) -> None:
556
+ span = _managed_block_span(array_text)
557
+ if span is None:
558
+ if ledger:
559
+ raise _error(
560
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
561
+ "VS Code ledger exists but its managed settings block is missing.",
562
+ action="sync_ide_projections",
563
+ )
564
+ return
565
+ block = array_text[span[0] : span[1]]
566
+ lines = block.splitlines()
567
+ payload_lines = [
568
+ line
569
+ for line in lines
570
+ if _VSCODE_START not in line and _VSCODE_END not in line
571
+ ]
572
+ try:
573
+ block_entries = tuple(json.loads("[" + "\n".join(payload_lines) + "]"))
574
+ except (json.JSONDecodeError, TypeError) as exc:
575
+ raise _error(
576
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
577
+ "VS Code PZ managed settings block is invalid.",
578
+ action="sync_ide_projections",
579
+ detail=str(exc),
580
+ ) from exc
581
+ if block_entries != ledger:
582
+ raise _error(
583
+ "PZ_DEV_IDE_VSCODE_STATE_INVALID",
584
+ "VS Code ledger and managed settings block disagree.",
585
+ action="sync_ide_projections",
586
+ )
587
+
588
+
589
+ def _vscode_paths(
590
+ project_dir: Path,
591
+ projections: tuple[VisibleAppProjection, ...],
592
+ ) -> tuple[str, ...]:
593
+ entries: list[str] = []
594
+ for projection in projections:
595
+ relative = projection.visible_root.absolute().relative_to(project_dir)
596
+ entry = "${workspaceFolder}/" + relative.as_posix()
597
+ if entry not in entries:
598
+ entries.append(entry)
599
+ return tuple(entries)
600
+
601
+
602
+ def _render_managed_block(entries: tuple[str, ...], *, needs_separator: bool) -> str:
603
+ if not entries:
604
+ return ""
605
+ first_line = f", {_VSCODE_START}" if needs_separator else _VSCODE_START
606
+ lines = [first_line]
607
+ lines.extend(
608
+ f" {json.dumps(entry, ensure_ascii=True)}{',' if index + 1 < len(entries) else ''}"
609
+ for index, entry in enumerate(entries)
610
+ )
611
+ lines.append(_VSCODE_END)
612
+ return "\n" + "\n".join(
613
+ " " + line if not line.startswith(" ") else line for line in lines
614
+ ) + "\n"
615
+
616
+
617
+ def _merge_vscode_settings(
618
+ text: str,
619
+ payload: dict[str, object],
620
+ previous: tuple[str, ...],
621
+ required: tuple[str, ...],
622
+ ) -> tuple[str, tuple[str, ...]]:
623
+ existing = tuple(payload.get(_VSCODE_SETTING, []))
624
+ user_entries = tuple(item for item in existing if item not in previous)
625
+ owned = tuple(item for item in required if item not in user_entries)
626
+ try:
627
+ span = _top_level_value_span(text, _VSCODE_SETTING)
628
+ except ValueError as exc:
629
+ raise _error(
630
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
631
+ "VS Code settings structure cannot be preserved.",
632
+ action="sync_ide_projections",
633
+ detail=str(exc),
634
+ ) from exc
635
+ if span is not None:
636
+ array_text = text[span[0] : span[1]]
637
+ if not array_text.lstrip().startswith("["):
638
+ raise _error(
639
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
640
+ f"{_VSCODE_SETTING} must be an array.",
641
+ action="sync_ide_projections",
642
+ )
643
+ _validate_managed_block(array_text, previous)
644
+ marker_span = _managed_block_span(array_text)
645
+ if marker_span is not None:
646
+ array_text = array_text[: marker_span[0]] + array_text[marker_span[1] :]
647
+ closing = array_text.rfind("]")
648
+ prefix = array_text[:closing].rstrip()
649
+ needs_separator = (
650
+ bool(user_entries) and _last_significant_json_char(prefix) != ","
651
+ )
652
+ block = _render_managed_block(owned, needs_separator=needs_separator)
653
+ merged_array = prefix + block + array_text[closing:]
654
+ return text[: span[0]] + merged_array + text[span[1] :], owned
655
+
656
+ if not owned:
657
+ return text, ()
658
+ try:
659
+ closing = _root_object_end(text)
660
+ except ValueError as exc:
661
+ raise _error(
662
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
663
+ "VS Code settings root cannot be preserved.",
664
+ action="sync_ide_projections",
665
+ detail=str(exc),
666
+ ) from exc
667
+ block = _render_managed_block(owned, needs_separator=False)
668
+ value = "[" + block + "]"
669
+ prefix = text[:closing].rstrip()
670
+ comma = (
671
+ ","
672
+ if payload and _last_significant_json_char(prefix) != ","
673
+ else ""
674
+ )
675
+ insertion = f'{comma}\n {json.dumps(_VSCODE_SETTING)}: {value}\n'
676
+ return prefix + insertion + text[closing:], owned
677
+
678
+
679
+ def _ledger_bytes(entries: tuple[str, ...]) -> bytes:
680
+ return (
681
+ json.dumps(
682
+ {"entries": list(entries), "version": 1},
683
+ ensure_ascii=True,
684
+ indent=2,
685
+ sort_keys=True,
686
+ )
687
+ + "\n"
688
+ ).encode("utf-8")
689
+
690
+
691
+ def _resolve_git_exclude(project_dir: Path) -> Path | None:
692
+ completed = subprocess.run(
693
+ ("git", "-C", str(project_dir), "rev-parse", "--git-path", "info/exclude"),
694
+ check=False,
695
+ capture_output=True,
696
+ text=True,
697
+ )
698
+ if completed.returncode != 0:
699
+ return None
700
+ value = completed.stdout.strip()
701
+ if not value:
702
+ return None
703
+ path = Path(value)
704
+ return path if path.is_absolute() else (project_dir / path).resolve(strict=False)
705
+
706
+
707
+ def _ensure_git_excludes(project_dir: Path, required: tuple[str, ...]) -> None:
708
+ exclude = _resolve_git_exclude(project_dir)
709
+ if exclude is None:
710
+ return
711
+ exclude.parent.mkdir(parents=True, exist_ok=True)
712
+ existing = exclude.read_text(encoding="utf-8") if exclude.is_file() else ""
713
+ missing = tuple(item for item in required if item not in existing.splitlines())
714
+ if not missing:
715
+ return
716
+ prefix = existing
717
+ if prefix and not prefix.endswith("\n"):
718
+ prefix += "\n"
719
+ _atomic_write(exclude, (prefix + "\n".join(missing) + "\n").encode("utf-8"))
720
+
721
+
722
+ def _recover_vscode_transaction(vscode: Path) -> None:
723
+ journal = vscode / _VSCODE_JOURNAL
724
+ if not journal.exists():
725
+ return
726
+ if journal.is_symlink() or not journal.is_file():
727
+ raise _error(
728
+ "PZ_DEV_IDE_TRANSACTION_INCOMPLETE",
729
+ "VS Code projection transaction journal is not a real file.",
730
+ action="sync_ide_projections",
731
+ )
732
+ try:
733
+ payload = json.loads(journal.read_text(encoding="utf-8"))
734
+ if payload.get("version") != 1:
735
+ raise ValueError("unsupported transaction journal version")
736
+ files = payload["files"]
737
+ if not isinstance(files, list):
738
+ raise ValueError("files must be an array")
739
+ records: list[
740
+ tuple[Path, Path, bool, Path | None, str | None, str, str | None]
741
+ ] = []
742
+ seen_names: set[str] = set()
743
+ allowed_names = {"settings.json", _VSCODE_LEDGER}
744
+ for item in files:
745
+ if not isinstance(item, dict):
746
+ raise ValueError("file entry must be an object")
747
+ name = str(item["name"])
748
+ backup_name = str(item["backup"])
749
+ existed = item["existed"]
750
+ old_hash = item.get("old_sha256")
751
+ new_hash = item.get("new_sha256")
752
+ if Path(name).name != name or Path(backup_name).name != backup_name or not isinstance(existed, bool):
753
+ raise ValueError("journal paths must be local filenames")
754
+ if name not in allowed_names or name in seen_names:
755
+ raise ValueError("journal contains an unexpected or duplicate asset")
756
+ seen_names.add(name)
757
+ if not backup_name.startswith(f".{name}.") or not backup_name.endswith(".bak"):
758
+ raise ValueError("backup path does not match its IDE asset")
759
+ destination = vscode / name
760
+ backup = vscode / backup_name
761
+ if old_hash is not None and (
762
+ not isinstance(old_hash, str) or len(old_hash) != 64
763
+ ):
764
+ raise ValueError("old asset hash is invalid")
765
+ if not isinstance(new_hash, str) or len(new_hash) != 64:
766
+ raise ValueError("new asset hash is invalid")
767
+ if existed != (old_hash is not None):
768
+ raise ValueError("old asset hash does not match existence state")
769
+ if existed and (backup.is_symlink() or not backup.is_file()):
770
+ raise ValueError("transaction backup is missing")
771
+ if existed and _sha256_file(backup) != old_hash:
772
+ raise ValueError("transaction backup hash does not match journal")
773
+ staged: Path | None = None
774
+ staged_name = item.get("staged")
775
+ if isinstance(staged_name, str):
776
+ if Path(staged_name).name != staged_name:
777
+ raise ValueError("staged path must be a local filename")
778
+ if not staged_name.startswith(f".{name}.") or not staged_name.endswith(".tmp"):
779
+ raise ValueError("staged path does not match its IDE asset")
780
+ staged = vscode / staged_name
781
+ if staged.exists() and (
782
+ staged.is_symlink()
783
+ or not staged.is_file()
784
+ or _sha256_file(staged) != new_hash
785
+ ):
786
+ raise ValueError("staged asset hash does not match journal")
787
+ if destination.exists() and (
788
+ destination.is_symlink() or not destination.is_file()
789
+ ):
790
+ raise ValueError("IDE destination changed to an unsafe path")
791
+ current_hash = _sha256_file(destination) if destination.is_file() else None
792
+ if current_hash not in {old_hash, new_hash}:
793
+ raise ValueError(
794
+ f"IDE destination changed after interruption: {name}"
795
+ )
796
+ records.append(
797
+ (
798
+ destination,
799
+ backup,
800
+ existed,
801
+ staged,
802
+ old_hash,
803
+ new_hash,
804
+ current_hash,
805
+ )
806
+ )
807
+ fully_applied = all(current_hash == new_hash for *_, new_hash, current_hash in records)
808
+ for destination, backup, existed, staged, old_hash, new_hash, current_hash in records:
809
+ if not fully_applied and current_hash == new_hash:
810
+ if existed:
811
+ _restore_from_backup(backup, destination)
812
+ else:
813
+ destination.unlink(missing_ok=True)
814
+ journal.unlink()
815
+ _fsync_dir(vscode)
816
+ for _, backup, _, staged, _, _, _ in records:
817
+ if staged is not None:
818
+ staged.unlink(missing_ok=True)
819
+ backup.unlink(missing_ok=True)
820
+ except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
821
+ raise _error(
822
+ "PZ_DEV_IDE_TRANSACTION_INCOMPLETE",
823
+ "VS Code projection has an unrecoverable interrupted transaction.",
824
+ action="sync_ide_projections",
825
+ detail=str(exc),
826
+ ) from exc
827
+
828
+
829
+ def _replace_vscode_pair(vscode: Path, updates: dict[Path, bytes]) -> bool:
830
+ changed = {
831
+ path: content
832
+ for path, content in updates.items()
833
+ if not path.is_file() or path.read_bytes() != content
834
+ }
835
+ if not changed:
836
+ return False
837
+ transaction_id = uuid4().hex
838
+ records: list[dict[str, object]] = []
839
+ journal = vscode / _VSCODE_JOURNAL
840
+ try:
841
+ for path, content in changed.items():
842
+ staged = vscode / f".{path.name}.{transaction_id}.tmp"
843
+ backup = vscode / f".{path.name}.{transaction_id}.bak"
844
+ _durable_write(staged, content)
845
+ existed = path.is_file()
846
+ old_hash = _sha256_file(path) if existed else None
847
+ if existed:
848
+ shutil.copy2(path, backup)
849
+ _fsync_file(backup)
850
+ records.append(
851
+ {
852
+ "name": path.name,
853
+ "staged": staged.name,
854
+ "backup": backup.name,
855
+ "existed": existed,
856
+ "old_sha256": old_hash,
857
+ "new_sha256": _sha256_bytes(content),
858
+ }
859
+ )
860
+ _fsync_dir(vscode)
861
+ _atomic_write(
862
+ journal,
863
+ (json.dumps({"files": records, "version": 1}, sort_keys=True) + "\n").encode("utf-8"),
864
+ )
865
+ for record in records:
866
+ os.replace(vscode / str(record["staged"]), vscode / str(record["name"]))
867
+ _fsync_dir(vscode)
868
+ journal.unlink()
869
+ _fsync_dir(vscode)
870
+ for record in records:
871
+ (vscode / str(record["backup"])).unlink(missing_ok=True)
872
+ return True
873
+ except Exception:
874
+ if journal.exists():
875
+ _recover_vscode_transaction(vscode)
876
+ else:
877
+ for record in records:
878
+ (vscode / str(record["staged"])).unlink(missing_ok=True)
879
+ (vscode / str(record["backup"])).unlink(missing_ok=True)
880
+ raise
881
+
882
+
883
+ def _sync_vscode(
884
+ project_dir: Path,
885
+ projections: tuple[VisibleAppProjection, ...],
886
+ ) -> IdeProviderResult:
887
+ vscode = project_dir / ".vscode"
888
+ if not _safe_provider_dir(vscode, provider="VS Code"):
889
+ return IdeProviderResult(provider="vscode", status="not_applicable")
890
+ _recover_vscode_transaction(vscode)
891
+ settings_path = vscode / "settings.json"
892
+ ledger_path = vscode / _VSCODE_LEDGER
893
+ _validate_asset_path(settings_path, provider="VS Code")
894
+ _validate_asset_path(ledger_path, provider="VS Code")
895
+ text, payload = _load_vscode_settings(settings_path)
896
+ previous = _load_vscode_ledger(ledger_path)
897
+ merged, owned = _merge_vscode_settings(
898
+ text,
899
+ payload,
900
+ previous,
901
+ _vscode_paths(project_dir, projections),
902
+ )
903
+ _ensure_git_excludes(
904
+ project_dir,
905
+ (f".vscode/{_VSCODE_LEDGER}", ".vscode/.pz.ide-sync.*"),
906
+ )
907
+ changed = _replace_vscode_pair(
908
+ vscode,
909
+ {
910
+ settings_path: merged.encode("utf-8"),
911
+ ledger_path: _ledger_bytes(owned),
912
+ },
913
+ )
914
+ return IdeProviderResult(
915
+ provider="vscode",
916
+ status="updated" if changed else "unchanged",
917
+ assets=(settings_path, ledger_path),
918
+ )
919
+
920
+
921
+ def sync_ide_projections(project_dir: str | Path) -> IdeSyncResult:
922
+ root = _project_root(project_dir, action="sync_ide_projections")
923
+ projections = _app_projections(root)
924
+ providers: list[IdeProviderResult] = []
925
+ failures: list[tuple[str, PzError]] = []
926
+ for provider, sync in (
927
+ ("pycharm", _sync_pycharm),
928
+ ("vscode", _sync_vscode),
929
+ ):
930
+ try:
931
+ providers.append(sync(root, projections))
932
+ except Exception as exc:
933
+ error = (
934
+ exc
935
+ if isinstance(exc, PzError)
936
+ else _error(
937
+ "PZ_DEV_IDE_SYNC_FAILED",
938
+ f"{provider} projection failed.",
939
+ action="sync_ide_projections",
940
+ detail=str(exc),
941
+ )
942
+ )
943
+ failures.append((provider, error))
944
+ providers.append(
945
+ IdeProviderResult(provider=provider, status="failed") # type: ignore[arg-type]
946
+ )
947
+ if failures:
948
+ _, first = failures[0]
949
+ detail = json.dumps(
950
+ {
951
+ "providers": {
952
+ result.provider: {
953
+ "status": result.status,
954
+ "code": next(
955
+ (
956
+ failure.code
957
+ for failed_provider, failure in failures
958
+ if failed_provider == result.provider
959
+ ),
960
+ None,
961
+ )
962
+ if result.status == "failed"
963
+ else None,
964
+ }
965
+ for result in providers
966
+ },
967
+ "first_error": first.detail or first.message,
968
+ },
969
+ ensure_ascii=True,
970
+ sort_keys=True,
971
+ )
972
+ raise _error(
973
+ first.code,
974
+ first.message,
975
+ action="sync_ide_projections",
976
+ detail=detail,
977
+ ) from first
978
+ return IdeSyncResult(
979
+ project_dir=root,
980
+ app_ids=tuple(item.app_id for item in projections),
981
+ providers=tuple(providers),
982
+ )
983
+
984
+
985
+ def _inspect_pycharm(
986
+ project_dir: Path,
987
+ projections: tuple[VisibleAppProjection, ...],
988
+ ) -> None:
989
+ idea = project_dir / ".idea"
990
+ if not _safe_provider_dir(idea, provider="PyCharm"):
991
+ return
992
+ module_path = idea / _PYCHARM_MODULE
993
+ modules_path = idea / "modules.xml"
994
+ if not module_path.is_file() or not modules_path.is_file():
995
+ raise _error(
996
+ "PZ_DEV_IDE_PROJECTION_INVALID",
997
+ "PyCharm PZ projection is missing.",
998
+ action="check_ide_projections",
999
+ )
1000
+ try:
1001
+ module = ET.fromstring(module_path.read_bytes(), parser=_xml_parser())
1002
+ modules = ET.fromstring(modules_path.read_bytes(), parser=_xml_parser())
1003
+ except (ET.ParseError, OSError) as exc:
1004
+ raise _error(
1005
+ "PZ_DEV_IDE_PROJECTION_INVALID",
1006
+ "PyCharm PZ projection is invalid.",
1007
+ action="check_ide_projections",
1008
+ detail=str(exc),
1009
+ ) from exc
1010
+ actual_urls = tuple(
1011
+ item.get("url", "") for item in module.findall("./component/content/sourceFolder")
1012
+ )
1013
+ expected_urls = tuple(_pycharm_url(project_dir, item) for item in projections)
1014
+ module_path_value = f"$PROJECT_DIR$/.idea/{_PYCHARM_MODULE}"
1015
+ module_entries = tuple(
1016
+ item
1017
+ for item in modules.findall("./component/modules/module")
1018
+ if item.get("filepath") == module_path_value
1019
+ )
1020
+ if actual_urls != expected_urls or len(module_entries) != 1:
1021
+ raise _error(
1022
+ "PZ_DEV_IDE_PROJECTION_INVALID",
1023
+ "PyCharm PZ projection is stale or duplicated.",
1024
+ action="check_ide_projections",
1025
+ )
1026
+
1027
+
1028
+ def _inspect_vscode(
1029
+ project_dir: Path,
1030
+ projections: tuple[VisibleAppProjection, ...],
1031
+ ) -> None:
1032
+ vscode = project_dir / ".vscode"
1033
+ if not _safe_provider_dir(vscode, provider="VS Code"):
1034
+ return
1035
+ if (vscode / _VSCODE_JOURNAL).exists():
1036
+ raise _error(
1037
+ "PZ_DEV_IDE_TRANSACTION_INCOMPLETE",
1038
+ "VS Code projection has an unfinished transaction.",
1039
+ action="check_ide_projections",
1040
+ )
1041
+ settings_path = vscode / "settings.json"
1042
+ ledger_path = vscode / _VSCODE_LEDGER
1043
+ _validate_asset_path(settings_path, provider="VS Code")
1044
+ _validate_asset_path(ledger_path, provider="VS Code")
1045
+ if not settings_path.is_file() or not ledger_path.is_file():
1046
+ raise _error(
1047
+ "PZ_DEV_IDE_PROJECTION_INVALID",
1048
+ "VS Code PZ projection is missing.",
1049
+ action="check_ide_projections",
1050
+ )
1051
+ text, payload = _load_vscode_settings(settings_path)
1052
+ ledger = _load_vscode_ledger(ledger_path)
1053
+ try:
1054
+ span = _top_level_value_span(text, _VSCODE_SETTING)
1055
+ except ValueError as exc:
1056
+ raise _error(
1057
+ "PZ_DEV_IDE_VSCODE_SETTINGS_INVALID",
1058
+ "VS Code settings structure cannot be inspected.",
1059
+ action="check_ide_projections",
1060
+ detail=str(exc),
1061
+ ) from exc
1062
+ if span is None:
1063
+ array_text = "[]"
1064
+ else:
1065
+ array_text = text[span[0] : span[1]]
1066
+ _validate_managed_block(array_text, ledger)
1067
+ existing = tuple(payload.get(_VSCODE_SETTING, []))
1068
+ required = _vscode_paths(project_dir, projections)
1069
+ if (
1070
+ len(existing) != len(tuple(dict.fromkeys(existing)))
1071
+ or any(item not in existing for item in required)
1072
+ or any(item not in required for item in ledger)
1073
+ ):
1074
+ raise _error(
1075
+ "PZ_DEV_IDE_PROJECTION_INVALID",
1076
+ "VS Code PZ projection is stale or duplicated.",
1077
+ action="check_ide_projections",
1078
+ )
1079
+
1080
+
1081
+ def build_ide_projection_check_items(project_dir: str | Path):
1082
+ from pz_core.assembly.diagnostics.checks import CheckItem
1083
+
1084
+ candidate = Path(project_dir).expanduser().resolve(strict=False)
1085
+ if not candidate.is_dir():
1086
+ return ()
1087
+ root = _project_root(project_dir, action="check_ide_projections")
1088
+ applicable = (root / ".idea").exists() or (root / ".vscode").exists()
1089
+ if not applicable:
1090
+ return ()
1091
+ try:
1092
+ projections = _app_projections(root)
1093
+ _inspect_pycharm(root, projections)
1094
+ _inspect_vscode(root, projections)
1095
+ except PzError as exc:
1096
+ return (
1097
+ CheckItem(
1098
+ severity="warning",
1099
+ code=exc.code,
1100
+ owner=_OWNER,
1101
+ scope="dev.ide",
1102
+ message=exc.message,
1103
+ ok=False,
1104
+ expected="IDE projections match visible minimal apps",
1105
+ actual=exc.detail or exc.message,
1106
+ repair_command="pz dev ide sync --project-dir .",
1107
+ ),
1108
+ )
1109
+ return (
1110
+ CheckItem(
1111
+ severity="info",
1112
+ code="PZ_CHECK_DEV_IDE_VALID",
1113
+ owner=_OWNER,
1114
+ scope="dev.ide",
1115
+ message="IDE projections match visible minimal apps.",
1116
+ ok=True,
1117
+ expected="IDE projections match visible minimal apps",
1118
+ actual="valid",
1119
+ repair_command=None,
1120
+ ),
1121
+ )
1122
+
1123
+
1124
+ __all__ = [
1125
+ "IdeProviderResult",
1126
+ "IdeSyncResult",
1127
+ "build_ide_projection_check_items",
1128
+ "sync_ide_projections",
1129
+ ]