@apralabs/apra-fleet 0.4.2 → 0.4.3

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 (370) hide show
  1. package/README.md +38 -5
  2. package/dist/agents/backlog-groomer.md +25 -0
  3. package/dist/agents/ci-watcher.md +11 -0
  4. package/dist/agents/deployer.md +37 -2
  5. package/dist/agents/doer.md +36 -12
  6. package/dist/agents/harvester.md +11 -0
  7. package/dist/agents/integ-test-runner.md +11 -0
  8. package/dist/agents/kb-reconciler.md +9 -0
  9. package/dist/agents/plan-reviewer.md +110 -22
  10. package/dist/agents/planner.md +125 -37
  11. package/dist/agents/regression-test-runner.md +11 -0
  12. package/dist/agents/reviewer.md +13 -2
  13. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  14. package/dist/cli/agent-transform.d.ts +83 -2
  15. package/dist/cli/agent-transform.d.ts.map +1 -1
  16. package/dist/cli/agent-transform.js +266 -21
  17. package/dist/cli/agent-transform.js.map +1 -1
  18. package/dist/cli/auth.d.ts.map +1 -1
  19. package/dist/cli/auth.js +28 -9
  20. package/dist/cli/auth.js.map +1 -1
  21. package/dist/cli/config.d.ts +7 -5
  22. package/dist/cli/config.d.ts.map +1 -1
  23. package/dist/cli/config.js +44 -34
  24. package/dist/cli/config.js.map +1 -1
  25. package/dist/cli/install.d.ts +33 -0
  26. package/dist/cli/install.d.ts.map +1 -1
  27. package/dist/cli/install.js +290 -23
  28. package/dist/cli/install.js.map +1 -1
  29. package/dist/cli/kb-directives.d.ts.map +1 -1
  30. package/dist/cli/kb-directives.js +2 -1
  31. package/dist/cli/kb-directives.js.map +1 -1
  32. package/dist/cli/register-member.d.ts.map +1 -1
  33. package/dist/cli/register-member.js +6 -2
  34. package/dist/cli/register-member.js.map +1 -1
  35. package/dist/commands/kb-server.d.ts +3 -0
  36. package/dist/commands/kb-server.d.ts.map +1 -1
  37. package/dist/commands/kb-server.js +43 -3
  38. package/dist/commands/kb-server.js.map +1 -1
  39. package/dist/index.js +3 -3
  40. package/dist/os/linux.d.ts +6 -0
  41. package/dist/os/linux.d.ts.map +1 -1
  42. package/dist/os/linux.js +35 -2
  43. package/dist/os/linux.js.map +1 -1
  44. package/dist/os/os-commands.d.ts +61 -2
  45. package/dist/os/os-commands.d.ts.map +1 -1
  46. package/dist/os/windows-gitbash.d.ts +5 -0
  47. package/dist/os/windows-gitbash.d.ts.map +1 -1
  48. package/dist/os/windows-gitbash.js +15 -0
  49. package/dist/os/windows-gitbash.js.map +1 -1
  50. package/dist/os/windows.d.ts +6 -0
  51. package/dist/os/windows.d.ts.map +1 -1
  52. package/dist/os/windows.js +46 -3
  53. package/dist/os/windows.js.map +1 -1
  54. package/dist/providers/agy.d.ts +115 -6
  55. package/dist/providers/agy.d.ts.map +1 -1
  56. package/dist/providers/agy.js +569 -53
  57. package/dist/providers/agy.js.map +1 -1
  58. package/dist/providers/claude.d.ts +81 -3
  59. package/dist/providers/claude.d.ts.map +1 -1
  60. package/dist/providers/claude.js +344 -10
  61. package/dist/providers/claude.js.map +1 -1
  62. package/dist/providers/codex.d.ts +4 -2
  63. package/dist/providers/codex.d.ts.map +1 -1
  64. package/dist/providers/codex.js +19 -2
  65. package/dist/providers/codex.js.map +1 -1
  66. package/dist/providers/copilot.d.ts +4 -2
  67. package/dist/providers/copilot.d.ts.map +1 -1
  68. package/dist/providers/copilot.js +20 -2
  69. package/dist/providers/copilot.js.map +1 -1
  70. package/dist/providers/none.d.ts +4 -2
  71. package/dist/providers/none.d.ts.map +1 -1
  72. package/dist/providers/none.js +17 -2
  73. package/dist/providers/none.js.map +1 -1
  74. package/dist/providers/opencode.d.ts +3 -1
  75. package/dist/providers/opencode.d.ts.map +1 -1
  76. package/dist/providers/opencode.js +22 -2
  77. package/dist/providers/opencode.js.map +1 -1
  78. package/dist/providers/provider.d.ts +201 -6
  79. package/dist/providers/provider.d.ts.map +1 -1
  80. package/dist/providers/provider.js +56 -0
  81. package/dist/providers/provider.js.map +1 -1
  82. package/dist/services/agy-project.d.ts +102 -0
  83. package/dist/services/agy-project.d.ts.map +1 -0
  84. package/dist/services/agy-project.js +356 -0
  85. package/dist/services/agy-project.js.map +1 -0
  86. package/dist/services/auth-socket.js +4 -4
  87. package/dist/services/auth-web.js +1 -1
  88. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  89. package/dist/services/cloud/lifecycle.js +33 -4
  90. package/dist/services/cloud/lifecycle.js.map +1 -1
  91. package/dist/services/credential-cleanup.d.ts.map +1 -1
  92. package/dist/services/credential-cleanup.js +35 -17
  93. package/dist/services/credential-cleanup.js.map +1 -1
  94. package/dist/services/exit-drain.d.ts +44 -0
  95. package/dist/services/exit-drain.d.ts.map +1 -0
  96. package/dist/services/exit-drain.js +52 -0
  97. package/dist/services/exit-drain.js.map +1 -0
  98. package/dist/services/github-app.d.ts.map +1 -1
  99. package/dist/services/github-app.js +32 -4
  100. package/dist/services/github-app.js.map +1 -1
  101. package/dist/services/http-transport.d.ts +1 -0
  102. package/dist/services/http-transport.d.ts.map +1 -1
  103. package/dist/services/http-transport.js +48 -1
  104. package/dist/services/http-transport.js.map +1 -1
  105. package/dist/services/knowledge/kb-config.d.ts +42 -0
  106. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  107. package/dist/services/knowledge/kb-config.js +54 -0
  108. package/dist/services/knowledge/kb-config.js.map +1 -0
  109. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  110. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  111. package/dist/services/knowledge/kb-providers.js +191 -17
  112. package/dist/services/knowledge/kb-providers.js.map +1 -1
  113. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  114. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  115. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  116. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  117. package/dist/services/model-pricing.d.ts.map +1 -1
  118. package/dist/services/model-pricing.js +7 -3
  119. package/dist/services/model-pricing.js.map +1 -1
  120. package/dist/services/secret-token.d.ts +38 -0
  121. package/dist/services/secret-token.d.ts.map +1 -0
  122. package/dist/services/secret-token.js +51 -0
  123. package/dist/services/secret-token.js.map +1 -0
  124. package/dist/services/service-manager/types.d.ts +3 -1
  125. package/dist/services/service-manager/types.d.ts.map +1 -1
  126. package/dist/services/service-manager/windows.d.ts +14 -2
  127. package/dist/services/service-manager/windows.d.ts.map +1 -1
  128. package/dist/services/service-manager/windows.js +65 -7
  129. package/dist/services/service-manager/windows.js.map +1 -1
  130. package/dist/services/ssh.d.ts.map +1 -1
  131. package/dist/services/ssh.js +58 -2
  132. package/dist/services/ssh.js.map +1 -1
  133. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  134. package/dist/services/stall/read-log-tail.js +20 -10
  135. package/dist/services/stall/read-log-tail.js.map +1 -1
  136. package/dist/services/stall/stall-detector.d.ts +53 -4
  137. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  138. package/dist/services/stall/stall-detector.js +212 -34
  139. package/dist/services/stall/stall-detector.js.map +1 -1
  140. package/dist/services/strategy.d.ts.map +1 -1
  141. package/dist/services/strategy.js +79 -2
  142. package/dist/services/strategy.js.map +1 -1
  143. package/dist/services/substitution-engine.js +2 -2
  144. package/dist/services/substitution-engine.js.map +1 -1
  145. package/dist/services/tool-registry.d.ts.map +1 -1
  146. package/dist/services/tool-registry.js +5 -3
  147. package/dist/services/tool-registry.js.map +1 -1
  148. package/dist/services/vcs/azure-devops.d.ts +66 -1
  149. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  150. package/dist/services/vcs/azure-devops.js +192 -21
  151. package/dist/services/vcs/azure-devops.js.map +1 -1
  152. package/dist/services/vcs/types.d.ts +1 -1
  153. package/dist/skills/fleet-sprint-cli/SKILL.md +18 -0
  154. package/dist/skills/pm/SKILL.md +1 -1
  155. package/dist/skills/pm/cost.md +0 -3
  156. package/dist/skills/pm/fleet-addendum.md +2 -2
  157. package/dist/tools/check-status.d.ts +7 -4
  158. package/dist/tools/check-status.d.ts.map +1 -1
  159. package/dist/tools/check-status.js +2 -0
  160. package/dist/tools/check-status.js.map +1 -1
  161. package/dist/tools/compose-permissions.d.ts +6 -0
  162. package/dist/tools/compose-permissions.d.ts.map +1 -1
  163. package/dist/tools/compose-permissions.js +182 -34
  164. package/dist/tools/compose-permissions.js.map +1 -1
  165. package/dist/tools/credential-store-set.js +1 -1
  166. package/dist/tools/execute-command.d.ts.map +1 -1
  167. package/dist/tools/execute-command.js +31 -20
  168. package/dist/tools/execute-command.js.map +1 -1
  169. package/dist/tools/execute-prompt.d.ts +15 -2
  170. package/dist/tools/execute-prompt.d.ts.map +1 -1
  171. package/dist/tools/execute-prompt.js +1196 -892
  172. package/dist/tools/execute-prompt.js.map +1 -1
  173. package/dist/tools/kb-capture.d.ts +2 -2
  174. package/dist/tools/kb-capture.d.ts.map +1 -1
  175. package/dist/tools/kb-capture.js +29 -5
  176. package/dist/tools/kb-capture.js.map +1 -1
  177. package/dist/tools/kb-export.d.ts +2 -2
  178. package/dist/tools/kb-export.d.ts.map +1 -1
  179. package/dist/tools/kb-export.js +3 -28
  180. package/dist/tools/kb-export.js.map +1 -1
  181. package/dist/tools/kb-feedback.d.ts.map +1 -1
  182. package/dist/tools/kb-feedback.js +3 -1
  183. package/dist/tools/kb-feedback.js.map +1 -1
  184. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  185. package/dist/tools/kb-freshness-sweep.js +3 -1
  186. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  187. package/dist/tools/kb-import.d.ts.map +1 -1
  188. package/dist/tools/kb-import.js +2 -1
  189. package/dist/tools/kb-import.js.map +1 -1
  190. package/dist/tools/kb-list.d.ts.map +1 -1
  191. package/dist/tools/kb-list.js +3 -1
  192. package/dist/tools/kb-list.js.map +1 -1
  193. package/dist/tools/kb-query.d.ts +2 -2
  194. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  195. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  196. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  197. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  198. package/dist/tools/kb-resolve-contradiction.js +3 -1
  199. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  200. package/dist/tools/kb-setup.d.ts.map +1 -1
  201. package/dist/tools/kb-setup.js +125 -20
  202. package/dist/tools/kb-setup.js.map +1 -1
  203. package/dist/tools/kb-stats.d.ts.map +1 -1
  204. package/dist/tools/kb-stats.js +64 -43
  205. package/dist/tools/kb-stats.js.map +1 -1
  206. package/dist/tools/list-members.d.ts +2 -2
  207. package/dist/tools/list-members.d.ts.map +1 -1
  208. package/dist/tools/list-members.js +1 -0
  209. package/dist/tools/list-members.js.map +1 -1
  210. package/dist/tools/member-detail.d.ts +2 -2
  211. package/dist/tools/member-detail.d.ts.map +1 -1
  212. package/dist/tools/member-detail.js +17 -0
  213. package/dist/tools/member-detail.js.map +1 -1
  214. package/dist/tools/member-reservation.d.ts +58 -1
  215. package/dist/tools/member-reservation.d.ts.map +1 -1
  216. package/dist/tools/member-reservation.js +61 -20
  217. package/dist/tools/member-reservation.js.map +1 -1
  218. package/dist/tools/provision-auth.d.ts +80 -1
  219. package/dist/tools/provision-auth.d.ts.map +1 -1
  220. package/dist/tools/provision-auth.js +142 -54
  221. package/dist/tools/provision-auth.js.map +1 -1
  222. package/dist/tools/provision-vcs-auth.d.ts +91 -1
  223. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  224. package/dist/tools/provision-vcs-auth.js +209 -49
  225. package/dist/tools/provision-vcs-auth.js.map +1 -1
  226. package/dist/tools/register-member.d.ts +12 -9
  227. package/dist/tools/register-member.d.ts.map +1 -1
  228. package/dist/tools/register-member.js +99 -12
  229. package/dist/tools/register-member.js.map +1 -1
  230. package/dist/tools/remove-member.d.ts.map +1 -1
  231. package/dist/tools/remove-member.js +27 -2
  232. package/dist/tools/remove-member.js.map +1 -1
  233. package/dist/tools/send-email.d.ts +2 -2
  234. package/dist/tools/setup-git-app.d.ts.map +1 -1
  235. package/dist/tools/setup-git-app.js +11 -7
  236. package/dist/tools/setup-git-app.js.map +1 -1
  237. package/dist/tools/shutdown-server.d.ts +2 -0
  238. package/dist/tools/shutdown-server.d.ts.map +1 -1
  239. package/dist/tools/shutdown-server.js +23 -1
  240. package/dist/tools/shutdown-server.js.map +1 -1
  241. package/dist/tools/update-member.d.ts +12 -9
  242. package/dist/tools/update-member.d.ts.map +1 -1
  243. package/dist/tools/update-member.js +43 -11
  244. package/dist/tools/update-member.js.map +1 -1
  245. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  246. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  247. package/dist/tools/vcs-credential-exec.js +197 -0
  248. package/dist/tools/vcs-credential-exec.js.map +1 -0
  249. package/dist/types.d.ts +13 -0
  250. package/dist/types.d.ts.map +1 -1
  251. package/dist/utils/log-helpers.d.ts.map +1 -1
  252. package/dist/utils/log-helpers.js +2 -2
  253. package/dist/utils/log-helpers.js.map +1 -1
  254. package/dist/utils/prompt-errors.d.ts.map +1 -1
  255. package/dist/utils/prompt-errors.js +7 -1
  256. package/dist/utils/prompt-errors.js.map +1 -1
  257. package/dist/utils/shell-escape.d.ts +16 -0
  258. package/dist/utils/shell-escape.d.ts.map +1 -1
  259. package/dist/utils/shell-escape.js +22 -2
  260. package/dist/utils/shell-escape.js.map +1 -1
  261. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  262. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  263. package/dist/utils/vcs-provider-detect.js +109 -0
  264. package/dist/utils/vcs-provider-detect.js.map +1 -0
  265. package/dist/utils/workspace-trust.d.ts +20 -17
  266. package/dist/utils/workspace-trust.d.ts.map +1 -1
  267. package/dist/utils/workspace-trust.js +87 -1
  268. package/dist/utils/workspace-trust.js.map +1 -1
  269. package/dist/workflows/auto-sprint.js +176 -15
  270. package/package.json +6 -4
  271. package/packages/apra-fleet-client/src/client/api.mjs +319 -17
  272. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  273. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  274. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +25 -0
  275. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +11 -0
  276. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -2
  277. package/packages/apra-fleet-se/apra-pm/agents/doer.md +36 -12
  278. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +11 -0
  279. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +11 -0
  280. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +9 -0
  281. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +110 -22
  282. package/packages/apra-fleet-se/apra-pm/agents/planner.md +125 -37
  283. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +11 -0
  284. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +13 -2
  285. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  286. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -1
  287. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  288. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  289. package/packages/apra-fleet-se/bin/cli.mjs +149 -1
  290. package/packages/apra-fleet-se/bin/serve.mjs +78 -4
  291. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  292. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  293. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  294. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  295. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  296. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  297. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  298. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  299. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +61 -14
  300. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  301. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  302. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  303. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  304. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  305. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +276 -0
  306. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  307. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  308. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  309. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +996 -32
  310. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +267 -0
  311. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  312. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  313. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  314. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  315. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  316. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  317. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  318. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  319. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  320. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  321. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  322. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  323. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  324. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  325. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  326. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  327. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  328. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  329. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  330. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  331. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  332. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  333. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  334. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  335. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  336. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  337. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  338. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  339. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  340. package/packages/apra-fleet-se/fleet-sprint/runner.js +1467 -9798
  341. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +17 -12
  342. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  343. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +18 -0
  344. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  345. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  346. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  347. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  348. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  349. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  350. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  351. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +153 -19
  352. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +71 -21
  353. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  354. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +131 -0
  355. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +140 -16
  356. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +1 -0
  357. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +77 -2
  358. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  359. package/packages/apra-fleet-se/package.json +1 -1
  360. package/packages/apra-fleet-workflow/src/viewer/index.mjs +17 -6
  361. package/packages/apra-fleet-workflow/src/workflow/index.mjs +49 -7
  362. package/skills/fleet/SKILL.md +8 -8
  363. package/skills/fleet/auth-azdevops.md +14 -3
  364. package/skills/fleet/auth-bitbucket.md +2 -2
  365. package/skills/fleet/auth-github.md +5 -4
  366. package/skills/fleet/onboarding.md +3 -3
  367. package/skills/fleet/permissions.md +5 -1
  368. package/skills/fleet/profiles/node.json +1 -1
  369. package/skills/fleet/troubleshooting.md +3 -3
  370. package/version.json +1 -1
