@apralabs/apra-fleet 0.4.1 → 0.4.2

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 (276) hide show
  1. package/README.md +16 -8
  2. package/dist/agents/backlog-groomer.md +17 -21
  3. package/dist/agents/ci-watcher.md +3 -0
  4. package/dist/agents/deployer.md +22 -44
  5. package/dist/agents/doer.md +131 -132
  6. package/dist/agents/harvester.md +20 -32
  7. package/dist/agents/integ-test-runner.md +81 -113
  8. package/dist/agents/kb-reconciler.md +31 -42
  9. package/dist/agents/plan-reviewer.md +32 -44
  10. package/dist/agents/planner.md +51 -63
  11. package/dist/agents/regression-test-runner.md +65 -80
  12. package/dist/agents/reviewer.md +56 -83
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  15. package/dist/cli/auth.d.ts.map +1 -1
  16. package/dist/cli/auth.js +1 -2
  17. package/dist/cli/auth.js.map +1 -1
  18. package/dist/cli/config.d.ts +3 -3
  19. package/dist/cli/config.d.ts.map +1 -1
  20. package/dist/cli/config.js +4 -13
  21. package/dist/cli/config.js.map +1 -1
  22. package/dist/cli/install.d.ts.map +1 -1
  23. package/dist/cli/install.js +5 -39
  24. package/dist/cli/install.js.map +1 -1
  25. package/dist/cli/register-member.js +1 -1
  26. package/dist/cli/start.d.ts.map +1 -1
  27. package/dist/cli/start.js +7 -0
  28. package/dist/cli/start.js.map +1 -1
  29. package/dist/cli/uninstall.d.ts.map +1 -1
  30. package/dist/cli/uninstall.js +5 -3
  31. package/dist/cli/uninstall.js.map +1 -1
  32. package/dist/cli/watch.d.ts +26 -3
  33. package/dist/cli/watch.d.ts.map +1 -1
  34. package/dist/cli/watch.js +41 -9
  35. package/dist/cli/watch.js.map +1 -1
  36. package/dist/os/git-bash-candidates.d.ts +35 -0
  37. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  38. package/dist/os/git-bash-candidates.js +46 -0
  39. package/dist/os/git-bash-candidates.js.map +1 -0
  40. package/dist/os/index.d.ts +13 -4
  41. package/dist/os/index.d.ts.map +1 -1
  42. package/dist/os/index.js +17 -2
  43. package/dist/os/index.js.map +1 -1
  44. package/dist/os/linux.js +1 -1
  45. package/dist/os/linux.js.map +1 -1
  46. package/dist/os/os-commands.d.ts +7 -0
  47. package/dist/os/os-commands.d.ts.map +1 -1
  48. package/dist/os/os-commands.js.map +1 -1
  49. package/dist/os/windows-gitbash.d.ts +93 -0
  50. package/dist/os/windows-gitbash.d.ts.map +1 -0
  51. package/dist/os/windows-gitbash.js +244 -0
  52. package/dist/os/windows-gitbash.js.map +1 -0
  53. package/dist/os/windows.d.ts.map +1 -1
  54. package/dist/os/windows.js +27 -5
  55. package/dist/os/windows.js.map +1 -1
  56. package/dist/providers/agy.d.ts +3 -2
  57. package/dist/providers/agy.d.ts.map +1 -1
  58. package/dist/providers/agy.js +11 -2
  59. package/dist/providers/agy.js.map +1 -1
  60. package/dist/providers/claude.d.ts +3 -2
  61. package/dist/providers/claude.d.ts.map +1 -1
  62. package/dist/providers/claude.js +22 -3
  63. package/dist/providers/claude.js.map +1 -1
  64. package/dist/providers/codex.d.ts +3 -2
  65. package/dist/providers/codex.d.ts.map +1 -1
  66. package/dist/providers/codex.js +5 -2
  67. package/dist/providers/codex.js.map +1 -1
  68. package/dist/providers/copilot.d.ts +3 -2
  69. package/dist/providers/copilot.d.ts.map +1 -1
  70. package/dist/providers/copilot.js +7 -2
  71. package/dist/providers/copilot.js.map +1 -1
  72. package/dist/providers/index.d.ts +0 -1
  73. package/dist/providers/index.d.ts.map +1 -1
  74. package/dist/providers/index.js +0 -3
  75. package/dist/providers/index.js.map +1 -1
  76. package/dist/providers/none.d.ts +3 -2
  77. package/dist/providers/none.d.ts.map +1 -1
  78. package/dist/providers/none.js +5 -2
  79. package/dist/providers/none.js.map +1 -1
  80. package/dist/providers/opencode.d.ts +3 -2
  81. package/dist/providers/opencode.d.ts.map +1 -1
  82. package/dist/providers/opencode.js +5 -2
  83. package/dist/providers/opencode.js.map +1 -1
  84. package/dist/providers/provider.d.ts +16 -7
  85. package/dist/providers/provider.d.ts.map +1 -1
  86. package/dist/providers/provider.js +2 -2
  87. package/dist/providers/provider.js.map +1 -1
  88. package/dist/services/agent-provisioner.js +2 -2
  89. package/dist/services/agent-provisioner.js.map +1 -1
  90. package/dist/services/cloud/activity.js +2 -2
  91. package/dist/services/cloud/activity.js.map +1 -1
  92. package/dist/services/context-admission.d.ts.map +1 -1
  93. package/dist/services/context-admission.js +9 -7
  94. package/dist/services/context-admission.js.map +1 -1
  95. package/dist/services/credential-cleanup.d.ts.map +1 -1
  96. package/dist/services/credential-cleanup.js +22 -3
  97. package/dist/services/credential-cleanup.js.map +1 -1
  98. package/dist/services/member-home.d.ts +1 -1
  99. package/dist/services/member-home.d.ts.map +1 -1
  100. package/dist/services/member-home.js +15 -12
  101. package/dist/services/member-home.js.map +1 -1
  102. package/dist/services/model-pricing.d.ts.map +1 -1
  103. package/dist/services/model-pricing.js +0 -5
  104. package/dist/services/model-pricing.js.map +1 -1
  105. package/dist/services/orphan-recovery.d.ts +6 -3
  106. package/dist/services/orphan-recovery.d.ts.map +1 -1
  107. package/dist/services/orphan-recovery.js +17 -14
  108. package/dist/services/orphan-recovery.js.map +1 -1
  109. package/dist/services/preflight-check.js +2 -2
  110. package/dist/services/preflight-check.js.map +1 -1
  111. package/dist/services/shell-probe.d.ts +131 -0
  112. package/dist/services/shell-probe.d.ts.map +1 -0
  113. package/dist/services/shell-probe.js +210 -0
  114. package/dist/services/shell-probe.js.map +1 -0
  115. package/dist/services/singleton.d.ts +2 -0
  116. package/dist/services/singleton.d.ts.map +1 -1
  117. package/dist/services/singleton.js +1 -1
  118. package/dist/services/singleton.js.map +1 -1
  119. package/dist/services/ssh.js +2 -2
  120. package/dist/services/ssh.js.map +1 -1
  121. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  122. package/dist/services/stall/find-log-file.js +22 -16
  123. package/dist/services/stall/find-log-file.js.map +1 -1
  124. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  125. package/dist/services/stall/read-log-tail.js +6 -5
  126. package/dist/services/stall/read-log-tail.js.map +1 -1
  127. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  128. package/dist/services/stall/stall-poller.js +35 -42
  129. package/dist/services/stall/stall-poller.js.map +1 -1
  130. package/dist/services/strategy.d.ts +9 -0
  131. package/dist/services/strategy.d.ts.map +1 -1
  132. package/dist/services/strategy.js +40 -6
  133. package/dist/services/strategy.js.map +1 -1
  134. package/dist/services/user-config.js +1 -1
  135. package/dist/services/user-config.js.map +1 -1
  136. package/dist/services/vcs/azure-devops.d.ts +1 -1
  137. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  138. package/dist/services/vcs/azure-devops.js +105 -10
  139. package/dist/services/vcs/azure-devops.js.map +1 -1
  140. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  141. package/dist/services/vcs/bitbucket.js +16 -0
  142. package/dist/services/vcs/bitbucket.js.map +1 -1
  143. package/dist/services/vcs/github.d.ts.map +1 -1
  144. package/dist/services/vcs/github.js +24 -0
  145. package/dist/services/vcs/github.js.map +1 -1
  146. package/dist/services/vcs/types.d.ts +123 -2
  147. package/dist/services/vcs/types.d.ts.map +1 -1
  148. package/dist/skills/fleet-sprint-cli/SKILL.md +2 -1
  149. package/dist/skills/pm/SKILL.md +0 -1
  150. package/dist/skills/pm/cost.md +0 -1
  151. package/dist/skills/pm/fleet-addendum.md +0 -1
  152. package/dist/tools/check-status.js +3 -3
  153. package/dist/tools/check-status.js.map +1 -1
  154. package/dist/tools/cloud-control.js +2 -2
  155. package/dist/tools/cloud-control.js.map +1 -1
  156. package/dist/tools/compose-permissions.d.ts.map +1 -1
  157. package/dist/tools/compose-permissions.js +37 -24
  158. package/dist/tools/compose-permissions.js.map +1 -1
  159. package/dist/tools/execute-command.d.ts.map +1 -1
  160. package/dist/tools/execute-command.js +28 -12
  161. package/dist/tools/execute-command.js.map +1 -1
  162. package/dist/tools/execute-prompt.d.ts.map +1 -1
  163. package/dist/tools/execute-prompt.js +55 -18
  164. package/dist/tools/execute-prompt.js.map +1 -1
  165. package/dist/tools/list-members.d.ts.map +1 -1
  166. package/dist/tools/list-members.js +6 -2
  167. package/dist/tools/list-members.js.map +1 -1
  168. package/dist/tools/member-detail.d.ts.map +1 -1
  169. package/dist/tools/member-detail.js +5 -3
  170. package/dist/tools/member-detail.js.map +1 -1
  171. package/dist/tools/member-reservation.d.ts.map +1 -1
  172. package/dist/tools/member-reservation.js +13 -1
  173. package/dist/tools/member-reservation.js.map +1 -1
  174. package/dist/tools/monitor-task.d.ts.map +1 -1
  175. package/dist/tools/monitor-task.js +17 -2
  176. package/dist/tools/monitor-task.js.map +1 -1
  177. package/dist/tools/provision-auth.js +5 -5
  178. package/dist/tools/provision-auth.js.map +1 -1
  179. package/dist/tools/provision-vcs-auth.d.ts +5 -2
  180. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  181. package/dist/tools/provision-vcs-auth.js +58 -52
  182. package/dist/tools/provision-vcs-auth.js.map +1 -1
  183. package/dist/tools/register-member.d.ts +18 -12
  184. package/dist/tools/register-member.d.ts.map +1 -1
  185. package/dist/tools/register-member.js +42 -4
  186. package/dist/tools/register-member.js.map +1 -1
  187. package/dist/tools/remove-member.js +2 -2
  188. package/dist/tools/remove-member.js.map +1 -1
  189. package/dist/tools/revoke-vcs-auth.js +2 -2
  190. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  191. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  192. package/dist/tools/setup-ssh-key.js +2 -1
  193. package/dist/tools/setup-ssh-key.js.map +1 -1
  194. package/dist/tools/stop-prompt.js +2 -2
  195. package/dist/tools/stop-prompt.js.map +1 -1
  196. package/dist/tools/update-agent-cli.js +2 -2
  197. package/dist/tools/update-agent-cli.js.map +1 -1
  198. package/dist/tools/update-member.d.ts +18 -12
  199. package/dist/tools/update-member.d.ts.map +1 -1
  200. package/dist/tools/update-member.js +18 -1
  201. package/dist/tools/update-member.js.map +1 -1
  202. package/dist/types.d.ts +11 -1
  203. package/dist/types.d.ts.map +1 -1
  204. package/dist/utils/agent-helpers.d.ts +36 -0
  205. package/dist/utils/agent-helpers.d.ts.map +1 -1
  206. package/dist/utils/agent-helpers.js +39 -1
  207. package/dist/utils/agent-helpers.js.map +1 -1
  208. package/dist/utils/platform.d.ts +7 -0
  209. package/dist/utils/platform.d.ts.map +1 -1
  210. package/dist/utils/platform.js +11 -1
  211. package/dist/utils/platform.js.map +1 -1
  212. package/dist/utils/workspace-trust.d.ts.map +1 -1
  213. package/dist/utils/workspace-trust.js +5 -1
  214. package/dist/utils/workspace-trust.js.map +1 -1
  215. package/dist/workflows/auto-sprint.js +4 -17
  216. package/package.json +2 -2
  217. package/packages/apra-fleet-client/src/client/api.mjs +92 -3
  218. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -21
  219. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +3 -0
  220. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +22 -44
  221. package/packages/apra-fleet-se/apra-pm/agents/doer.md +131 -132
  222. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +20 -32
  223. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +81 -113
  224. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +31 -42
  225. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +32 -44
  226. package/packages/apra-fleet-se/apra-pm/agents/planner.md +51 -63
  227. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +65 -80
  228. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +56 -83
  229. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  230. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  231. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
  232. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
  233. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +0 -1
  234. package/packages/apra-fleet-se/bin/cli.mjs +132 -3
  235. package/packages/apra-fleet-se/bin/serve.mjs +36 -1
  236. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +151 -33
  237. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +22 -7
  238. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  239. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +9 -4
  240. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +2 -2
  241. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  242. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  243. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  244. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +67 -16
  245. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +41 -0
  246. package/packages/apra-fleet-se/fleet-sprint/runner.js +1140 -209
  247. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  248. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
  249. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  250. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  251. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +2 -1
  252. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
  253. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
  254. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  255. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -43
  256. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
  257. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
  258. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +92 -37
  259. package/packages/apra-fleet-workflow/src/viewer/index.mjs +167 -1
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +435 -31
  261. package/skills/fleet/SKILL.md +20 -9
  262. package/skills/fleet/auth-azdevops.md +44 -5
  263. package/skills/fleet/auth-bitbucket.md +3 -3
  264. package/skills/fleet/auth-github.md +2 -2
  265. package/skills/fleet/beads-conflict-resolution.md +141 -0
  266. package/skills/fleet/beads.md +16 -12
  267. package/skills/fleet/onboarding.md +4 -4
  268. package/skills/fleet/permissions.md +6 -6
  269. package/skills/fleet/skill-matrix.md +1 -1
  270. package/skills/fleet/troubleshooting.md +2 -1
  271. package/version.json +1 -1
  272. package/dist/providers/gemini.d.ts +0 -52
  273. package/dist/providers/gemini.d.ts.map +0 -1
  274. package/dist/providers/gemini.js +0 -236
  275. package/dist/providers/gemini.js.map +0 -1
  276. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
