@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
@@ -37,6 +37,8 @@ import {
37
37
  getVcsProvider,
38
38
  resolveVcsProviderChain,
39
39
  resolveVcsProviderForHost,
40
+ resolveVcsAuthProviderForHost,
41
+ isAuthBackend,
40
42
  } from './vcs-providers/index.mjs';
41
43
 
42
44
  /**
@@ -70,9 +72,44 @@ function buildVcsCommand(action, params) {
70
72
  return builder(params);
71
73
  }
72
74
 
73
- /** Build a "raise a PR" command for the given provider. */
75
+ /**
76
+ * Deterministic hard cap on a PR description's length (apra-fleet PR-body
77
+ * length fix): Azure DevOps rejects/fails to raise a pull request whose
78
+ * description is too long, and the LLM role that drafts a PR description is
79
+ * only ever prompted to respect a limit -- it can and does ignore that
80
+ * guidance. This constant is the single source of truth for the cap, shared
81
+ * by every provider's create-pull-request path (buildCreatePrCommand below)
82
+ * rather than a magic number duplicated per provider.
83
+ * @type {number}
84
+ */
85
+ export const PR_DESCRIPTION_MAX_LENGTH = 3500;
86
+
87
+ /**
88
+ * Build a "raise a PR" command for the given provider.
89
+ *
90
+ * Enforces PR_DESCRIPTION_MAX_LENGTH on `params.body` DETERMINISTICALLY,
91
+ * regardless of provider (GitHub, Azure DevOps, ...) and regardless of
92
+ * whether the LLM that drafted the description obeyed the prompt guidance to
93
+ * stay under the limit. A body over the limit is truncated to exactly its
94
+ * first PR_DESCRIPTION_MAX_LENGTH characters before it reaches the provider's
95
+ * own command builder, so a PR can always be raised.
96
+ *
97
+ * This module stays pure (no I/O, no logging of its own -- see the header
98
+ * doc): a truncation is reported back to the caller as the returned
99
+ * `descriptionTruncated` field ({ originalLength, maxLength }, or `null` when
100
+ * no truncation occurred) so the caller (runner.js's raiseVcsPrForMember) can
101
+ * log/emit the warning through its own logging convention.
102
+ */
74
103
  export function buildCreatePrCommand(params) {
75
- return buildVcsCommand('create-pull-request', params);
104
+ const { body } = params || {};
105
+ let effectiveBody = body;
106
+ let descriptionTruncated = null;
107
+ if (typeof body === 'string' && body.length > PR_DESCRIPTION_MAX_LENGTH) {
108
+ descriptionTruncated = { originalLength: body.length, maxLength: PR_DESCRIPTION_MAX_LENGTH };
109
+ effectiveBody = body.slice(0, PR_DESCRIPTION_MAX_LENGTH);
110
+ }
111
+ const built = buildVcsCommand('create-pull-request', { ...params, body: effectiveBody });
112
+ return descriptionTruncated ? { ...built, descriptionTruncated } : { ...built, descriptionTruncated: null };
76
113
  }
77
114
 
78
115
  // ---------------------------------------------------------------------------
