shapewall 0.3.2 → 0.6.0

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 (119) hide show
  1. package/CHANGELOG.md +357 -0
  2. package/NOTICE +7 -0
  3. package/README.md +50 -4
  4. package/THIRD_PARTY.md +39 -0
  5. package/dist/agent/package-lock.json +2 -2
  6. package/dist/client/assets/BoardChat-DdwBcb2N.js +27 -0
  7. package/dist/client/assets/BuzzDialog-DpUcnU6S.js +1 -0
  8. package/dist/client/assets/ChecksPanel-CngYV4yz.js +1 -0
  9. package/dist/client/assets/History-CD0saQA5.js +1 -0
  10. package/dist/client/assets/LocalSettings-MZy2baig.js +1 -0
  11. package/dist/client/assets/{Management-DmTh1-tA.js → Management-CSvZ-SHO.js} +1 -1
  12. package/dist/client/assets/QuickConnect-foLh2QUm.js +1 -0
  13. package/dist/client/assets/ShareDialog-DPWDftoL.js +2 -0
  14. package/dist/client/assets/app-update-dialog-CtiXpTRD.js +1 -0
  15. package/dist/client/assets/{circle-x-3UxAvczM.js → circle-x-CteRBtXC.js} +1 -1
  16. package/dist/client/assets/index-Cxz1UVcV.css +2 -0
  17. package/dist/client/assets/index-uUZVBYUS.js +37 -0
  18. package/dist/client/assets/play-BjRNIGSf.js +1 -0
  19. package/dist/client/assets/{refresh-cw-BRHNyCnY.js → refresh-cw-r_tZiFfB.js} +1 -1
  20. package/dist/client/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  21. package/dist/client/assets/{runtime-Bft6x_6E.js → runtime-Bvq10IhH.js} +1 -1
  22. package/dist/client/assets/ui-zQpn-PdL.js +41 -0
  23. package/dist/client/build-info.json +1 -1
  24. package/dist/client/index.html +4 -3
  25. package/dist/client/sw.js +2 -2
  26. package/dist/console/assets/{LocalAccountsApp-IvHd9zWN.js → LocalAccountsApp-DIdy1KnN.js} +1 -1
  27. package/dist/console/assets/{LocalConsole-DOyLou56.js → LocalConsole-DfcQztF-.js} +1 -1
  28. package/dist/console/assets/{app-update-dialog-Da46CJpv.js → app-update-dialog-ttl9lF5A.js} +1 -1
  29. package/dist/console/assets/console-OqAjD0kV.js +55 -0
  30. package/dist/console/assets/console-kvjrAArQ.css +2 -0
  31. package/dist/console/build-info.json +1 -1
  32. package/dist/console/console.html +2 -2
  33. package/docs/agent-hardening.md +192 -0
  34. package/docs/agent-recipes.md +23 -0
  35. package/docs/agent-workflow.md +5 -0
  36. package/docs/agents.md +74 -6
  37. package/docs/config.md +1 -1
  38. package/docs/deployment.md +2 -0
  39. package/docs/design-system.md +20 -15
  40. package/docs/hosted.md +815 -3
  41. package/docs/where-to-run.md +123 -0
  42. package/package.json +2 -1
  43. package/src/agent/agent-logos.js +81 -0
  44. package/src/agent/backends/acp.js +528 -25
  45. package/src/agent/branch-mode.js +17 -3
  46. package/src/agent/card-hash.js +65 -0
  47. package/src/agent/config.js +27 -2
  48. package/src/agent/context.js +41 -0
  49. package/src/agent/exec-paths.js +105 -0
  50. package/src/agent/icon-store.js +100 -0
  51. package/src/agent/identity.js +77 -0
  52. package/src/agent/owner-mcp.js +19 -3
  53. package/src/agent/routes.js +82 -22
  54. package/src/agent/run.js +14 -2
  55. package/src/agent/settings-routes.js +233 -14
  56. package/src/agent/starter/cli.js +6 -1
  57. package/src/agent/test-timing.js +14 -0
  58. package/src/agent/tools.js +4 -2
  59. package/src/agent/turn-changes.js +70 -8
  60. package/src/agent/user-settings.js +51 -3
  61. package/src/capture/element-map.js +61 -4
  62. package/src/cli/args.js +13 -0
  63. package/src/cli/commands.js +20 -5
  64. package/src/cli/help.js +36 -1
  65. package/src/hosted/admin.js +7 -0
  66. package/src/hosted/agent-approvals.js +28 -3
  67. package/src/hosted/agent-link.js +1032 -0
  68. package/src/hosted/agent-policy.js +10 -3
  69. package/src/hosted/agent-presence.js +81 -0
  70. package/src/hosted/agent-routes.js +135 -0
  71. package/src/hosted/agents.js +1199 -0
  72. package/src/hosted/app.js +94 -4
  73. package/src/hosted/board-routes.js +134 -3
  74. package/src/hosted/chat-frames.js +256 -0
  75. package/src/hosted/chat-job.js +204 -0
  76. package/src/hosted/chat-permissions.js +191 -0
  77. package/src/hosted/chat-routes.js +1009 -0
  78. package/src/hosted/chat-store.js +460 -0
  79. package/src/hosted/comment-files.js +8 -1
  80. package/src/hosted/comments.js +1 -1
  81. package/src/hosted/console-routes.js +58 -1
  82. package/src/hosted/db.js +165 -0
  83. package/src/hosted/device-routes.js +64 -8
  84. package/src/hosted/device.js +35 -4
  85. package/src/hosted/events.js +8 -6
  86. package/src/hosted/membership.js +9 -1
  87. package/src/hosted/pages.js +2 -0
  88. package/src/hosted/permissions.js +38 -0
  89. package/src/hosted/presence.js +18 -1
  90. package/src/hosted/projects.js +60 -2
  91. package/src/hosted/ratelimit.js +8 -0
  92. package/src/hosted/tenancy.js +18 -0
  93. package/src/hosted/token-api.js +118 -15
  94. package/src/hosted/token-events.js +7 -2
  95. package/src/hosted/tokens.js +24 -7
  96. package/src/hosted/turn-hub.js +152 -0
  97. package/src/mcp.js +10 -2
  98. package/src/remote/agent-connect.js +433 -0
  99. package/src/remote/agent-fix.js +611 -0
  100. package/src/remote/agent-job.js +216 -0
  101. package/src/remote/agent-link.js +904 -0
  102. package/src/remote/agent-policy-file.js +242 -0
  103. package/src/remote/credentials.js +35 -1
  104. package/src/remote/login.js +12 -2
  105. package/src/store.js +5 -0
  106. package/dist/client/assets/BoardChat-BeRp6007.js +0 -27
  107. package/dist/client/assets/BuzzDialog-CrYy48hh.js +0 -1
  108. package/dist/client/assets/ChecksPanel-CB820mhj.js +0 -1
  109. package/dist/client/assets/History-Ba909bGJ.js +0 -1
  110. package/dist/client/assets/LocalSettings-ChMi9Zir.js +0 -1
  111. package/dist/client/assets/QuickConnect-CrVweWZB.js +0 -1
  112. package/dist/client/assets/ShareDialog-DO2HhY6g.js +0 -2
  113. package/dist/client/assets/app-update-dialog-C09ODdUQ.js +0 -1
  114. package/dist/client/assets/index-BIjfZKnp.js +0 -37
  115. package/dist/client/assets/index-CXtuJi1K.css +0 -2
  116. package/dist/client/assets/shield-check-DMpniYP6.js +0 -1
  117. package/dist/client/assets/ui-mhL9gsne.js +0 -41
  118. package/dist/console/assets/console-CIBv7cXU.js +0 -55
  119. package/dist/console/assets/console-Fp4k9iyx.css +0 -2