@@ -0,0 +1,239 @@
1
+ // PR-body and cost-report text surface for fleet-sprint (apra-fleet-3swo.6.14).
2
+ // Extracted out of runner.js; runner.js re-exports every symbol it previously
3
+ // exported from this region, so existing importers of fleet-sprint/runner.js
4
+ // resolve unchanged.
5
+ //
6
+ // This module owns:
7
+ // - sanitizePrText: the PR title/body sanitizer the Publish PR step runs
8
+ // the final verdict's LLM-authored notes through before handing them to
9
+ // VCSModule's create-pull-request command builder.
10
+ // - buildAnalysisText: the Harvester dispatch's `analysisText` block
11
+ // builder (module-private -- it is the body builder buildCostAnalysis
12
+ // and the PR text path share, so it moves with them rather than staying
13
+ // behind).
14
+ // - buildCostAnalysis: the Harvester dispatch's `costAnalysis` block
15
+ // builder, reporting budget/spend honestly from the live `budget` object.
16
+ // - computeBranchSlug: the collision-resistant filesystem slug for
17
+ // `docs/sprint-analysis-<slug>.md`.
18
+ //
19
+ // sanitizePrText depends on SAFE_TEXT_RE, which moved to newtask-text.mjs
20
+ // (apra-fleet-3swo.6.14 Part Two) alongside the newTask-title validation
21
+ // surface it also guards -- imported back here rather than duplicated.
22
+
23
+ import { createHash } from 'crypto';
24
+ import { SAFE_TEXT_RE } from './newtask-text.mjs';
25
+
26
+ // ---------------------------------------------------------------------------
27
+ // PR body/title text sanitization. The final reviewer's verdict notes are LLM
28
+ // output embedded in the PR title/body that the Publish PR step passes into
29
+ // VCSModule's create-pull-request command builder, which JSON-encodes them
30
+ // into the curl request payload -- the same injection class SAFE_TEXT_RE
31
+ // exists to close for newTask titles, at a different call site.
32
+ //
33
+ // Unlike validateNewTask(), rejecting is not an option here: the PR must still
34
+ // carry the sprint's verdict to a human even when the notes are malformed, and
35
+ // failing closed would drop the one thing that human most needs to read. So
36
+ // this strips instead: every character outside SAFE_TEXT_RE becomes a space,
37
+ // keeping the notes readable while nothing that could break out of the
38
+ // shell-quoted command string VCSModule builds around it.
39
+ /**
40
+ * Sanitizes LLM-authored free text (e.g. finalVerdictResult.notes) before it
41
+ * is embedded in a VCSModule-built PR title/body and dispatched via
42
+ * `command()`. Replaces every character outside SAFE_TEXT_RE with a space,
43
+ * collapses the resulting whitespace, and returns the readable remainder.
44
+ * @param {unknown} text
45
+ * @returns {string}
46
+ */
47
+ export function sanitizePrText(text) {
48
+ const str = String(text ?? '');
49
+ let out = '';
50
+ for (const ch of str) {
51
+ // Newlines and tabs collapse to a space along with every other
52
+ // disallowed character: SAFE_TEXT_RE has no multi-line allowance,
53
+ // because a literal newline inside a double-quoted command-string
54
+ // argument is not reliably safe across mixed POSIX/Windows shells.
55
+ out += SAFE_TEXT_RE.test(ch) ? ch : ' ';
56
+ }
57
+ return out.replace(/\s+/g, ' ').trim();
58
+ }
59
+
60
+ // The Regression Test phase is informational-only and must never gate the
61
+ // sprint; packages/apra-fleet-se/test/regression-phase-never-gates.test.mjs
62
+ // enforces that.
63
+ // ---------------------------------------------------------------------------
64
+ // Finalization prompt builders
65
+ // ---------------------------------------------------------------------------
66
+
67
+ /**
68
+ * Assembles the `analysisText` block for the Harvester dispatch from this
69
+ * run's in-memory tracking state: cycle-by-cycle closed-bead progress,
70
+ * deploy/integration outcomes, rejected reviewer newTasks, the final verdict,
71
+ * and the regression pass. Pure formatting -- every value is computed
72
+ * elsewhere. harvester.md requires this content be written verbatim to
73
+ * `analysisArtifactFile`.
74
+ * @param {object} opts
75
+ * @returns {string}
76
+ */
77
+ export function buildAnalysisText({
78
+ targetIssues, branch, baseBranch, cyclesRun,
79
+ closedCountHistory, highWaterClosedCount,
80
+ deployFailures, integFailures, rejectedNewTasks,
81
+ finalVerdictResult, finalClosedCount, finalOpenAtGoalCount,
82
+ // apra-fleet-rp7a.1: the ids excluded from finalOpenAtGoalCount because
83
+ // they are DEFERRED. Reported as their own line rather than folded into
84
+ // the count, so "Final open-at-goal-priority count: 0" can never be read
85
+ // as "nothing was skipped".
86
+ finalDeferredAtGoalIds = [],
87
+ regressionResult = null,
88
+ }) {
89
+ // The once-per-sprint Regression Test phase runs after the final verdict
90
+ // and never gates it. Its failures are filed as parent-less carry-over
91
+ // beads, so they never appear in the open-at-goal count and are reported
92
+ // separately here.
93
+ const regressionLines = regressionResult === null
94
+ ? ['Regression pass: not run this sprint (no regression-test-playbook.md, or the probe failed).']
95
+ : [
96
+ `Regression pass: ${regressionResult.passed === true ? 'PASSED' : 'FAILED'} `
97
+ + `(real-bd suite: ${regressionResult.suitePassed === true ? 'pass' : 'fail'}, `
98
+ + `smoke test: ${regressionResult.smokePassed === true ? 'pass' : 'fail'}).`,
99
+ `Carry-over beads filed: ${(regressionResult.bugsFiled || []).join(', ') || 'none'}.`,
100
+ `Summary: ${regressionResult.summary || '(none reported)'}`,
101
+ 'Informational only -- this pass ran after the final verdict and did not gate it; any bead '
102
+ + 'above is parent-less by design and carries over to a future sprint.',
103
+ ];
104
+ const lines = [
105
+ `# Sprint Analysis: ${branch}`,
106
+ '',
107
+ `Scope issue id(s): ${targetIssues.join(', ') || '(none specified)'}.`,
108
+ `Base branch: ${baseBranch}.`,
109
+ `Cycles run: ${cyclesRun}.`,
110
+ '',
111
+ '## Progress',
112
+ '',
113
+ `Closed-bead count history (per cycle evaluation): [${closedCountHistory.join(', ') || 'none recorded'}].`,
114
+ `High-water-mark closed count this sprint: ${highWaterClosedCount}.`,
115
+ `Final closed count: ${finalClosedCount}.`,
116
+ `Final open-at-goal-priority count: ${finalOpenAtGoalCount}.`,
117
+ finalDeferredAtGoalIds.length > 0
118
+ ? `Deferred bead(s) at/above goal priority, excluded from that count and treated as out of scope `
119
+ + `(a deferred bead is never dispatchable, so no cycle could advance it): ${finalDeferredAtGoalIds.join(', ')}.`
120
+ : 'No beads were deferred out of scope at/above goal priority this sprint.',
121
+ '',
122
+ '## Deploy/Integration outcomes',
123
+ '',
124
+ deployFailures.length > 0
125
+ ? `Deploy failures (${deployFailures.length}): ` + deployFailures.map((f) => `C${f.cycle}: ${f.notes}`).join(' | ')
126
+ : 'No deploy failures recorded this sprint.',
127
+ integFailures.length > 0
128
+ ? `Integration test failures (${integFailures.length}): ` + integFailures.map((f) => `C${f.cycle}: ${f.notes} (bugs filed: ${(f.bugsFiled || []).join(', ') || 'none'})`).join(' | ')
129
+ : 'No integration test failures recorded this sprint.',
130
+ '',
131
+ '## Reviewer-proposed newTask rejections',
132
+ '',
133
+ rejectedNewTasks.length > 0
134
+ ? `${rejectedNewTasks.length} newTask(s) rejected before reaching bd create: ` + rejectedNewTasks.map((r) => `C${r.cycle}: ${r.reason}`).join(' | ')
135
+ : 'None.',
136
+ '',
137
+ '## Final verdict',
138
+ '',
139
+ `${finalVerdictResult.verdict}${finalVerdictResult.notes ? ` -- ${finalVerdictResult.notes}` : ''}`,
140
+ '',
141
+ '## Regression pass (once per sprint, informational)',
142
+ '',
143
+ ...regressionLines,
144
+ ];
145
+ return lines.join('\n');
146
+ }
147
+
148
+ /**
149
+ * Builds the `costAnalysis` block for the Harvester dispatch from the live
150
+ * `budget` object. Reports only what is known: an unset ceiling, an absent
151
+ * spent() and an unpriced-model spend gap are each stated as such rather than
152
+ * backfilled with a fabricated number, since harvester.md inserts this block
153
+ * verbatim and never recomputes it. The remaining budget is derived from
154
+ * `total` and `spent()`, not read from the budget object.
155
+ * @param {{ total: number|null, spent?: () => number, pricingSummary?: () => { real: number, fallback: number } }} budget
156
+ * @param {{ spend?: number, dispatchCount?: number }} [integTestRunnerStats] -- apra-fleet-nwh.1:
157
+ * this sprint's own tracked integ-test-runner spend (a before/after
158
+ * `budget.spent()` delta accumulated by the caller around each Integ Test
159
+ * phase dispatch, see runSprintCycle's integTestRunnerSpend/
160
+ * integTestRunnerDispatchCount) and how many times that phase dispatched.
161
+ * Reported as its OWN line, distinct from doer/reviewer/overhead, instead
162
+ * of being silently folded into "overhead" -- often the single longest/
163
+ * most expensive phase (a full playbook run against a real sandbox).
164
+ * @returns {string}
165
+ */
166
+ export function buildCostAnalysis(budget, integTestRunnerStats = {}) {
167
+ const total = budget && budget.total;
168
+ const spent = budget && typeof budget.spent === 'function' ? budget.spent() : null;
169
+ const lines = [
170
+ total !== null && total !== undefined
171
+ ? `Budget ceiling: $${total.toFixed(4)}.`
172
+ : 'Budget ceiling: not set (no --budget flag) -- unlimited for this run.',
173
+ typeof spent === 'number'
174
+ ? `Tracked spend (priced dispatches only): $${spent.toFixed(4)}.`
175
+ : 'Tracked spend: not tracked -- the budget object did not expose spent() for this run.',
176
+ ];
177
+ if (total !== null && total !== undefined && typeof spent === 'number') {
178
+ lines.push(`Remaining budget: $${(total - spent).toFixed(4)}.`);
179
+ } else {
180
+ lines.push('Remaining budget: unknown/unbounded.');
181
+ }
182
+ // apra-fleet-nwh.1: an explicit integ-test-runner spend line, broken out
183
+ // of the totals above (it is a SUBSET of `spent`, not additional spend)
184
+ // so this often-longest phase is never silently bucketed into
185
+ // "overhead" by a reader of this block. Honest about all three states:
186
+ // the phase never dispatched this run, it dispatched but spend was not
187
+ // trackable (same `spent()`-unavailable case as above), or a real
188
+ // tracked figure.
189
+ const integDispatchCount = Number.isInteger(integTestRunnerStats.dispatchCount) ? integTestRunnerStats.dispatchCount : 0;
190
+ if (integDispatchCount === 0) {
191
+ lines.push('Integ-test-runner spend: $0.0000 -- no integ-test-runner dispatch ran this sprint (no playbook found, or deploy never succeeded).');
192
+ } else if (typeof spent !== 'number') {
193
+ lines.push(`Integ-test-runner spend: not tracked -- ${integDispatchCount} dispatch(es) ran but the budget object did not expose spent() for this run.`);
194
+ } else {
195
+ const integSpend = typeof integTestRunnerStats.spend === 'number' ? integTestRunnerStats.spend : 0;
196
+ lines.push(`Integ-test-runner spend: $${integSpend.toFixed(4)} across ${integDispatchCount} dispatch(es) this sprint (a subset of the tracked spend above, broken out of overhead/doer/reviewer).`);
197
+ }
198
+ // Report the SOURCE of each priced dispatch's cost -- real per-member
199
+ // rates vs. pricing.mjs's tier-band fallback -- so the figures above are
200
+ // not read as uniformly exact.
201
+ const summary = budget && typeof budget.pricingSummary === 'function' ? budget.pricingSummary() : null;
202
+ if (summary) {
203
+ const { real, fallback } = summary;
204
+ if (real === 0 && fallback === 0) {
205
+ lines.push('Pricing source: no dispatch was priced this run.');
206
+ } else if (real > 0 && fallback === 0) {
207
+ lines.push(`Pricing source: all ${real} priced dispatch(es) used real per-member rates (get_member_model_pricing).`);
208
+ } else if (real === 0 && fallback > 0) {
209
+ lines.push(`Pricing source: all ${fallback} priced dispatch(es) used the tier-band/concrete-model fallback estimate (real per-member pricing was unavailable) -- see pricing.mjs.`);
210
+ } else {
211
+ lines.push(`Pricing source: mixed -- ${real} dispatch(es) priced via real per-member rates, ${fallback} via the tier-band/concrete-model fallback estimate.`);
212
+ }
213
+ }
214
+ lines.push(
215
+ 'Note: dispatches using an unpriced model id are not reflected above (see N10, feedback-reassessment.md) -- '
216
+ + 'this figure is a lower bound on actual spend, not a complete total, and is reported honestly rather than fabricated.'
217
+ );
218
+ return lines.join('\n');
219
+ }
220
+
221
+ /**
222
+ * Computes the collision-resistant filesystem slug used for
223
+ * `docs/sprint-analysis-<slug>.md`, the harvester's `analysisArtifactFile`
224
+ * input.
225
+ *
226
+ * Replacing separators alone is not collision-free: two branches differing
227
+ * only in a `/` versus a pre-existing `-` at the same position (e.g.
228
+ * `feat/fleet-reorg` and `feat-fleet-reorg`) would collapse to the same slug
229
+ * and clobber each other's artifact. Appending a short hash of the RAW branch
230
+ * name disambiguates them while staying deterministic per branch, so reruns
231
+ * still produce the same slug.
232
+ * @param {string} branch
233
+ * @returns {string}
234
+ */
235
+ export function computeBranchSlug(branch) {
236
+ const humanReadablePrefix = branch.replace(/[\\/]+/g, '-');
237
+ const disambiguatingHash = createHash('sha256').update(branch).digest('hex').slice(0, 8);
238
+ return `${humanReadablePrefix}-${disambiguatingHash}`;
239
+ }
@@ -0,0 +1,163 @@
1
+ import { ApraFleet } from '@apralabs/apra-fleet-client';
2
+ import { resolveMemberTarget } from './member-target.mjs';
3
+ import { createMemberVcsProviderResolver } from './vcs-auth.mjs';
4
+
5
+ // =============================================================================
6
+ // PER-SPRINT RESOLVED STATE (apra-fleet-3swo.6.1).
7
+ //
8
+ // One explicit object, created ONCE at sprint start (runSprintCycle) and
9
+ // threaded into every site that used to re-derive the same two things per
10
+ // call:
11
+ //
12
+ // 1. the fleet MCP client used to resolve a member's registered shell for
13
+ // the dolt-settle call sites. runner.js's `resolveSettleShell` built a
14
+ // brand new `ApraFleet({ callTool })` on EVERY invocation, at seven call
15
+ // sites, several of them per dispatch -- a fresh wrapper object per
16
+ // settle-shell resolution for the whole sprint. The wrapper is pure
17
+ // transport plumbing over the injected `callTool`, so exactly one is
18
+ // needed per sprint.
19
+ // 2. the per-member VCS provider resolver
20
+ // (`createMemberVcsProviderResolver`). This one was ALREADY constructed
21
+ // once per sprint inside runSprintCycle and already carries its own
22
+ // per-member Map cache; this module RELOCATES that single construction
23
+ // so the phase modules Phase 4 slices out of runSprintCycle receive it
24
+ // through sprint state instead of closing over a runSprintCycle local.
25
+ // It is deliberately NOT first-time caching, and no phase module may
26
+ // construct a second resolver of its own -- there must stay exactly one
27
+ // construction site in this directory (pinned by
28
+ // test/sprint-state.test.mjs).
29
+ //
30
+ // WHAT THIS MODULE DELIBERATELY DOES *NOT* CACHE -- READ BEFORE ADDING A MAP.
31
+ //
32
+ // The resolved { os, shell } pair is NOT memoized here, per member or
33
+ // otherwise. member-target.mjs owns that cache and deliberately caches ONLY a
34
+ // genuine member_detail-derived result: a member that was asleep, flaky over
35
+ // SSH or hit an MCP hiccup degrades to { os: 'linux', shell: '' } UNCACHED, so
36
+ // the next call re-resolves it instead of pinning it to POSIX command
37
+ // construction for the rest of the runner process (the auth-retry credential
38
+ // read at raiseVcsPrForMember depends on exactly that recovery --
39
+ // apra-fleet-ot2z.13).
40
+ //
41
+ // A sprint-state object that resolved every member once at sprint start and
42
+ // froze whatever it got would cache that fallback BY CONSTRUCTION and silently
43
+ // undo it. So this module holds the CLIENT (sprint-lifetime, cheap, stateless)
44
+ // and re-asks member-target.mjs on every resolution (which is a no-op for any
45
+ // member already resolved successfully). Do not "optimize" that into a shell
46
+ // cache here.
47
+ //
48
+ // CONTRACT: the resolved shell value set is unchanged for its three downstream
49
+ // consumers (dolt-settle.mjs, vcs-providers/azure-devops.mjs,
50
+ // vcs-providers/shell-helpers.mjs) -- 'gitbash', 'pwsh7', 'powershell5' or the
51
+ // empty string. Sites with no `callTool` wired (mock-sprint scenarios with no
52
+ // MCP client) keep the pre-shell-aware default of the empty string, exactly as
53
+ // runner.js's guarded `resolveSettleShell` did.
54
+ // =============================================================================
55
+
56
+ /**
57
+ * Logged once per constructed sprint-scoped fleet client. Exported so a test
58
+ * can count constructions over a whole simulated sprint cycle from the run's
59
+ * logs without reaching into this module's internals.
60
+ */
61
+ export const SPRINT_STATE_CLIENT_CONSTRUCTED_LOG =
62
+ '[sprint-state] constructed the sprint-scoped fleet client (one per sprint; every settle-shell resolution shares it).';
63
+
64
+ /**
65
+ * Prefix logged on every settle-shell resolution served through the
66
+ * sprint-scoped client. Exported for the same reason as the constant above:
67
+ * it is the observable that distinguishes "resolved through sprint state" from
68
+ * "re-derived at the call site".
69
+ */
70
+ export const SPRINT_STATE_SETTLE_SHELL_LOG_PREFIX = '[sprint-state] settle shell for member';
71
+
72
+ // callTool -> the single ApraFleet wrapper built over it. Keyed by the
73
+ // injected callTool function identity (which a sprint has exactly one of, from
74
+ // bin/cli.mjs's connected MCP client), so the call sites that receive only
75
+ // `args` -- syncMemberAfterOrdered, reached from git-sync.mjs's withGitSync
76
+ // teardown, which has no sprint-state to thread -- share the SAME client as
77
+ // the sprint-state object rather than reintroducing a per-call construction.
78
+ // A WeakMap so a finished sprint's callTool (and its client) stay collectable.
79
+ let fleetApiByCallTool = new WeakMap();
80
+
81
+ /**
82
+ * Test seam: the client memo is process-lifetime state keyed by function
83
+ * identity, so a test that counts constructions must be able to drop it.
84
+ */
85
+ export function clearSprintStateClientCache() {
86
+ fleetApiByCallTool = new WeakMap();
87
+ }
88
+
89
+ /**
90
+ * The one fleet client per `callTool`. Returns null when no callTool is wired
91
+ * (no MCP client -- nothing to build a client over), which every caller treats
92
+ * as "keep the pre-shell-aware default".
93
+ *
94
+ * @param {{ callTool?: Function, log?: Function, createFleetApi?: (opts: object) => object }} opts
95
+ * `createFleetApi` is an injectable construction seam (defaults to
96
+ * `new ApraFleet(...)`) so a test can COUNT constructions -- the property
97
+ * this hoist creates is unobservable through callTool alone, since building
98
+ * the wrapper makes no MCP call.
99
+ * @returns {object|null}
100
+ */
101
+ export function sprintScopedFleetApi({ callTool, log = () => {}, createFleetApi } = {}) {
102
+ if (typeof callTool !== 'function') return null;
103
+ const cached = fleetApiByCallTool.get(callTool);
104
+ if (cached) return cached;
105
+ const construct = typeof createFleetApi === 'function' ? createFleetApi : (opts) => new ApraFleet(opts);
106
+ const fleetApi = construct({ callTool });
107
+ fleetApiByCallTool.set(callTool, fleetApi);
108
+ log(SPRINT_STATE_CLIENT_CONSTRUCTED_LOG);
109
+ return fleetApi;
110
+ }
111
+
112
+ /**
113
+ * Resolves `member`'s registered shell through an already-built client. No
114
+ * memoization here on purpose (see this file's header): member-target.mjs is
115
+ * the single owner of the { os, shell } cache and of the deliberately
116
+ * UNCACHED degrade, so a transiently-unreachable member is re-resolved on the
117
+ * next call.
118
+ *
119
+ * @param {{ fleetApi?: object|null, member: string, log?: Function }} opts
120
+ * @returns {Promise<string>} 'gitbash' | 'pwsh7' | 'powershell5' | ''
121
+ */
122
+ export async function resolveSettleShellWith({ fleetApi, member, log = () => {} }) {
123
+ if (!fleetApi) return '';
124
+ const target = await resolveMemberTarget({ fleetApi, member, log });
125
+ log(`${SPRINT_STATE_SETTLE_SHELL_LOG_PREFIX} '${member}' resolved to '${target.shell}' through the sprint-scoped fleet client.`);
126
+ return target.shell;
127
+ }
128
+
129
+ /**
130
+ * Builds the sprint's resolved state. Called exactly ONCE per sprint, at the
131
+ * top of runSprintCycle, and threaded from there -- never rebuilt per phase or
132
+ * per call site.
133
+ *
134
+ * @param {{ callTool?: Function, log?: Function, createFleetApi?: (opts: object) => object }} opts
135
+ * @returns {{
136
+ * callTool: Function|undefined,
137
+ * fleetApi: object|null,
138
+ * resolveMemberProvider: ((member: string) => Promise<string|undefined>)|undefined,
139
+ * resolveSettleShell: (opts: { member: string, log?: Function }) => Promise<string>,
140
+ * }}
141
+ */
142
+ export function createSprintState({ callTool, log = () => {}, createFleetApi } = {}) {
143
+ const active = typeof callTool === 'function';
144
+ const fleetApi = active ? sprintScopedFleetApi({ callTool, log, createFleetApi }) : null;
145
+ // The RELOCATED single construction (see this file's header, point 2).
146
+ // Undefined when no callTool is wired, which is the pre-existing tier-3
147
+ // behavior at runSprintCycle's old construction site: every runGitStep
148
+ // falls back to the default provider chain. A provider that fails to
149
+ // resolve still degrades to that same default chain with a logged
150
+ // non-fatal message and no throw, and an unresolvable member is still
151
+ // cached as undefined exactly once -- all of that lives in
152
+ // createMemberVcsProviderResolver and is unchanged by the relocation.
153
+ const resolveMemberProvider = active ? createMemberVcsProviderResolver({ callTool, log }) : undefined;
154
+
155
+ return {
156
+ callTool: active ? callTool : undefined,
157
+ fleetApi,
158
+ resolveMemberProvider,
159
+ resolveSettleShell({ member, log: callLog = log } = {}) {
160
+ return resolveSettleShellWith({ fleetApi, member, log: callLog });
161
+ },
162
+ };
163
+ }
@@ -0,0 +1,234 @@
1
+ import fs from 'fs';
2
+ import path from 'path';
3
+ import { isInsideSameLineString, skipStringLiteral, maskComments, canStartRegex, skipRegexLiteral } from './dispatch-safety-guard.mjs';
4
+ import { unbracketedPushModulePaths, UNBRACKETED_PUSH_EXEMPT } from './guarded-modules.mjs';
5
+
6
+ // =============================================================================
7
+ // apra-fleet-3swo.4.2 -- unbracketed-push guard checker.
8
+ //
9
+ // Invariant under test: NO scanned module may issue a bare, real call site of
10
+ // doltPushAfter(), syncMemberAfter(), DoltSync.syncBefore() or
11
+ // DoltSync.syncAfter() -- the four raw sync/push primitives -- outside the
12
+ // two structurally-sanctioned wrapper functions (SANCTIONED_WRAPPER_FUNCTIONS
13
+ // below) that are themselves only ever reached from inside an already-open
14
+ // sync bracket (git-sync.mjs's withGitSync() calls syncMemberAfterOrdered();
15
+ // every runner.js call site of verifyDoerStreakClosed() wraps it in
16
+ // gitSync.withOpenSyncBracket()). Every other caller must route through one
17
+ // of createGitSync()'s bracketed entry points (withGitSync,
18
+ // syncBeadsBefore/After, pushBeadsAfter, pushGitAfter) instead of reaching
19
+ // for a primitive directly -- a bare call is exactly the kind of hole
20
+ // apra-fleet-3swo.4.1 closed for the two sites the epic named, and this scan
21
+ // is the regression lock that keeps a future one from reopening either by
22
+ // construction or by adding a NEW hand-rolled call site.
23
+ //
24
+ // MODULE-LIST GENERALIZATION, mirroring dispatch-safety-guard.mjs /
25
+ // dolt-literal-guard.mjs: this guard reads the SHARED guarded-module list
26
+ // (./guarded-modules.mjs) rather than a single hard-coded file, so a bare
27
+ // call that moves out of runner.js into a newly extracted module stays
28
+ // covered. git-sync.mjs is exempted via UNBRACKETED_PUSH_EXEMPT -- it is the
29
+ // ONE module allowed to call these primitives directly, since that IS its
30
+ // bracketed-entry-point implementation (mirrors DOLT_LITERAL_EXEMPT's
31
+ // dolt-sync.mjs precedent for the sibling dolt-literal guard).
32
+ //
33
+ // PER-SITE, NOT PER-FILE: an earlier version of this scan required "exactly
34
+ // one sanctioned call" per whole file, keyed off a local variable name
35
+ // (`gPush = await syncMemberAfter(...)`). That broke on every module with
36
+ // ZERO calls to these primitives (a legitimate, common case once the guard
37
+ // scans the full module list, not just runner.js) and was brittle against an
38
+ // unrelated rename. This version flags each REAL call site individually,
39
+ // exempting only those whose containing function body is one of the two
40
+ // structurally-sanctioned wrappers -- meaningful for any module, including
41
+ // ones that never mention these primitives at all (zero call sites is not a
42
+ // violation).
43
+ // =============================================================================
44
+
45
+ /** The four raw sync/push primitives no module but git-sync.mjs may call bare. */
46
+ const SCANNED_PRIMITIVES = ['doltPushAfter', 'syncMemberAfter', 'DoltSync.syncBefore', 'DoltSync.syncAfter'];
47
+
48
+ /**
49
+ * Function names whose ENTIRE body is only ever reached through an
50
+ * already-open sync bracket, so a bare primitive call inside one is
51
+ * sanctioned:
52
+ * - syncMemberAfterOrdered: git-sync.mjs's withGitSync() is the only
53
+ * caller, and withGitSync() itself always runs inside
54
+ * brackets.withOpenSyncBracket(...).
55
+ * - verifyDoerStreakClosed: every call site in runner.js wraps it in
56
+ * gitSync.withOpenSyncBracket(() => verifyDoerStreakClosed(...)).
57
+ */
58
+ const SANCTIONED_WRAPPER_FUNCTIONS = ['syncMemberAfterOrdered', 'verifyDoerStreakClosed'];
59
+
60
+ /**
61
+ * Finds every real (non-comment, non-same-line-string, non-declaration) call
62
+ * site of `fnName(` in `src` (fnName may be dotted, e.g. `DoltSync.syncAfter`).
63
+ * Returns `{ index, line, lineText }` for each -- `index` is the character
64
+ * offset of the match, used to test containment inside a sanctioned wrapper's
65
+ * body range.
66
+ */
67
+ export function findRealCallSites(src, fnName) {
68
+ const escaped = fnName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
69
+ const callRe = new RegExp(`(?<![.\\w])${escaped}\\(`, 'g');
70
+ const sites = [];
71
+ let m;
72
+ while ((m = callRe.exec(src)) !== null) {
73
+ const lineStart = src.lastIndexOf('\n', m.index) + 1;
74
+ const lineEnd = src.indexOf('\n', m.index);
75
+ const lineNo = src.slice(0, m.index).split('\n').length;
76
+ const lineText = src.slice(lineStart, lineEnd === -1 ? src.length : lineEnd);
77
+ const trimmed = lineText.trim();
78
+ if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
79
+ if (/^(export\s+)?(async\s+)?function\b/.test(trimmed)) continue; // the function's own declaration
80
+ const col = m.index - lineStart;
81
+ if (isInsideSameLineString(lineText, col)) continue;
82
+ sites.push({ index: m.index, line: lineNo, lineText: trimmed });
83
+ }
84
+ return sites;
85
+ }
86
+
87
+ /**
88
+ * Returns the [start, end) character-offset range of `fnName`'s body --
89
+ * from its opening `{` through the matching closing `}` -- or `null` if no
90
+ * top-level `function fnName(` declaration is found. Tracks brace depth while
91
+ * skipping over string/template-literal contents and comments so a `{`/`}`
92
+ * embedded in a quoted value or a comment never disturbs the count.
93
+ *
94
+ * WHY THIS WALKS A maskComments()-MASKED COPY (apra-fleet-btj9.10): this used
95
+ * to re-implement its own inline comment-skip (`//`, `/*`) ahead of the
96
+ * quote-skip, the exact shape dispatch-safety-guard.mjs's maskComments() had
97
+ * before it learned to recognize regex literals. A regex literal containing
98
+ * a quote or apostrophe inside a SANCTIONED_WRAPPER_FUNCTIONS body (e.g.
99
+ * `const RE = /it's fine/;`) opened the same kind of phantom string that
100
+ * bug produced elsewhere: with no matching apostrophe later in the file, the
101
+ * "string" ran to end-of-file, so every subsequent `}` was read as string
102
+ * content and never closed the wrapper's body -- inflating its detected
103
+ * range to the WHOLE REST OF THE FILE and silently sanctioning every bare
104
+ * primitive call site after it (measured: a `doltPushAfter()` call in a
105
+ * later, unrelated function went unreported). Delegating to the same
106
+ * maskComments() the reference implementation (dispatch-safety-guard.mjs)
107
+ * uses closes this the same way for both call sites -- see that function's
108
+ * own header for the regex-literal handling.
109
+ *
110
+ * A SECOND, subtler instance of the same class of bug (also apra-fleet-
111
+ * btj9.10): maskComments() copies a regex literal's body through VERBATIM,
112
+ * so a quote embedded in one (e.g. `const RE = /it's fine/;`) is still
113
+ * sitting in the returned `masked` text. This function's own quote-skip
114
+ * below, walking that already-masked text a SECOND time, would otherwise
115
+ * re-discover that same apostrophe and misread it as opening a real string
116
+ * -- exactly dispatch-safety-guard.mjs's extractBalancedCall() had to guard
117
+ * against for the identical reason. canStartRegex()/skipRegexLiteral() are
118
+ * reused here (not re-derived) so both walks treat a `/` as a regex start in
119
+ * exactly the same cases maskComments() itself does.
120
+ */
121
+ function findFunctionBodyRange(src, fnName) {
122
+ const declRe = new RegExp(`(?:export\\s+)?(?:async\\s+)?function\\s+${fnName}\\s*\\(`);
123
+ const decl = declRe.exec(src);
124
+ if (!decl) return null;
125
+
126
+ const masked = maskComments(src);
127
+
128
+ // Skip past the parameter list (balanced parens, so default values
129
+ // containing '(' -- e.g. `opts = {}` never does, but a future
130
+ // `(a = f())` shape would -- do not end the scan early).
131
+ let depth = 0;
132
+ let i = masked.indexOf('(', decl.index);
133
+ for (; i < masked.length; i++) {
134
+ const ch = masked[i];
135
+ if (ch === '(') depth++;
136
+ else if (ch === ')') {
137
+ depth--;
138
+ if (depth === 0) break;
139
+ } else if (ch === '/' && canStartRegex(masked, i)) {
140
+ const end = skipRegexLiteral(masked, i);
141
+ if (end !== -1) i = end;
142
+ } else if (ch === '"' || ch === "'" || ch === '`') {
143
+ i = skipStringLiteral(masked, i, ch);
144
+ }
145
+ }
146
+
147
+ const braceOpen = masked.indexOf('{', i);
148
+ if (braceOpen === -1) return null;
149
+
150
+ depth = 0;
151
+ for (let j = braceOpen; j < masked.length; j++) {
152
+ const ch = masked[j];
153
+ if (ch === '/' && canStartRegex(masked, j)) {
154
+ const end = skipRegexLiteral(masked, j);
155
+ if (end !== -1) j = end;
156
+ continue;
157
+ }
158
+ if (ch === '"' || ch === "'" || ch === '`') {
159
+ j = skipStringLiteral(masked, j, ch);
160
+ continue;
161
+ }
162
+ if (ch === '{') depth++;
163
+ else if (ch === '}') {
164
+ depth--;
165
+ if (depth === 0) return [braceOpen, j];
166
+ }
167
+ }
168
+ return [braceOpen, masked.length - 1];
169
+ }
170
+
171
+ /**
172
+ * The mechanical scan itself: given a source string, returns every violation
173
+ * -- a real call site of one of SCANNED_PRIMITIVES that does NOT sit inside
174
+ * one of SANCTIONED_WRAPPER_FUNCTIONS' bodies. A module with zero call sites
175
+ * of these primitives reports zero violations (it simply never touches them
176
+ * -- not every module needs to).
177
+ */
178
+ export function findUnbracketedPushViolations(src, fileLabel = 'source') {
179
+ const violations = [];
180
+ const wrapperRanges = SANCTIONED_WRAPPER_FUNCTIONS
181
+ .map((name) => findFunctionBodyRange(src, name))
182
+ .filter((range) => range !== null);
183
+
184
+ for (const primitive of SCANNED_PRIMITIVES) {
185
+ for (const site of findRealCallSites(src, primitive)) {
186
+ const sanctioned = wrapperRanges.some(([start, end]) => site.index > start && site.index < end);
187
+ if (sanctioned) continue;
188
+ violations.push(`${fileLabel}:${site.line} bare ${primitive}() call site outside any bracket: ${site.lineText}`);
189
+ }
190
+ }
191
+ return violations;
192
+ }
193
+
194
+ /**
195
+ * Reads and scans the source file at `filePath`, returning { violations }.
196
+ * The path-parameterized entry point -- callers pass a fixture path to prove
197
+ * the scan actually detects a violation without mutating real source.
198
+ */
199
+ export function checkUnbracketedPushPath(filePath) {
200
+ const src = fs.readFileSync(filePath, 'utf8');
201
+ const fileLabel = path.basename(filePath);
202
+ return { violations: findUnbracketedPushViolations(src, fileLabel) };
203
+ }
204
+
205
+ /**
206
+ * Aggregate entry point: scans every module in the SHARED guarded-module list
207
+ * (./guarded-modules.mjs), MINUS UNBRACKETED_PUSH_EXEMPT, and returns the
208
+ * union of their violations. Follows checkModules()/checkDoltLiteralModules()
209
+ * -- the dispatch-safety-guard.mjs / dolt-literal-guard.mjs reference
210
+ * implementations -- so a bare primitive call that moves out of runner.js
211
+ * into a newly extracted module stays covered instead of silently falling
212
+ * out of scan scope. Defines no list of its own.
213
+ *
214
+ * @param {string[]} [paths]
215
+ * @returns {{ violations: string[], files: string[], skipped: string[] }}
216
+ */
217
+ export function checkUnbracketedPushModules(paths = unbracketedPushModulePaths()) {
218
+ if (!Array.isArray(paths)) {
219
+ throw new TypeError('checkUnbracketedPushModules(paths): paths must be an array of file paths');
220
+ }
221
+ const violations = [];
222
+ const files = [];
223
+ const skipped = [];
224
+ for (const p of paths) {
225
+ const file = path.basename(p);
226
+ if (UNBRACKETED_PUSH_EXEMPT.includes(file)) {
227
+ skipped.push(file);
228
+ continue;
229
+ }
230
+ files.push(file);
231
+ violations.push(...checkUnbracketedPushPath(p).violations);
232
+ }
233
+ return { violations, files, skipped };
234
+ }