@@ -50,10 +50,30 @@ const EMPTY_REMOTE = [
50
50
  /no branches found in remote/i,
51
51
  ];
52
52
 
53
- /** Verbatim DOLT_REMOTE_UNREACHABLE_PATTERNS. */
53
+ /** Verbatim DOLT_REMOTE_UNREACHABLE_PATTERNS.
54
+ *
55
+ * The first two patterns are guarded with a leading `(?!.*fork\/exec)`
56
+ * lookahead (checked against the WHOLE remaining string, hence `[\s\S]*`
57
+ * rather than `.*`, so it also spans the multi-line raw output these
58
+ * errors come as): Dolt wraps a git subprocess-spawn failure (the OS
59
+ * refusing to even start git.exe, e.g. a transient Windows CreateProcess
60
+ * resource error) in this SAME generic "could not be accessed"/"failed to
61
+ * get remote db" wrapper text it uses for a genuinely dead/misconfigured
62
+ * remote. Confirmed live: a `fork/exec ... git.exe: Not enough memory
63
+ * resources` failure was misclassified as REMOTE_UNREACHABLE (permanent,
64
+ * "retrying cannot succeed") purely from that wrapper phrasing, even
65
+ * though the remote was correctly configured and reachable -- an
66
+ * unmodified retry of the identical command succeeded outright, repeatedly.
67
+ * A `fork/exec` line is Dolt's/Go's structural marker for "the OS refused
68
+ * to start the child process", as opposed to git actually running and
69
+ * reporting a real remote problem -- so its presence anywhere in the
70
+ * output means this ISN'T evidence of a dead remote, and the classifier
71
+ * must fall through to the TRANSIENT check below instead. A genuinely
72
+ * dead/misconfigured remote (no fork/exec line present) is unaffected and
73
+ * still classifies here exactly as before. */
54
74
  const REMOTE_UNREACHABLE = [
55
- /could not be accessed/i,
56
- /failed to get remote db/i,
75
+ /^(?![\s\S]*fork\/exec)[\s\S]*could not be accessed/i,
76
+ /^(?![\s\S]*fork\/exec)[\s\S]*failed to get remote db/i,
57
77
  /stat [^:]+: no such file or directory/i,
58
78
  ];