@@ -117,6 +154,21 @@ export function buildCreatePrCommand(params) {
117
154
  * @param {{ fleetApi: { memberDetail: (opts: { member_name: string, format?: string }) => Promise<any> } }} opts
118
155
  * @returns {Promise<{ provider: string, authMode: string|null }>}
119
156
  */
157
+ /**
158
+ * The `code` resolveProvider() stamps on the ONE failure that means "this
159
+ * member simply has no usable registered VCS provider" -- as opposed to a
160
+ * member_detail RPC failure, an unresolvable member name, or a malformed
161
+ * response, all of which resolveProvider() also throws for.
162
+ *
163
+ * A caller that wants to self-heal ONLY that case (runner.js's dispatch-time
164
+ * VCS-provider fallback) must be able to tell them apart: applying a
165
+ * git-remote-derived guess after a network blip would paper over a real
166
+ * failure with a possibly-wrong provider. Matching on the message text would
167
+ * make that wording load-bearing, so the signal is a stable property instead.
168
+ * @type {string}
169
+ */
170
+ export const VCS_NO_REGISTERED_PROVIDER = 'VCS_NO_REGISTERED_PROVIDER';
171
+
120
172
  export async function resolveProvider(member, { fleetApi } = {}) {
121
173
  if (!fleetApi || typeof fleetApi.memberDetail !== 'function') {
122
174
  throw new Error(`ERROR: VCSModule: resolveProvider requires an injected fleetApi.memberDetail() -- cannot resolve a VCS provider for member '${member}' without one.`);
@@ -149,7 +201,12 @@ export async function resolveProvider(member, { fleetApi } = {}) {
149
201
 
150
202
  const provider = parsed && typeof parsed.vcsProvider === 'string' ? parsed.vcsProvider : null;
151
203
  if (!provider || !known.includes(provider)) {
152
- throw new Error(`ERROR: VCSModule: resolveProvider: member '${member}' has no registered VCS provider (vcsProvider: ${provider ? `"${provider}"` : '(absent)'}) -- known providers: ${known.join(', ')}. Provision one via provision_vcs_auth with an explicit 'provider' before relying on resolveProvider.`);
204
+ // shell-guard-allow: nested backtick template (${provider ? `"${provider}"` : ...}) is JS interpolation resolved before this Error is thrown, never dispatched as a command string -- shell-command-guard's segment tracker mis-classifies the nested backtick as surviving expansion.
205
+ const err = new Error(`ERROR: VCSModule: resolveProvider: member '${member}' has no registered VCS provider (vcsProvider: ${provider ? `"${provider}"` : '(absent)'}) -- known providers: ${known.join(', ')}. Provision one via provision_vcs_auth with an explicit 'provider' before relying on resolveProvider.`);
206
+ // See VCS_NO_REGISTERED_PROVIDER above: this is the only failure a
207
+ // caller may self-heal from, so it is the only one that carries a code.
208
+ err.code = VCS_NO_REGISTERED_PROVIDER;
209
+ throw err;
153
210
  }
154
211
 
155
212
  const impl = getVcsProvider(provider);
@@ -197,6 +254,19 @@ export function buildCommentCommand(params) {
197
254
  // the least dangerous to under-match. A provider may override the order with
198
255
  // its own `precedence` array (dolt's classifier, for example, promotes
199
256
  // no-remote to first) without any change here.
257
+ //
258
+ // PERMISSION SCOPE (a REFINEMENT of AUTH_DENIED, not a new kind). A provider
259
+ // may declare `permissionScope.rules` for the texts that mean "the identity
260
+ // was understood and the PRINCIPAL lacks the granted permission" (see
261
+ // ./vcs-providers/index.mjs's descriptor contract and ./vcs-providers/
262
+ // github.mjs's workflow-file refusal). Those rules are checked BEFORE the
263
+ // precedence loop and their match is the verdict outright -- because such a
264
+ // refusal typically arrives wrapped in the host's generic rejection tail,
265
+ // which a higher-precedence kind (DIVERGED) already claims. The match also
266
+ // travels on the result as `permissionScope: true`, which is what lets the
267
+ // self-heal gate (git-topology.mjs's runGitStep) tell "re-minting cannot
268
+ // possibly help" apart from every other AUTH_DENIED, WITHOUT re-reading
269
+ // stderr at the call site.
200
270
 
201
271
  const KIND_PRECEDENCE = Object.freeze([
202
272
  VCS_FAILURE_KINDS.DIVERGED,
@@ -227,30 +297,76 @@ const KIND_PRECEDENCE = Object.freeze([
227
297
  * @param {{ provider?: string }} [opts] - provider selects the rule chain;
228
298
  * defaults to DEFAULT_VCS_PROVIDER ('github'), which reproduces runner.js's
229
299
  * full auth pattern set exactly.
230
- * @returns {{ kind: string, providerCode: string|null, retryable: boolean, raw: string }}
231
- * `kind` is the ONLY field control flow may branch on. `providerCode` is the
300
+ * @returns {{ kind: string, providerCode: string|null, retryable: boolean, permissionScope: boolean, operatorReferral: string|null, raw: string }}
301
+ * `kind` is the ONLY field control flow may branch on, with ONE declared
302
+ * exception: `permissionScope` (see below), which is a REFINEMENT of
303
+ * AUTH_DENIED, not a parallel vocabulary. `providerCode` is the
232
304
  * provider-specific token (e.g. an HTTP status, or an Azure DevOps
233
- * 'TF401019') carried as a DIAGNOSTIC detail. `raw` is the input, normalized
234
- * to a string, so a caller can log the evidence behind the verdict.
305
+ * 'TF401019') carried as a DIAGNOSTIC detail. `permissionScope` is true when
306
+ * a provider's `permissionScope.rules` matched: the identity was understood
307
+ * and the PRINCIPAL lacks the granted permission, so re-minting the same
308
+ * credential cannot help and the caller must NOT self-heal or retry.
309
+ * `operatorReferral` is the provider's own operator-facing remedy text for
310
+ * that case (null otherwise), so a shared caller can surface WHICH resource
311
+ * and WHICH missing permission without carrying a vendor wording itself.
312
+ * `raw` is the input, normalized to a string, so a caller can log the
313
+ * evidence behind the verdict.
235
314
  */
236
315
  export function classifyFailure(rawStderr, opts = {}) {
237
316
  const raw = String(rawStderr == null ? '' : rawStderr);
238
317
  const providerName = (opts && opts.provider) || DEFAULT_VCS_PROVIDER;
239
318
  const chain = resolveVcsProviderChain(providerName);
240
319
 
320
+ // PERMISSION-SCOPE RULES ARE CHECKED FIRST, ahead of KIND_PRECEDENCE.
321
+ //
322
+ // A host's permission refusal almost always arrives wrapped in that host's
323
+ // GENERIC rejection tail -- for git, "error: failed to push some refs to
324
+ // ...", which is emitted for EVERY rejected push and which GenericGitVCS
325
+ // matches as DIVERGED, the highest-precedence kind. Running the normal
326
+ // precedence loop first would therefore read a permission refusal as a
327
+ // divergence and send the caller into a doomed pull --rebase. The
328
+ // alternative -- reordering the provider's whole `precedence` array to put
329
+ // AUTH_DENIED first -- would silently re-read every OTHER ambiguous text
330
+ // for that provider too (a publickey refusal that also mentions a
331
+ // non-fast-forward, a GitLab "Access denied" that also carries git's
332
+ // generic "Authentication failed" tail), which is exactly the kind of
333
+ // collateral verdict change this taxonomy exists to prevent. So the
334
+ // override is per-RULE and opt-in per provider, not per provider-wide
335
+ // ordering. Most-derived provider first, same as the precedence loop.
336
+ let permissionScope = false;
337
+ let operatorReferral = null;
338
+ for (const provider of chain) {
339
+ const scope = provider.permissionScope;
340
+ if (!scope || !Array.isArray(scope.rules)) continue;
341
+ if (!scope.rules.some((re) => re.test(raw))) continue;
342
+ permissionScope = true;
343
+ if (typeof scope.describe === 'function') {
344
+ const described = scope.describe(raw);
345
+ operatorReferral = typeof described === 'string' && described.trim() ? described : null;
346
+ }
347
+ break;
348
+ }
349
+
241
350
  const precedence = chain.find((p) => Array.isArray(p.precedence))?.precedence || KIND_PRECEDENCE;
242
351
 
243
- let kind = VCS_FAILURE_KINDS.UNKNOWN;
244
- outer:
245
- for (const candidate of precedence) {
246
- // Most-derived provider first within each kind, so a provider can
247
- // sharpen a base verdict without editing the base.
248
- for (const provider of chain) {
249
- const patterns = (provider.rules && provider.rules[candidate]) || [];
250
- for (const re of patterns) {
251
- if (re.test(raw)) {
252
- kind = candidate;
253
- break outer;
352
+ // A permission-scope match IS the verdict: identity understood, principal
353
+ // refused (errors.mjs's AUTH_DENIED, word for word). The precedence loop
354
+ // is skipped entirely in that case -- running it could only re-read the
355
+ // host's generic rejection tail as something else.
356
+ let kind = VCS_FAILURE_KINDS.AUTH_DENIED;
357
+ if (!permissionScope) {
358
+ kind = VCS_FAILURE_KINDS.UNKNOWN;
359
+ outer:
360
+ for (const candidate of precedence) {
361
+ // Most-derived provider first within each kind, so a provider can
362
+ // sharpen a base verdict without editing the base.
363
+ for (const provider of chain) {
364
+ const patterns = (provider.rules && provider.rules[candidate]) || [];
365
+ for (const re of patterns) {
366
+ if (re.test(raw)) {
367
+ kind = candidate;
368
+ break outer;
369
+ }
254
370
  }
255
371
  }
256
372
  }
@@ -264,7 +380,7 @@ export function classifyFailure(rawStderr, opts = {}) {
264
380
  }
265
381
  }
266
382
 
267
- return { kind, providerCode, retryable: VCS_RETRYABLE_KINDS.has(kind), raw };
383
+ return { kind, providerCode, retryable: VCS_RETRYABLE_KINDS.has(kind), permissionScope, operatorReferral, raw };
268
384
  }
269
385
 
270
386
  /**
@@ -469,7 +585,12 @@ export const VCSModule = {
469
585
  listVcsProviders,
470
586
  listVcsAuthProviders,
471
587
  getVcsProvider,
588
+ resolveVcsProviderForHost,
589
+ resolveVcsAuthProviderForHost,
590
+ isAuthBackend,
591
+ VCS_NO_REGISTERED_PROVIDER,
472
592
  DEFAULT_VCS_PROVIDER,
593
+ PR_DESCRIPTION_MAX_LENGTH,
473
594
  };
474
595
 
475
596
  export {
@@ -481,6 +602,19 @@ export {
481
602
  listVcsProviders,
482
603
  listVcsAuthProviders,
483
604
  getVcsProvider,
605
+ // apra-fleet-5oo: re-exported so runner.js can ask "which registered
606
+ // provider claims this remote host?" without reaching past this module
607
+ // into ./vcs-providers/index.mjs directly -- same seam every other
608
+ // provider-registry helper above is reached through.
609
+ resolveVcsProviderForHost,
610
+ // apra-fleet-5oo review fix: the credential-provisioning sibling of the
611
+ // above (anchored host matching, auth backends only), plus the predicate
612
+ // that defines "auth backend" -- reached through this same seam rather
613
+ // than runner.js reaching past it into ./vcs-providers/index.mjs.
614
+ resolveVcsAuthProviderForHost,
615
+ isAuthBackend,
616
+ // VCS_NO_REGISTERED_PROVIDER is already exported at its `export const`
617
+ // declaration above -- listing it again here is a duplicate-export error.
484
618
  };
485
619
 
486
620
  export default VCSModule;
@@ -301,9 +301,29 @@ function parseRepoRef(remoteUrl) {
301
301
  * default is used. */
302
302
  const DEFAULT_PAT_SECRET = 'azdevops_pat';
303
303
 
304
- /** The canonical remote shape parseRepoRef() expects, quoted into every
305
- * operator-facing remedy this module produces (see `repoRefHint` below). */
306
- const REPO_REF_HINT = 'https://dev.azure.com/ORG/PROJECT/_git/REPO';
304
+ /** The remote shapes parseRepoRef() expects, quoted into every
305
+ * operator-facing remedy this module produces (see `repoRefHint` below):
306
+ * the modern host an operator copies out of the "Clone" dialog and the
307
+ * legacy per-org host older projects still live on. */
308
+ const REPO_REF_HINT = 'https://dev.azure.com/ORG/PROJECT/_git/REPO or https://ORG.visualstudio.com/[DefaultCollection/]PROJECT/_git/REPO';
309
+
310
+ /** Classify a remote URL parseRepoRef() accepts by the HOST it lands on:
311
+ * which transport git will use (a PAT only applies to https; ssh uses the
312
+ * member's key) and whether it is the legacy `<org>.visualstudio.com` host,
313
+ * which needs the credential bound to that host rather than dev.azure.com.
314
+ * Returns null for anything parseRepoRef() rejects. */
315
+ function classifyRemote(remoteUrl) {
316
+ if (typeof remoteUrl !== 'string' || !remoteUrl.trim()) return null;
317
+ const split = splitRemote(remoteUrl.trim());
318
+ if (!split || !matchesHost(split.host)) return null;
319
+ const scheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(remoteUrl.trim())
320
+ ? remoteUrl.trim().replace(/:\/\/.*$/, '').toLowerCase()
321
+ : 'ssh';
322
+ const transport = scheme === 'ssh' ? 'ssh' : 'https';
323
+ const legacy = /visualstudio\.com$/i.test(split.host);
324
+ const sshHost = /^(?:ssh\.dev\.azure\.com|vs-ssh\.visualstudio\.com)$/i.test(split.host);
325
+ return { host: split.host, transport, legacy, legacyHttpsHost: legacy && !sshHost && transport === 'https' };
326
+ }
307
327
 
308
328
  /**
309
329
  * Build the provision_vcs_auth argument object for an Azure DevOps member
@@ -316,7 +336,7 @@ const REPO_REF_HINT = 'https://dev.azure.com/ORG/PROJECT/_git/REPO';
316
336
  * meaningless. Expressing that as a descriptor hook keeps the difference in
317
337
  * this file instead of adding a provider branch to the shared caller.
318
338
  *
319
- * SECRET TRANSPORT: the PAT is passed as a `{{secure.NAME}}` PLACEHOLDER, never
339
+ * SECRET TRANSPORT: the PAT is passed as a `{{secret.NAME}}` PLACEHOLDER, never
320
340
  * a value. Resolution happens hub-side inside the fleet server; the orchestrator
321
341
  * process that calls this hook never holds, logs or transports the plaintext,
322
342
  * and a remote member (which has no secret store of its own) never has to.
@@ -324,22 +344,43 @@ const REPO_REF_HINT = 'https://dev.azure.com/ORG/PROJECT/_git/REPO';
324
344
  * an unattended preflight/self-heal has no operator attached, and an
325
345
  * out-of-band prompt there would stall the sprint instead of failing it.
326
346
  *
347
+ * HOST BINDING: the server binds the PAT's git credential helper to the host
348
+ * named by `scope_url` (default dev.azure.com). git looks credentials up by
349
+ * the remote's OWN hostname, so a member whose remote is on the legacy
350
+ * `<org>.visualstudio.com` host gets `scope_url` set to that host here;
351
+ * otherwise the argument is omitted and the server default applies, which
352
+ * keeps the modern-host call byte-identical to what it was. An ssh remote
353
+ * cannot take a PAT at all: the PAT is still deployed (the REST
354
+ * pull-request call reads it), and `note` says that git push relies on the
355
+ * member's SSH key instead.
356
+ *
327
357
  * @param {{ base: object, repoRef: ({ org: string }|null|undefined),
328
- * availableSecrets: string[]|null, secretName?: string }} ctx
358
+ * availableSecrets: string[]|null, secretName?: string,
359
+ * remoteUrl?: string, remoteReadError?: string|null }} ctx
329
360
  * `base` is the shared argument object the caller would otherwise send;
330
361
  * `repoRef` is this provider's own parseRepoRef() output for the member's
331
362
  * remote; `availableSecrets` is the credential-store entry names the caller
332
363
  * observed (null when it could not be read -- then the check is skipped
333
364
  * rather than guessed, and a genuinely missing secret still fails loudly
334
- * server-side).
335
- * @returns {{ args: object }|{ error: string }}
365
+ * server-side). `remoteUrl` is the raw remote the caller read (used only to
366
+ * pick the credential host and to word the error precisely) and
367
+ * `remoteReadError` the reason it could not be read, when that is why
368
+ * `repoRef` is null -- a read failure is NOT a malformed remote and the
369
+ * error must not tell the operator to fix their URL.
370
+ * @returns {{ args: object, note?: string }|{ error: string }}
336
371
  */
337
372
  function buildProvisionArgs(ctx) {
338
- const { base = {}, repoRef, availableSecrets, secretName } = ctx || {};
373
+ const { base = {}, repoRef, availableSecrets, secretName, remoteUrl, remoteReadError } = ctx || {};
339
374
  const org = repoRef && typeof repoRef.org === 'string' ? repoRef.org.trim() : '';
340
375
  if (!org) {
376
+ const raw = typeof remoteUrl === 'string' ? remoteUrl.trim() : '';
377
+ const why = remoteReadError
378
+ ? `the member's git remote could not be read (${remoteReadError})`
379
+ : raw
380
+ ? `the member's git remote '${raw}' is not a recognized Azure DevOps repository URL`
381
+ : `no organization could be derived from the member's git remote`;
341
382
  return {
342
- error: `ERROR: cannot provision Azure DevOps auth for member '${base.member_name}': no organization could be derived from the member's git remote; expected a remote of the shape ${REPO_REF_HINT}`,
383
+ error: `ERROR: cannot provision Azure DevOps auth for member '${base.member_name}': ${why}; expected a remote of the shape ${REPO_REF_HINT}`,
343
384
  };
344
385
  }
345
386
 
@@ -350,19 +391,28 @@ function buildProvisionArgs(ctx) {
350
391
  };
351
392
  }
352
393
 
353
- return {
354
- args: {
355
- member_name: base.member_name,
356
- provider: base.provider,
357
- // Base org URL with no trailing path -- see auth-azdevops.md's
358
- // "Org URL must be base URL without trailing path" note and the
359
- // TF400813 troubleshooting row, which is what a wrong org URL
360
- // surfaces as.
361
- org_url: `https://dev.azure.com/${org}`,
362
- // Placeholder, NOT a value. See SECRET TRANSPORT above.
363
- pat: `{{secure.${name}}}`,
364
- },
394
+ const shape = classifyRemote(remoteUrl);
395
+ const args = {
396
+ member_name: base.member_name,
397
+ provider: base.provider,
398
+ // Base org URL with no trailing path -- see auth-azdevops.md's
399
+ // "Org URL must be base URL without trailing path" note and the
400
+ // TF400813 troubleshooting row, which is what a wrong org URL
401
+ // surfaces as. Always the MODERN host: the REST API serves every
402
+ // org there, legacy-hosted or not.
403
+ org_url: `https://dev.azure.com/${org}`,
404
+ // Placeholder, NOT a value. See SECRET TRANSPORT above.
405
+ pat: `{{secret.${name}}}`,
365
406
  };
407
+ if (shape && shape.legacyHttpsHost) {
408
+ // See HOST BINDING above: bind the credential helper to the legacy
409
+ // host the member actually pushes to.
410
+ args.scope_url = `https://${shape.host}`;
411
+ }
412
+ const note = shape && shape.transport === 'ssh'
413
+ ? `member '${base.member_name}' pushes over ssh (${shape.host}); the Azure DevOps PAT is deployed for REST pull-request calls only and git push authenticates with the member's own SSH key, which the fleet does not manage`
414
+ : undefined;
415
+ return note ? { args, note } : { args };
366
416
  }
367
417
 
368
418
  // ---------------------------------------------------------------------------
@@ -40,12 +40,40 @@ const AUTH_EXPIRED = [
40
40
  /Invalid or expired app password/i,
41
41
  ];
42
42
 
43
+ /** Bitbucket Cloud's own hosts, ANCHORED (never a substring test -- the same
44
+ * reasoning as ./azure-devops.mjs's HOST_RE, and unlike GitHub Enterprise
45
+ * Server which has no fixed domain):
46
+ * - bitbucket.org https and ssh remotes
47
+ * - www.bitbucket.org the www alias (bitbucket.org redirects it, and a
48
+ * remote copy-pasted from a browser address bar can
49
+ * carry it)
50
+ * - altssh.bitbucket.org the alternate-port ssh host
51
+ * A self-hosted Bitbucket Data Center install has an arbitrary domain and is
52
+ * deliberately left to GenericGitVCS's catch-all rather than guessed at.
53
+ *
54
+ * apra-fleet-5oo: declaring this makes resolveVcsProviderForHost() name
55
+ * 'bitbucket' for a Bitbucket remote, which is what lets runner.js's
56
+ * dispatch-time VCS-provider fallback detect it. Behaviour-neutral for
57
+ * VCSModule.capabilities(): this provider declares no capabilitiesForHost,
58
+ * and the caller's default (canOpenPullRequest:false) matches what
59
+ * GenericGitVCS returned for these hosts before.
60
+ *
61
+ * Kept character-for-character in step with
62
+ * src/utils/vcs-provider-detect.ts's BITBUCKET_HOST_RE -- the two halves of
63
+ * the same decision must never disagree about who owns a host. */
64
+ const HOST_RE = /^(?:www\.|altssh\.)?bitbucket\.org$/i;
65
+
66
+ function matchesHost(host) {
67
+ return typeof host === 'string' && HOST_RE.test(host.trim());
68
+ }
69
+
43
70
  export const BitbucketVCS = Object.freeze({
44
71
  name: 'bitbucket',
45
72
  extends: 'generic-git',
46
73
  rules: Object.freeze({
47
74
  [K.AUTH_EXPIRED]: AUTH_EXPIRED,
48
75
  }),
76
+ matchesHost,
49
77
  defaultAuthMode: null,
50
78
  builders: null,
51
79
  });
@@ -181,6 +181,101 @@ const AUTH_EXPIRED = [
181
181
  // self-heal. Widening the taxonomy is a real behavior change and belongs in its
182
182
  // own bead with its own tests, not smuggled in under a no-verdict-change
183
183
  // consolidation.
184
+ //
185
+ // The ONE exception, added deliberately and with its own tests: the
186
+ // workflow-file permission refusal below. It is not merely "unknown today" --
187
+ // it is actively MISREAD today (see the block comment on
188
+ // WORKFLOW_PERMISSION_REFUSAL), which is a different situation from the
189
+ // under-matched texts listed above.
190
+
191
+ // ---------------------------------------------------------------------------
192
+ // Workflow-file permission refusal (the permission-scope axis)
193
+ // ---------------------------------------------------------------------------
194
+ //
195
+ // git's stderr for a push that touches .github/workflows/** with a credential
196
+ // that was never granted the Workflows permission looks like:
197
+ //
198
+ // ! [remote rejected] feat/x -> feat/x (refusing to allow a GitHub App to
199
+ // create or update workflow .github/workflows/ci.yml without workflows
200
+ // permission)
201
+ // error: failed to push some refs to 'https://github.com/owner/repo.git'
202
+ //
203
+ // Two things about that text matter, and both are why this rule needs the
204
+ // `permissionScope` hook below rather than a plain entry in `rules`:
205
+ //
206
+ // 1. The trailing "error: failed to push some refs to ..." line is git's
207
+ // UNIVERSAL reaction to ANY rejected push -- a non-fast-forward, a
208
+ // protected-branch refusal, a hook rejection, this. GenericGitVCS's
209
+ // DIVERGED table matches it, and DIVERGED outranks both AUTH kinds in
210
+ // KIND_PRECEDENCE, so precedence alone reads this as a divergence and the
211
+ // caller answers a permission refusal with a doomed `pull --rebase`.
212
+ // 2. The identity was understood perfectly; the PRINCIPAL simply was never
213
+ // granted the permission. Re-minting the SAME credential (which is all the
214
+ // provision_vcs_auth self-heal does) produces a token with the SAME
215
+ // permission set and the SAME refusal, forever.
216
+ //
217
+ // So this is AUTH_DENIED ("identity understood, access refused" -- errors.mjs)
218
+ // and it must WIN over the DIVERGED tail, and it must NOT be self-healed. Both
219
+ // of those follow from declaring it under `permissionScope` (see
220
+ // ./index.mjs's descriptor contract); the SAME array is also listed under
221
+ // rules[AUTH_DENIED] so the kind is discoverable by pattern-table readers and
222
+ // by any caller that walks `rules` directly.
223
+ //
224
+ // Wordings: GitHub emits a different subject noun per credential type. The
225
+ // GitHub App and Personal Access Token wordings are the two the fleet can
226
+ // actually produce (fleet-minted installation tokens, and an operator-supplied
227
+ // PAT); the OAuth App wording is the same refusal from a credential type the
228
+ // fleet does not mint but a member may nonetheless be configured with, and
229
+ // leaving it out would silently return it to the DIVERGED misreading above.
230
+ // The trailing noun differs too ("without workflows permission" for an App,
231
+ // "without workflow scope" for a PAT/OAuth App), so the patterns stop at the
232
+ // stable "to create or update workflow" stem rather than pinning the tail.
233
+ const WORKFLOW_PERMISSION_REFUSAL = [
234
+ /refusing to allow a GitHub App to create or update workflow/i,
235
+ /refusing to allow a Personal Access Token to create or update workflow/i,
236
+ /refusing to allow an? OAuth App to create or update workflow/i,
237
+ ];
238
+
239
+ /** The operator referral for a workflow-permission refusal: WHICH workflow
240
+ * file(s) were refused, WHAT the credential is missing, and the remedy --
241
+ * stated as an operator action, never as "it will retry", because nothing
242
+ * here retries.
243
+ *
244
+ * Stateless: the /g regex is constructed fresh on every call (a hoisted /g
245
+ * regex would carry `lastIndex` between classifyFailure calls and make the
246
+ * same input describe differently on a second call -- see the PURITY note in
247
+ * this file's header and in ./generic-git.mjs).
248
+ *
249
+ * @param {string} raw - the raw stderr the refusal was classified from
250
+ * @returns {string} an ASCII operator-facing referral
251
+ */
252
+ function describeWorkflowPermissionRefusal(raw) {
253
+ const text = String(raw == null ? '' : raw);
254
+ const matched = text.match(/\.github\/workflows\/[A-Za-z0-9._/-]+/g) || [];
255
+ // Strip punctuation git/GitHub wraps the path in (a quote, a closing
256
+ // paren's neighbouring period, ...) and de-duplicate while preserving the
257
+ // order the refusal listed them in.
258
+ const paths = [...new Set(matched.map((p) => p.replace(/[.,'"]+$/, '')))];
259
+ const which = paths.length > 0
260
+ ? `workflow file(s) ${paths.join(', ')}`
261
+ : 'one or more files under .github/workflows/';
262
+ return (
263
+ `GitHub refused this push because the credential the member is pushing with was never granted the 'workflows' permission, ` +
264
+ `so it may not create or update ${which}. This is a permission-scope refusal, not a stale credential and not a divergence: ` +
265
+ `re-minting the same credential yields the same permission set and the same refusal, so no self-heal, no retry and no pull --rebase is attempted. ` +
266
+ 'OPERATOR REMEDY (required before this push can ever succeed): grant the fleet GitHub App the "Workflows" repository permission ' +
267
+ '(Read and write) in its App settings, accept the updated permission request on the repository installation, then re-register/re-provision ' +
268
+ 'the member with a git_access level that requests that permission. Until an operator does that, re-running the sprint will not help.'
269
+ );
270
+ }
271
+
272
+ /** The permission-scope axis for GitHub (see ./index.mjs's descriptor
273
+ * contract). Declared as the SAME array that rules[AUTH_DENIED] carries, so
274
+ * the two can never drift apart. */
275
+ const permissionScope = Object.freeze({
276
+ rules: Object.freeze(WORKFLOW_PERMISSION_REFUSAL),
277
+ describe: describeWorkflowPermissionRefusal,
278
+ });
184
279
 
185
280
  /** Best-effort GitHub provider code, purely DIAGNOSTIC: never branch on it --
186
281
  * branch on `kind`. Returns the HTTP status git/curl surfaced (e.g. '403'
@@ -215,6 +310,34 @@ function matchesHost(host) {
215
310
  return typeof host === 'string' && /github/i.test(host);
216
311
  }
217
312
 
313
+ /** github.com and its ssh/www aliases -- ANCHORED. Kept character-for-
314
+ * character in step with src/utils/vcs-provider-detect.ts's
315
+ * GITHUB_HOST_RE (the registration-time half of the same decision). */
316
+ const AUTH_HOST_RE = /^(?:www\.|ssh\.)?github\.com$/i;
317
+
318
+ /** Host-recognition for the CREDENTIAL-PROVISIONING axis
319
+ * (resolveVcsAuthProviderForHost() in ./index.mjs), deliberately NARROWER
320
+ * than matchesHost() above.
321
+ *
322
+ * matchesHost() is a substring test on purpose: it answers "can this host
323
+ * open a pull request?" for capabilities(), and a GitHub Enterprise Server
324
+ * install has no fixed domain, so the vendor name in the hostname is the
325
+ * only portable signal (pinned by test/vcs-capabilities-table.test.mjs).
326
+ * Answering YES there costs nothing -- the worst case is a PR attempt that
327
+ * fails.
328
+ *
329
+ * Auto-PROVISIONING is a different risk class entirely: it mints a real
330
+ * GitHub App push credential and points it at the host. A substring test
331
+ * would let a lookalike domain ("mygithubmirror.attacker.io",
332
+ * "github.com.evil.example") claim this provider and receive that
333
+ * credential -- exactly the leak src/utils/vcs-provider-detect.ts anchors
334
+ * against on the registration-time path. So GitHub Enterprise is NOT
335
+ * auto-detected for auth on either side: an operator registers a GHE
336
+ * member with an explicit `vcs_provider`. */
337
+ function matchesHostForAuth(host) {
338
+ return typeof host === 'string' && AUTH_HOST_RE.test(host.trim());
339
+ }
340
+
218
341
  /** Every host this provider matches can open a PR via the REST call
219
342
  * buildGitHubCreatePrCommand() builds -- github.com and GitHub Enterprise
220
343
  * Server alike speak the same `/repos/{owner}/{repo}/pulls` shape. */
@@ -227,9 +350,17 @@ export const GitHubVCS = Object.freeze({
227
350
  extends: 'generic-git',
228
351
  rules: Object.freeze({
229
352
  [K.AUTH_EXPIRED]: AUTH_EXPIRED,
353
+ // apra-fleet: the workflow-file permission refusal. AUTH_DENIED
354
+ // because the identity was understood and the PRINCIPAL lacks the
355
+ // permission -- see WORKFLOW_PERMISSION_REFUSAL above. The same array
356
+ // is declared under `permissionScope` below, which is what makes it
357
+ // outrank git's generic DIVERGED tail and skip the auth self-heal.
358
+ [K.AUTH_DENIED]: WORKFLOW_PERMISSION_REFUSAL,
230
359
  }),
360
+ permissionScope,
231
361
  extractProviderCode,
232
362
  matchesHost,
363
+ matchesHostForAuth,
233
364
  capabilitiesForHost,
234
365
  // apra-fleet-647.1.5.1: GitHub's own default auth mode (App, never PAT --
235
366
  // see vcs-module.mjs resolveProvider()'s header note on why this must stay