@@ -0,0 +1,611 @@
1
+ // A connected agent's fix: "Fix with <agent>" on a hosted comment, on a
2
+ // machine that takes edits from the board (`shapewall agent connect
3
+ // --approvals owner|admins`). The agent never works in the person's checkout:
4
+ //
5
+ // before a fresh copy of the base commit, with no .git in it, in a
6
+ // folder outside the project (branch mode's worktree:
7
+ // src/agent/branch-mode.js, src/agent/starter/worktree.js). The
8
+ // base is the branch the machine names (`--base`), else the commit
9
+ // the checkout is on, and then only while the checkout has no
10
+ // uncommitted changes (a fix would silently leave them out).
11
+ // Copies that dead processes left are swept first.
12
+ // during every edit is checked and asked for one at a time (acp.js
13
+ // remoteRequest); what was allowed is written down here, file by
14
+ // file, as the hash of the bytes the file should hold afterwards,
15
+ // and whether a person allowed it or it went without asking.
16
+ // after Shapewall commits the folder on a new branch itself (no hook,
17
+ // filter or attribute runs). The commit is kept only when it is
18
+ // exactly what was allowed: every file it changes was allowed and
19
+ // holds those bytes, with the mode it had; every allowed file is
20
+ // in it; nothing was removed. Anything else and the branch is
21
+ // taken back.
22
+ // push the branch goes to the machine's remote, and a pull request is
23
+ // opened when GitHub is set up here, only when (a) nothing in it
24
+ // runs on install, build, test or CI (src/agent/exec-paths.js) and
25
+ // (b) a person has seen every edit. A fix with an edit that went
26
+ // without asking is HELD: committed here, pushed nowhere, until
27
+ // someone who may answer cards allows one "Push this fix" card
28
+ // that shows its whole diff (agent-link.js).
29
+ //
30
+ // Stop (the turn's signal) is honoured between every step: after it nothing
31
+ // is committed, pushed or opened. A push that had already finished stays,
32
+ // and the thread says the branch exists.
33
+ //
34
+ // The checkout itself is only ever read (git status, rev-parse, check-ignore).
35
+
36
+ import fs from 'node:fs'
37
+ import os from 'node:os'
38
+ import path from 'node:path'
39
+ import { createHash } from 'node:crypto'
40
+ import { inside } from '../agent/acp/sandbox.js'
41
+ import {
42
+ BranchError,
43
+ branchModeSettings,
44
+ checkRepo,
45
+ checkoutSignature,
46
+ commitAgentBranch,
47
+ createAgentBranch,
48
+ validBranchName,
49
+ worktreeAgentEnv,
50
+ } from '../agent/branch-mode.js'
51
+ import { filesThatRun } from '../agent/exec-paths.js'
52
+ import { RUN_DIR_RE, git, processAlive, pushBranch, removeWorktree, sweepWorkRoot } from '../agent/starter/worktree.js'
53
+ import { diffForCard, diffForFiles } from '../agent/text-diff.js'
54
+ import { commentText } from '../comment-fields.js'
55
+ import { DEFAULT_API_URL, githubSettings, openPullRequest } from '../github.js'
56
+
57
+ const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/
58
+ export const FIX_FILES_MAX = 50
59
+ export const FIX_LIMITS = {
60
+ // Fixes held back from a remote, waiting for "Push this fix": the newest stay.
61
+ held: 20,
62
+ heldMs: 14 * 24 * 60 * 60 * 1000,
63
+ }
64
+
65
+ // A fix this machine does not start, with the reason for the board.
66
+ export class FixRefusal extends Error {
67
+ constructor(code, message) {
68
+ super(message)
69
+ this.code = code
70
+ }
71
+ }
72
+
73
+ const sha256 = (data) => createHash('sha256').update(data).digest('hex')
74
+ const aborted = (signal) => Boolean(signal?.aborted)
75
+
76
+ // Text from a comment, on its way into a commit subject or a pull request
77
+ // title: one line, no NUL or control characters, and nothing GitHub would act
78
+ // on. "@name" pings nobody, "#12" links and closes nothing, a URL is not one.
79
+ export function inertLine(text, max = 72) {
80
+ const first =
81
+ String(text || '')
82
+ .split('\0')
83
+ .join('')
84
+ .split('\n')
85
+ .map((line) => line.trim())
86
+ .find(Boolean) || ''
87
+ return (
88
+ first
89
+ // eslint-disable-next-line no-control-regex
90
+ .replace(/[\u0001-\u001f\u007f]/g, ' ')
91
+ .replace(/@(?=\S)/g, '@\u200b')
92
+ .replace(/#(?=\S)/g, '#\u200b')
93
+ .replace(/:\/\//g, ':/\u200b/')
94
+ .slice(0, max)
95
+ )
96
+ }
97
+
98
+ // Where fixes are made: outside every project, one folder per project.
99
+ // Throws FixRefusal when that place would be inside the project itself
100
+ // (the project is the home folder, say): a copy of the project inside the
101
+ // project is a write to the checkout.
102
+ export function fixRoot(projectDir, env = process.env) {
103
+ const home = env.HOME || os.homedir()
104
+ // Only an absolute XDG_STATE_HOME counts (a relative one would be read against the project).
105
+ const state = env.XDG_STATE_HOME && path.isAbsolute(env.XDG_STATE_HOME) ? env.XDG_STATE_HOME : path.join(home, '.local', 'state')
106
+ const project = fs.realpathSync(projectDir)
107
+ const root = path.join(state, 'shapewall', 'agent-fixes', sha256(project).slice(0, 16))
108
+ // The nearest folder that exists, resolved: a link in the way does not hide where it lands.
109
+ let existing = root
110
+ while (!fs.existsSync(existing) && path.dirname(existing) !== existing) existing = path.dirname(existing)
111
+ const real = path.join(fs.realpathSync(existing), path.relative(existing, root))
112
+ if (!path.isAbsolute(real) || inside(project, real))
113
+ throw new FixRefusal(
114
+ 'bad_fix_root',
115
+ "On the agent's machine, the folder fixes are made in would be inside the project itself. Set XDG_STATE_HOME there to a folder outside the project.",
116
+ )
117
+ return real
118
+ }
119
+
120
+ const heldFile = (root, id) => path.join(root, `held-${id}.json`)
121
+
122
+ // What dead processes left behind for this project: copies whose owner is
123
+ // gone (with their records, so their branch names are free again), records
124
+ // without a copy, and held fixes past their time or beyond the newest few.
125
+ // Run when `agent connect` starts and around every fix. -> ids removed
126
+ export function sweepFixes(projectDir, env = process.env, { isAlive = processAlive, now = Date.now() } = {}) {
127
+ let root
128
+ try {
129
+ root = fixRoot(projectDir, env)
130
+ } catch {
131
+ return []
132
+ }
133
+ if (!fs.existsSync(root)) return []
134
+ const removed = sweepWorkRoot(root, { isAlive, now })
135
+ for (const id of removed) fs.rmSync(path.join(root, `${id}.json`), { force: true })
136
+ let names = []
137
+ try {
138
+ names = fs.readdirSync(root)
139
+ } catch {
140
+ return removed
141
+ }
142
+ for (const name of names) {
143
+ // A record (or an index or owner file) whose copy is gone.
144
+ const id = /^(\d{14}-[a-f0-9]{6})\.(json|owner|checkout\.index|commit\.index)$/.exec(name)?.[1]
145
+ if (id && RUN_DIR_RE.test(id) && !fs.existsSync(path.join(root, id))) {
146
+ let pid = null
147
+ try {
148
+ pid = Number(fs.readFileSync(path.join(root, `${id}.owner`), 'utf8').trim())
149
+ } catch {
150
+ /* no owner file */
151
+ }
152
+ if (pid === null || !isAlive(pid)) {
153
+ fs.rmSync(path.join(root, name), { force: true })
154
+ if (!removed.includes(id)) removed.push(id)
155
+ }
156
+ }
157
+ if (/\.tmp$/.test(name)) fs.rmSync(path.join(root, name), { force: true })
158
+ }
159
+ const held = names
160
+ .filter((name) => /^held-\d{14}-[a-f0-9]{6}\.json$/.test(name))
161
+ .map((name) => ({ name, at: fs.statSync(path.join(root, name)).mtimeMs }))
162
+ .sort((a, b) => b.at - a.at)
163
+ for (const [index, item] of held.entries())
164
+ if (index >= FIX_LIMITS.held || now - item.at > FIX_LIMITS.heldMs) fs.rmSync(path.join(root, item.name), { force: true })
165
+ return removed
166
+ }
167
+
168
+ const REPO_REFUSALS = {
169
+ not_a_repo: "The agent's project folder is not a Git repository, so it cannot make a fix on a branch.",
170
+ unborn_head: "The agent's repository has no commit yet, so there is nothing to branch from.",
171
+ }
172
+
173
+ // The commit a fix starts from: { commit, name } (`name`: the branch a pull
174
+ // request goes into, when known).
175
+ async function baseOf(config, policy, repo) {
176
+ const run = (args, options = {}) => git(args, { cwd: config.dir, timeoutMs: 20000, ...options })
177
+ if (policy.base) {
178
+ for (const ref of [`refs/heads/${policy.base}`, ...(policy.remote ? [`refs/remotes/${policy.remote}/${policy.base}`] : [])]) {
179
+ const commit = (await run(['rev-parse', '--verify', '-q', `${ref}^{commit}`]).catch(() => '')).trim()
180
+ if (SHA_RE.test(commit)) return { commit, name: policy.base }
181
+ }
182
+ throw new FixRefusal('no_base', `The branch "${policy.base}" this agent starts fixes from does not exist on its machine.`)
183
+ }
184
+ // No branch named: the checkout's own commit, and only a clean checkout.
185
+ const status = await run(['--no-optional-locks', 'status', '--porcelain=v1', '--untracked-files=no', '--ignore-submodules=all'])
186
+ if (status.trim())
187
+ throw new FixRefusal(
188
+ 'checkout_dirty',
189
+ "The agent's checkout has uncommitted changes, which a fix would not include. On its machine: commit or stash them, or connect with --base BRANCH to always start from that branch.",
190
+ )
191
+ return { commit: repo.head, name: repo.branch }
192
+ }
193
+
194
+ // The worktree for one fix. Throws FixRefusal with words for the board.
195
+ // -> { work, workdir, base, checkoutBefore, ignored(rel) }
196
+ export async function prepareFix({ config, policy, job, env = process.env }) {
197
+ let repo
198
+ try {
199
+ repo = await checkRepo(config)
200
+ } catch (error) {
201
+ if (error instanceof BranchError)
202
+ throw new FixRefusal(error.code, REPO_REFUSALS[error.code] || `On the agent's machine: ${error.message}`)
203
+ throw error
204
+ }
205
+ const base = await baseOf(config, policy, repo)
206
+ const root = fixRoot(config.dir, env)
207
+ fs.mkdirSync(root, { recursive: true, mode: 0o700 })
208
+ sweepFixes(config.dir, env)
209
+ const body = typeof job.context.comment?.body === 'string' ? job.context.comment.body : commentText(job.context.comment || {}) || ''
210
+ let work
211
+ try {
212
+ work = await createAgentBranch(config, {
213
+ prefix: branchModeSettings(config, env).prefix,
214
+ kind: 'comment',
215
+ boardId: job.turn.board,
216
+ threadId: job.turn.thread,
217
+ commentId: job.turn.comment,
218
+ text: body.split('\0').join(''),
219
+ base: base.commit,
220
+ root,
221
+ })
222
+ } catch (error) {
223
+ if (error instanceof BranchError) throw new FixRefusal(error.code, `On the agent's machine: ${error.message}`)
224
+ throw error
225
+ }
226
+ const { tree } = work
227
+ const sub = path.relative(tree.dir, tree.projectDir).split(path.sep).filter(Boolean).join('/')
228
+ return {
229
+ work,
230
+ base,
231
+ checkoutBefore: await checkoutSignature(config),
232
+ // Whether Git's ignore rules leave this project-relative path out of a
233
+ // commit: asked of the person's repository (read only), about the path
234
+ // as such, tracked or not.
235
+ ignored: async (rel) => {
236
+ const file = sub ? `${sub}/${rel}` : rel
237
+ const out = await git(['check-ignore', '-q', '--no-index', '--', file], { cwd: repo.top, status: true, timeoutMs: 20000 })
238
+ return out.code === 0
239
+ },
240
+ workdir: {
241
+ root: tree.projectDir,
242
+ env: worktreeAgentEnv(work.root),
243
+ protect: [path.join(tree.projectDir, '.shapewall')],
244
+ sensitivePaths: [],
245
+ },
246
+ }
247
+ }
248
+
249
+ // Removes the fix's folder and record. The branch, when one was made, stays.
250
+ export async function dropFixFolder(prepared) {
251
+ const { work } = prepared
252
+ await removeWorktree({ tree: work.tree }).catch(() => {})
253
+ fs.rmSync(path.join(work.root, `${work.meta.id}.json`), { force: true })
254
+ }
255
+
256
+ // The mode and type of one path at a revision, or null.
257
+ async function entryAt(tree, rev, rel) {
258
+ const out = await git(['--git-dir', tree.gitDir, 'ls-tree', '-z', rev, '--', rel], { cwd: tree.repo }).catch(() => '')
259
+ const line = out.split('\0').find(Boolean)
260
+ if (!line) return null
261
+ const [mode, type] = line.slice(0, line.indexOf('\t')).split(' ')
262
+ return { mode, type }
263
+ }
264
+ const blobAt = (record, rev, rel) =>
265
+ git(['--git-dir', record.gitDir, 'cat-file', 'blob', `${rev}:${rel}`], { cwd: record.repo }).catch(() => null)
266
+
267
+ // The files of a fix with their line counts, read from its commit.
268
+ async function filesOf(record) {
269
+ const files = []
270
+ for (const item of record.files.slice(0, FIX_FILES_MAX)) {
271
+ const before = item.status === 'added' ? null : await blobAt(record, record.base, item.rel)
272
+ const after = await blobAt(record, record.commit, item.rel)
273
+ const diff = after === null ? null : diffForCard(item.path, before, after)
274
+ files.push({ path: item.path, status: item.status, added: diff?.added ?? null, removed: diff?.removed ?? null })
275
+ }
276
+ return files
277
+ }
278
+ async function summaryOf(record) {
279
+ const files = await filesOf(record)
280
+ return {
281
+ kind: 'remote-branch',
282
+ files,
283
+ added: files.reduce((sum, item) => sum + (item.added || 0), 0),
284
+ removed: files.reduce((sum, item) => sum + (item.removed || 0), 0),
285
+ more: Math.max(0, record.files.length - files.length),
286
+ branch: {
287
+ name: record.branch,
288
+ commit: record.commit,
289
+ base: record.base,
290
+ baseName: record.baseName || null,
291
+ pushed: false,
292
+ remote: null,
293
+ held: false,
294
+ },
295
+ pr: null,
296
+ }
297
+ }
298
+
299
+ // The whole diff of a fix, every changed file, for the "Push this fix" card.
300
+ // null when it cannot be shown in full (then it cannot be approved from the board).
301
+ export async function heldDiff(record) {
302
+ const files = []
303
+ for (const item of record.files) {
304
+ const before = item.status === 'added' ? null : await blobAt(record, record.base, item.rel)
305
+ const after = await blobAt(record, record.commit, item.rel)
306
+ if (after === null) return null
307
+ files.push({ path: item.path, oldText: before, newText: after, outside: false })
308
+ }
309
+ const diff = files.length ? diffForFiles(files) : null
310
+ return diff && !diff.truncated ? diff : null
311
+ }
312
+
313
+ // The end of a fix turn. Commits what the agent changed when it is exactly
314
+ // what was allowed. `approved`: Map of project-relative path -> { hash, auto }
315
+ // (sha256 of the bytes that were shown and allowed; `auto`: nobody looked).
316
+ // Then pushes (pushFix), unless an edit went without asking: such a fix is
317
+ // held (its record is kept beside the copies) and `out.held` is that record.
318
+ // -> { status: 'branch-ready' | 'needs-human' | 'stopped', summary, notes, line, held }
319
+ export async function finishFix({
320
+ config,
321
+ policy,
322
+ prepared,
323
+ job,
324
+ approved,
325
+ signal = null,
326
+ env = process.env,
327
+ fetchImpl = undefined,
328
+ log = () => {},
329
+ push = pushBranch,
330
+ }) {
331
+ const { work, base, checkoutBefore } = prepared
332
+ const { tree, meta } = work
333
+ const notes = []
334
+ const out = { status: 'needs-human', summary: null, notes, line: null, held: null }
335
+ const sub = path.relative(tree.dir, tree.projectDir).split(path.sep).filter(Boolean).join('/')
336
+ const inProject = (rel) => (!sub ? rel : rel.startsWith(`${sub}/`) ? rel.slice(sub.length + 1) : null)
337
+ const body = typeof job.context.comment?.body === 'string' ? job.context.comment.body : ''
338
+ const subject = inertLine(body)
339
+ const message = `Fix for Shapewall comment ${job.turn.comment}: ${subject || 'agent change'}\n\nshapewall:${job.turn.board}/${job.turn.comment}\nMade by a connected agent from a hosted board; review before merging.\n`
340
+ const stopped = () => {
341
+ out.status = 'stopped'
342
+ out.summary = null
343
+ out.line = null
344
+ return out
345
+ }
346
+ try {
347
+ if (aborted(signal)) return stopped()
348
+ let commit = null
349
+ try {
350
+ commit = await commitAgentBranch(config, { ...work, message })
351
+ } catch (error) {
352
+ log(`fix: commit: ${error.message}`)
353
+ notes.push(error instanceof BranchError ? error.message : "The agent's work could not be committed on its branch.")
354
+ return out
355
+ }
356
+ if (!commit?.committed) {
357
+ if (approved.size) notes.push('Nothing was committed: the edits that were allowed left no change in the files Git keeps.')
358
+ return out
359
+ }
360
+ const takeBack = () =>
361
+ git(['--git-dir', tree.gitDir, 'update-ref', '-d', `refs/heads/${meta.branch}`, commit.commit], { cwd: tree.repo }).catch(() => {})
362
+ // Exactly what was shown and allowed. Every changed file: allowed, those
363
+ // very bytes, a plain file, the mode it had (a new file: not executable).
364
+ const beyond = []
365
+ for (const rel of commit.files) {
366
+ const shown = inProject(rel)
367
+ const expected = shown === null ? null : approved.get(shown)?.hash
368
+ let ok = Boolean(expected) && !commit.deleted.includes(rel) && !commit.links.includes(rel)
369
+ if (ok) {
370
+ try {
371
+ const file = path.join(tree.dir, rel)
372
+ const stat = fs.lstatSync(file)
373
+ const was = await entryAt(tree, tree.base, rel)
374
+ const now = await entryAt(tree, commit.commit, rel)
375
+ ok =
376
+ stat.isFile() &&
377
+ sha256(fs.readFileSync(file)) === expected &&
378
+ now?.type === 'blob' &&
379
+ (was ? was.type === 'blob' && was.mode === now.mode : now.mode === '100644')
380
+ } catch {
381
+ ok = false
382
+ }
383
+ }
384
+ if (!ok) beyond.push(shown ?? rel)
385
+ }
386
+ // And every allowed file is in it: one that Git left out (ignored, kept
387
+ // at its base version) would be an allowed edit that silently vanished.
388
+ const changed = new Set(commit.files.map((rel) => inProject(rel)))
389
+ const missing = []
390
+ for (const [rel, entry] of approved) {
391
+ if (changed.has(rel)) continue
392
+ // An edit that left the file as the base has it is no change at all.
393
+ const baseText = await blobAt({ gitDir: tree.gitDir, repo: tree.repo }, tree.base, sub ? `${sub}/${rel}` : rel)
394
+ if (baseText === null || sha256(baseText) !== entry.hash) missing.push(rel)
395
+ }
396
+ if (beyond.length || missing.length) {
397
+ await takeBack()
398
+ const list = (items) => `${items.slice(0, 5).join(', ')}${items.length > 5 ? ` and ${items.length - 5} more` : ''}`
399
+ notes.push(
400
+ beyond.length
401
+ ? `Nothing was committed: the agent's folder held changes beyond the edits that were allowed (${list(beyond)}).`
402
+ : `Nothing was committed: it would not have been what was allowed. Git leaves ${list(missing)} out of a commit (ignored, or one of its own files).`,
403
+ )
404
+ return out
405
+ }
406
+ if (aborted(signal)) {
407
+ await takeBack()
408
+ return stopped()
409
+ }
410
+ const record = {
411
+ id: meta.id,
412
+ branch: meta.branch,
413
+ commit: commit.commit,
414
+ base: tree.base,
415
+ baseName: base.name || null,
416
+ gitDir: tree.gitDir,
417
+ repo: tree.repo,
418
+ board: job.turn.board,
419
+ comment: job.turn.comment,
420
+ subject,
421
+ files: commit.files.map((rel) => ({
422
+ rel,
423
+ path: inProject(rel) ?? rel,
424
+ status: commit.added.includes(rel) ? 'added' : 'modified',
425
+ })),
426
+ madeAt: new Date().toISOString(),
427
+ }
428
+ out.summary = await summaryOf(record)
429
+ out.status = 'branch-ready'
430
+ out.line = `Fix ready on branch ${meta.branch}.`
431
+ // An edit nobody looked at: the fix stays here until someone has seen its whole diff.
432
+ if ([...approved.values()].some((entry) => entry.auto)) {
433
+ const file = heldFile(work.root, meta.id)
434
+ fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
435
+ fs.renameSync(`${file}.tmp`, file)
436
+ out.summary.branch.held = true
437
+ out.held = { ...record, file }
438
+ out.line = `Fix ready on branch ${meta.branch}, on the agent's machine. It is not pushed until someone has looked at its whole diff on the board (Push this fix).`
439
+ return out
440
+ }
441
+ const pushed = await pushFix({ config, policy, record, signal, env, fetchImpl, log, push })
442
+ out.summary = pushed.summary
443
+ notes.push(...pushed.notes)
444
+ if (pushed.line) out.line = pushed.line
445
+ return out
446
+ } finally {
447
+ if (checkoutBefore && (await checkoutSignature(config)) !== checkoutBefore)
448
+ notes.push("Files in the agent's own checkout changed during this fix. Check git status on its machine.")
449
+ await dropFixFolder(prepared)
450
+ sweepFixes(config.dir, env)
451
+ }
452
+ }
453
+
454
+ // A pull request link this machine passes on: on the host of the GitHub it
455
+ // is set up for, shaped like one. Anything else is no link.
456
+ export function pullLink(url, settings) {
457
+ try {
458
+ const parsed = new URL(String(url))
459
+ const api = new URL(settings?.apiUrl || DEFAULT_API_URL)
460
+ const host = api.hostname === 'api.github.com' ? 'github.com' : api.hostname
461
+ if (parsed.protocol !== 'https:' || parsed.hostname !== host || parsed.username || parsed.password) return null
462
+ if (!/^\/[\w.-]+\/[\w.-]+\/pull\/\d+$/.test(parsed.pathname) || parsed.search || parsed.hash) return null
463
+ return parsed.href.slice(0, 300)
464
+ } catch {
465
+ return null
466
+ }
467
+ }
468
+
469
+ // Pushes a committed fix and opens its pull request, where this machine can.
470
+ // `record`: what finishFix made (or a held fix, read back). Nothing that
471
+ // runs on install, build, test or CI is pushed from here.
472
+ // -> { summary, notes, line, pushed }
473
+ export async function pushFix({
474
+ config,
475
+ policy,
476
+ record,
477
+ signal = null,
478
+ env = process.env,
479
+ fetchImpl = undefined,
480
+ log = () => {},
481
+ push = pushBranch,
482
+ }) {
483
+ const notes = []
484
+ const summary = await summaryOf(record)
485
+ const out = { summary, notes, line: null, pushed: false }
486
+ const remote = policy.remote
487
+ const hasRemote = remote ? (await git(['remote', 'get-url', remote], { cwd: config.dir }).catch(() => '')).trim() : ''
488
+ if (!hasRemote || aborted(signal)) return out
489
+ // A pushed branch runs CI, with the repository's secrets, before anyone reviews it.
490
+ const guarded = filesThatRun(record.files.map((item) => item.rel))
491
+ if (guarded.length) {
492
+ notes.push(
493
+ `Not pushed: the fix changes ${guarded.slice(0, 3).join(', ')}${guarded.length > 3 ? ', ...' : ''}, which runs on install, build, test or CI. Review the branch on the agent's machine.`,
494
+ )
495
+ return out
496
+ }
497
+ try {
498
+ await push({ tree: { branch: record.branch, gitDir: record.gitDir, repo: record.repo }, remote })
499
+ summary.branch.pushed = true
500
+ summary.branch.remote = remote
501
+ out.pushed = true
502
+ out.line = `Fix ready on branch ${record.branch}, pushed to ${remote}.`
503
+ } catch (error) {
504
+ log(`fix: push: ${error.message}`)
505
+ notes.push(`The branch could not be pushed to "${remote}" from the agent's machine. It is there, on that machine.`)
506
+ return out
507
+ }
508
+ // Stop after the push: the branch is out, and the thread says so. No pull request.
509
+ if (aborted(signal)) {
510
+ notes.push(`Stopped after the branch ${record.branch} was pushed to "${remote}": it exists there. No pull request was opened.`)
511
+ return out
512
+ }
513
+ const settings = githubSettings(config, env)
514
+ if (!settings.ready) return out
515
+ try {
516
+ let into = record.baseName
517
+ if (!into) {
518
+ const head = await git(['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`], { cwd: config.dir }).catch(() => '')
519
+ into = head.trim().split('/').slice(1).join('/') || 'main'
520
+ }
521
+ const pull = await openPullRequest(config, {
522
+ head: record.branch,
523
+ base: into,
524
+ title: `Shapewall comment ${record.comment}: ${inertLine(record.subject, 70) || 'fix'}`,
525
+ body: [
526
+ `Made by a connected Shapewall agent for comment shapewall:${record.board}/${record.comment}.`,
527
+ '',
528
+ 'The request came from a board comment (untrusted text). Review the whole diff before merging.',
529
+ ].join('\n'),
530
+ env,
531
+ ...(fetchImpl ? { fetchImpl } : {}),
532
+ })
533
+ const url = pullLink(pull.url, settings)
534
+ if (url) {
535
+ summary.pr = { number: pull.number, url }
536
+ out.line = `Fix ready: ${url} (branch ${record.branch}).`
537
+ } else notes.push(`A pull request (number ${pull.number}) was opened for the branch.`)
538
+ } catch (error) {
539
+ log(`fix: pull request: ${error.message}`)
540
+ notes.push("The branch was pushed, but the pull request could not be opened from the agent's machine.")
541
+ }
542
+ return out
543
+ }
544
+
545
+ // The newest held fix of a comment on this machine, checked field by field
546
+ // (the folder is the person's, but everything that reaches git is checked
547
+ // again), and only while its branch still is the commit that was made and
548
+ // that commit changes exactly the files the record names.
549
+ export async function readHeld({ config, env = process.env, board, comment }) {
550
+ let root
551
+ let names = []
552
+ try {
553
+ root = fixRoot(config.dir, env)
554
+ names = fs.readdirSync(root).filter((name) => /^held-\d{14}-[a-f0-9]{6}\.json$/.test(name))
555
+ } catch {
556
+ return null
557
+ }
558
+ const repo = await checkRepo(config).catch(() => null)
559
+ if (!repo) return null
560
+ for (const name of names.sort().reverse()) {
561
+ let raw
562
+ try {
563
+ raw = JSON.parse(fs.readFileSync(path.join(root, name), 'utf8'))
564
+ } catch {
565
+ continue
566
+ }
567
+ if (raw?.board !== board || raw?.comment !== comment) continue
568
+ if (!validBranchName(raw.branch) || !SHA_RE.test(String(raw.commit || '')) || !SHA_RE.test(String(raw.base || ''))) continue
569
+ const listed = Array.isArray(raw.files) ? raw.files : []
570
+ const files = listed.filter(
571
+ (item) =>
572
+ typeof item?.rel === 'string' &&
573
+ typeof item?.path === 'string' &&
574
+ !item.rel.split('/').some((part) => !part || part === '..' || part === '.') &&
575
+ ['added', 'modified'].includes(item.status),
576
+ )
577
+ if (!files.length || files.length !== listed.length) continue
578
+ const record = {
579
+ id: name.slice(5, -5),
580
+ branch: raw.branch,
581
+ commit: raw.commit,
582
+ base: raw.base,
583
+ baseName: typeof raw.baseName === 'string' && /^[\w./-]{1,120}$/.test(raw.baseName) ? raw.baseName : null,
584
+ // Never from the record: this machine's own repository.
585
+ gitDir: repo.gitDir,
586
+ repo: repo.top,
587
+ board,
588
+ comment,
589
+ subject: inertLine(raw.subject),
590
+ files: files.map((item) => ({ rel: item.rel, path: item.path, status: item.status })),
591
+ file: path.join(root, name),
592
+ }
593
+ const tip = (await git(['rev-parse', '--verify', '-q', `refs/heads/${record.branch}`], { cwd: config.dir }).catch(() => '')).trim()
594
+ if (tip !== record.commit) continue
595
+ const inCommit = (
596
+ await git(['diff-tree', '-r', '-z', '--no-renames', '--name-only', record.base, record.commit], { cwd: config.dir }).catch(() => '')
597
+ )
598
+ .split('\0')
599
+ .filter(Boolean)
600
+ .sort()
601
+ if (JSON.stringify(inCommit) !== JSON.stringify(record.files.map((item) => item.rel).sort())) continue
602
+ return record
603
+ }
604
+ return null
605
+ }
606
+ export const dropHeld = (record) => fs.rmSync(record.file, { force: true })
607
+ export async function heldSummary(record) {
608
+ const summary = await summaryOf(record)
609
+ summary.branch.held = true
610
+ return summary
611
+ }