59
79
 
@@ -91,8 +111,17 @@ const DIVERGED = [
91
111
  /working set (is )?not clean/i,
92
112
  ];
93
113
 
94
- /** Verbatim DOLT_TRANSIENT_PATTERNS. */
114
+ /** Verbatim DOLT_TRANSIENT_PATTERNS.
115
+ *
116
+ * fork/exec: the OS refused to start git.exe itself (e.g. a transient
117
+ * Windows CreateProcess resource error) -- see the REMOTE_UNREACHABLE
118
+ * guard above, which this pattern is the other half of. Deliberately
119
+ * broad (any fork/exec line, not just the "Not enough memory resources"
120
+ * wording observed live) since any process-spawn-refusal is the same
121
+ * class of transient, retry-worthy failure regardless of the OS's exact
122
+ * phrasing for why it refused. */
95
123
  const TRANSIENT = [
124
+ /fork\/exec /i,
96
125
  /could not resolve host/i,
97
126
  /unable to (access|connect)/i,
98
127
  /connection (timed out|reset|refused)/i,
@@ -26,30 +26,12 @@
26
26
  */
27
27
 
28
28
  import { VCS_FAILURE_KINDS as K } from '../errors.mjs';
29
+ import { shQuote, shQuoteJson, curlBinary, assertToken } from './shell-helpers.mjs';
29
30
 
30
31
  const GITHUB_API = 'https://api.github.com';
31
32
  const REDACTED = '***REDACTED***';
32
33
  const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
33
34
 
34
- /** Single-quote a string for embedding in a shell command. The built curl
35
- * command is dispatched through the member's own shell -- POSIX sh/bash
36
- * closes/reopens the quote around an embedded single quote ('\''), but
37
- * Windows PowerShell (the shell every Windows member's commands actually
38
- * run through -- see wrapPowerShellEncoded()/isWindows in
39
- * src/tools/remove-member.ts) escapes an embedded single quote inside a
40
- * single-quoted string by DOUBLING it (''), not by backslash-closing. Using
41
- * the POSIX form on a Windows member breaks the quoting outright (observed
42
- * live: Publish PR crashing on any title/body containing an apostrophe).
43
- * `os` is one of resolveMemberOs()'s return values ('windows'/'linux'/
44
- * 'darwin'); anything other than 'windows' keeps the POSIX behavior
45
- * byte-identical to before this branch existed. */
46
- function shQuote(value, os) {
47
- if (os === 'windows') {
48
- return `'${String(value).replace(/'/g, "''")}'`;
49
- }
50
- return `'${String(value).replace(/'/g, `'\\''`)}'`;
51
- }
52
-
53
35
  function assertRepo(repo) {
54
36
  const value = String(repo ?? '').trim();
55
37
  if (!REPO_RE.test(value)) {
@@ -58,18 +40,10 @@ function assertRepo(repo) {
58
40
  return value;
59
41
  }
60
42
 
61
- function assertToken(token) {
62
- const value = String(token ?? '');
63
- if (!value) {
64
- throw new Error('ERROR: VCSModule: no token supplied -- caller must mint one via provision_vcs_auth before calling VCSModule.');
65
- }
66
- return value;
67
- }
68
-
69
43
  /** Build the GitHub REST "create pull request" curl command.
70
44
  * POST /repos/{owner}/{repo}/pulls -- see
71
45
  * https://docs.github.com/en/rest/pulls/pulls#create-a-pull-request */
72
- function buildGitHubCreatePrCommand({ repo, base, head, title, body, token, os }) {
46
+ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token, os, shell }) {
73
47
  const safeRepo = assertRepo(repo);
74
48
  const safeToken = assertToken(token);
75
49
  if (!base) throw new Error('ERROR: VCSModule: "base" branch is required to build a create-pull-request command.');
@@ -82,13 +56,13 @@ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token, os }
82
56
  const url = `${GITHUB_API}/repos/${safeRepo}/pulls`;
83
57
 
84
58
  const buildCurl = (authToken) => [
85
- 'curl -sS -X POST',
86
- `-H ${shQuote(`Authorization: Bearer ${authToken}`, os)}`,
87
- `-H ${shQuote('Accept: application/vnd.github+json', os)}`,
88
- `-H ${shQuote('Content-Type: application/json', os)}`,
89
- `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os)}`,
90
- `-d ${shQuote(payloadJson, os)}`,
91
- `-w ${shQuote('\n%{http_code}', os)}`,
59
+ `${curlBinary(os)} -sS -X POST`,
60
+ `-H ${shQuote(`Authorization: Bearer ${authToken}`, os, shell)}`,
61
+ `-H ${shQuote('Accept: application/vnd.github+json', os, shell)}`,
62
+ `-H ${shQuote('Content-Type: application/json', os, shell)}`,
63
+ `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os, shell)}`,
64
+ `-d ${shQuoteJson(payloadJson, os, shell)}`,
65
+ `-w ${shQuote('\n%{http_code}', os, shell)}`,
92
66
  url,
93
67
  ].join(' ');
94
68
 
@@ -116,7 +90,7 @@ function buildGitHubCreatePrCommand({ repo, base, head, title, body, token, os }
116
90
  * raised (rather than opening a second PR for the same head).
117
91
  * POST /repos/{owner}/{repo}/issues/{issue_number}/comments -- see
118
92
  * https://docs.github.com/en/rest/issues/comments#create-an-issue-comment */
119
- function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, token, os }) {
93
+ function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, token, os, shell }) {
120
94
  const safeRepo = assertRepo(repo);
121
95
  const safeToken = assertToken(token);
122
96
  if (!issueNumber) throw new Error('ERROR: VCSModule: "issue_number" is required to build a comment command.');
@@ -126,13 +100,13 @@ function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, toke
126
100
  const url = `${GITHUB_API}/repos/${safeRepo}/issues/${issueNumber}/comments`;
127
101
 
128
102
  const buildCurl = (authToken) => [
129
- 'curl -sS -X POST',
130
- `-H ${shQuote(`Authorization: Bearer ${authToken}`, os)}`,
131
- `-H ${shQuote('Accept: application/vnd.github+json', os)}`,
132
- `-H ${shQuote('Content-Type: application/json', os)}`,
133
- `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os)}`,
134
- `-d ${shQuote(payloadJson, os)}`,
135
- `-w ${shQuote('\n%{http_code}', os)}`,
103
+ `${curlBinary(os)} -sS -X POST`,
104
+ `-H ${shQuote(`Authorization: Bearer ${authToken}`, os, shell)}`,
105
+ `-H ${shQuote('Accept: application/vnd.github+json', os, shell)}`,
106
+ `-H ${shQuote('Content-Type: application/json', os, shell)}`,
107
+ `-H ${shQuote('X-GitHub-Api-Version: 2022-11-28', os, shell)}`,
108
+ `-d ${shQuoteJson(payloadJson, os, shell)}`,
109
+ `-w ${shQuote('\n%{http_code}', os, shell)}`,
136
110
  url,
137
111
  ].join(' ');
138
112
 
@@ -147,6 +121,46 @@ function buildGitHubCommentCommand({ repo, issue_number: issueNumber, body, toke
147
121
  };
148
122
  }
149
123
 
124
+ // ---------------------------------------------------------------------------
125
+ // Pull-request RESPONSE mapping (apra-fleet-lzfv.4)
126
+ // ---------------------------------------------------------------------------
127
+ //
128
+ // GitHub's create-pull-request 2xx body carries the PR number as `number` and
129
+ // the browsable page as `html_url`. That mapping was previously IMPLICIT -- a
130
+ // consumer (runner.js's raiseVcsPrForMember) read `html_url` off the body
131
+ // directly, which is a GitHub dialect literal living in a provider-agnostic
132
+ // caller. It is declared here instead, so a provider whose body speaks a
133
+ // different dialect (see ./azure-devops.mjs: `pullRequestId`, and no web-URL
134
+ // field at all) is read through the SAME descriptor hook rather than a caller
135
+ // branch. See ./index.mjs for the contract.
136
+
137
+ const PR_ID_FIELD = 'number';
138
+ const PR_WEB_URL_FIELD = 'html_url';
139
+
140
+ /** Map a GitHub create-pull-request response body to { id, url }. Reads the
141
+ * DECLARED field names above rather than hardcoding them a second time, and
142
+ * reproduces runner.js's historical behavior exactly: a missing or non-string
143
+ * `html_url` yields `url: null` rather than a guessed URL. `ctx` is unused --
144
+ * GitHub's body already carries the browsable URL. */
145
+ function mapPullRequestResponse(body, _ctx) {
146
+ const source = (body && typeof body === 'object') ? body : {};
147
+ const rawId = source[PR_ID_FIELD];
148
+ let id = null;
149
+ if (typeof rawId === 'number' && Number.isFinite(rawId)) id = rawId;
150
+ else if (typeof rawId === 'string' && /^\d+$/.test(rawId.trim())) id = Number(rawId.trim());
151
+ const rawUrl = source[PR_WEB_URL_FIELD];
152
+ return { id, url: typeof rawUrl === 'string' ? rawUrl : null };
153
+ }
154
+
155
+ const pullRequestResponse = Object.freeze({
156
+ idField: PR_ID_FIELD,
157
+ webUrlField: PR_WEB_URL_FIELD,
158
+ // The web URL is READ from the body, never constructed, so there is no
159
+ // template -- contrast ./azure-devops.mjs.
160
+ webUrlTemplate: null,
161
+ map: mapPullRequestResponse,
162
+ });
163
+
150
164
  /** GitHub's credential-rejection literals. "remote: Invalid username or
151
165
  * token/password" is what a git push over HTTPS gets back from GitHub with a
152
166
  * dead PAT; "Bad credentials" is the REST API's equivalent, which reaches us
@@ -226,6 +240,9 @@ export const GitHubVCS = Object.freeze({
226
240
  // makes a provider part of resolveProvider()'s/buildVcsCommand()'s known
227
241
  // vocabulary -- see ./index.mjs's isAuthBackend().
228
242
  defaultAuthMode: 'github-app',
243
+ // apra-fleet-lzfv.4: GitHub's create-pull-request response dialect, stated
244
+ // explicitly instead of left implicit in a caller (see above).
245
+ pullRequestResponse,
229
246
  builders: Object.freeze({
230
247
  'create-pull-request': buildGitHubCreatePrCommand,
231
248
  comment: buildGitHubCommentCommand,
@@ -22,8 +22,76 @@
22
22
  * rules: { [VCS_FAILURE_KIND]: RegExp[] } // classifyFailure() axis
23
23
  * precedence: string[]|undefined // optional kind-check order override
24
24
  * extractProviderCode: (raw) => string|null // classifyFailure() axis
25
- * matchesHost: (host) => boolean // capabilities() axis
26
- * capabilitiesForHost: (host) => { canOpenPullRequest: boolean } // capabilities() axis
25
+ * matchesHost: (host) => boolean // OPTIONAL; capabilities()
26
+ * // axis. Which remote hosts this
27
+ * // provider claims, for
28
+ * // resolveVcsProviderForHost()
29
+ * // below. Omit for a provider that
30
+ * // never owns a host (dolt), and
31
+ * // for the generic-git catch-all
32
+ * // it returns true unconditionally.
33
+ * capabilitiesForHost: (host) => { canOpenPullRequest: boolean } // OPTIONAL;
34
+ * // capabilities() axis. What a
35
+ * // claimed host supports. MUST stay
36
+ * // in lockstep with `builders`:
37
+ * // report canOpenPullRequest:false
38
+ * // while the create-pull-request
39
+ * // builder is absent, so publish
40
+ * // never builds an unsupported
41
+ * // command (see ./azure-devops.mjs).
42
+ * // A provider that omits this hook
43
+ * // is treated as capability-less.
44
+ * parseRepoRef: (url) => { org, project, repo, canonical }|null // OPTIONAL;
45
+ * // remote-URL axis. Parse a git
46
+ * // remote URL into the coordinates
47
+ * // this provider's REST API needs,
48
+ * // for providers whose identity is
49
+ * // not the portable "owner/name"
50
+ * // pair (see ./azure-devops.mjs).
51
+ * // MUST return null -- never throw,
52
+ * // never a partial guess -- for
53
+ * // input it does not recognize, so
54
+ * // the caller can raise its own
55
+ * // typed ERROR naming the expected
56
+ * // shape.
57
+ * repoRefHint: string // OPTIONAL; remote-URL axis. The
58
+ * // human-readable remote shape
59
+ * // parseRepoRef() expects, e.g.
60
+ * // 'https://dev.azure.com/ORG/
61
+ * // PROJECT/_git/REPO'. Quoted
62
+ * // verbatim into the typed ERROR
63
+ * // VCSModule.parseProviderRepoRef()
64
+ * // raises for a claimed-but-
65
+ * // unrecognized remote, which is
66
+ * // what keeps that remedy text --
67
+ * // and every other provider-specific
68
+ * // literal -- out of the shared
69
+ * // callers. Only meaningful
70
+ * // alongside parseRepoRef.
71
+ * buildProvisionArgs: (ctx) => { args }|{ error } // OPTIONAL;
72
+ * // provisioning axis. Build the
73
+ * // provision_vcs_auth argument
74
+ * // object for a member of this
75
+ * // provider, given the shared
76
+ * // caller's `base` args, this
77
+ * // provider's own parseRepoRef()
78
+ * // output for the member's remote
79
+ * // (`repoRef`) and the credential-
80
+ * // store entry names the caller
81
+ * // observed (`availableSecrets`,
82
+ * // null when unreadable). Omit it
83
+ * // and the caller sends its shared
84
+ * // GitHub-App-shaped arguments
85
+ * // unchanged. MUST return a typed
86
+ * // 'ERROR: ' string in `error`
87
+ * // rather than prompting: the
88
+ * // callers are unattended preflight
89
+ * // and self-heal paths, where an
90
+ * // out-of-band prompt stalls a
91
+ * // sprint. MUST pass a secret as a
92
+ * // {{secure.NAME}} placeholder,
93
+ * // never a value -- resolution is
94
+ * // hub-side (see ./azure-devops.mjs).
27
95
  * defaultAuthMode: string|null // OPTIONAL, but declaring it (even
28
96
  * // as null) is what makes a provider
29
97
  * // part of resolveProvider()'s/
@@ -33,12 +101,91 @@
33
101
  * // classification-only provider
34
102
  * // (generic-git, dolt) that is not a
35
103
  * // member-facing VCS auth backend.
104
+ * pullRequestResponse: { // OPTIONAL; response axis
105
+ * idField: string, // apra-fleet-lzfv.4. How to read a
106
+ * webUrlField: string|null, // create-pull-request 2xx response
107
+ * webUrlTemplate: string|null, // BODY, which is as provider-
108
+ * map: (body, ctx) => { id, url } // specific as the request is:
109
+ * } // GitHub answers with `number` +
110
+ * // `html_url`, Azure DevOps with
111
+ * // `pullRequestId` and NO web-URL
112
+ * // field at all (its `url` is the
113
+ * // REST resource, not a page), so
114
+ * // its browsable URL must be
115
+ * // CONSTRUCTED from the request's
116
+ * // own org/project/repo plus the
117
+ * // returned id. Declaring the
118
+ * // mapping on the descriptor is
119
+ * // what keeps either dialect out
120
+ * // of the shared caller, which
121
+ * // until this hook existed read
122
+ * // `html_url` off the body itself.
123
+ * // `idField`/`webUrlField`/
124
+ * // `webUrlTemplate` are the
125
+ * // DECLARATION (what a consumer
126
+ * // mirroring this contract in
127
+ * // another language/package
128
+ * // restates); `map` is the single
129
+ * // executable source of truth and
130
+ * // MUST read those same declared
131
+ * // fields rather than repeat them.
132
+ * // `map` MUST NOT throw and MUST
133
+ * // return { id: number|null,
134
+ * // url: string|null } -- an
135
+ * // unreadable id or a coordinate
136
+ * // missing from `ctx` yields null,
137
+ * // never a guessed value, so a
138
+ * // successful PR is never turned
139
+ * // into a crash by its own
140
+ * // reporting step. `ctx` is the
141
+ * // request-side coordinates
142
+ * // (org/project/repo, or a
143
+ * // `repoRef` object -- the same
144
+ * // shape the builders take); a
145
+ * // provider whose body is
146
+ * // self-sufficient ignores it.
36
147
  * builders: { [action]: Function }|null // create-pull-request/comment
37
148
  * // command builders; null means
38
149
  * // "known provider, action(s)
39
150
  * // not yet implemented" (fails
40
151
  * // closed with a typed ERROR:,
41
152
  * // never a silently wrong command)
153
+ * authRemedy: { // OPTIONAL; auth-self-heal axis
154
+ * serverSideReMintable: boolean, // (apra-fleet-5co8.4.2). Whether
155
+ * hint: string // the REACTIVE self-heal callback
156
+ * } // (runner.js's
157
+ * // createVcsAuthSelfHealCallback)
158
+ * // can actually fix an
159
+ * // auth-classified failure by
160
+ * // calling provision_vcs_auth
161
+ * // again on its own: true for a
162
+ * // GitHub App installation token
163
+ * // (minted fresh server-side
164
+ * // every call) or a credential the
165
+ * // fleet can otherwise regenerate
166
+ * // without a human; false for a
167
+ * // long-lived PAT/app password the
168
+ * // fleet only ever stores and
169
+ * // redeploys, never mints (see
170
+ * // ./azure-devops.mjs) -- re-
171
+ * // provisioning there just
172
+ * // redeploys the SAME dead
173
+ * // secret, so the self-heal
174
+ * // attempt is expected to fail
175
+ * // again. `hint` is the exact
176
+ * // operator-facing remedy text
177
+ * // printed alongside the self-
178
+ * // heal attempt when
179
+ * // `serverSideReMintable` is
180
+ * // false, so a provider-specific
181
+ * // literal never leaks into the
182
+ * // shared runner.js caller.
183
+ * // Omitting this hook (or
184
+ * // omitting `serverSideReMintable`
185
+ * // from it) means "assume
186
+ * // re-mintable" -- the
187
+ * // pre-existing GitHub/generic
188
+ * // behavior, unchanged.
42
189
  * }
43
190
  *
44
191
  * The manifest is an explicit import list rather than a directory scan on
@@ -92,6 +239,22 @@ export function registerVcsProvider(impl) {
92
239
  if (impl.extractProviderCode != null && typeof impl.extractProviderCode !== 'function') {
93
240
  throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-function \`extractProviderCode\`.`);
