@veda-hq/niyam 0.6.21 → 0.6.23
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/README.md +136 -12
- package/dist/agent.js +33 -12
- package/dist/board-audit.js +177 -0
- package/dist/board.js +30 -4
- package/dist/cloud-key.js +193 -0
- package/dist/cloud.js +122 -4
- package/dist/doc-numbers.js +508 -0
- package/dist/doctor.js +77 -16
- package/dist/hermetic-git.js +32 -0
- package/dist/onboard.js +101 -25
- package/dist/renumber-doc.js +321 -0
- package/dist/run.js +45 -4
- package/dist/secrets.js +21 -0
- package/dist/session-start.js +31 -4
- package/dist/work-item-number.js +262 -0
- package/dist/work.js +78 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -444,11 +444,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
|
|
|
444
444
|
you (`label:needs-owner is:open`), Board (`type:Slice,Brief`, by Status,
|
|
445
445
|
showing linked pull requests), Work items (`type:"Work item"`, grouped by Step), Decisions
|
|
446
446
|
(`type:Decision`, grouped by Decision) and Reviews due (`"Review
|
|
447
|
-
date":<=@today`), with its workflows
|
|
448
|
-
|
|
447
|
+
date":<=@today`), with its workflows. A copy lacks one workflow: Auto-add
|
|
448
|
+
to project, which names a repository, and which GitHub's API can neither
|
|
449
|
+
create nor set. Without it, a Work item or Slice an agent opens is on no
|
|
450
|
+
board, so "By hand:" names it, and Auto-add sub-issues to project when a
|
|
451
|
+
Project lacks that too, with the repository and the filter
|
|
452
|
+
`is:issue is:open` to give it. What the board lacks is known only once you have signed in, so the
|
|
449
453
|
plan says "set up or check"; issue types are an organisation-wide
|
|
450
454
|
setting, so the plan says "org-wide" and lists what it would change. If
|
|
451
|
-
a copy's workflows arrive off, "By hand:" links where to turn them on.
|
|
455
|
+
a copy's workflows arrive off, "By hand:" links where to turn them on.
|
|
456
|
+
Auto-add adds an issue only as it opens or changes, never one already
|
|
457
|
+
open: `niyam board-audit` (below) lists those. A
|
|
452
458
|
Project of that title made before the template is left as it is: the plan's
|
|
453
459
|
yes does not replace it. When GitHub refuses the copy, or for such an
|
|
454
460
|
older Project, `onboard` adds the fields and makes or updates the views
|
|
@@ -601,10 +607,23 @@ hold their issues, so this reads no issue on its own. A Project whose Step
|
|
|
601
607
|
has no Done, made before it, gets one line saying so, and `onboard` adds the
|
|
602
608
|
option, keeping every item's Step. A workflow's `GITHUB_TOKEN` cannot write to a Project, so the
|
|
603
609
|
agent's push does this, with the agent token's `project` scope, with `board`
|
|
604
|
-
on
|
|
605
|
-
Claude cloud session's GitHub proxy, which refuses GraphQL.
|
|
610
|
+
on, through GitHub's REST API for Projects alone.
|
|
606
611
|
A board it cannot read, or a move GitHub refuses, is said and does not stop
|
|
607
|
-
the push; a push for a closed slice, such as a fix, moves nothing.
|
|
612
|
+
the push; a push for a closed slice, such as a fix, moves nothing. A Claude
|
|
613
|
+
cloud session's GitHub proxy lets through only `repos/{owner}/{repo}/…`, so
|
|
614
|
+
its push never reaches an organization's Projects and says only that the
|
|
615
|
+
workflow moves the slice. When a pull request from the repository opens or
|
|
616
|
+
reopens, the shared workflow's Slice started job makes the same moves, under
|
|
617
|
+
the same conditions, with a token from the board GitHub App. The client's
|
|
618
|
+
workflow passes it the app's client id and private key as the
|
|
619
|
+
`NIYAM_BOARD_APP_ID` and `NIYAM_BOARD_APP_KEY` secrets. With `board` on,
|
|
620
|
+
onboard writes them under the `niyam` job's secrets, the pull request job
|
|
621
|
+
alone. Where the repository lacks either, its own or its organization's,
|
|
622
|
+
onboard's by-hand list and its pull request say how to set up the app once
|
|
623
|
+
per organization: organization Projects read and write and repository Issues
|
|
624
|
+
read, installed on the repository. `niyam doctor` marks a missing one ▲.
|
|
625
|
+
Without them, the job says so in one line and passes, as it does when the
|
|
626
|
+
board refuses: the board never fails a pull request. When a pull request naming a slice merges into the default branch,
|
|
608
627
|
the shared workflow comments on the slice, linking the pull request, and
|
|
609
628
|
closes it, and the Project's Item closed workflow moves it to Done: a
|
|
610
629
|
`Slice: #N` line is not one of GitHub's closing keywords, so GitHub does not
|
|
@@ -617,6 +636,22 @@ beside it, still gets the comment; one that has it gets no second one. That job
|
|
|
617
636
|
pull requests from the repository itself: a fork's run gets a read-only token, so
|
|
618
637
|
a slice a fork's pull request builds is closed by hand.
|
|
619
638
|
|
|
639
|
+
**Checking the board.** `niyam board-audit [owner/repo] [--project <title>]`
|
|
640
|
+
compares a repository with its Project and changes nothing: the open issues
|
|
641
|
+
not on it, the unarchived items whose Status disagrees with their issue
|
|
642
|
+
(open but Done, or closed but not Done), and whether Auto-add to project
|
|
643
|
+
and Auto-add sub-issues to project are on. Open issues archived on the
|
|
644
|
+
Project are listed in one line but not counted, since the audit cannot tell
|
|
645
|
+
an archive made on purpose from one made before the issue reopened. The
|
|
646
|
+
repository is the clone's here when none is named, and the Project is the
|
|
647
|
+
one `.github/niyam.json`'s `"project"` names, else "<repo> work". GitHub's
|
|
648
|
+
API shows a workflow's name and whether it is on, not the repository or
|
|
649
|
+
filter it adds from, so the audit says so. It runs with `GH_TOKEN`, which
|
|
650
|
+
needs read access to the Project, and exits 0 when the board matches, 3 when
|
|
651
|
+
something is to fix, and 1 when it could not check. A Claude cloud
|
|
652
|
+
session's GitHub proxy refuses GraphQL and an organisation's Projects
|
|
653
|
+
(veda-hq/niyam#399), so there it says it cannot run and checks nothing.
|
|
654
|
+
|
|
620
655
|
**What needs the owner.** A request the owner made on the work item is its
|
|
621
656
|
own approval, linked as above. A fix needs none: it restores what the owner
|
|
622
657
|
approved and changes nothing they would see beyond it, so it is filed as a
|
|
@@ -913,6 +948,41 @@ records are in `.tmp/keep-going/`. The settings:
|
|
|
913
948
|
origin's default branch. `printMode` names older print-mode variables read beside `NIYAM_PRINT_MODE`;
|
|
914
949
|
`owner` is who the messages tell a session to tell; `tag` ends each message.
|
|
915
950
|
|
|
951
|
+
**Document numbers are never reused.** `niyam doc-number <kind>` prints the
|
|
952
|
+
next free number for a numbered document kind on stdout, and where it looked
|
|
953
|
+
on stderr (`--json` for both at once). It takes one past every number held in:
|
|
954
|
+
- every ref's history and every worktree's folder;
|
|
955
|
+
- the reservation refs;
|
|
956
|
+
- open pull requests;
|
|
957
|
+
- the titles of Work item issues and the frozen folders, for the kind they share.
|
|
958
|
+
|
|
959
|
+
`--reserve` claims the number for good with an atomic `git update-ref` in the
|
|
960
|
+
repository's shared git store, so concurrent sessions in linked worktrees get
|
|
961
|
+
distinct numbers. It refuses when any GitHub source could not be read.
|
|
962
|
+
`niyam renumber-doc <kind> <from> <to>` previews moving a document to another
|
|
963
|
+
number; `--apply` moves it and rewrites every reference and frontmatter
|
|
964
|
+
relationship to it, outside the history paths. `niyam work-item-number`,
|
|
965
|
+
run from a workflow on issue events and on a schedule, renumbers a Work item
|
|
966
|
+
filed with a taken number. It comments first, then retitles, and stops if the
|
|
967
|
+
title changed meanwhile. It also adds `label` to every Work item that lacks it.
|
|
968
|
+
The settings, inline or as the path of a JSON file:
|
|
969
|
+
|
|
970
|
+
```json
|
|
971
|
+
{ "docNumbers": {
|
|
972
|
+
"reservations": "refs/niyam/{kind}-reservations/",
|
|
973
|
+
"kinds": {
|
|
974
|
+
"adr": { "dir": "docs/adr", "citation": "ADR", "frontmatterKey": "adr",
|
|
975
|
+
"relationships": { "docs/adr": ["supersedes", "superseded_by"] } },
|
|
976
|
+
"rfc": { "dir": "docs/rfcs", "citation": "RFC", "frontmatterKey": "rfc",
|
|
977
|
+
"relationships": { "docs/rfcs": ["supersedes"] } } },
|
|
978
|
+
"workItems": { "kind": "rfc", "issueType": "Work item", "label": "work-item", "lastMovedIssue": 1,
|
|
979
|
+
"frozen": { "dir": "docs/work", "entries": [] } },
|
|
980
|
+
"history": ["docs/work/"]
|
|
981
|
+
} }
|
|
982
|
+
```
|
|
983
|
+
|
|
984
|
+
`workItems` is optional; so is `history`, whose `!` entries are exceptions.
|
|
985
|
+
|
|
916
986
|
**Design frames** is the `figma` feature, an optional extension for clients
|
|
917
987
|
that design in Figma: with it on and two Actions secrets, `FIGMA_LIBRARY`
|
|
918
988
|
(the design library's file key) and `FIGMA_TOKEN`, each State of the slice
|
|
@@ -1231,11 +1301,65 @@ session's shell, so run by hand there it always says STOP, which says
|
|
|
1231
1301
|
nothing about the session.
|
|
1232
1302
|
The hook's own line at session start is what counts.
|
|
1233
1303
|
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
while the
|
|
1237
|
-
an agent, so these pass, and GitHub records the agent as having
|
|
1238
|
-
them.
|
|
1304
|
+
By default, the platform authors and commits a cloud session's git commits as
|
|
1305
|
+
`Claude <noreply@anthropic.com>` and signs them with Anthropic's key
|
|
1306
|
+
(Verified), while the agent makes the push. PR identity checks only commits
|
|
1307
|
+
that claim an agent, so these pass, and GitHub records the agent as having
|
|
1308
|
+
pushed them.
|
|
1309
|
+
|
|
1310
|
+
**The agent's commits, signed.** A cloud environment whose variables hold
|
|
1311
|
+
the agent's cloud signing key, `NIYAM_SIGNING_KEY`, makes its commits the
|
|
1312
|
+
agent's, as on a Mac: authored and committed with the agent's no-reply
|
|
1313
|
+
address and signed with that key.
|
|
1314
|
+
|
|
1315
|
+
Once `session-start` confirms the login as the agent, it does four things:
|
|
1316
|
+
|
|
1317
|
+
- reads the account's id from the same GitHub answer;
|
|
1318
|
+
- writes the key to the agent's key file (`~/.ssh/<agent>_signing`, mode 0600) and checks GitHub lists its public half as one of the agent's signing keys;
|
|
1319
|
+
- makes a probe commit object, on no branch, with exactly the settings the session will get;
|
|
1320
|
+
- checks that its signature verifies as that key's.
|
|
1321
|
+
|
|
1322
|
+
Only then does it add the agent's author and committer variables and SSH
|
|
1323
|
+
signing, with `gpg.ssh.program` set back from the platform's own program to
|
|
1324
|
+
`ssh-keygen`, all together to `CLAUDE_ENV_FILE`. It also unsets the key's
|
|
1325
|
+
variable there, so commands do not carry it in their environment.
|
|
1326
|
+
|
|
1327
|
+
When any step fails, nothing is set and the commits stay Claude's, which PR
|
|
1328
|
+
identity passes. Steps that can fail: no key, one that is not an OpenSSH
|
|
1329
|
+
private key, a key GitHub does not list, a lookup the proxy refuses, or a
|
|
1330
|
+
probe that does not verify. The session's line says why and the session
|
|
1331
|
+
works on as the agent. A commit claiming the agent without the agent's
|
|
1332
|
+
signature would fail PR identity, so it is all or nothing.
|
|
1333
|
+
|
|
1334
|
+
Set the key up once per cloud environment, in your own terminal on the Mac
|
|
1335
|
+
`niyam machine` set up for the agent: run `niyam cloud-key [agent]` (`--yes`
|
|
1336
|
+
skips its one question). It does four things:
|
|
1337
|
+
|
|
1338
|
+
- makes a new ed25519 key in a private temporary folder, for the agent's cloud sessions alone, apart from the Mac's signing key, so it can be revoked on its own;
|
|
1339
|
+
- registers it as the agent's signing key, titled `niyam cloud signing`, with the token `machine` stored, and checks GitHub lists it;
|
|
1340
|
+
- puts `NIYAM_SIGNING_KEY=<the private key, base64>` on the clipboard, never on the screen;
|
|
1341
|
+
- deletes the files, at a Ctrl-C too.
|
|
1342
|
+
|
|
1343
|
+
Paste the line into the cloud environment's variables (https://claude.ai/code →
|
|
1344
|
+
the environment's settings). Claude Code has no API for them, so this step stays
|
|
1345
|
+
yours. A key GitHub does not list, or one the clipboard does not take, is deleted
|
|
1346
|
+
from GitHub again, since no one holds it, and so is one a Ctrl-C stops after it
|
|
1347
|
+
was registered.
|
|
1348
|
+
|
|
1349
|
+
`cloud-key` also names the agent's other cloud signing keys, by date and id. Delete
|
|
1350
|
+
one at https://github.com/settings/keys, signed in as the agent, once no environment
|
|
1351
|
+
uses it; `cloud-key` deletes none itself. It refuses in an agent session or a cloud
|
|
1352
|
+
session, and without a working agent token (`niyam machine` first). In a cloud
|
|
1353
|
+
session, `doctor` says whether the session's commits are the agent's, and names
|
|
1354
|
+
`niyam cloud-key` when the environment has no key.
|
|
1355
|
+
|
|
1356
|
+
Anyone who uses the environment can read its variables, and so can any
|
|
1357
|
+
command its sessions run. Claude's settings warn against keeping secrets
|
|
1358
|
+
there. Whoever holds the key can sign commits that GitHub shows as Verified
|
|
1359
|
+
for the agent, though pushing still needs the agent's GitHub connection,
|
|
1360
|
+
which PR identity checks. To revoke the key, delete it from the agent's
|
|
1361
|
+
signing keys. The platform's own git hooks may still add a `Co-authored-by`
|
|
1362
|
+
trailer for Claude.
|
|
1239
1363
|
|
|
1240
1364
|
The proxy refuses GitHub's GraphQL API, so the work rules and `reviews-due`
|
|
1241
1365
|
read only its REST API, here and everywhere else. The one exception is who
|
|
@@ -1420,7 +1544,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
|
|
|
1420
1544
|
once; nothing is built on install:
|
|
1421
1545
|
|
|
1422
1546
|
```bash
|
|
1423
|
-
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.
|
|
1547
|
+
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.23/veda-hq-niyam-0.6.23.tgz
|
|
1424
1548
|
```
|
|
1425
1549
|
|
|
1426
1550
|
The package puts one command on `PATH`, `niyam`. Since P-57 a release
|
package/dist/agent.js
CHANGED
|
@@ -187,7 +187,8 @@ const LOCKED_CONFIG = [
|
|
|
187
187
|
[`url.${GITHUB_WEB}/.insteadOf`, `ssh://${GITHUB_SSH}:22/`],
|
|
188
188
|
[`url.${GITHUB_WEB}/.insteadOf`, `ssh://${GITHUB_SSH_443}:443/`],
|
|
189
189
|
];
|
|
190
|
-
|
|
190
|
+
/** Git config, as the GIT_CONFIG_COUNT variables that carry it over every config file. */
|
|
191
|
+
export function configVars(config) {
|
|
191
192
|
return [
|
|
192
193
|
['GIT_CONFIG_COUNT', String(config.length)],
|
|
193
194
|
...config.flatMap(([key, value], i) => [
|
|
@@ -203,26 +204,46 @@ function configVars(config) {
|
|
|
203
204
|
* release since sets or reads that name (P-57).
|
|
204
205
|
*/
|
|
205
206
|
const AGENT_VARS_0610 = [AGENT_VAR, 'PROCESS_RULES_AGENT'];
|
|
207
|
+
/**
|
|
208
|
+
* The variables that make the agent the author and committer of a session's
|
|
209
|
+
* commits, over any `user.name` and `user.email` git config: the same in a
|
|
210
|
+
* local session's file and a cloud session's env file.
|
|
211
|
+
*/
|
|
212
|
+
export function authorVars(agent, id) {
|
|
213
|
+
const email = noreplyEmail(id, agent);
|
|
214
|
+
return [
|
|
215
|
+
['GIT_AUTHOR_NAME', agent],
|
|
216
|
+
['GIT_COMMITTER_NAME', agent],
|
|
217
|
+
['GIT_AUTHOR_EMAIL', email],
|
|
218
|
+
['GIT_COMMITTER_EMAIL', email],
|
|
219
|
+
];
|
|
220
|
+
}
|
|
221
|
+
/** Git config that signs commits and tags with the SSH key whose public half is at `pub`. */
|
|
222
|
+
export function signingConfig(pub) {
|
|
223
|
+
return [
|
|
224
|
+
['gpg.format', 'ssh'],
|
|
225
|
+
['user.signingkey', pub],
|
|
226
|
+
['commit.gpgsign', 'true'],
|
|
227
|
+
['tag.gpgsign', 'true'],
|
|
228
|
+
];
|
|
229
|
+
}
|
|
230
|
+
/** `vars` as shell lines exporting each, quoted. */
|
|
231
|
+
export function exportLines(vars) {
|
|
232
|
+
return vars.map(([name, value]) => `export ${name}=${quote(value)}`);
|
|
233
|
+
}
|
|
206
234
|
/** The variables an agent session gets, except GH_TOKEN. */
|
|
207
235
|
function identityVars(agent, id, paths, agentVars = [AGENT_VAR]) {
|
|
208
|
-
const email = noreplyEmail(id, agent);
|
|
209
236
|
const helper = `!f() { test "$1" = get && printf 'username=%s\\npassword=%s\\n' ${agent} "$GH_TOKEN"; }; f`;
|
|
210
237
|
const [reset, askpass, ...https] = LOCKED_CONFIG;
|
|
211
238
|
return [
|
|
212
239
|
...agentVars.map((name) => [name, agent]),
|
|
213
240
|
['GH_CONFIG_DIR', paths.gh],
|
|
214
|
-
|
|
215
|
-
['GIT_COMMITTER_NAME', agent],
|
|
216
|
-
['GIT_AUTHOR_EMAIL', email],
|
|
217
|
-
['GIT_COMMITTER_EMAIL', email],
|
|
241
|
+
...authorVars(agent, id),
|
|
218
242
|
['GIT_TERMINAL_PROMPT', '0'],
|
|
219
243
|
// Any SSH remote left (a host alias in ~/.ssh/config) fails instead of using the owner's key.
|
|
220
244
|
['GIT_SSH_COMMAND', NO_SSH],
|
|
221
245
|
...configVars([
|
|
222
|
-
|
|
223
|
-
['user.signingkey', `${paths.key}.pub`],
|
|
224
|
-
['commit.gpgsign', 'true'],
|
|
225
|
-
['tag.gpgsign', 'true'],
|
|
246
|
+
...signingConfig(`${paths.key}.pub`),
|
|
226
247
|
// After the reset, the agent's token goes to GitHub's host only.
|
|
227
248
|
reset,
|
|
228
249
|
[`credential.${GITHUB_WEB}.helper`, helper],
|
|
@@ -292,7 +313,7 @@ function sessionText(agent, id, paths, read, agentVars = [AGENT_VAR]) {
|
|
|
292
313
|
`[ -n "$GH_TOKEN" ] || export GH_TOKEN=${NO_TOKEN}`,
|
|
293
314
|
// Inherited `git -c` and config-file injection could bring back a helper; askpass could prompt.
|
|
294
315
|
`unset ${UNSET.join(' ')}`,
|
|
295
|
-
...identityVars(agent, id, paths, agentVars)
|
|
316
|
+
...exportLines(identityVars(agent, id, paths, agentVars)),
|
|
296
317
|
'',
|
|
297
318
|
].join('\n');
|
|
298
319
|
}
|
|
@@ -336,7 +357,7 @@ export function lockScript(home) {
|
|
|
336
357
|
`# Written by ${CLI} session-start. GitHub is locked out unless an agent identity below replaces this.`,
|
|
337
358
|
`export GH_TOKEN=${NO_TOKEN}`,
|
|
338
359
|
`unset ${UNSET.join(' ')}`,
|
|
339
|
-
...vars
|
|
360
|
+
...exportLines(vars),
|
|
340
361
|
'',
|
|
341
362
|
].join('\n');
|
|
342
363
|
}
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import { API, SETTINGS_PATH, repoAt } from './agent.js';
|
|
2
|
+
import { AUTO_ADD, AUTO_ADD_FILTER, graphql } from './board.js';
|
|
3
|
+
/** board-audit's options: the repository, and the Project's title. */
|
|
4
|
+
export function auditArgs(args) {
|
|
5
|
+
const parsed = {};
|
|
6
|
+
for (let at = 0; at < args.length; at++) {
|
|
7
|
+
const arg = args[at];
|
|
8
|
+
if (arg === '--project') {
|
|
9
|
+
const value = args[++at];
|
|
10
|
+
if (!value || value.startsWith('-'))
|
|
11
|
+
throw new Error("board-audit --project needs the Project's title");
|
|
12
|
+
parsed.project = value;
|
|
13
|
+
}
|
|
14
|
+
else if (parsed.slug === undefined && /^[\w.-]+\/[\w.-]+$/.test(arg)) {
|
|
15
|
+
parsed.slug = arg;
|
|
16
|
+
}
|
|
17
|
+
else {
|
|
18
|
+
throw new Error(`board-audit takes [owner/repo] [--project <title>], not "${arg}"`);
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
return parsed;
|
|
22
|
+
}
|
|
23
|
+
/** The `project` the repository's settings name, from the clone here when it is that repository, else from GitHub; undefined when they name none. */
|
|
24
|
+
async function settingsTitle(sys, token, slug) {
|
|
25
|
+
let text;
|
|
26
|
+
try {
|
|
27
|
+
const here = repoAt(sys);
|
|
28
|
+
const path = `${here.root}/${SETTINGS_PATH}`;
|
|
29
|
+
if (here.slug.toLowerCase() === slug.toLowerCase() && sys.exists(path))
|
|
30
|
+
text = sys.read(path);
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
// fail-open: not in a clone, so the settings come from GitHub, read next.
|
|
34
|
+
}
|
|
35
|
+
if (text === undefined) {
|
|
36
|
+
const { status, json } = await sys.http(`${API}/repos/${slug}/contents/${SETTINGS_PATH}`, { token });
|
|
37
|
+
const content = json?.content;
|
|
38
|
+
if (status === 404)
|
|
39
|
+
return undefined;
|
|
40
|
+
if (status !== 200 || typeof content !== 'string')
|
|
41
|
+
throw new Error(`cannot read ${slug}'s ${SETTINGS_PATH} (HTTP ${status})`);
|
|
42
|
+
text = Buffer.from(content, 'base64').toString('utf8');
|
|
43
|
+
}
|
|
44
|
+
const raw = JSON.parse(text);
|
|
45
|
+
const project = raw !== null && typeof raw === 'object' && 'project' in raw ? raw.project : undefined;
|
|
46
|
+
return typeof project === 'string' && project.trim() ? project.trim() : undefined;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Compares `slug`'s issues with its open Project titled `title`, reading only:
|
|
50
|
+
* the open issues not on it, the items whose Status disagrees with their
|
|
51
|
+
* issue, and whether the auto-add workflows are on. GitHub's API shows a
|
|
52
|
+
* workflow's name and whether it is on, not the repository or filter it adds
|
|
53
|
+
* from.
|
|
54
|
+
*/
|
|
55
|
+
export async function auditBoard(sys, token, slug, title) {
|
|
56
|
+
const [owner, name] = slug.split('/');
|
|
57
|
+
let project;
|
|
58
|
+
for (let after = null;;) {
|
|
59
|
+
const read = (await graphql(sys, token, 'query BoardAuditProject($login: String!, $title: String!, $after: String) { repositoryOwner(login: $login) { ... on ProjectV2Owner { projectsV2(first: 100, query: $title, after: $after) { nodes { id title url closed } pageInfo { hasNextPage endCursor } } } } }', { login: owner, title, after }));
|
|
60
|
+
const projects = read.repositoryOwner?.projectsV2;
|
|
61
|
+
if (!projects)
|
|
62
|
+
throw new Error(`GitHub shows no owner ${owner} with Projects`);
|
|
63
|
+
project = projects.nodes.find((node) => node.title === title && !node.closed);
|
|
64
|
+
if (project || !projects.pageInfo.hasNextPage)
|
|
65
|
+
break;
|
|
66
|
+
after = projects.pageInfo.endCursor;
|
|
67
|
+
}
|
|
68
|
+
if (!project)
|
|
69
|
+
throw new Error(`${owner} has no open Project titled "${title}"; name it with --project`);
|
|
70
|
+
const missing = [];
|
|
71
|
+
const archived = [];
|
|
72
|
+
for (let after = null;;) {
|
|
73
|
+
const read = (await graphql(sys, token, 'query BoardAuditIssues($owner: String!, $name: String!, $after: String) { repository(owner: $owner, name: $name) { issues(states: OPEN, first: 100, after: $after) { nodes { number title projectItems(first: 50, includeArchived: true) { nodes { isArchived project { id } } } } pageInfo { hasNextPage endCursor } } } }', { owner, name, after }));
|
|
74
|
+
if (!read.repository)
|
|
75
|
+
throw new Error(`GitHub shows no repository ${slug}`);
|
|
76
|
+
for (const issue of read.repository.issues.nodes) {
|
|
77
|
+
const items = issue.projectItems.nodes.filter((item) => item.project.id === project.id);
|
|
78
|
+
if (items.some((item) => !item.isArchived))
|
|
79
|
+
continue;
|
|
80
|
+
(items.length > 0 ? archived : missing).push({ number: issue.number, title: issue.title });
|
|
81
|
+
}
|
|
82
|
+
if (!read.repository.issues.pageInfo.hasNextPage)
|
|
83
|
+
break;
|
|
84
|
+
after = read.repository.issues.pageInfo.endCursor;
|
|
85
|
+
}
|
|
86
|
+
const disagree = [];
|
|
87
|
+
let workflows = [];
|
|
88
|
+
for (let after = null;;) {
|
|
89
|
+
const read = (await graphql(sys, token, 'query BoardAuditItems($id: ID!, $after: String) { node(id: $id) { ... on ProjectV2 { workflows(first: 50) { nodes { name enabled } } items(first: 100, after: $after) { nodes { isArchived status: fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } } content { __typename ... on Issue { number title state repository { nameWithOwner } } } } pageInfo { hasNextPage endCursor } } } } }', { id: project.id, after }));
|
|
90
|
+
workflows = read.node.workflows.nodes;
|
|
91
|
+
for (const item of read.node.items.nodes) {
|
|
92
|
+
const issue = item.content;
|
|
93
|
+
if (item.isArchived || issue?.__typename !== 'Issue' || issue.number === undefined || issue.repository?.nameWithOwner.toLowerCase() !== slug.toLowerCase())
|
|
94
|
+
continue;
|
|
95
|
+
const status = item.status?.name;
|
|
96
|
+
const done = status?.toLowerCase() === 'done';
|
|
97
|
+
const open = issue.state === 'OPEN';
|
|
98
|
+
if (open === done)
|
|
99
|
+
disagree.push({ number: issue.number, title: issue.title ?? '', state: open ? 'open' : 'closed', status });
|
|
100
|
+
}
|
|
101
|
+
if (!read.node.items.pageInfo.hasNextPage)
|
|
102
|
+
break;
|
|
103
|
+
after = read.node.items.pageInfo.endCursor;
|
|
104
|
+
}
|
|
105
|
+
return {
|
|
106
|
+
project: { title: project.title, url: project.url },
|
|
107
|
+
missing: missing.sort((a, b) => a.number - b.number),
|
|
108
|
+
archived: archived.sort((a, b) => a.number - b.number),
|
|
109
|
+
disagree: disagree.sort((a, b) => a.number - b.number),
|
|
110
|
+
workflows: AUTO_ADD.map((name) => ({ name, on: workflows.find((workflow) => workflow.name === name)?.enabled })),
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
/** The audit as lines, ✓ or ✗ each, with what to do; and how many things are wrong. */
|
|
114
|
+
export function auditLines(audit, slug) {
|
|
115
|
+
const { url } = audit.project;
|
|
116
|
+
const lines = [`board-audit: ${slug} on "${audit.project.title}" (${url})`];
|
|
117
|
+
let wrong = 0;
|
|
118
|
+
for (const { name, on } of audit.workflows) {
|
|
119
|
+
if (on) {
|
|
120
|
+
lines.push(`✓ workflow ${name} is on`);
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
wrong++;
|
|
124
|
+
const what = name === 'Auto-add to project' ? `, for the repository ${slug} with the filter ${AUTO_ADD_FILTER}` : '';
|
|
125
|
+
lines.push(on === false ? `✗ workflow ${name} is off: turn it on at ${url}/workflows${what}` : `✗ workflow ${name} is missing: add it at ${url}/workflows${what} (GitHub's API cannot)`);
|
|
126
|
+
}
|
|
127
|
+
lines.push(` GitHub's API shows whether a workflow is on, not the repository or filter it adds from; Auto-add adds an issue only as it opens or changes, never one already open`);
|
|
128
|
+
if (audit.missing.length === 0)
|
|
129
|
+
lines.push('✓ every open issue is on the board');
|
|
130
|
+
else {
|
|
131
|
+
wrong += audit.missing.length;
|
|
132
|
+
const one = audit.missing.length === 1;
|
|
133
|
+
lines.push(`✗ ${audit.missing.length} open issue${one ? ' is' : 's are'} not on the board: add ${one ? 'it' : 'them'} at ${url} (+ Add item, then #N), or gh project item-add`);
|
|
134
|
+
for (const issue of audit.missing)
|
|
135
|
+
lines.push(` #${issue.number} ${issue.title}`);
|
|
136
|
+
}
|
|
137
|
+
if (audit.archived.length > 0) {
|
|
138
|
+
// Archived by someone, or by the auto-archive workflow before a reopen: the audit cannot tell, so it says them without counting them.
|
|
139
|
+
const plural = audit.archived.length === 1 ? ' is' : 's are';
|
|
140
|
+
lines.push(`- ${audit.archived.length} open issue${plural} archived on the board, so hidden there; restore any that belong on it: ${audit.archived.map((issue) => `#${issue.number}`).join(', ')}`);
|
|
141
|
+
}
|
|
142
|
+
if (audit.disagree.length === 0)
|
|
143
|
+
lines.push("✓ every item's Status agrees with its issue");
|
|
144
|
+
else {
|
|
145
|
+
wrong += audit.disagree.length;
|
|
146
|
+
lines.push(`✗ ${audit.disagree.length} item${audit.disagree.length === 1 ? "'s Status disagrees" : "s' Status disagree"} with the issue: set it at ${url}`);
|
|
147
|
+
for (const issue of audit.disagree)
|
|
148
|
+
lines.push(` #${issue.number} is ${issue.state}, Status ${issue.status ?? 'empty'}: ${issue.title}`);
|
|
149
|
+
}
|
|
150
|
+
lines.push(wrong > 0 ? `board-audit: ${wrong} to fix` : audit.archived.length > 0 ? 'board-audit: nothing to fix but the archived issues above' : 'board-audit: the board matches the repository');
|
|
151
|
+
return { lines, wrong };
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* `niyam board-audit [owner/repo] [--project <title>]`: lists where the
|
|
155
|
+
* repository and its work board disagree, changing nothing. The repository
|
|
156
|
+
* is the clone's here when none is named; the Project is the one the
|
|
157
|
+
* settings' `project` names, or `<repo> work`. Exit 0 when they agree, 3
|
|
158
|
+
* when something is to fix, 1 when it could not run. A Claude cloud
|
|
159
|
+
* session's GitHub proxy refuses GraphQL and every path outside
|
|
160
|
+
* `repos/{owner}/{repo}/…` (veda-hq/niyam#399), so the audit cannot run there.
|
|
161
|
+
*/
|
|
162
|
+
export async function boardAudit(sys, io, args) {
|
|
163
|
+
if (sys.env.CLAUDE_CODE_REMOTE === 'true') {
|
|
164
|
+
io.err("board-audit: cannot run in a Claude cloud session: its GitHub proxy refuses GraphQL and an organisation's Projects (veda-hq/niyam#399), so nothing was checked; run it on a Mac");
|
|
165
|
+
return 1;
|
|
166
|
+
}
|
|
167
|
+
const parsed = auditArgs(args);
|
|
168
|
+
const token = sys.env.GH_TOKEN;
|
|
169
|
+
if (!token)
|
|
170
|
+
throw new Error('board-audit needs GH_TOKEN, with read access to the Project: run it in an agent session, or GH_TOKEN="$(gh auth token)" niyam board-audit');
|
|
171
|
+
const slug = parsed.slug ?? repoAt(sys).slug;
|
|
172
|
+
const title = parsed.project ?? (await settingsTitle(sys, token, slug)) ?? `${slug.split('/')[1]} work`;
|
|
173
|
+
const { lines, wrong } = auditLines(await auditBoard(sys, token, slug, title), slug);
|
|
174
|
+
for (const line of lines)
|
|
175
|
+
io.out(line);
|
|
176
|
+
return wrong === 0 ? 0 : 3;
|
|
177
|
+
}
|
package/dist/board.js
CHANGED
|
@@ -49,6 +49,20 @@ const GROUPING = [
|
|
|
49
49
|
* workflow takes closed items off after it.
|
|
50
50
|
*/
|
|
51
51
|
const ARCHIVE_FILTER = 'is:closed updated:<@today-7d';
|
|
52
|
+
/**
|
|
53
|
+
* The Project workflows that put a repository's issues on the board, by
|
|
54
|
+
* GitHub's names. GitHub's API can neither create nor set one, and lists
|
|
55
|
+
* one only once it is set up; a copy of the template has no Auto-add to
|
|
56
|
+
* project, since that one names a repository. Without them an issue an
|
|
57
|
+
* agent opens directly, such as a Work item or a Slice, is on no board.
|
|
58
|
+
*/
|
|
59
|
+
export const AUTO_ADD = ['Auto-add to project', 'Auto-add sub-issues to project'];
|
|
60
|
+
/** The filter Auto-add to project takes: every open issue of the repository. */
|
|
61
|
+
export const AUTO_ADD_FILTER = 'is:issue is:open';
|
|
62
|
+
/** What the owner sets up for an auto-add workflow that is missing, at the repository `slug`. */
|
|
63
|
+
function autoAddStep(name, slug) {
|
|
64
|
+
return name === 'Auto-add to project' ? `${name}, for the repository ${slug} with the filter ${AUTO_ADD_FILTER}` : `${name}, turned on`;
|
|
65
|
+
}
|
|
52
66
|
/**
|
|
53
67
|
* How the owner shows Type on Needs you. GitHub's API can neither read nor
|
|
54
68
|
* set the issue-type column: GraphQL lists no such field, REST cannot update
|
|
@@ -66,7 +80,7 @@ export function viewsChecklist(url) {
|
|
|
66
80
|
` [ ] Workflows → Auto-archive items: ${ARCHIVE_FILTER}`,
|
|
67
81
|
];
|
|
68
82
|
}
|
|
69
|
-
async function graphql(sys, token, query, variables) {
|
|
83
|
+
export async function graphql(sys, token, query, variables) {
|
|
70
84
|
const { status, json } = await sys.http(`${API}/graphql`, { method: 'POST', token, body: { query, variables } });
|
|
71
85
|
const reply = json;
|
|
72
86
|
if (status !== 200 || reply?.errors?.length || !reply?.data) {
|
|
@@ -248,6 +262,12 @@ approved) {
|
|
|
248
262
|
}
|
|
249
263
|
io.out(`- Board shows slices and briefs; Done keeps one until the Auto-archive items workflow archives it, with the template's filter ${ARCHIVE_FILTER}, which GitHub's API can neither read nor set`);
|
|
250
264
|
}
|
|
265
|
+
if (done.missing.length > 0) {
|
|
266
|
+
const steps = done.missing.map((name) => autoAddStep(name, slug)).join('; ');
|
|
267
|
+
const plural = done.missing.length === 1 ? '' : 's';
|
|
268
|
+
io.out(`Add the workflow${plural} ${steps} in ${project.url} → Workflows (GitHub's API cannot); it adds issues as they open or change, not those already open, which niyam board-audit lists`);
|
|
269
|
+
byHand.push(`Once for the board: at ${project.url}/workflows, add the workflow${plural} ${steps}, which GitHub's API cannot; then niyam board-audit lists the open issues still not on the board.`);
|
|
270
|
+
}
|
|
251
271
|
if (done.off.length > 0) {
|
|
252
272
|
io.out(`Turn on the workflows ${done.off.join(', ')} in ${project.url} → Workflows (GitHub's API cannot)`);
|
|
253
273
|
byHand.push(`Once for the board: turn on the workflow${done.off.length === 1 ? '' : 's'} ${done.off.join(', ')} at ${project.url}/workflows, which GitHub's API cannot.`);
|
|
@@ -297,7 +317,8 @@ async function copyTemplate(sys, io, token, ownerId, title, instead) {
|
|
|
297
317
|
/**
|
|
298
318
|
* What a copy of the template has that GitHub's API cannot set: whether the
|
|
299
319
|
* views are grouped as the template's are, which marks a Project copied from
|
|
300
|
-
* it,
|
|
320
|
+
* it, the names of its workflows that are off, and the auto-add workflows it
|
|
321
|
+
* lacks.
|
|
301
322
|
*/
|
|
302
323
|
async function finished(sys, token, projectId) {
|
|
303
324
|
const read = (await graphql(sys, token, 'query($id: ID!) { node(id: $id) { ... on ProjectV2 { views(first: 50) { nodes { name groupByFields(first: 5) { nodes { ... on ProjectV2FieldCommon { name } } } } } workflows(first: 50) { nodes { name enabled } } } } }', { id: projectId }));
|
|
@@ -305,6 +326,7 @@ async function finished(sys, token, projectId) {
|
|
|
305
326
|
return {
|
|
306
327
|
grouped: GROUPING.every(({ view, field }) => views.some((had) => had.name === view && had.groupByFields.nodes.some((by) => by.name === field))),
|
|
307
328
|
off: read.node.workflows.nodes.filter((workflow) => !workflow.enabled).map((workflow) => workflow.name),
|
|
329
|
+
missing: AUTO_ADD.filter((name) => !read.node.workflows.nodes.some((workflow) => workflow.name === name)),
|
|
308
330
|
};
|
|
309
331
|
}
|
|
310
332
|
/** The field kinds whose values move with an item; the others belong to the issue or are GitHub's own. */
|
|
@@ -588,8 +610,12 @@ export async function boardSwept(sys, token, slug) {
|
|
|
588
610
|
* Work item's Step to Build, as its first slice has started; and every
|
|
589
611
|
* other Work item to the Step `stepDue` gives it, so a closed one is Done
|
|
590
612
|
* and a new one is at Frame. A workflow's GITHUB_TOKEN cannot write a
|
|
591
|
-
* Project, so the agent's
|
|
592
|
-
*
|
|
613
|
+
* Project, so this runs with the agent's token on its push from the desktop,
|
|
614
|
+
* and with the board GitHub App's token in the shared workflow's Slice
|
|
615
|
+
* started job when the pull request opens. A Claude cloud session's proxy
|
|
616
|
+
* refuses GraphQL and every path outside `repos/{owner}/{repo}/…`, so it
|
|
617
|
+
* never reaches an org's Projects; there only the workflow moves the board.
|
|
618
|
+
* It uses GitHub's REST API alone. Returns what moved, as lines.
|
|
593
619
|
*/
|
|
594
620
|
export async function boardStarted(sys, token, slug, slice) {
|
|
595
621
|
const issue = (await rest(sys, token, `${API}/repos/${slug}/issues/${slice}`)).json;
|