@fro.bot/systematic 3.36.0 → 3.38.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 +2 -1
- package/dist/ce-connect-helper.d.ts +4 -1
- package/dist/cli.js +5 -3
- package/dist/{index-1cj1mrpb.js → index-ahm7y9zh.js} +150 -72
- package/dist/index.js +20 -20
- package/dist/lib/config-handler.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +12 -0
- package/dist/lib/config.d.ts +1 -1
- package/dist/lib/connect-ci.d.ts +9 -1
- package/dist/lib/connect-config.d.ts +81 -9
- package/dist/lib/connect-helper-core.d.ts +5 -0
- package/dist/lib/connect-pins.d.ts +131 -0
- package/dist/lib/connect-provenance.d.ts +34 -0
- package/dist/lib/connect-repo-identity.d.ts +30 -3
- package/dist/lib/discovered-skills.d.ts +3 -3
- package/dist/lib/opencode-config-dir.d.ts +26 -0
- package/dist/lib/opencode-v2.d.ts +1 -1
- package/dist/lib/search-user-config.d.ts +5 -3
- package/dist/pi.js +119 -41
- package/package.json +6 -6
- package/skills/ce-compound/assets/resolution-template.md +1 -1
- package/skills/ce-compound-refresh/assets/resolution-template.md +1 -1
- package/skills/ce-connect/SKILL.md +21 -8
- package/skills/ce-connect/references/candidate-contract.md +3 -1
- package/skills/ce-connect/references/fetch-and-import.md +162 -20
- package/skills/ce-connect/references/headless-and-outcomes.md +24 -3
- package/skills/ce-connect/scripts/connect.mjs +1081 -327
- package/skills/compound-docs/SKILL.md +1 -2
- package/skills/compound-docs/assets/resolution-template.md +1 -1
|
@@ -1,34 +1,149 @@
|
|
|
1
1
|
# Fetch and import
|
|
2
2
|
|
|
3
|
-
`fetch:<run>.<attempt>` brings the candidates of one attempt of a scheduled CI run to this machine, so a lesson the runner found can be promoted here after the runner is gone. A bare `fetch:<run>` does the same for the newest attempt of that run. In every command below, `<run>` and `<attempt>` are the numbers `SKILL.md` already checked: positive integers, nothing else. The skill does the part that needs the network, with the user's own `gh`. The helper's `import` operation does the rest and never touches the network.
|
|
3
|
+
`fetch:<run>.<attempt>` brings the candidates of one attempt of a scheduled CI run to this machine, so a lesson the runner found can be promoted here after the runner is gone. A bare `fetch:<run>` does the same for the newest attempt of that run. A bare word means Systematic. A named word, `fetch:<owner>/<repo>:<run>.<attempt>`, does the same for one attempt of a scheduled run in another repository that called Systematic's reusable workflow; there the attempt is required. In every command below, `<run>` and `<attempt>` are the numbers `SKILL.md` already checked: positive integers, nothing else. `<repo>` is `marcusrbrown/systematic` for a bare word, and for a named word the `owner/repo` of the word, lowercased, after step 1 found it among the allowed origins. The skill does the part that needs the network, with the user's own `gh`. The helper's `import` operation does the rest and never touches the network.
|
|
4
|
+
|
|
5
|
+
Every `gh` call below names github.com explicitly, as a host flag or as a `github.com/` repository, because the allow-list origin is a github.com origin, so `GH_HOST` or a GHE remote must not redirect the checks.
|
|
4
6
|
|
|
5
7
|
A fetch dispatches no agent, asks nothing and takes no host observation. It uses neither `begin` nor `publish`. It ends with the `finalLine` that `import` answers, or with `Connect failed` for a stop before `import`.
|
|
6
8
|
|
|
7
|
-
The repository is fixed: `marcusrbrown/systematic`. Never take a repository, a path or a workflow name from the user's
|
|
9
|
+
The repository of a bare word is fixed: `marcusrbrown/systematic`. The repository of a named word is the one in the word, used only after step 1 found it among the allowed origins. Never take a repository, a path or a workflow name from the downloaded record or from any other file: a repository comes from the user's word, never from a downloaded file.
|
|
10
|
+
|
|
11
|
+
A bare word never reads `referenced_workflows`. Its whole check is the fixed repository, the event and the run's top-level workflow path, so Systematic's own fetch does not depend on the proof a named word needs.
|
|
8
12
|
|
|
9
13
|
## Order
|
|
10
14
|
|
|
11
|
-
Do these in order. Start every block that runs a command with the same anchor lines as the other steps, with `SKILL_DIR` set to the skill directory stated when this skill loads.
|
|
15
|
+
Do these in order. Start every block that runs a command with the same anchor lines as the other steps, with `SKILL_DIR` set to the skill directory stated when this skill loads. A bare word skips steps 1 and 3.
|
|
16
|
+
|
|
17
|
+
### 1. Resolve the repository
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
A bare word keeps the fixed repository; skip to step 2 and check no origin.
|
|
20
|
+
|
|
21
|
+
For a named word, ask the helper which origins are allowed before any `gh` command:
|
|
14
22
|
|
|
15
23
|
```bash
|
|
16
24
|
# Resolve helper scripts relative to this skill's directory.
|
|
17
25
|
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
18
|
-
|
|
26
|
+
node "$SKILL_DIR/scripts/connect.mjs" allowed-origins
|
|
19
27
|
```
|
|
20
28
|
|
|
21
|
-
`
|
|
29
|
+
It takes no request and answers one line of JSON with three fields: `origins`, the lowercase `owner/repo` of the GitHub origin of each allowed checkout; `ambiguous`, the origins that two or more allowed checkouts share; and `configUnreadable`. It reads configuration only: it takes no lock, writes nothing and never prints a local path. Never read the configuration yourself.
|
|
30
|
+
|
|
31
|
+
Lowercase the word's `<owner>/<repo>` and look for it in `origins`, which is already lowercase, so the match ignores case: `Fro-Bot/Agent` matches the origin `fro-bot/agent`. From here on, use that lowercase form as `<repo>`.
|
|
22
32
|
|
|
23
|
-
-
|
|
33
|
+
- It is not in `origins`: stop with `origin-not-allowed`. Run no `gh` command. Nothing was downloaded. To fix it, allow-list a checkout of that repository: add a local checkout whose `origin` remote is `<repo>` to `connect.allow_projects`, then try again. When `configUnreadable` is `true`, say that the allow list could not be read.
|
|
34
|
+
- It is in `ambiguous`: stop with `repo-ambiguous`. `import` would refuse every candidate of that repository for the same reason. Nothing was downloaded. Remove all but one of the checkouts from the allow list, then try again.
|
|
35
|
+
- The answer is JSON with `ok: false`, or JSON without `origins`: stop and print the helper's `reason`, then `Connect failed`, without running `gh`. Nothing was downloaded. Never guess an origin from a path or from the checkouts you can see.
|
|
36
|
+
- If `node` is missing, the helper file is gone, or `allowed-origins` prints no JSON answer, the helper is unavailable: print `helper-unavailable` and its hint, then `Connect failed`. Nothing was downloaded.
|
|
37
|
+
|
|
38
|
+
### 2. Check the run, before any download
|
|
39
|
+
|
|
40
|
+
`gh run view --json` has no workflow path, so the API call is the check.
|
|
41
|
+
|
|
42
|
+
#### Bare word
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
46
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
47
|
+
gh api --hostname github.com "repos/marcusrbrown/systematic/actions/runs/<run>" --jq '[.path, .event, .head_sha] | @tsv'
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
It prints three tab-separated values: the workflow path, the event and the head commit.
|
|
51
|
+
|
|
52
|
+
- The path must be `.github/workflows/connect.yaml` (a direct run) or `.github/workflows/connect-scheduled.yaml` (Systematic's own scheduled wrapper). Drop a trailing `@<ref>` before comparing. Any other path (for example `.github/workflows/fro-bot.yaml`): stop with `not-a-connect-run`.
|
|
24
53
|
- The event must be `schedule` or `workflow_dispatch`. Any other event: stop with `unsupported-run-event`. A run triggered by a pull request is never read, whatever its artifacts hold.
|
|
25
54
|
- The command fails with a 404: stop with `run-not-found`. It fails because `gh` is not logged in: stop with `gh-not-authenticated`.
|
|
26
55
|
- Keep the head commit for the request below. It must be 40 or 64 lowercase hex characters; otherwise leave `commit` out.
|
|
56
|
+
- Skip step 3 and go to step 4.
|
|
27
57
|
|
|
28
|
-
|
|
58
|
+
#### Named word
|
|
29
59
|
|
|
30
60
|
```bash
|
|
31
|
-
|
|
61
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
62
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
63
|
+
gh api --hostname github.com "repos/<repo>/actions/runs/<run>" --jq '[.event, .head_sha] | @tsv'
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
It prints two tab-separated values: the event and the head commit.
|
|
67
|
+
|
|
68
|
+
- The event must be `schedule` or `workflow_dispatch`. Any other event: stop with `unsupported-run-event`.
|
|
69
|
+
- The command fails with a 404: stop with `run-not-found`. It fails because `gh` is not logged in: stop with `gh-not-authenticated`. It fails for any other reason: stop with `provenance-unprovable`.
|
|
70
|
+
- The run's own path is the caller's wrapper, so it is not read here, and a wrapper's own path proves nothing. Step 3 proves what the run called.
|
|
71
|
+
- Keep the head commit for the request below. It must be 40 or 64 lowercase hex characters; otherwise leave `commit` out.
|
|
72
|
+
|
|
73
|
+
### 3. Prove the provenance (named words only)
|
|
74
|
+
|
|
75
|
+
The helper decides this step. You fetch the text from `gh`, send it to the helper and act on the answer. Never judge `referenced_workflows` yourself: never read the list, pick an entry or check a hash. The helper's `verify-provenance` operation takes no lock, writes nothing, reads no network or configuration and never prints a path.
|
|
76
|
+
|
|
77
|
+
Read the exact attempt the word names. Never read the run's newest attempt instead.
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
gh api --hostname github.com "repos/<repo>/actions/runs/<run>/attempts/<attempt>" --jq .referenced_workflows
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
It prints the attempt's `referenced_workflows`.
|
|
84
|
+
|
|
85
|
+
- The attempt does not exist (a 404): stop with `run-not-found`.
|
|
86
|
+
- `gh` is not logged in: stop with `gh-not-authenticated`.
|
|
87
|
+
- The API call fails for any other reason: stop with `provenance-unprovable`, with its remedy from the table below.
|
|
88
|
+
|
|
89
|
+
Never download on any stop below. Send the text `gh` printed, unchanged, to the helper on stdin:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
93
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
94
|
+
node "$SKILL_DIR/scripts/connect.mjs" verify-provenance <<'JSON'
|
|
95
|
+
<the text gh printed, unchanged>
|
|
96
|
+
JSON
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
It answers one line of JSON. It takes the text as it is, so text that is not JSON is judged by the helper, not refused as a bad request. It decides, in this order:
|
|
100
|
+
|
|
101
|
+
- The value is absent or `null`, is not a list, is empty, or an entry has no string `path`: `provenance-unprovable`.
|
|
102
|
+
- It takes the entries whose `path`, the part before the `@`, is `marcusrbrown/systematic/.github/workflows/connect.yaml`, comparing `marcusrbrown/systematic` without regard to case and the rest exactly (`MarcusRBrown/Systematic/.github/workflows/connect.yaml@<sha>` matches; `marcusrbrown/systematic/.github/Workflows/connect.yaml` does not). It matches by path, never by position in the list.
|
|
103
|
+
- No entry matches: `not-a-connect-run`. The run is proven to be another workflow, such as another repository's workflow, a fork or another path.
|
|
104
|
+
- More than one entry matches: `provenance-unprovable`.
|
|
105
|
+
- The matching entry's `sha` is not 40 lowercase hex characters: `provenance-unprovable`. It never uses `ref` or the text after the `@`.
|
|
106
|
+
|
|
107
|
+
Read the answer:
|
|
108
|
+
|
|
109
|
+
- `ok: true` with `stage: "selected"`: the answer carries `sha`. Go on to the compare below.
|
|
110
|
+
- `ok: false`: stop with the `reason` it names, `provenance-unprovable` or `not-a-connect-run`, and print the remedy from the table below. Download nothing and run no further `gh` command.
|
|
111
|
+
- JSON with any other `reason` (such as `invalid-request`), or JSON with neither `ok: true` nor a `reason`: stop and print that `reason`, then `Connect failed`, without running `gh`. Nothing was downloaded.
|
|
112
|
+
- If `node` is missing, the helper file is gone, or the operation prints no JSON answer, the helper is unavailable: print `helper-unavailable` and its hint, then `Connect failed`. Nothing was downloaded.
|
|
113
|
+
|
|
114
|
+
Then check that the commit is on Systematic's default branch:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
gh api --hostname github.com "repos/marcusrbrown/systematic/compare/main...<sha>" --jq .status
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`<sha>` is the `sha` the helper answered. The base is `main` and the head is the `sha`. Never swap the two sides of the range.
|
|
121
|
+
|
|
122
|
+
- The command fails (a 404, which an unknown commit and no access both give, or any other failure): stop with `provenance-unprovable`, with its remedy from the table below. Do not call the helper again.
|
|
123
|
+
- It prints a status. Send the same text again, with the status as `gh` printed it, with no trailing newline:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# Resolve helper scripts relative to this skill's directory.
|
|
127
|
+
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
128
|
+
node "$SKILL_DIR/scripts/connect.mjs" verify-provenance --status "<status>" <<'JSON'
|
|
129
|
+
<the same text again>
|
|
130
|
+
JSON
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
- `ok: true` with `stage: "accepted"`: the commit is behind or identical to `main`, so it is in the history of `main`. Go on.
|
|
134
|
+
- `ok: false`: stop with the `reason` it names. The helper refuses `ahead` (the commit is not in `main`), `diverged`, an empty status and any other status as `provenance-unprovable`.
|
|
135
|
+
- Any other answer: stop as above.
|
|
136
|
+
|
|
137
|
+
`provenance-unprovable` means the proof is missing. It is not a finding that the run is hostile. To fix it, check that the caller's wrapper calls `marcusrbrown/systematic/.github/workflows/connect.yaml` at a commit on Systematic's `main`, then try again. If an API call failed, try again later.
|
|
138
|
+
|
|
139
|
+
### 4. Choose the artifact
|
|
140
|
+
|
|
141
|
+
The record is in an artifact named `connect-run-<run>-<attempt>`, where `<attempt>` is digits only. How to list it depends on whether the attempt is known.
|
|
142
|
+
|
|
143
|
+
For a named word or an explicit attempt (`fetch:<run>.<attempt>` or `fetch:<owner>/<repo>:<run>.<attempt>`), look the artifact up by its exact name:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
gh api --hostname github.com "repos/<repo>/actions/runs/<run>/artifacts?name=connect-run-<run>-<attempt>" --jq '[.artifacts[] | {name: .name, expired: .expired}]'
|
|
32
147
|
```
|
|
33
148
|
|
|
34
149
|
It prints one JSON array of `{name, expired}` objects. Check the call before you read the array:
|
|
@@ -36,10 +151,24 @@ It prints one JSON array of `{name, expired}` objects. Check the call before you
|
|
|
36
151
|
- The command fails because `gh` is not logged in: stop with `gh-not-authenticated`.
|
|
37
152
|
- The command fails for any other reason (a non-zero exit), or its output is not a JSON array: stop with `artifact-list-failed`. An empty array is an answer; a failed call is not. Never read a failed call as `artifact-not-found`.
|
|
38
153
|
|
|
39
|
-
|
|
154
|
+
Only a name that is exactly `connect-run-<run>-<attempt>` counts.
|
|
155
|
+
|
|
156
|
+
For a bare `fetch:<run>`, the attempt is not known, so list every artifact of the run. A run can hold more than one page of them, so paginate:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
gh api --hostname github.com --paginate "repos/<repo>/actions/runs/<run>/artifacts?per_page=100" --jq '.artifacts[] | {name: .name, expired: .expired}'
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
It prints one JSON object per line, `{name, expired}`, across all pages. Check the call before you read the lines:
|
|
163
|
+
|
|
164
|
+
- The command fails because `gh` is not logged in: stop with `gh-not-authenticated`.
|
|
165
|
+
- The command fails for any other reason (a non-zero exit), or a line is not a JSON object: stop with `artifact-list-failed`. An empty output with a zero exit is an answer; a failed call is not. Never read a failed call as `artifact-not-found`.
|
|
166
|
+
|
|
167
|
+
Take the names that match `connect-run-<run>-<attempt>` for this run id exactly.
|
|
40
168
|
|
|
41
169
|
- With a bare `fetch:<run>`, pick the one with the highest attempt. A run with attempts 1 and 2 downloads `connect-run-<run>-2`.
|
|
42
170
|
- With `fetch:<run>.<attempt>`, download exactly `connect-run-<run>-<attempt>` with that attempt. Do not pick the highest attempt. A report names the attempt a candidate came from, and a later attempt may not hold it.
|
|
171
|
+
- With `fetch:<owner>/<repo>:<run>.<attempt>`, download exactly `connect-run-<run>-<attempt>` with the attempt that step 3 proved, from the named repository's run. There is no other choice.
|
|
43
172
|
|
|
44
173
|
Then:
|
|
45
174
|
|
|
@@ -47,16 +176,22 @@ Then:
|
|
|
47
176
|
- The chosen artifact is expired: stop with `artifact-expired`. The user can tick Rejected in the scheduled run's report, or wait for the candidate to be proposed again.
|
|
48
177
|
- If the named attempt has no artifact, stop with `artifact-not-found`, even when another attempt of the run has one. If the named attempt's artifact is expired, stop with `artifact-expired`. Print the fixed reason and its hint only. Never fall back to another attempt and do not suggest one.
|
|
49
178
|
|
|
50
|
-
###
|
|
179
|
+
### 5. Download into a fresh directory
|
|
51
180
|
|
|
52
181
|
```bash
|
|
53
182
|
mktemp -d
|
|
54
183
|
```
|
|
55
184
|
|
|
56
|
-
Shell state does not persist between tool calls, so write the absolute path it prints (`<DEST>`) into each later command. Then download into it:
|
|
185
|
+
Shell state does not persist between tool calls, so write the absolute path it prints (`<DEST>`) into each later command. Then download into it. For a bare word:
|
|
57
186
|
|
|
58
187
|
```bash
|
|
59
|
-
gh run download <run> --repo marcusrbrown/systematic --name "connect-run-<run>-<attempt>" --dir "<DEST>"
|
|
188
|
+
gh run download <run> --repo github.com/marcusrbrown/systematic --name "connect-run-<run>-<attempt>" --dir "<DEST>"
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
For a named word, use the repository step 1 checked:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
gh run download <run> --repo github.com/<repo> --name "connect-run-<run>-<attempt>" --dir "<DEST>"
|
|
60
195
|
```
|
|
61
196
|
|
|
62
197
|
- `gh` fails because it is not logged in or the token cannot read the run: stop with `gh-not-authenticated`.
|
|
@@ -65,21 +200,23 @@ gh run download <run> --repo marcusrbrown/systematic --name "connect-run-<run>-<
|
|
|
65
200
|
|
|
66
201
|
The artifact holds one file, `run.json`, at its root. Do not open it and do not list the directory. The helper reads that one path and nothing else.
|
|
67
202
|
|
|
68
|
-
###
|
|
203
|
+
### 6. Import
|
|
69
204
|
|
|
70
205
|
```bash
|
|
71
206
|
# Resolve helper scripts relative to this skill's directory.
|
|
72
207
|
SKILL_DIR="<skill directory stated when this skill loads>";
|
|
73
208
|
node "$SKILL_DIR/scripts/connect.mjs" import <<'JSON'
|
|
74
|
-
{"directory": "<DEST>", "provenance": {"repo": "
|
|
209
|
+
{"directory": "<DEST>", "provenance": {"repo": "<repo>", "runId": "<run>", "commit": "<head commit>"}}
|
|
75
210
|
JSON
|
|
76
211
|
```
|
|
77
212
|
|
|
78
|
-
`directory` is the absolute path `mktemp -d` printed. `runId` is the run id from the `fetch:` word, without the attempt. Leave `commit` out when step
|
|
213
|
+
`directory` is the absolute path `mktemp -d` printed. `repo` is `<repo>`: `<repo>` is `marcusrbrown/systematic` for a bare word, and the named repository for a named word. `runId` is the run id from the `fetch:` word, without the attempt. Leave `commit` out when step 2 gave none. For a named word that `head_sha` is the caller's wrapper commit, not the callee's commit of Systematic's workflow. The record carries no attempt, so the request carries none either: the artifact name in step 4 is the only place the attempt is checked.
|
|
214
|
+
|
|
215
|
+
A named fetch that passed steps 1 to 3 has proven where the run came from. It has not widened what `import` accepts: `import` still checks every project of the record against the allowed checkouts by its own check, and refuses a candidate from a project that is not allowed as `repo-not-allowed`.
|
|
79
216
|
|
|
80
217
|
If `node` is missing, the helper file is gone, or `import` prints no JSON answer, the helper is unavailable. Remove `<DEST>`, print `helper-unavailable` and its hint, then `Connect failed`. Nothing was imported.
|
|
81
218
|
|
|
82
|
-
###
|
|
219
|
+
### 7. Report
|
|
83
220
|
|
|
84
221
|
The helper answers one line of JSON. Read `outcome`:
|
|
85
222
|
|
|
@@ -98,9 +235,12 @@ Print the reason as it is, then the hint.
|
|
|
98
235
|
|
|
99
236
|
| Reason | Hint |
|
|
100
237
|
|---|---|
|
|
101
|
-
| `not-
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
238
|
+
| `origin-not-allowed` | The named repository is not the origin of any allowed checkout. Nothing was downloaded. Allow-list a checkout of that repository in `connect.allow_projects`, then try again. |
|
|
239
|
+
| `repo-ambiguous` | Two or more allowed checkouts have the named repository as their origin. Nothing was downloaded. Remove all but one from the allow list. |
|
|
240
|
+
| `provenance-unprovable` | The named run cannot be shown to have called Systematic's `connect.yaml` at a commit on Systematic's default branch: the attempt's `referenced_workflows` is absent, empty or malformed, more than one entry matches, the `sha` is not 40 lowercase hex characters, the commit is not behind or identical to `main`, or an API call failed. Nothing was downloaded. This fails closed: it is a missing proof, not a finding that the run is hostile. To fix it, check that the caller's wrapper calls `marcusrbrown/systematic/.github/workflows/connect.yaml` at a commit on Systematic's `main`, then try again. If an API call failed, try again later. |
|
|
241
|
+
| `not-a-connect-run` | The run is not a run of Systematic's `connect.yaml`. For a bare word its top-level path is neither `.github/workflows/connect.yaml` nor `.github/workflows/connect-scheduled.yaml`. For a named word the attempt's `referenced_workflows` names other workflows only. Nothing was downloaded. Name a scheduled run of Systematic's `connect.yaml`, or of a caller that calls it, then try again. |
|
|
242
|
+
| `unsupported-run-event` | Only `schedule` and `workflow_dispatch` runs are read. Nothing was downloaded. Name a scheduled or manually dispatched run, then try again. |
|
|
243
|
+
| `run-not-found` | No run with that id in the repository, or, for a named word, no such attempt of it. Check the run and attempt in the report's fetch word, then try again. |
|
|
104
244
|
| `gh-not-authenticated` | `gh` is not logged in, or its token cannot read this repository's runs. Run `gh auth login` and try again. |
|
|
105
245
|
| `artifact-list-failed` | `gh` could not list the run's artifacts, or its answer was not a JSON array. Nothing was downloaded. Try again. |
|
|
106
246
|
| `artifact-not-found` | The run has no `connect-run-<run>-<attempt>` artifact for the attempt asked for. It stopped before it made a record. |
|
|
@@ -117,6 +257,8 @@ Print the reason as it is, then the hint.
|
|
|
117
257
|
| `lock-failed`, `publish-…` | The run could not be written. Nothing was imported. |
|
|
118
258
|
| `ledger-write-failed` | The run directory was written and the ledger was not. Run the fetch again. |
|
|
119
259
|
|
|
260
|
+
A run of `connect-scheduled.yaml`, Systematic's own wrapper, can be fetched only by a skill from a Systematic release that includes this change. An earlier skill refuses that path as `not-a-connect-run`. Earlier runs of `connect.yaml` fetch on any version.
|
|
261
|
+
|
|
120
262
|
## Reasons a candidate is refused
|
|
121
263
|
|
|
122
264
|
The helper prints one of these for each refused candidate. The record never supplies the text: it supplies only the candidate's title, which is cleaned of control characters and shortened first.
|
|
@@ -36,14 +36,15 @@ The digest header and the run record name the selection: `all`, the group, or th
|
|
|
36
36
|
|
|
37
37
|
## Reading a fetch
|
|
38
38
|
|
|
39
|
-
A `fetch:<run>.<attempt>` word,
|
|
39
|
+
A `fetch:<run>.<attempt>` word, a bare `fetch:<run>` for the newest attempt, or a named `fetch:<owner>/<repo>:<run>.<attempt>` for a run of another repository, is read from the same place as the mode tokens and the selection words. It brings the candidates of a scheduled CI run to this machine and follows `fetch-and-import.md`. A bare word means Systematic. A named word must name an allowed origin and must prove that its run called Systematic's reusable workflow; the reference lists both checks.
|
|
40
40
|
|
|
41
41
|
| Words found | Result |
|
|
42
42
|
|---|---|
|
|
43
|
-
| One `fetch:<run>.<attempt>` or `fetch:<run>`, or the same word twice or more | A fetch of that attempt,
|
|
43
|
+
| One `fetch:<run>.<attempt>`, `fetch:<run>` or `fetch:<owner>/<repo>:<run>.<attempt>`, or the same word twice or more | A fetch of that attempt, of the newest attempt of that run, or of that attempt of the named repository's run. It observes no host, dispatches no agent and asks nothing, so `mode:` has no effect. |
|
|
44
44
|
| `fetch:` with a `group:` or `projects:` word | Stop: `conflicting-selection`. |
|
|
45
45
|
| Two different `fetch:` words | Stop: `conflicting-selection`. |
|
|
46
46
|
| An empty value, or a value that is not a positive run id, or a run id and a positive attempt | Stop: `invalid-request`. |
|
|
47
|
+
| A named word without an attempt, or with a repository that is not a GitHub `owner/repo`, or with a run or attempt that is not a positive integer | Stop: `invalid-request`. |
|
|
47
48
|
|
|
48
49
|
A stop here happens before any command. End as for a failed run: the reason on a line of its own, then `Connect failed`.
|
|
49
50
|
|
|
@@ -54,6 +55,7 @@ Headless mode asks no question and offers nothing after the digest. It does not
|
|
|
54
55
|
- A host and version the helper does not support is refused: `begin` answers `unsupported-host`. Supported means the lowest version where the tool limits were observed, or any newer release of the same host and major version. A version below that, a prerelease, an unknown host, a version the helper cannot read and a release on its known-bad list are all refused. Interactive mode asks consent instead, except for a known-bad release: that is refused in every mode, and consent does not change it.
|
|
55
56
|
- A user decision (`decide`) is never taken. The digest is the only output.
|
|
56
57
|
- Anything unclear is a stop with a reason, not a question.
|
|
58
|
+
- A `Pins:` line in the summary is printed as the helper wrote it, unchanged, like every other summary line. It lists notes about declared pins, as codes and project keys only. Headless mode asks no question about it and the line never changes the outcome.
|
|
57
59
|
|
|
58
60
|
## Host permissions for unattended runs
|
|
59
61
|
|
|
@@ -76,7 +78,7 @@ Every run ends with exactly one of these lines as its last line. The reason and
|
|
|
76
78
|
| `Connect complete` | `import` answered `complete` (a fetch whose candidates were all checked and none refused), or `publish` answered `complete`: every project read, every offered rule covered by a complete family, nothing failed, and the run committed. Rules the run was not offered are not a degrade reason, and neither is the stale-citation check reaching its cap: the digest notes it under "Not read or not covered" and the run record keeps the counts, and the outcome is unchanged. Nothing found is still `complete`, labeled "no candidate in searched scope". |
|
|
77
79
|
| `Connect degraded` | `import` answered `degraded` (at least one candidate of the fetched record was refused; the summary names each), or `publish` answered `degraded`: something was not read, an offered rule was not covered, a file a candidate cited changed or vanished during the run (`evidence-changed`, `unresolved-source`; the rule of that candidate is then not counted as covered), or a bound on the file inventory, a family or a batch was reached. The digest names what. A degraded run is never proof that nothing is there. A dropped candidate never changes the outcome; the digest lists each one under "Dropped candidates" with its reason and quoted title, and the run record keeps the same list. |
|
|
78
80
|
| `Connect busy` | `begin` or `import` answered `busy`: another run holds the lock, or the holder cannot be verified. Nothing was written and nothing was dispatched. |
|
|
79
|
-
| `Connect failed` | Any other stop: a bad mode token, a bad `fetch:` word, a run that is not a scheduled `ce:connect` run, a missing or expired artifact, a record `import` cannot use, a refused selection, the helper missing, an unsupported host in headless mode, consent declined, no allowed projects, a malformed batch, or a helper error. Nothing was published. |
|
|
81
|
+
| `Connect failed` | Any other stop: a bad mode token, a bad `fetch:` word, a run that is not a scheduled `ce:connect` run, a named repository that is not an allowed origin, a named run whose provenance cannot be proven, a missing or expired artifact, a record `import` cannot use, a refused selection, the helper missing, an unsupported host in headless mode, consent declined, no allowed projects, a malformed batch, or a helper error. Nothing was published. |
|
|
80
82
|
|
|
81
83
|
Copy the final line from the helper's `finalLine` when `publish` answers. For every other stop, print the line from this table.
|
|
82
84
|
|
|
@@ -88,6 +90,25 @@ Rules that are not offered are not a reason to degrade a run. `Connect complete`
|
|
|
88
90
|
|
|
89
91
|
Coverage is kept in the ledger, and only for a committed run: an aborted or crashed run records none. It holds rule ids, hashes and run ids, no text. Coverage of a rule whose learning has disappeared is dropped. `ledger clear` removes coverage with the rest of the ledger, and the sweep starts over.
|
|
90
92
|
|
|
93
|
+
## Pin hints and notes
|
|
94
|
+
|
|
95
|
+
A user may declare dependency pins in config (`connect.pins`). At `begin` the helper turns each pin that matches a selected project and a selected checkout of the upstream into one line, and returns the lines as `pinHints`, keyed by project key. The skill copies them into the dispatch of the families that hold rules of the pinning project (Step 5 of the skill). A run with no pins has empty `pinHints` and `pinNotes`. For setting up `connect.pins`, see the [guide](https://fro.bot/systematic/guides/cross-project-connections/#declare-dependency-pins).
|
|
96
|
+
|
|
97
|
+
`pinNotes` is a separate channel from `degradeReasons`. A note explains why a declared pin gave no line, or what the helper cut, and it is not a degrade reason: it never degrades the run. The summary prints notes as one `Pins:` line. A note is a fixed code, with the 12-character key of the pinning project when it belongs to one:
|
|
98
|
+
|
|
99
|
+
| Code | Meaning |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `pin-file-missing` | The pin file is missing, a directory, a symlink, outside the project or unreadable. |
|
|
102
|
+
| `pin-file-too-large` | The pin file is over the read cap. |
|
|
103
|
+
| `pin-file-invalid` | The pin file is empty or is not valid JSON or JSONC. |
|
|
104
|
+
| `pin-key-absent` | The key does not lead to a value. |
|
|
105
|
+
| `pin-value-invalid` | The value is not a string of the allowed form, or a path in the pin cannot be rendered. |
|
|
106
|
+
| `pin-conflict` | Entries for one project, upstream and key name different files. The helper dropped them all. It carries no key. |
|
|
107
|
+
| `hints-truncated` | The helper cut the lines to its cap. It carries no key. |
|
|
108
|
+
| `notes-truncated` | The helper cut the notes to its cap. It carries no key. |
|
|
109
|
+
|
|
110
|
+
A pin whose project is not selected, or that no selected checkout matches, gives no line and no note. A hint is not evidence, and the researcher agent's rules and the helper's validation are unchanged.
|
|
111
|
+
|
|
91
112
|
## Reasons worth naming
|
|
92
113
|
|
|
93
114
|
Print the helper's `reason` as it is, then add the hint when one fits.
|