94
241
  }
242
+ // apra-fleet-5co8.1.1: the host/URL-axis hooks. All OPTIONAL (a
243
+ // classification-only provider declares none of them), but validated up
244
+ // front for the same reason as `extractProviderCode` above -- a malformed
245
+ // hook must fail at registration, not inside resolveVcsProviderForHost()
246
+ // or a remote-URL preflight where the error would mask the real failure.
247
+ for (const hook of ['matchesHost', 'capabilitiesForHost', 'parseRepoRef', 'buildProvisionArgs']) {
248
+ if (impl[hook] != null && typeof impl[hook] !== 'function') {
249
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-function \`${hook}\`.`);
250
+ }
251
+ }
252
+ // apra-fleet-5co8.1.2: the remedy text quoted into a preflight ERROR. A
253
+ // non-string here would land the literal 'undefined'/'[object Object]' in
254
+ // an operator-facing error, so reject it at registration too.
255
+ if (impl.repoRefHint != null && typeof impl.repoRefHint !== 'string') {
256
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-string \`repoRefHint\`.`);
257
+ }
95
258
  // apra-fleet-647.1.5.1: the two auth-backend fields folded in from
96
259
  // vcs-module.mjs's former BUILDERS/DEFAULT_AUTH_MODES tables. Both are
