@fro.bot/systematic 3.25.1 → 3.26.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.
- package/HARNESSES.md +49 -1
- package/README.md +1 -1
- package/dist/ce-review-validator.d.ts +22 -3
- package/dist/cli.js +69 -34
- package/dist/{index-bmsgc2em.js → index-1dyb2x0z.js} +1 -0
- package/dist/index.js +1 -1
- package/dist/lib/bundled-names.d.ts +1 -1
- package/dist/lib/review-artifact-path.d.ts +66 -0
- package/dist/lib/review-artifact-schema.d.ts +12 -0
- package/dist/lib/review-pipeline.d.ts +25 -17
- package/dist/lib/review-return-validator.d.ts +3 -6
- package/dist/pi.js +1 -0
- package/package.json +2 -1
- package/skills/ce-review/SKILL.md +2 -2
- package/skills/ce-review/references/pipeline-invocation.md +36 -1
- package/skills/ce-review/references/review-pipeline-schema.json +3 -3
- package/skills/ce-review/references/review-summary-schema.json +12 -12
- package/skills/ce-review/references/validator-template.md +12 -11
- package/skills/ce-review/scripts/validate-review.mjs +355 -136
- package/skills/git-commit-push-pr/SKILL.md +79 -6
- package/skills/pr-attachments/SKILL.md +764 -0
- package/skills/pr-attachments/scripts/pr-attachments.mjs +3140 -0
|
@@ -0,0 +1,764 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pr-attachments
|
|
3
|
+
description: "Use when attaching local screenshots or other images to a pull request, publishing evidence images as commit-pinned embeds in a managed Demo section of the PR description, re-pinning those embeds after a rebase or force-push, or cleaning up evidence images once the PR is done."
|
|
4
|
+
argument-hint: "[mode:embed] [image paths...] [pr:<number or branch>] | mode:carry old=<old body file> new=<new body file>"
|
|
5
|
+
metadata:
|
|
6
|
+
harness-portability: neutral-v1
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# PR Attachments
|
|
10
|
+
|
|
11
|
+
Publish local images as commit-pinned embeds in a managed `## Demo` section of a pull request description. Confirm that every embed serves an image before the description is written.
|
|
12
|
+
|
|
13
|
+
The images are committed under `docs/evidence/<topic>/` on the PR head branch and linked by commit SHA. Cleanup removes them from the branch once the PR is done. This skill does not capture screenshots.
|
|
14
|
+
|
|
15
|
+
The managed section starts at a `## Demo` heading at column 0. A `## Demo` line that is indented, or that sits inside a code fence, a quote, a comment or a `<pre>`, `<script>`, `<style>` or `<textarea>` block, is text and not the section. The helper never replaces or copies it, and it never removes a line outside the section.
|
|
16
|
+
|
|
17
|
+
The helper replaces or copies an existing Demo section only when every non-blank line under its heading is one this skill writes: an image embed (``) in the raw or the blob form. A heading, a fence, HTML, a table or free prose under the heading means the section is not the managed one, or its end was misjudged. The helper then changes nothing and reports `unexpected-section-content`.
|
|
18
|
+
|
|
19
|
+
| Mode | Trigger | Writes the description |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| PR mode | An open PR and image paths | Yes |
|
|
22
|
+
| Embed mode | `mode:embed` and image paths | No. Returns a Demo file and a status line |
|
|
23
|
+
| Carry mode | `mode:carry`, `old=` and `new=` | No. Edits the new body file in place and returns a status line |
|
|
24
|
+
| Re-pin mode | An open PR and no paths | Only when a pin is stale |
|
|
25
|
+
| Cleanup | Offered at the end of PR mode and Re-pin mode | No. Removes the evidence files from the branch |
|
|
26
|
+
|
|
27
|
+
## Preconditions
|
|
28
|
+
|
|
29
|
+
- `git`, and `gh` signed in with push access to the head repository.
|
|
30
|
+
- The helper needs node 18+ on PATH. Check `node --version` once. Without it, stop.
|
|
31
|
+
- Carry mode needs only node. The other modes also need the repository root: `git rev-parse --show-prefix` prints nothing there.
|
|
32
|
+
- Run from the repository root.
|
|
33
|
+
- Shell state does not persist between tool calls. Fill every placeholder in angle brackets with a real value in every block.
|
|
34
|
+
- Every block that calls the helper starts with the same anchor lines. Reuse them verbatim. Set `SKILL_DIR` to the skill directory stated when this skill loads.
|
|
35
|
+
|
|
36
|
+
## Never bypass the helper
|
|
37
|
+
|
|
38
|
+
The helper does the work that must be exact: classification, byte-exact splicing, pin selection, the cleanup set and verification. A helper failure (exit 1 or exit 2) is never permission to hand-write its output.
|
|
39
|
+
|
|
40
|
+
- If node is missing, cannot launch, or the helper exits 2, stop and report the state reached: what is committed, what is pushed, and that the description is untouched. In embed mode the reason is `node-unavailable` when node is missing or cannot launch.
|
|
41
|
+
- Never write Demo text, a pin, a cleanup set or a verification verdict by hand.
|
|
42
|
+
- Never run `git rm` by hand.
|
|
43
|
+
- A `usage-error` or `internal-error` is a stop in every mode. Report its `error`, and its `field` when it has one: `field` names the input field that failed. In embed mode the reason is `helper-failed`.
|
|
44
|
+
- Any other `git` or `gh` command that fails is a stop too. In embed mode the reason is `git-failed`.
|
|
45
|
+
|
|
46
|
+
In embed mode every stop ends with the failed status line (Step 8), and its reason comes from the table there. In carry mode every stop ends with the failed status line (Carry mode).
|
|
47
|
+
|
|
48
|
+
## Step 1: Read the arguments
|
|
49
|
+
|
|
50
|
+
Read tokens from the skill arguments, or from the invoking instruction when none are shown. Some hosts pass no arguments, so the instruction text then carries the tokens. Use no positional placeholders.
|
|
51
|
+
|
|
52
|
+
Split on whitespace. A path with spaces must be wrapped in double quotes; strip the quotes after splitting. A path that starts with `mode:`, `pr:`, `old=` or `new=` must be written with a leading `./`.
|
|
53
|
+
|
|
54
|
+
- `mode:embed` selects embed mode.
|
|
55
|
+
- `mode:carry` selects carry mode and skips Steps 2 to 8; go straight to Carry mode.
|
|
56
|
+
- Any other `mode:` token stops the run with an error that names the token. Two different `mode:` values stop the run too. The same `mode:` token twice counts as one token.
|
|
57
|
+
- `pr:<number or branch>` selects the PR. Without it, use the PR for the current branch.
|
|
58
|
+
- `old=<file>` and `new=<file>` are for carry mode only. An `old=` or `new=` token outside carry mode stops the run with a message that names the token. It is never read as an image path. In embed mode the reason is `bad-arguments`.
|
|
59
|
+
- Every other token is an image path, relative to the repository root.
|
|
60
|
+
|
|
61
|
+
`mode:embed` with no paths stops: embed mode needs image paths. In embed mode the reason is `no-target`.
|
|
62
|
+
|
|
63
|
+
## Step 2: Classify the images
|
|
64
|
+
|
|
65
|
+
Skip this step when there are no paths. This step is local and runs before any network call, so a bad batch is caught first.
|
|
66
|
+
|
|
67
|
+
Read the current branch. It is the topic source:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
git branch --show-current
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Classify the paths. JSON-escape each string:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
77
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
78
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" classify <<'JSON'
|
|
79
|
+
{"paths": ["<image path>"], "branch": "<current branch>"}
|
|
80
|
+
JSON
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A detached HEAD prints no branch. Ask the user for a topic and send `"topic"` in place of `"branch"`. A topic from the user goes through the same slug function and wins over the branch.
|
|
84
|
+
|
|
85
|
+
Then check which destinations already exist at `HEAD`. Run it once with every `destination` from the result:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
set -- "<destination 1>" "<destination 2>";
|
|
89
|
+
for DEST in "$@"; do printf '%s ' "$DEST"; git rev-parse --verify --quiet "HEAD:$DEST" || echo absent; done
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
If any destination exists, run classify again with `"existing"` set to a map of destination to the blob SHA printed here. Include only destinations whose line printed a 40-hex SHA, and omit the `absent` ones. Copy the SHAs from the output. The second result wins.
|
|
93
|
+
|
|
94
|
+
Route the result:
|
|
95
|
+
|
|
96
|
+
- `accepted` (exit 0): `entries` hold `source`, `destination`, `type`, `bytes`, `blob_sha` and `status`, which is `new` or `reused`. Surface every warning: `trailing-data` means bytes after the image end are published as is.
|
|
97
|
+
- `rejected` (exit 1): the whole batch is rejected and nothing is copied. Relay each rejection `message` as is, for example "SVG is not supported by this skill". A file over 10 MiB is rejected before anything is published, because GitHub does not serve larger files as images; its code is `too-large`. Stop. In embed mode the reason is `rejected-images`.
|
|
98
|
+
- `needs-input` (exit 1): read `asks` and settle each with the user, then classify again. If the user cannot or will not settle one, stop. In embed mode the reason is `needs-input`.
|
|
99
|
+
- `empty-topic`: ask for a topic and send it as `"topic"`.
|
|
100
|
+
- `empty-name`: the source name slugs to nothing. Ask for a copy under a better name. Never move the original.
|
|
101
|
+
- `duplicate-destination`: two inputs map to one name. Ask which one to rename.
|
|
102
|
+
- `destination-conflict`: different bytes already sit at the destination. Ask for another topic or a rename.
|
|
103
|
+
- `usage-error` (exit 2) or `internal-error`: stop. In embed mode the reason is `helper-failed`.
|
|
104
|
+
|
|
105
|
+
## Step 3: Resolve the target and pick the mode
|
|
106
|
+
|
|
107
|
+
Pick the mode from the tokens and whether an open PR exists:
|
|
108
|
+
|
|
109
|
+
| Tokens | Open PR | Mode |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| `mode:carry`, `old=` and `new=` | Not needed | Carry mode |
|
|
112
|
+
| `mode:embed` and paths | Not needed | Embed mode |
|
|
113
|
+
| Paths, no `mode:embed` | Yes | PR mode |
|
|
114
|
+
| No paths, no `mode:embed` | Yes | Re-pin mode |
|
|
115
|
+
| No `mode:` token | No | Stop |
|
|
116
|
+
|
|
117
|
+
A load that sees no `mode:` token and finds no open PR stops with this message and never guesses a mode: open the PR first, or run through git-commit-push-pr. Never infer paths or a mode from the working directory.
|
|
118
|
+
|
|
119
|
+
### Embed mode
|
|
120
|
+
|
|
121
|
+
Resolve the head from the upstream of the current branch:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
git rev-parse --abbrev-ref "@{u}"
|
|
125
|
+
git remote -v
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The upstream prints `<remote>/<branch>`. With no upstream, stop. The remote is the text before the first `/` and must be listed by `git remote -v`. The head branch is the rest. Read owner and repo from that remote's URL. The URL host must be `github.com`; any other host is refused. Step 4 then runs `gh repo view` on that repository. In embed mode the reason for a missing upstream, an unlisted remote or a refused host is `no-target`.
|
|
129
|
+
|
|
130
|
+
### PR mode and Re-pin mode
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
gh pr view "<PR>" --json number,url,state,headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner,isCrossRepository
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Omit the PR argument when no `pr:` token was given.
|
|
137
|
+
|
|
138
|
+
- The command fails, or `state` is not `OPEN`: there is no open PR. Stop with the message above.
|
|
139
|
+
- A null `headRepository` (a deleted fork) is refused: stop.
|
|
140
|
+
- The head repo is `headRepositoryOwner.login` and `headRepository.name`.
|
|
141
|
+
- The remote is the one in `git remote -v` whose URL is `github.com` and this repo, compared without case. If none maps, stop and name the remote to add. If several map, use `origin`, else ask.
|
|
142
|
+
- Another host is refused. Fork PRs need push access, which Step 4 checks.
|
|
143
|
+
|
|
144
|
+
The PR head must be checked out and level. Fetch, then compare:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
git fetch "<remote>" "<head branch>"
|
|
148
|
+
git branch --show-current
|
|
149
|
+
git rev-parse HEAD
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The current branch must equal `headRefName` and `HEAD` must equal `headRefOid`. On any difference, stop with the exact fix. If `git merge-base --is-ancestor "<headRefOid>" HEAD` succeeds, local is ahead: say push first. Otherwise say to check out the PR head and update it to `headRefOid`.
|
|
153
|
+
|
|
154
|
+
## Step 4: Check visibility
|
|
155
|
+
|
|
156
|
+
Applies to embed mode, PR mode and Re-pin mode.
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
gh repo view "<owner>/<repo>" --json visibility,isPrivate,viewerPermission,url,defaultBranchRef
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Every repository must pass these checks:
|
|
163
|
+
|
|
164
|
+
- `url` starts with `https://github.com/`.
|
|
165
|
+
- `viewerPermission` is `ADMIN`, `MAINTAIN` or `WRITE`. Otherwise stop: the user cannot push to the head repository. A rejected push stops the run too. In embed mode the reason is `no-push-access`.
|
|
166
|
+
- In embed mode and PR mode, a push target equal to the default branch is refused: stop. The push target is the upstream branch in embed mode and `headRefName` in PR mode, and the default branch is `defaultBranchRef`. Pushing there would send the evidence commit, and any local commits that are not on the remote yet, straight to the default branch. Tell the user to create a feature branch and set its upstream, then run again. In embed mode the reason is `default-branch`. Re-pin mode does not push, so it skips this check. Cleanup applies it before its own push.
|
|
167
|
+
|
|
168
|
+
Then pick the link form from the visibility:
|
|
169
|
+
|
|
170
|
+
- `visibility` is `PUBLIC` and `isPrivate` is false: the repository is public, so use the raw form and go on.
|
|
171
|
+
- Anything else is a private, internal or unknown-visibility repository. Use the blob form, after the explicit answer below.
|
|
172
|
+
|
|
173
|
+
If `gh repo view` fails, stop. Remember the form for Steps 5 to 8. Re-pin mode takes it from the embeds that already exist.
|
|
174
|
+
|
|
175
|
+
### Private, internal and unknown-visibility repositories
|
|
176
|
+
|
|
177
|
+
PR mode and embed mode only. Re-pin mode publishes nothing, so it asks nothing and goes straight on.
|
|
178
|
+
|
|
179
|
+
Private repositories use the blob form because raw links do not render for signed-in members. Proceeding emits the blob form for every embed, and only the blob form.
|
|
180
|
+
|
|
181
|
+
Before anything is published, ask the user and wait for the answer. Name the repository:
|
|
182
|
+
|
|
183
|
+
> `<owner>/<repo>` is not public. The images stay in the repository's history. If the repository is later made public, or is forked, the images become public. Cleanup removes them from the branch but not from history. Publish them here?
|
|
184
|
+
|
|
185
|
+
Require an explicit answer. There is no default answer. Never infer consent from the original request. Only an explicit yes proceeds. On anything else the user declines: nothing is published and the images stay local. In embed mode finish with this line, and no Demo file:
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
pr-attachments: status=failed evidence=none reason=declined
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Step 5: List the set and confirm the scrub
|
|
192
|
+
|
|
193
|
+
PR mode and embed mode only.
|
|
194
|
+
|
|
195
|
+
List for the user:
|
|
196
|
+
|
|
197
|
+
- the topic slug, for confirmation;
|
|
198
|
+
- each source, its destination, type, size and `blob_sha`, and whether it is `new` or `reused`;
|
|
199
|
+
- every warning from Step 2.
|
|
200
|
+
|
|
201
|
+
In embed mode the push also publishes local commits that are not on the remote yet. List them:
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
git log --oneline "@{u}..HEAD"
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Then run the scrub confirmation. Ask the user, and wait for the answer:
|
|
208
|
+
|
|
209
|
+
> These images will be published to a public GitHub repository. Open each one. Confirm that its visible content shows no secrets, tokens, credentials, personal data or private URLs.
|
|
210
|
+
|
|
211
|
+
For a private, internal or unknown-visibility repository, say "a private GitHub repository" instead of "a public GitHub repository".
|
|
212
|
+
|
|
213
|
+
The scrub confirmation covers visible content only. Metadata inside an image (EXIF, text chunks, trailing bytes) is not stripped and is published as is.
|
|
214
|
+
|
|
215
|
+
Require an explicit yes. There is no default answer. Never infer consent from the original request. On anything else, stop and publish nothing. In embed mode the reason is `declined`.
|
|
216
|
+
|
|
217
|
+
## Step 6: Publish the evidence commit
|
|
218
|
+
|
|
219
|
+
PR mode and embed mode only. If every entry is `reused`, skip the copy and the commit and go to the push.
|
|
220
|
+
|
|
221
|
+
### Copy into place
|
|
222
|
+
|
|
223
|
+
Check every destination, new and reused:
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
set -- "<destination 1>" "<destination 2>";
|
|
227
|
+
for DEST in "$@"; do git check-ignore -- "$DEST"; git check-attr text eol filter -- "$DEST" | grep -Ev ': (text: (unspecified|unset|auto)|eol: unspecified|filter: unspecified)$'; git status --porcelain --untracked-files=all -- "$DEST"; done
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Any output stops the run. In embed mode the reason is `destination-blocked`:
|
|
231
|
+
|
|
232
|
+
- `git check-ignore` printed the path: the destination is gitignored, so stop and never force-add.
|
|
233
|
+
- `git check-attr` printed a line: a git attribute would rewrite the bytes when they are staged. A `filter` (LFS or another) does, and so does an `eol` setting or a `text` that is set, such as `docs/evidence/** text eol=lf`, because git then normalizes the line endings and the committed file is no longer the approved image. Stop, and name the attribute. An unset `text` (`-text`, `binary`) and `text=auto` pass. With `auto`, git treats a real image as binary, because image files hold NUL bytes, and leaves it alone. The checks of the staged and the committed blob below catch what this rule cannot see, such as `core.autocrlf`.
|
|
234
|
+
- `git status` printed a line: the destination holds uncommitted content. Stop.
|
|
235
|
+
|
|
236
|
+
Copy each new entry. The copy leaves the original in place. Before each copy, recompute the git blob SHA of the source from its raw bytes and compare it with the `blob_sha` that classify reported, as shown in the Step 5 list. When the SHA differs, the file changed after the list was shown and confirmed, so stop and copy nothing. In embed mode the reason is `source-changed`. `--no-filters` makes git hash the raw bytes, which is how the helper computes `blob_sha`, so a text or LFS filter cannot change the result.
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
SRC="<source path>";
|
|
240
|
+
DEST="<destination path>";
|
|
241
|
+
BLOB_SHA="<blob_sha from the Step 5 list>";
|
|
242
|
+
if [ "$(git hash-object --no-filters -- "$SRC")" = "$BLOB_SHA" ]; then mkdir -p "$(dirname "$DEST")" && cp -- "$SRC" "$DEST"; else echo "source-changed $SRC"; false; fi
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Commit by pathspec
|
|
246
|
+
|
|
247
|
+
Stage and commit only the new destinations. A pathspec commit leaves other staged work out of the commit. Never pass `--no-verify`; a failing hook stops the run.
|
|
248
|
+
|
|
249
|
+
Stage the destinations:
|
|
250
|
+
|
|
251
|
+
```bash
|
|
252
|
+
set -- "<destination 1>" "<destination 2>";
|
|
253
|
+
git add -- "$@"
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Staging can change bytes: a `.gitattributes` text, eol or filter setting, or `core.autocrlf`, normalizes the file as it goes in. The copy check passed on the source, so check what is staged. Each item is a destination and the `blob_sha` that classify reported for it, as shown in the Step 5 list:
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
set -- "<destination 1> <blob_sha 1>" "<destination 2> <blob_sha 2>";
|
|
260
|
+
FAILED=0
|
|
261
|
+
for ITEM in "$@"; do
|
|
262
|
+
DEST="${ITEM% *}"; EXPECTED="${ITEM##* }"
|
|
263
|
+
ACTUAL="$(git rev-parse ":$DEST")"
|
|
264
|
+
[ "$ACTUAL" = "$EXPECTED" ] || { echo "blob-mismatch staged $DEST ${ACTUAL:-none}"; FAILED=1; }
|
|
265
|
+
done
|
|
266
|
+
test "$FAILED" = 0
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Exit 0 passes. A `blob-mismatch` line means that git changed the bytes while staging. Unstage the paths with the recovery below, commit nothing and stop. Say that the likely cause is a `.gitattributes` text, eol or filter setting, or `core.autocrlf`. In embed mode the reason is `blob-mismatch`.
|
|
270
|
+
|
|
271
|
+
Commit the staged destinations:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
TOPIC="<topic slug>";
|
|
275
|
+
set -- "<destination 1>" "<destination 2>";
|
|
276
|
+
git commit -m "chore(evidence): add screenshots for $TOPIC" -- "$@"
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
If the commit fails (a hook rejects it, or git reports an error), run `git restore --staged` with the same paths and check that none of them is still staged. Then stop with the state reached. The copied files stay in the working tree, untracked. In embed mode the reason is `commit-failed`.
|
|
280
|
+
|
|
281
|
+
```bash
|
|
282
|
+
set -- "<destination 1>" "<destination 2>";
|
|
283
|
+
git restore --staged -- "$@"
|
|
284
|
+
test -z "$(git diff --cached --name-only -- "$@")"
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Exit 0 means that none of the paths is staged. A failed cleanup commit uses the same recovery.
|
|
288
|
+
|
|
289
|
+
A hook can also change the content during the commit, so check the committed blobs against the same list:
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
set -- "<destination 1> <blob_sha 1>" "<destination 2> <blob_sha 2>";
|
|
293
|
+
FAILED=0
|
|
294
|
+
for ITEM in "$@"; do
|
|
295
|
+
DEST="${ITEM% *}"; EXPECTED="${ITEM##* }"
|
|
296
|
+
ACTUAL="$(git rev-parse "HEAD:$DEST")"
|
|
297
|
+
[ "$ACTUAL" = "$EXPECTED" ] || { echo "blob-mismatch committed $DEST ${ACTUAL:-none}"; FAILED=1; }
|
|
298
|
+
done
|
|
299
|
+
test "$FAILED" = 0
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
On a `blob-mismatch` line, do not push. The altered image is in a local commit. Leave the commit as it is and report the state: the evidence commit is local, and it holds a blob that differs from the approved one. In embed mode the reason is `blob-mismatch`, and the evidence commit is local.
|
|
303
|
+
|
|
304
|
+
### Assert the committed file set
|
|
305
|
+
|
|
306
|
+
The commit must hold exactly the new destinations:
|
|
307
|
+
|
|
308
|
+
```bash
|
|
309
|
+
set -- "<destination 1>" "<destination 2>";
|
|
310
|
+
EXPECTED="$(printf '%s\n' "$@" | LC_ALL=C sort)"
|
|
311
|
+
ACTUAL="$(git diff-tree --no-commit-id --name-only -r --no-renames HEAD | LC_ALL=C sort)"
|
|
312
|
+
test "$ACTUAL" = "$EXPECTED"
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Exit 0 passes. On a mismatch, stop. Do not push. Tell the user the commit holds files outside the list, and leave it as it is until they decide. In embed mode the reason is `file-set-mismatch`, and the evidence commit is local.
|
|
316
|
+
|
|
317
|
+
### Push with an explicit refspec
|
|
318
|
+
|
|
319
|
+
`REMOTE` is the remote from Step 3. `BRANCH` is `headRefName`, or the upstream branch in embed mode.
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
REMOTE="<remote>";
|
|
323
|
+
BRANCH="<head branch>";
|
|
324
|
+
GIT_TERMINAL_PROMPT=0 git push "$REMOTE" "HEAD:refs/heads/$BRANCH"
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
`GIT_TERMINAL_PROMPT=0` turns credential prompts off, so a push that needs input fails instead of hanging. The push has no timeout wrapper, because `timeout` is not on every platform's default PATH and nothing else in this skill depends on it.
|
|
328
|
+
|
|
329
|
+
If the push is rejected, stop and report. Never force-push and never retry with another refspec. A non-fast-forward rejection means the branch moved. Tell the user to fetch and rebase or merge, then re-run. A re-run reuses evidence that is already committed, because reuse is keyed on the destination and the blob SHA. In embed mode the reason is `push-rejected`.
|
|
330
|
+
|
|
331
|
+
If the push exits non-zero, check what the remote holds with `git ls-remote` before reporting anything, because the remote may have accepted the push even though the command failed (for example, when the connection dropped afterwards):
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
REMOTE="<remote>";
|
|
335
|
+
BRANCH="<head branch>";
|
|
336
|
+
if REMOTE_LINE="$(GIT_TERMINAL_PROMPT=0 git ls-remote "$REMOTE" "refs/heads/$BRANCH")"; then
|
|
337
|
+
if [ "${REMOTE_LINE%%[[:space:]]*}" = "$(git rev-parse HEAD)" ]; then echo landed; else echo local; fi
|
|
338
|
+
else
|
|
339
|
+
echo unchecked
|
|
340
|
+
fi
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
- `landed`: the remote SHA equals `HEAD`, so the push landed and counts as pushed. Go on as if the push had succeeded.
|
|
344
|
+
- `local`: the remote SHA differs from `HEAD`, or the branch is not on the remote. The evidence commit exists only locally. In embed mode the status line carries `evidence=local`.
|
|
345
|
+
- `unchecked`: `git ls-remote` failed too, so the push is not confirmed. Treat it as `local` and say that the remote could not be checked.
|
|
346
|
+
|
|
347
|
+
## Step 7: Verify the embeds
|
|
348
|
+
|
|
349
|
+
Verification runs in every mode, before the description is written or the Demo file is returned. The link form from Step 4 picks the subsection: public repositories use the raw form, and every other repository uses the blob form.
|
|
350
|
+
|
|
351
|
+
Make the temp files. Each is created with mode 0600. Note the three paths:
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
for NAME in demo backup new-body; do printf '%s %s\n' "$NAME" "$(mktemp)"; done
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
### Select the pins and write the Demo text
|
|
358
|
+
|
|
359
|
+
PR mode and embed mode only. Every pin the skill embeds comes from the helper. Never choose a pin with `git log` and never retype or transcribe a SHA by hand. For each destination the helper picks the newest commit on `HEAD` that added or changed the file, counting a merge that resolved it. It then checks that the blob at that pin is the `blob_sha` that classify reported for the destination, and writes the Demo text to the Demo file. The form is `raw` for a public repository and `blob` for every other repository.
|
|
360
|
+
|
|
361
|
+
Send one `select` item for every destination, new and reused, in the order the images should appear:
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
365
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
366
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" pins <<'JSON'
|
|
367
|
+
{"select": [{"path": "<destination 1>", "blob_sha": "<blob_sha 1>"}, {"path": "<destination 2>", "blob_sha": "<blob_sha 2>"}], "head_repo": "<owner/repo of the head repository>", "form": "<raw or blob>", "out_file": "<demo file>"}
|
|
368
|
+
JSON
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
- `selected` (exit 0): the Demo file is written. `evidence_sha` is the newest commit that added or changed any of these files. Copy it for the status line.
|
|
372
|
+
- `pin-mismatch` (exit 1): at a chosen pin, the blob of a destination differs from its `blob_sha`. Read `mismatched`. The Demo file is not written. Stop: the pushed image is not the approved one. In embed mode the reason is `pin-mismatch`.
|
|
373
|
+
- `unresolved` (exit 1): no commit on `HEAD` added a destination, so there is no pin to embed. Treat it as a `pin-mismatch`, and name `unresolved_paths`.
|
|
374
|
+
- `head-not-found`, `git-failed` or `git-timeout` (exit 1): stop and report `reached`. In embed mode the reason is `git-failed`.
|
|
375
|
+
- `write-failed` (exit 1): the Demo file could not be written. Stop with `status=failed`, `reason=helper-failed` and `evidence=pushed`.
|
|
376
|
+
- `usage-error` (exit 2): stop. In embed mode the reason is `helper-failed`.
|
|
377
|
+
|
|
378
|
+
Never write the description, and never return the Demo file, after a stop here. The evidence commit is pushed and unreferenced. In PR mode say: the evidence commit is pushed, the description is not written, and a re-run retries and reuses the pushed commit.
|
|
379
|
+
|
|
380
|
+
### Public repositories: the raw form
|
|
381
|
+
|
|
382
|
+
List the URLs to verify, from the Demo file that the helper wrote:
|
|
383
|
+
|
|
384
|
+
```bash
|
|
385
|
+
FILE="<Demo file, the new body file in Re-pin mode, or the backup file after an already-valid result>";
|
|
386
|
+
OWNER_REPO="<owner/repo of the head repository>";
|
|
387
|
+
grep -Eo "https://raw\.githubusercontent\.com/$OWNER_REPO/[0-9a-f]{40}/docs/evidence/[a-z0-9._/-]+" "$FILE" | sort -u
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Copy the printed URLs into the call. Use at most 50 per call and at most 90 for `max_wait_s`, so a call fits a host timeout:
|
|
391
|
+
|
|
392
|
+
```bash
|
|
393
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
394
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
395
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" verify <<'JSON'
|
|
396
|
+
{"head_repo": "<owner/repo>", "urls": ["<raw URL 1>", "<raw URL 2>"], "max_wait_s": 90, "waited_s": 0}
|
|
397
|
+
JSON
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Route the result:
|
|
401
|
+
|
|
402
|
+
- `verified` (exit 0): every embed serves an image. Continue.
|
|
403
|
+
- `failed` (exit 1): read `failed`. Report each failing URL with its `status` and `http_status`. If the top-level `retryable` is true, call again with the same URLs and `waited_s` set to the `waited_s` of the latest report, unchanged. That value is already the running total of all calls. When the latest report has a `resume_at`, add `"resume_at"` to the JSON and set it to that value, unchanged. Stop once `retryable` is false.
|
|
404
|
+
|
|
405
|
+
`resume_at` is an epoch-millisecond deadline. A 429 with a Retry-After longer than one call sets it, because the helper keeps no state and a new call would otherwise send a request at once. The call that gets it sleeps until `resume_at` before its first request, within its own `max_wait_s`, and counts the sleep in `waited_s`, so no request goes out before the deadline. Omit `resume_at` on the first call and when the latest report has none. Never compute, edit or drop it. A `resume_at` past the 300 s total ends the run: `retryable` is false.
|
|
406
|
+
- `usage-error` (exit 2) with `blob-url`: a blob-form URL never goes to this call, so stop.
|
|
407
|
+
- Any other `usage-error`: stop.
|
|
408
|
+
|
|
409
|
+
In embed mode a `usage-error` here ends with the reason `helper-failed`, and `evidence` is `pushed`.
|
|
410
|
+
|
|
411
|
+
Never print or paste a response body, and never fetch one yourself.
|
|
412
|
+
|
|
413
|
+
Never write the description, and never return the Demo file, when verification fails. The evidence commit is pushed and unreferenced. In PR mode say: the evidence commit is pushed, the description is not written, and a re-run retries and reuses the pushed commit. In embed mode the reason is `verify-failed`.
|
|
414
|
+
|
|
415
|
+
### Private repositories: the blob form
|
|
416
|
+
|
|
417
|
+
The Demo text is written in the blob form by the pin selection above. List the URLs to check, from the Demo file that the helper wrote:
|
|
418
|
+
|
|
419
|
+
```bash
|
|
420
|
+
FILE="<Demo file, the new body file in Re-pin mode, or the backup file after an already-valid result>";
|
|
421
|
+
OWNER_REPO="<owner/repo of the head repository>";
|
|
422
|
+
grep -o -E "https://github\.com/$OWNER_REPO/blob/[0-9a-f]{40}/docs/evidence/[a-z0-9._/-]+\?raw=true" "$FILE" | sort -u
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
Check each URL through `gh`, never through the helper's `verify`, which fetches anonymously and cannot see a private repository. The check asks GitHub for the file at the pinned commit and compares its git blob SHA with the expected one. Equal blob SHAs mean the file is byte-identical to the one that classify already accepted as an image, so nothing is downloaded.
|
|
426
|
+
|
|
427
|
+
The expected SHA is the `blob_sha` that classify reported for that file. Pair each URL with the entry whose `destination` ends the URL path. Re-pin mode has no classify result, so write `local` in place of the SHA: the block then reads the blob SHA from git at the pinned commit.
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
OWNER_REPO="<owner/repo of the head repository>";
|
|
431
|
+
set -- "<blob URL 1> <blob_sha 1, or local>" "<blob URL 2> <blob_sha 2, or local>";
|
|
432
|
+
ERR_FILE="$(mktemp)"
|
|
433
|
+
FAILED=0
|
|
434
|
+
for ITEM in "$@"; do
|
|
435
|
+
URL="${ITEM%% *}"; EXPECTED="${ITEM#* }"
|
|
436
|
+
REST="${URL#https://github.com/$OWNER_REPO/blob/}"; PIN="${REST%%/*}"; DEST="${REST#*/}"; DEST="${DEST%%\?*}"
|
|
437
|
+
[ "$EXPECTED" = local ] && EXPECTED="$(git rev-parse "$PIN:$DEST")"
|
|
438
|
+
printf '%s\n' "$EXPECTED" | grep -Eqx '[0-9a-f]{40}' || { echo "no expected blob SHA for $DEST"; FAILED=1; continue; }
|
|
439
|
+
ACTUAL=""; API_FAILED=0
|
|
440
|
+
for ATTEMPT in 1 2 3 4; do
|
|
441
|
+
API_FAILED=0
|
|
442
|
+
ACTUAL="$(gh api "repos/$OWNER_REPO/contents/$DEST?ref=$PIN" --jq .sha 2>"$ERR_FILE")" || API_FAILED=1
|
|
443
|
+
[ "$API_FAILED" = 0 ] && [ "$ACTUAL" = "$EXPECTED" ] && break
|
|
444
|
+
[ "$ATTEMPT" -lt 4 ] && sleep 5
|
|
445
|
+
done
|
|
446
|
+
if [ "$API_FAILED" = 1 ]; then echo "api-error $DEST $(head -n 1 "$ERR_FILE" | cut -c1-200)"; FAILED=1
|
|
447
|
+
elif [ "$ACTUAL" = "$EXPECTED" ]; then echo "ok $DEST"
|
|
448
|
+
else echo "mismatch $DEST ${ACTUAL:-none}"; FAILED=1; fi
|
|
449
|
+
done
|
|
450
|
+
rm -f "$ERR_FILE"
|
|
451
|
+
test "$FAILED" = 0
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
Exit 0 passes: every file exists at its pinned commit with the expected blob SHA. Each file gets four attempts, five seconds apart, so GitHub has time to serve a new commit. Every file prints one line:
|
|
455
|
+
|
|
456
|
+
- `ok`: the file is at its pinned commit with the expected blob SHA.
|
|
457
|
+
- `mismatch`: GitHub answered, and the blob SHA differs from the expected one.
|
|
458
|
+
- `api-error`: the `gh api` call itself failed (access denied, a rate limit, a missing file or a network failure), and the line carries the first line of stderr, which the block keeps in a temp file instead of discarding it. An `api-error` is not a content problem, so report it as an access or API problem.
|
|
459
|
+
|
|
460
|
+
A file that still fails after the attempts, or a line that says `no expected blob SHA`, stops the run. Stop with the state reached: what is committed, what is pushed, which files failed and how, and that the description is untouched.
|
|
461
|
+
|
|
462
|
+
Never write the description, and never return the Demo file, when this check fails. The evidence commit is pushed and unreferenced. In PR mode say: the evidence commit is pushed, the description is not written, and a re-run retries and reuses the pushed commit. In embed mode the reason is `verify-failed`.
|
|
463
|
+
|
|
464
|
+
## Step 8: Write the description or return the Demo file
|
|
465
|
+
|
|
466
|
+
### PR mode
|
|
467
|
+
|
|
468
|
+
Back up the description, then splice the Demo file into a copy of it. The backup is the helper input: JSON whose `body` field holds the original description. Tell the user the backup path now.
|
|
469
|
+
|
|
470
|
+
```bash
|
|
471
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
472
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
473
|
+
PR="<PR number>";
|
|
474
|
+
BACKUP="<backup file>";
|
|
475
|
+
gh pr view "$PR" --json body --jq '{body: .body, demo_file: "<demo file>", out_file: "<new body file>"}' > "$BACKUP"
|
|
476
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" splice < "$BACKUP"
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Route the result:
|
|
480
|
+
|
|
481
|
+
- `spliced` (exit 0): read `action`. `appended` and `replaced` continue. On `replaced`, tell the user the old Demo section is replaced and the backup holds it. On `unchanged`, the description already holds this Demo text: write nothing and go to Cleanup.
|
|
482
|
+
- `needs-input` (exit 1): read `asks` and stop. Write nothing.
|
|
483
|
+
- `multiple-demo-sections`: the description has more than one `## Demo` section. Ask the user which to keep.
|
|
484
|
+
- `unterminated-region`: a code fence (also one inside a list item or a quote), a comment, or a `<pre>`, `<script>`, `<style>` or `<textarea>` block is never closed. It would swallow the section, or it sits inside the existing Demo section so that the end of that section is unknown. A comment that contains `--!>` is refused the same way (kind `comment`): GitHub ends a comment only at `-->`, but a browser also ends it at `--!>`, so the text after it cannot be placed. Nothing is replaced. Ask the user to close the block, or to remove the `--!>`.
|
|
485
|
+
- `unexpected-section-content`: the existing Demo section holds a line this skill does not write, such as a heading, a table or prose. The section is not the managed one, or its end is misjudged. Nothing is replaced and the description stays untouched. Ask the user to move that content out of the section.
|
|
486
|
+
- `line-ending-conflict`: the Demo text and the description use different line endings at the join. Ask the user.
|
|
487
|
+
- `write-failed` (exit 1): the output file could not be written. Stop.
|
|
488
|
+
- `usage-error` (exit 2): stop.
|
|
489
|
+
|
|
490
|
+
If `screenshots_present` is true, warn the user: the description has a `## Screenshots` section, which is left alone. Nothing is merged into it.
|
|
491
|
+
|
|
492
|
+
Re-read the description immediately before writing, and write only if it is unchanged since the backup. Compare only the `body` field of the backup and of the re-read. The two files are JSON objects whose other fields differ by mode (PR mode and Re-pin mode build their backups with different fields), so a whole-file comparison would never match. This guard applies to every mode that writes. A changed description stops the run with nothing written; re-run to start from the new text. Write with a body file, never an inline body:
|
|
493
|
+
|
|
494
|
+
```bash
|
|
495
|
+
PR="<PR number>";
|
|
496
|
+
BACKUP="<backup file>";
|
|
497
|
+
NEW_BODY="<new body file>";
|
|
498
|
+
RECHECK="$(mktemp)"
|
|
499
|
+
gh pr view "$PR" --json body > "$RECHECK"
|
|
500
|
+
node -e 'const body = (file) => JSON.parse(require("fs").readFileSync(file, "utf8")).body; process.exit(body(process.argv[1]) === body(process.argv[2]) ? 0 : 1)' "$BACKUP" "$RECHECK" && gh pr edit "$PR" --body-file "$NEW_BODY"
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
Re-read it afterwards and compare it with the body file. This holds the regions outside Demo to the same bytes too:
|
|
504
|
+
|
|
505
|
+
```bash
|
|
506
|
+
PR="<PR number>";
|
|
507
|
+
NEW_BODY="<new body file>";
|
|
508
|
+
POST="$(mktemp)"
|
|
509
|
+
gh pr view "$PR" --json body --jq .body > "$POST"
|
|
510
|
+
{ cat "$NEW_BODY"; printf '\n'; } | cmp -s - "$POST"
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
Exit 0 passes. Then delete the temp files with `rm -f` and go to Cleanup.
|
|
514
|
+
|
|
515
|
+
On a mismatch, warn the user and print the backup path. Never auto-restore: a restore could overwrite a concurrent edit. Keep the backup until the re-read passes.
|
|
516
|
+
|
|
517
|
+
### Embed mode
|
|
518
|
+
|
|
519
|
+
Embed mode returns the Demo file from Step 7, made with mktemp (mode 0600), and prints one status line. Embed mode never edits the pull request. The caller splices the file and deletes it. Embed mode ends here, with no cleanup offer. The caller prints the cleanup command after the PR opens.
|
|
520
|
+
|
|
521
|
+
```text
|
|
522
|
+
pr-attachments: status=ok evidence_sha=<40-hex> demo_file=<path> images=<count>
|
|
523
|
+
pr-attachments: status=failed evidence=<pushed|local|none> reason=<reason>
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
- `evidence_sha` is the SHA that the pin selection in Step 7 reported. Copy it.
|
|
527
|
+
- `evidence` is `pushed` once the push landed, `local` when the evidence commit exists only on this machine (it was committed, but the push did not land), and `none` otherwise. A failed line never comes with a Demo file.
|
|
528
|
+
- `reason` comes from this table. Every embed-mode stop has exactly one row:
|
|
529
|
+
|
|
530
|
+
| Stop | Reason |
|
|
531
|
+
|---|---|
|
|
532
|
+
| Node is missing or cannot launch | `node-unavailable` |
|
|
533
|
+
| A helper call exits 2 with a `usage-error` | `helper-failed` |
|
|
534
|
+
| A helper call returns `internal-error` | `helper-failed` |
|
|
535
|
+
| A helper call returns `write-failed` | `helper-failed` |
|
|
536
|
+
| Classify returns `rejected` | `rejected-images` |
|
|
537
|
+
| Classify returns `needs-input` and the user does not settle it | `needs-input` |
|
|
538
|
+
| No image paths, no upstream, an unlisted remote or a host other than github.com | `no-target` |
|
|
539
|
+
| A stray `old=` or `new=` token | `bad-arguments` |
|
|
540
|
+
| The user cannot push to the head repository | `no-push-access` |
|
|
541
|
+
| Any other git or gh command fails | `git-failed` |
|
|
542
|
+
| The user declines the private-repository question or the scrub | `declined` |
|
|
543
|
+
| The push target is the default branch | `default-branch` |
|
|
544
|
+
| A destination is gitignored | `destination-blocked` |
|
|
545
|
+
| A destination has an LFS filter, or an `eol` or `text` attribute that rewrites bytes | `destination-blocked` |
|
|
546
|
+
| A destination holds uncommitted content | `destination-blocked` |
|
|
547
|
+
| A source file changed since classify | `source-changed` |
|
|
548
|
+
| A hook rejects the evidence commit, or the commit fails | `commit-failed` |
|
|
549
|
+
| A staged or committed blob differs from the one classify reported | `blob-mismatch` |
|
|
550
|
+
| The committed file set differs from the destinations | `file-set-mismatch` |
|
|
551
|
+
| The push is rejected, or exits non-zero and the remote does not hold `HEAD` | `push-rejected` |
|
|
552
|
+
| The pin chosen for a destination is missing, or its blob differs from the one classify reported | `pin-mismatch` |
|
|
553
|
+
| An embed does not serve the image, or its blob check fails | `verify-failed` |
|
|
554
|
+
|
|
555
|
+
## Carry mode
|
|
556
|
+
|
|
557
|
+
`mode:carry old=<old body file> new=<new body file>` copies the `## Demo` section of an old description into a regenerated one. A caller that rewrites a description uses it, because the caller cannot reach this skill's helper from its own directory.
|
|
558
|
+
|
|
559
|
+
Carry mode reads and writes the two named files and nothing else. It never commits, never pushes, never calls `gh` and never touches the network. The caller owns both files and writes the description itself. Carry mode ends at the status line, with no cleanup offer.
|
|
560
|
+
|
|
561
|
+
Take both `old=` and `new=` from Step 1. Wrap a value that has spaces in double quotes, for example `old="/tmp/a b/old.md"`, and strip the quotes after splitting. If either is missing, or any image path or `pr:` token is present, stop. There are no image paths and no `pr:` token in carry mode. The reason is `bad-arguments`.
|
|
562
|
+
|
|
563
|
+
Make the file that holds the extracted section. Note its path:
|
|
564
|
+
|
|
565
|
+
```bash
|
|
566
|
+
printf 'demo %s\n' "$(mktemp)"
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
Extract the section from the old body. The `node -e` part only reads the old file into the helper's JSON input, so the text is never retyped:
|
|
570
|
+
|
|
571
|
+
```bash
|
|
572
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
573
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
574
|
+
OLD_BODY="<old body file>";
|
|
575
|
+
DEMO_FILE="<demo file>";
|
|
576
|
+
node -e 'process.stdout.write(JSON.stringify({body: require("fs").readFileSync(process.argv[1], "utf8"), out_file: process.argv[2]}))' "$OLD_BODY" "$DEMO_FILE" | node "$SKILL_DIR/scripts/pr-attachments.mjs" extract
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
Route the result:
|
|
580
|
+
|
|
581
|
+
- `extracted` (exit 0): continue.
|
|
582
|
+
- `absent` (exit 0): the old description has no Demo section, so there is nothing to carry; leave the new file untouched, remove the demo file and finish with `status=absent`, which is not a failure.
|
|
583
|
+
- `needs-input` (exit 1): the old file is untouched and nothing is copied. Finish with `status=failed`. The reason is the code in `asks`: `multiple-demo-sections` (the old description has more than one `## Demo` section), `unterminated-region` (an unclosed block, or a comment that contains `--!>`, sits in the old description, so where its Demo section ends is unknown) or `unexpected-section-content` (its Demo section holds a line this skill does not write, such as a heading, a table or prose).
|
|
584
|
+
- `write-failed` (exit 1): finish with `status=failed`.
|
|
585
|
+
- `usage-error` (exit 2) or `internal-error`: finish with `status=failed`.
|
|
586
|
+
|
|
587
|
+
Splice the section into the new body. The new file is read first and then written in place:
|
|
588
|
+
|
|
589
|
+
```bash
|
|
590
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
591
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
592
|
+
NEW_BODY="<new body file>";
|
|
593
|
+
DEMO_FILE="<demo file>";
|
|
594
|
+
node -e 'process.stdout.write(JSON.stringify({body: require("fs").readFileSync(process.argv[1], "utf8"), demo_file: process.argv[2], out_file: process.argv[1]}))' "$NEW_BODY" "$DEMO_FILE" | node "$SKILL_DIR/scripts/pr-attachments.mjs" splice
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
Route the result:
|
|
598
|
+
|
|
599
|
+
- `spliced` (exit 0): `appended`, `replaced` and `unchanged` all finish with `status=ok`.
|
|
600
|
+
- `needs-input` (exit 1): the new file is untouched. Finish with `status=failed`. The reason is the code in `asks`: `multiple-demo-sections` (the new file has more than one `## Demo` section), `unterminated-region` (an unclosed code fence, comment or HTML block would swallow the section, or a comment contains `--!>` and so ends in two places), `unexpected-section-content` (the existing Demo section in the new file holds a line this skill does not write) or `line-ending-conflict` (the two texts use different line endings at the join).
|
|
601
|
+
- `write-failed` (exit 1): finish with `status=failed`. The new file may be partly written, so the caller discards it.
|
|
602
|
+
- `usage-error` (exit 2) or `internal-error`: finish with `status=failed`.
|
|
603
|
+
|
|
604
|
+
On every path, remove the demo file:
|
|
605
|
+
|
|
606
|
+
```bash
|
|
607
|
+
DEMO_FILE="<demo file>";
|
|
608
|
+
rm -f "$DEMO_FILE"
|
|
609
|
+
```
|
|
610
|
+
|
|
611
|
+
Then print exactly one status line:
|
|
612
|
+
|
|
613
|
+
```text
|
|
614
|
+
pr-attachments: status=<ok|absent|failed> [reason=<reason>]
|
|
615
|
+
```
|
|
616
|
+
|
|
617
|
+
`reason` appears only with `failed`. It is one of `node-unavailable`, `bad-arguments`, `helper-failed`, `multiple-demo-sections`, `unterminated-region`, `unexpected-section-content`, `line-ending-conflict` or `write-failed`. A missing node is `node-unavailable`, and a `usage-error` or `internal-error` is `helper-failed`. Never write a Demo section by hand when carry mode fails.
|
|
618
|
+
|
|
619
|
+
## Re-pin mode
|
|
620
|
+
|
|
621
|
+
An open PR and no paths. It re-points the embeds after a rebase or force-push. On a fresh PR it changes nothing.
|
|
622
|
+
|
|
623
|
+
After a rebase or force-push, re-run this skill with no paths. Steps 3 and 4 apply. `HEAD` must equal `headRefOid`; if it does not, say push first.
|
|
624
|
+
|
|
625
|
+
### Read the managed URLs
|
|
626
|
+
|
|
627
|
+
Read them from the description. Other URLs are ignored; report how many.
|
|
628
|
+
|
|
629
|
+
```bash
|
|
630
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
631
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
632
|
+
PR="<PR number>";
|
|
633
|
+
BACKUP="<backup file>";
|
|
634
|
+
gh pr view "$PR" --json body --jq '{body: .body, head_repo: "<owner/repo>"}' > "$BACKUP"
|
|
635
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" urls < "$BACKUP"
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
With no managed URL, report that there is nothing to re-pin and go to Cleanup.
|
|
639
|
+
|
|
640
|
+
Each URL reports its `form`. The form must match the repository (`raw` for a public repository, `blob` for any other) or the run stops. Say which embeds use the wrong form and why: a raw link does not render in a private repository, and a blob link cannot be verified anonymously in a public one. To fix it, re-run in PR mode with the image paths, which replaces the Demo section.
|
|
641
|
+
|
|
642
|
+
### Pick the pins
|
|
643
|
+
|
|
644
|
+
Ask git for the newest commit of each managed path. Send the `urls` array unchanged:
|
|
645
|
+
|
|
646
|
+
```bash
|
|
647
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
648
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
649
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" pins <<'JSON'
|
|
650
|
+
{"head_ref_oid": "<headRefOid>", "urls": [<the urls array from the previous report>]}
|
|
651
|
+
JSON
|
|
652
|
+
```
|
|
653
|
+
|
|
654
|
+
- `already-valid` (exit 0): write nothing. The pins were checked only against local git, so verify the embed URLs that the description holds before Cleanup. Read them from the backup file made above, and use the same checks as in Step 7: a public repository uses "Public repositories: the raw form", and any other repository uses "Private repositories: the blob form" with `local` as the expected SHA of every URL. If a check fails, report each failure, write nothing and do not offer Cleanup. If every check passes, report already valid and go to Cleanup.
|
|
655
|
+
- `repin-needed` (exit 0): continue with the `pins` map.
|
|
656
|
+
- `partial` (exit 1): report partial and name `unresolved_paths`. Write nothing yet. Then offer the next actions: re-pin the resolved paths, which still writes only the resolved ones through the normal write guard, or re-add the missing images in PR mode. If the user chooses to re-pin the resolved paths, continue with the `pins` map.
|
|
657
|
+
- `unresolved` (exit 1): no managed path ever existed on the head. Stop and point to PR mode: re-run with image paths.
|
|
658
|
+
- `head-not-found` (exit 1): the head commit is not in this repository. Stop and say fetch or push first.
|
|
659
|
+
- `git-failed` or `git-timeout` (exit 1): report `reached`. Stop.
|
|
660
|
+
|
|
661
|
+
### Rewrite the stale pins
|
|
662
|
+
|
|
663
|
+
Rewrite only the 40-hex segment of the stale URLs. Send the `pins` map unchanged:
|
|
664
|
+
|
|
665
|
+
```bash
|
|
666
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
667
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
668
|
+
PR="<PR number>";
|
|
669
|
+
BACKUP="<backup file>";
|
|
670
|
+
gh pr view "$PR" --json body --jq '{body: .body, head_repo: "<owner/repo>", pins: {<the pins map from the previous report>}, out_file: "<new body file>"}' > "$BACKUP"
|
|
671
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" repin-rewrite < "$BACKUP"
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
- `repinned` (exit 0): report `rewritten`, `ignored` and `unmapped_paths`. A non-empty `unmapped_paths` means the description changed since the first read: stop and re-run. After a `partial` result, `unmapped_paths` holds exactly the `unresolved_paths`, and anything else stops the run.
|
|
675
|
+
- `write-failed` (exit 1): stop.
|
|
676
|
+
- `usage-error` (exit 2): stop.
|
|
677
|
+
|
|
678
|
+
### Verify and write
|
|
679
|
+
|
|
680
|
+
Verify the URLs of the rewritten file with Step 7. Take the list from the new body file. A public repository uses the raw form subsection. Any other repository uses "Private repositories: the blob form", with `local` as the expected SHA of every URL.
|
|
681
|
+
|
|
682
|
+
Re-pin mode never meets `unexpected-section-content`, because it does not call `splice` or `extract`: it edits only the 40-hex segment of managed URLs and no other line.
|
|
683
|
+
|
|
684
|
+
Then do the write step of Step 8 with the new body file and this backup. Tell the user the backup path first. The guard compares only `body`, so this backup works although it also holds `head_repo` and `pins`. Then go to Cleanup.
|
|
685
|
+
|
|
686
|
+
## Cleanup
|
|
687
|
+
|
|
688
|
+
Offered only once a PR exists, at the end of PR mode and Re-pin mode. Embed mode never offers it. Recommended before merge: it removes the evidence files the PR added from the head branch. The embeds keep working, because they point at the pinned commit.
|
|
689
|
+
|
|
690
|
+
Cleanup works with no Demo section, because the set comes from git and not from the description. Never run `git rm` by hand, including when the helper cannot run, and never fall back to a manual removal.
|
|
691
|
+
|
|
692
|
+
Fetch the base first. `BASE_REMOTE` is the remote that maps to the repository in the PR URL. If none maps, stop.
|
|
693
|
+
|
|
694
|
+
```bash
|
|
695
|
+
BASE_REMOTE="<remote that maps to the base repository>";
|
|
696
|
+
BASE_BRANCH="<baseRefName>";
|
|
697
|
+
git fetch "$BASE_REMOTE" "+refs/heads/$BASE_BRANCH:refs/remotes/$BASE_REMOTE/$BASE_BRANCH"
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
Compute the set. `head_ref_oid` is `headRefOid`, or local `HEAD` after a push in this run:
|
|
701
|
+
|
|
702
|
+
```bash
|
|
703
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
704
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
705
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" cleanup-set <<'JSON'
|
|
706
|
+
{"head_ref_oid": "<headRefOid>", "base_ref_name": "<baseRefName>", "remote": "<base remote>"}
|
|
707
|
+
JSON
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
Route the result:
|
|
711
|
+
|
|
712
|
+
- `empty` (exit 0): report cleanup already done. Stop.
|
|
713
|
+
- `set` (exit 0): list `paths` and `count`, and say cleanup is recommended before merge. Read the merge methods:
|
|
714
|
+
|
|
715
|
+
```bash
|
|
716
|
+
gh repo view "<owner>/<repo>" --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
If `mergeCommitAllowed` or `rebaseMergeAllowed` is true, add one line: the images stay in default-branch history unless the PR is squash-merged. Always add this disclosure verbatim: Cleanup does not revoke access, so any published secret must be rotated.
|
|
720
|
+
|
|
721
|
+
For a private, internal or unknown-visibility repository, cleanup works the same way, and you also say that the images stay in the repository's history and become public if it is later made public or forked.
|
|
722
|
+
|
|
723
|
+
Then ask whether to remove the files, and wait for an explicit yes. On anything else, stop and leave the files.
|
|
724
|
+
- `base-not-found`, `no-merge-base`, `head-not-found` (exit 1): stop. Report the state. Fetch the base or push first.
|
|
725
|
+
- `git-failed` or `git-timeout` (exit 1): stop. Report `reached`.
|
|
726
|
+
- `usage-error` (exit 2): stop.
|
|
727
|
+
|
|
728
|
+
After the yes, call again with the `digest` from the `set` result. The helper recomputes the set and stages the removals; it commits nothing:
|
|
729
|
+
|
|
730
|
+
```bash
|
|
731
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
732
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
733
|
+
node "$SKILL_DIR/scripts/pr-attachments.mjs" cleanup-set <<'JSON'
|
|
734
|
+
{"head_ref_oid": "<headRefOid>", "base_ref_name": "<baseRefName>", "remote": "<base remote>", "remove_digest": "<digest>"}
|
|
735
|
+
JSON
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
- `removed` (exit 0): the removals are staged. Commit them.
|
|
739
|
+
- `digest-mismatch` (exit 1): the set changed since the yes, so show the new set and ask again for an explicit yes. Nothing was removed.
|
|
740
|
+
- `head-not-checked-out` (exit 1): check out the PR head first. Stop.
|
|
741
|
+
- `git-failed` with step `remove`: `git rm` refuses a locally modified file and is never forced. Report it and stop.
|
|
742
|
+
- Any other result: as above.
|
|
743
|
+
|
|
744
|
+
Commit the removals by pathspec, using the `paths` from the result. The slug is the directory under `docs/evidence/`:
|
|
745
|
+
|
|
746
|
+
```bash
|
|
747
|
+
TOPIC="<topic slug>";
|
|
748
|
+
set -- "<path 1>" "<path 2>";
|
|
749
|
+
git commit -m "chore(evidence): remove screenshots for $TOPIC" -- "$@"
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
If the commit fails, run `git restore --staged` with the same paths, as in Commit by pathspec, and stop. The removed files then show as deleted but unstaged.
|
|
753
|
+
|
|
754
|
+
Then run the file-set assertion from Assert the committed file set, with these paths as the expected set. Before the push, apply the refusal from Step 4 for a push target that is the default branch. Then run the push from Push with an explicit refspec. A rejection stops the run as it does there.
|
|
755
|
+
|
|
756
|
+
## Disclosures
|
|
757
|
+
|
|
758
|
+
- Evidence binaries appear in the Files tab of the PR until cleanup.
|
|
759
|
+
- Published images stay in git history, forks and caches. Cleanup removes files from the branch. It does not revoke access.
|
|
760
|
+
- For a public repository, verification confirms the raw URL serves an image. For a private repository, it confirms that the file at the pinned commit is the image that was classified. Neither confirms GitHub renders it. Files over 10 MiB never reach this point, because they are rejected before anything is published.
|
|
761
|
+
- A private repository's images stay in its history. If it is later made public or forked, they become public. Cleanup does not remove them from history.
|
|
762
|
+
- Blob links in a private repository render only for signed-in viewers who have access to it. Anyone else sees no image.
|
|
763
|
+
- A commit-pinned link survived cleanup, squash merge and branch deletion on one observed PR. That is observed, not guaranteed. A re-run re-verifies.
|
|
764
|
+
- A rebase or force-push needs a re-run with no paths.
|