97
260
  // OPTIONAL (a classification-only provider like generic-git/dolt omits
@@ -100,6 +263,46 @@ export function registerVcsProvider(impl) {
100
263
  if (Object.prototype.hasOwnProperty.call(impl, 'defaultAuthMode') && impl.defaultAuthMode !== null && typeof impl.defaultAuthMode !== 'string') {
101
264
  throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-string, non-null \`defaultAuthMode\`.`);
102
265
  }
266
+ // apra-fleet-lzfv.4: the create-pull-request RESPONSE mapping. OPTIONAL
267
+ // (a classification-only provider, or one with no PR builder, declares
268
+ // none), but validated up front for the same reason as the hooks above --
269
+ // a malformed mapping must fail at registration, not while reporting an
270
+ // already-created pull request, where the error would mask a success.
271
+ if (impl.pullRequestResponse != null) {
272
+ const prr = impl.pullRequestResponse;
273
+ if (typeof prr !== 'object') {
274
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-object \`pullRequestResponse\`.`);
275
+ }
276
+ if (typeof prr.idField !== 'string' || !prr.idField.trim()) {
277
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a \`pullRequestResponse\` with no non-empty string \`idField\`.`);
278
+ }
279
+ if (typeof prr.map !== 'function') {
280
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a \`pullRequestResponse\` with a non-function \`map\`.`);
281
+ }
282
+ for (const field of ['webUrlField', 'webUrlTemplate']) {
283
+ if (prr[field] != null && typeof prr[field] !== 'string') {
284
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a \`pullRequestResponse\` with a non-string, non-null \`${field}\`.`);
285
+ }
286
+ }
287
+ }
288
+ // apra-fleet-5co8.4.2: the auth-self-heal remedy axis. OPTIONAL (omitting
289
+ // it means "assume re-mintable", the pre-existing behavior), but
290
+ // validated up front for the same reason as the hooks above -- a
291
+ // malformed remedy must fail at registration, not while reporting an
292
+ // already-failed self-heal attempt, where the error would mask the real
293
+ // auth failure.
294
+ if (impl.authRemedy != null) {
295
+ const remedy = impl.authRemedy;
296
+ if (typeof remedy !== 'object') {
297
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-object \`authRemedy\`.`);
298
+ }
299
+ if (typeof remedy.serverSideReMintable !== 'boolean') {
300
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has an \`authRemedy\` with a non-boolean \`serverSideReMintable\`.`);
301
+ }
302
+ if (typeof remedy.hint !== 'string' || !remedy.hint.trim()) {
303
+ throw new Error(`ERROR: VCSModule: provider "${impl.name}" has an \`authRemedy\` with no non-empty string \`hint\`.`);
304
+ }
305
+ }
103
306
  if (impl.builders != null) {
104
307
  if (typeof impl.builders !== 'object') {
105
308
  throw new Error(`ERROR: VCSModule: provider "${impl.name}" has a non-object \`builders\` table.`);
@@ -0,0 +1,164 @@
1
+ /**
2
+ * Shared shell-quoting, curl-binary and token-assertion helpers for VCS
3
+ * provider command builders. Used by GitHub and Azure DevOps, and available
4
+ * for use by other providers to ensure consistent shell-escaping rules across
5
+ * all providers.
6
+ *
7
+ * RE-LANDED (apra-fleet-lzfv.2): apra-fleet-lzfv.1 first hoisted shQuote() and
8
+ * assertToken() out of ./github.mjs into this module; commit 1188d2ab (an
9
+ * unrelated orchestrator-sync/dolt-timeout change) then deleted this file and
10
+ * re-inlined both as private definitions in github.mjs. This is that same pure
11
+ * move re-applied, with curlBinary() added to it -- ./azure-devops.mjs needs
12
+ * the Windows curl.exe token for exactly the same reason github.mjs does, and
13
+ * copying it would recreate the duplication this module exists to prevent.
14
+ *
15
+ * shQuote's shell-aware (3rd `shell` arg) form was re-landed here on top of
16
+ * that: 0e291ace (fix(fleet-sprint): quote VCS curl commands by member shell,
17
+ * not bare OS) found that a Windows member whose registered shell is
18
+ * Git-for-Windows bash got PowerShell doubled-quote escaping from the
19
+ * OS-only check, corrupting the create-PR curl -d JSON payload. That fix
20
+ * originally landed inline in github.mjs (github.mjs was still the only
21
+ * caller); merged in here so both providers share the corrected logic
22
+ * instead of github.mjs re-diverging from this module a second time.
23
+ *
24
+ * ASCII only.
25
+ */
26
+
27
+ /** Single-quote a string for embedding in a shell command. The built curl
28
+ * command is dispatched through the member's own COMMAND SHELL, so the
29
+ * quoting dialect must follow that shell -- NOT the bare OS:
30
+ * - POSIX sh/bash (and Git-for-Windows bash on a Windows member) closes/
31
+ * reopens the quote around an embedded single quote ('\'').
32
+ * - Windows PowerShell (see wrapPowerShellEncoded()/isWindows in
33
+ * src/tools/remove-member.ts) escapes an embedded single quote inside a
34
+ * single-quoted string by DOUBLING it (''), not by backslash-closing.
35
+ * Using the POSIX form on a PowerShell member breaks the quoting outright
36
+ * (observed live: Publish PR crashing on any title/body containing an
37
+ * apostrophe) -- and, the mirror defect, using the PowerShell form on a
38
+ * Windows member whose registered shell is gitbash corrupts the curl -d
39
+ * JSON payload (observed live: GitHub's create-PR endpoint answering
40
+ * "HTTP 400: Problems parsing JSON"), because bash reads '' as
41
+ * close-then-reopen, not as an escaped quote.
42
+ *
43
+ * `os` is one of resolveMemberOs()'s return values ('windows'/'linux'/
44
+ * 'darwin'); `shell` is the member's registered shell as resolved by
45
+ * runner.js's resolveMemberTarget() -- 'gitbash' | 'pwsh7' | 'powershell5'
46
+ * | '' (empty/undefined when the registry recorded none, or when a caller
47
+ * does not yet thread shell through -- see usesPowerShellQuoting below).
48
+ * Resolution, mirroring se-os-commands.mjs's getSeCommands() matrix:
49
+ * - shell 'gitbash' -> POSIX quoting, even on Windows
50
+ * - shell 'pwsh7'/'powershell5' -> PowerShell doubling
51
+ * - unresolved shell ('' / undefined) + windows -> PowerShell doubling
52
+ * (the historical default: every Windows member was assumed PowerShell
53
+ * before shells were recorded -- the fallback stays byte-identical)
54
+ * - any non-Windows os -> POSIX quoting, byte-identical to
55
+ * before this parameter existed. */
56
+ function usesPowerShellQuoting(os, shell) {
57
+ if (shell === 'gitbash') return false;
58
+ if (shell === 'pwsh7' || shell === 'powershell5') return true;
59
+ return os === 'windows';
60
+ }
61
+
62
+ /** Pre-escape `value` for the Windows C-runtime argv parser that a NATIVE
63
+ * executable (curl.exe) applies to the command line PowerShell hands it.
64
+ *
65
+ * Windows PowerShell 5.1's native-command argument binder (and pwsh before
66
+ * 7.3) passes a single-quoted argument's VALUE through to the child process
67
+ * command line without escaping anything: the only thing it does is wrap
68
+ * the value in double quotes when it finds whitespace OUTSIDE what it
69
+ * counts as a double-quoted region. The child's CRT parser then eats every
70
+ * embedded `"` as a quote toggle, so a JSON payload like {"title":"x y"}
71
+ * reaches curl.exe as {title:x y} (measured live on powershell.exe
72
+ * 5.1.19041 with a node argv probe: every `"` stripped, spaces kept) and
73
+ * Azure DevOps/GitHub answer HTTP 400 to the unparseable body. Same defect
74
+ * class dolt-settle.mjs's nodeEval() already works around for its
75
+ * PowerShell branch.
76
+ *
77
+ * The CRT rules (CommandLineToArgvW / MSVC argv), which this function
78
+ * inverts so the child reconstructs `value` byte-for-byte:
79
+ * - 2n backslashes + `"` -> n backslashes, `"` toggles quoting
80
+ * - 2n+1 backslashes + `"` -> n backslashes, literal `"`
81
+ * - backslashes NOT followed by `"` are literal (so a JSON `\n` escape
82
+ * inside a string value is left alone)
83
+ * So every run of n backslashes that precedes a `"` becomes 2n+1
84
+ * backslashes + `"` (n=0: `"` -> `\"`).
85
+ *
86
+ * LIMIT (measured, not assumed): the 5.1 binder counts a backslash-escaped
87
+ * `\"` toward its quote parity exactly like a bare `"`, while the CRT does
88
+ * NOT toggle on it -- so for a value carrying BOTH whitespace and quotes
89
+ * the two parsers disagree about whether that whitespace is "inside
90
+ * quotes", the binder skips its wrapping, and the CRT splits the argument
91
+ * at the whitespace (observed: a JSON title 'Auto-sprint [PASS]: x'
92
+ * arrived as two argv entries). There is no escape sequence both parsers
93
+ * read the same way, so a caller must keep such a value whitespace-free --
94
+ * see shQuoteJson() below, which does exactly that for JSON payloads (the
95
+ * only quote-bearing arguments the VCS builders emit). A value with
96
+ * whitespace but NO quotes (an `-H 'Content-Type: application/json'`
97
+ * header) is wrapped by the binder and parsed back intact by the CRT.
98
+ *
99
+ * NOTE pwsh 7.3+ defaults $PSNativeCommandArgumentPassing to 'Windows'
100
+ * mode, which escapes embedded `"` itself; this pre-escaping is for the
101
+ * legacy binder that every Windows member in this fleet is driven through
102
+ * today (src/os/windows.ts cleanExec() spawns `powershell.exe`, and the
103
+ * remote path sends raw PowerShell text to the member's default shell). */
104
+ function escapeForWindowsArgv(value) {
105
+ return String(value).replace(/(\\*)"/g, (_m, backslashes) => `${backslashes}${backslashes}\\"`);
106
+ }
107
+
108
+ function shQuote(value, os, shell) {
109
+ if (usesPowerShellQuoting(os, shell)) {
110
+ // Two layers, applied inside-out: first the CRT argv pre-escaping
111
+ // above (what the NATIVE child parses), then PowerShell's own
112
+ // single-quoted-string escape (what PowerShell parses to get the
113
+ // value it hands the binder) -- a lone `'` inside a `'...'` string
114
+ // is written as `''`.
115
+ return `'${escapeForWindowsArgv(value).replace(/'/g, "''")}'`;
116
+ }
117
+ return `'${String(value).replace(/'/g, `'\\''`)}'`;
118
+ }
119
+
120
+ /** Quote a JSON document for a `-d` argument. POSIX: plain shQuote of the
121
+ * JSON.stringify() text. PowerShell dialect: every literal whitespace code
122
+ * point left in the JSON text (a space inside a string value; JSON.stringify
123
+ * already escapes \n \t \r) is rewritten as its equivalent JSON `\uXXXX`
124
+ * escape -- byte-different, semantically identical JSON -- so the argument
125
+ * carries NO whitespace and the 5.1 binder-vs-CRT disagreement described on
126
+ * escapeForWindowsArgv() can never arise: the binder leaves the value bare,
127
+ * the CRT reads each `\"` as a literal quote, and curl.exe receives the
128
+ * exact JSON the caller built. Whitespace cannot appear outside a string
129
+ * in JSON.stringify() output, so the rewrite is always inside a string. */
130
+ function shQuoteJson(json, os, shell) {
131
+ const text = String(json);
132
+ if (!usesPowerShellQuoting(os, shell)) return shQuote(text, os, shell);
133
+ const noWhitespace = text.replace(/\s/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
134
+ return shQuote(noWhitespace, os, shell);
135
+ }
136
+
137
+ /** Which curl binary token to emit for a given member OS. On Windows the bare
138
+ * word `curl` is a built-in PowerShell alias for Invoke-WebRequest, NOT the
139
+ * real curl -- Invoke-WebRequest's -Headers parameter wants a hashtable, not
140
+ * curl's repeatable `-H 'k: v'` string syntax, so a bare `curl -H ...`
141
+ * command sent to a Windows/PowerShell member fails with a parameter-bind
142
+ * error (observed live on the Publish PR step). The real curl.exe binary has
143
+ * shipped in %SystemRoot%\System32 since Windows 10 1803 and is resolvable
144
+ * from PowerShell's default PATH (verified locally: `where curl.exe` and
145
+ * `Get-Command curl.exe` both resolve on a live Windows box), so emitting
146
+ * the explicit `curl.exe` token sidesteps the alias entirely without
147
+ * needing a different request mechanism. Non-Windows os values keep the
148
+ * bare `curl` token byte-identical to before this branch existed.
149
+ * Deliberately OS-keyed (not shell-keyed like shQuote above): curl.exe is
150
+ * equally resolvable from Git-for-Windows bash, so a windows+gitbash member
151
+ * keeps the same binary token. */
152
+ function curlBinary(os) {
153
+ return os === 'windows' ? 'curl.exe' : 'curl';
154
+ }
155
+
156
+ function assertToken(token) {
157
+ const value = String(token ?? '');
158
+ if (!value) {
159
+ throw new Error('ERROR: VCSModule: no token supplied -- caller must mint one via provision_vcs_auth before calling VCSModule.');
160
+ }
161
+ return value;
162
+ }
163
+
164
+ export { shQuote, shQuoteJson, usesPowerShellQuoting, escapeForWindowsArgv, curlBinary, assertToken };