@veda-hq/niyam 0.6.22 → 0.6.24
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 +130 -13
- package/dist/agent.js +33 -12
- package/dist/board-audit.js +177 -0
- package/dist/board.js +30 -4
- package/dist/cloud-key.js +219 -0
- package/dist/cloud.js +122 -4
- package/dist/doctor.js +77 -16
- package/dist/onboard.js +152 -28
- package/dist/pr-autocreate.js +87 -12
- package/dist/run.js +23 -4
- package/dist/secrets.js +21 -0
- package/dist/session-start.js +31 -4
- package/dist/work.js +78 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -421,7 +421,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
|
|
|
421
421
|
every run (see Claude cloud sessions below); a cloud session with no
|
|
422
422
|
niyam runs it from the SessionStart hook, so there is nothing to paste,
|
|
423
423
|
and the first time, the plan lists the one connection of claude.ai's
|
|
424
|
-
GitHub as the agent, once per claude.ai account.
|
|
424
|
+
GitHub as the agent, once per claude.ai account. When the agent has no
|
|
425
|
+
signing key on GitHub titled `niyam cloud signing`, the plan's Claude
|
|
426
|
+
cloud group also lists one, "signing key for AGENT, on the clipboard":
|
|
427
|
+
as its last step, after the pull request opens, `onboard` makes it as
|
|
428
|
+
`niyam cloud-key` does (below), and "By hand:" starts with the paste
|
|
429
|
+
into each cloud environment's variables. The key is the agent's, not the
|
|
430
|
+
repository's, so onboarding a second repository finds it and says nothing
|
|
431
|
+
about it. A key that fails only warns, leaving the pull request and every
|
|
432
|
+
step before it in place, and "By hand:" names `niyam cloud-key <agent>`
|
|
433
|
+
instead; so does a run where `cloud-key` would refuse, in a Claude Code
|
|
434
|
+
or cloud session. A dry run plans no key. Where the
|
|
425
435
|
repo still has `.github/process-rules/cloud-setup.sh`, which releases up
|
|
426
436
|
to 0.6.10 wrote beside it, the pull request deletes it, but only where it
|
|
427
437
|
leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
|
|
@@ -444,11 +454,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
|
|
|
444
454
|
you (`label:needs-owner is:open`), Board (`type:Slice,Brief`, by Status,
|
|
445
455
|
showing linked pull requests), Work items (`type:"Work item"`, grouped by Step), Decisions
|
|
446
456
|
(`type:Decision`, grouped by Decision) and Reviews due (`"Review
|
|
447
|
-
date":<=@today`), with its workflows
|
|
448
|
-
|
|
457
|
+
date":<=@today`), with its workflows. A copy lacks one workflow: Auto-add
|
|
458
|
+
to project, which names a repository, and which GitHub's API can neither
|
|
459
|
+
create nor set. Without it, a Work item or Slice an agent opens is on no
|
|
460
|
+
board, so "By hand:" names it, and Auto-add sub-issues to project when a
|
|
461
|
+
Project lacks that too, with the repository and the filter
|
|
462
|
+
`is:issue is:open` to give it. What the board lacks is known only once you have signed in, so the
|
|
449
463
|
plan says "set up or check"; issue types are an organisation-wide
|
|
450
464
|
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.
|
|
465
|
+
a copy's workflows arrive off, "By hand:" links where to turn them on.
|
|
466
|
+
Auto-add adds an issue only as it opens or changes, never one already
|
|
467
|
+
open: `niyam board-audit` (below) lists those. A
|
|
452
468
|
Project of that title made before the template is left as it is: the plan's
|
|
453
469
|
yes does not replace it. When GitHub refuses the copy, or for such an
|
|
454
470
|
older Project, `onboard` adds the fields and makes or updates the views
|
|
@@ -601,10 +617,23 @@ hold their issues, so this reads no issue on its own. A Project whose Step
|
|
|
601
617
|
has no Done, made before it, gets one line saying so, and `onboard` adds the
|
|
602
618
|
option, keeping every item's Step. A workflow's `GITHUB_TOKEN` cannot write to a Project, so the
|
|
603
619
|
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.
|
|
620
|
+
on, through GitHub's REST API for Projects alone.
|
|
606
621
|
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.
|
|
622
|
+
the push; a push for a closed slice, such as a fix, moves nothing. A Claude
|
|
623
|
+
cloud session's GitHub proxy lets through only `repos/{owner}/{repo}/…`, so
|
|
624
|
+
its push never reaches an organization's Projects and says only that the
|
|
625
|
+
workflow moves the slice. When a pull request from the repository opens or
|
|
626
|
+
reopens, the shared workflow's Slice started job makes the same moves, under
|
|
627
|
+
the same conditions, with a token from the board GitHub App. The client's
|
|
628
|
+
workflow passes it the app's client id and private key as the
|
|
629
|
+
`NIYAM_BOARD_APP_ID` and `NIYAM_BOARD_APP_KEY` secrets. With `board` on,
|
|
630
|
+
onboard writes them under the `niyam` job's secrets, the pull request job
|
|
631
|
+
alone. Where the repository lacks either, its own or its organization's,
|
|
632
|
+
onboard's by-hand list and its pull request say how to set up the app once
|
|
633
|
+
per organization: organization Projects read and write and repository Issues
|
|
634
|
+
read, installed on the repository. `niyam doctor` marks a missing one ▲.
|
|
635
|
+
Without them, the job says so in one line and passes, as it does when the
|
|
636
|
+
board refuses: the board never fails a pull request. When a pull request naming a slice merges into the default branch,
|
|
608
637
|
the shared workflow comments on the slice, linking the pull request, and
|
|
609
638
|
closes it, and the Project's Item closed workflow moves it to Done: a
|
|
610
639
|
`Slice: #N` line is not one of GitHub's closing keywords, so GitHub does not
|
|
@@ -617,6 +646,22 @@ beside it, still gets the comment; one that has it gets no second one. That job
|
|
|
617
646
|
pull requests from the repository itself: a fork's run gets a read-only token, so
|
|
618
647
|
a slice a fork's pull request builds is closed by hand.
|
|
619
648
|
|
|
649
|
+
**Checking the board.** `niyam board-audit [owner/repo] [--project <title>]`
|
|
650
|
+
compares a repository with its Project and changes nothing: the open issues
|
|
651
|
+
not on it, the unarchived items whose Status disagrees with their issue
|
|
652
|
+
(open but Done, or closed but not Done), and whether Auto-add to project
|
|
653
|
+
and Auto-add sub-issues to project are on. Open issues archived on the
|
|
654
|
+
Project are listed in one line but not counted, since the audit cannot tell
|
|
655
|
+
an archive made on purpose from one made before the issue reopened. The
|
|
656
|
+
repository is the clone's here when none is named, and the Project is the
|
|
657
|
+
one `.github/niyam.json`'s `"project"` names, else "<repo> work". GitHub's
|
|
658
|
+
API shows a workflow's name and whether it is on, not the repository or
|
|
659
|
+
filter it adds from, so the audit says so. It runs with `GH_TOKEN`, which
|
|
660
|
+
needs read access to the Project, and exits 0 when the board matches, 3 when
|
|
661
|
+
something is to fix, and 1 when it could not check. A Claude cloud
|
|
662
|
+
session's GitHub proxy refuses GraphQL and an organisation's Projects
|
|
663
|
+
(veda-hq/niyam#399), so there it says it cannot run and checks nothing.
|
|
664
|
+
|
|
620
665
|
**What needs the owner.** A request the owner made on the work item is its
|
|
621
666
|
own approval, linked as above. A fix needs none: it restores what the owner
|
|
622
667
|
approved and changes nothing they would see beyond it, so it is filed as a
|
|
@@ -888,6 +933,21 @@ checked. The settings:
|
|
|
888
933
|
`retire`, a command with `{number}` for the merged pull request, is the way out
|
|
889
934
|
`refuse-retired` names; `footer` ends the placeholder body.
|
|
890
935
|
|
|
936
|
+
**On sarathi's Auto-fix list.** Outside a cloud session, `claude-hook` puts
|
|
937
|
+
the open pull request it opened or found on the session's sarathi Auto-fix
|
|
938
|
+
list (sarathi 0.6.15's `autofix-watch.sh`): an `opened` row
|
|
939
|
+
`{ "at", "pr": "owner/repo#N", "url", "event": "opened", "source": "niyam pr-autocreate" }`
|
|
940
|
+
in `<dir>/<session id>.jsonl`, where `<dir>` is `SARATHI_AUTOFIX_DIR`, else
|
|
941
|
+
`$XDG_STATE_HOME/sarathi/autofix`, else `~/.local/state/sarathi/autofix`. A
|
|
942
|
+
pull request the list names already gets no second row. With
|
|
943
|
+
`"autofixList": true`, for a repository whose sessions run that sarathi hook,
|
|
944
|
+
the instruction leaves out its `set_monitor` step, because sarathi's warning
|
|
945
|
+
repeats that call at every `wrap_up` until the app confirms Auto-fix. The
|
|
946
|
+
ToolSearch step, the `<pr-created>` tag and `bind_pr` stay: without them the
|
|
947
|
+
app refuses `set_monitor` for a pull request a hook opened. When the row
|
|
948
|
+
cannot be written, or the session id cannot name a list, the whole
|
|
949
|
+
instruction goes out.
|
|
950
|
+
|
|
891
951
|
**Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
|
|
892
952
|
sends a session back while its branch has commits the base lacks and its
|
|
893
953
|
pull request has not merged at this commit, saying what is left (push, open
|
|
@@ -1266,11 +1326,68 @@ session's shell, so run by hand there it always says STOP, which says
|
|
|
1266
1326
|
nothing about the session.
|
|
1267
1327
|
The hook's own line at session start is what counts.
|
|
1268
1328
|
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
while the
|
|
1272
|
-
an agent, so these pass, and GitHub records the agent as having
|
|
1273
|
-
them.
|
|
1329
|
+
By default, the platform authors and commits a cloud session's git commits as
|
|
1330
|
+
`Claude <noreply@anthropic.com>` and signs them with Anthropic's key
|
|
1331
|
+
(Verified), while the agent makes the push. PR identity checks only commits
|
|
1332
|
+
that claim an agent, so these pass, and GitHub records the agent as having
|
|
1333
|
+
pushed them.
|
|
1334
|
+
|
|
1335
|
+
**The agent's commits, signed.** A cloud environment whose variables hold
|
|
1336
|
+
the agent's cloud signing key, `NIYAM_SIGNING_KEY`, makes its commits the
|
|
1337
|
+
agent's, as on a Mac: authored and committed with the agent's no-reply
|
|
1338
|
+
address and signed with that key.
|
|
1339
|
+
|
|
1340
|
+
Once `session-start` confirms the login as the agent, it does four things:
|
|
1341
|
+
|
|
1342
|
+
- reads the account's id from the same GitHub answer;
|
|
1343
|
+
- 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;
|
|
1344
|
+
- makes a probe commit object, on no branch, with exactly the settings the session will get;
|
|
1345
|
+
- checks that its signature verifies as that key's.
|
|
1346
|
+
|
|
1347
|
+
Only then does it add the agent's author and committer variables and SSH
|
|
1348
|
+
signing, with `gpg.ssh.program` set back from the platform's own program to
|
|
1349
|
+
`ssh-keygen`, all together to `CLAUDE_ENV_FILE`. It also unsets the key's
|
|
1350
|
+
variable there, so commands do not carry it in their environment.
|
|
1351
|
+
|
|
1352
|
+
When any step fails, nothing is set and the commits stay Claude's, which PR
|
|
1353
|
+
identity passes. Steps that can fail: no key, one that is not an OpenSSH
|
|
1354
|
+
private key, a key GitHub does not list, a lookup the proxy refuses, or a
|
|
1355
|
+
probe that does not verify. The session's line says why and the session
|
|
1356
|
+
works on as the agent. A commit claiming the agent without the agent's
|
|
1357
|
+
signature would fail PR identity, so it is all or nothing.
|
|
1358
|
+
|
|
1359
|
+
`niyam onboard` makes the key the first time it runs for an agent that has
|
|
1360
|
+
none (see Adopting above), so all that is left is the paste. To make one
|
|
1361
|
+
yourself, as when the line was lost, run `niyam cloud-key [agent]` in your own
|
|
1362
|
+
terminal on the Mac `niyam machine` set up for the agent (`--yes` skips its
|
|
1363
|
+
one question). One line serves every cloud environment the agent works in.
|
|
1364
|
+
`onboard` and `cloud-key` make the key alike, in four steps:
|
|
1365
|
+
|
|
1366
|
+
- 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;
|
|
1367
|
+
- registers it as the agent's signing key, titled `niyam cloud signing`, with the token `machine` stored, and checks GitHub lists it;
|
|
1368
|
+
- puts `NIYAM_SIGNING_KEY=<the private key, base64>` on the clipboard, never on the screen;
|
|
1369
|
+
- deletes the files, at a Ctrl-C too.
|
|
1370
|
+
|
|
1371
|
+
Paste the line into the cloud environment's variables (https://claude.ai/code →
|
|
1372
|
+
the environment's settings). Claude Code has no API for them, so this step stays
|
|
1373
|
+
yours. A key GitHub does not list, or one the clipboard does not take, is deleted
|
|
1374
|
+
from GitHub again, since no one holds it, and so is one a Ctrl-C stops after it
|
|
1375
|
+
was registered.
|
|
1376
|
+
|
|
1377
|
+
`cloud-key` also names the agent's other cloud signing keys, by date and id. Delete
|
|
1378
|
+
one at https://github.com/settings/keys, signed in as the agent, once no environment
|
|
1379
|
+
uses it; `cloud-key` deletes none itself. It refuses in an agent session or a cloud
|
|
1380
|
+
session, and without a working agent token (`niyam machine` first). In a cloud
|
|
1381
|
+
session, `doctor` says whether the session's commits are the agent's, and names
|
|
1382
|
+
`niyam cloud-key` when the environment has no key.
|
|
1383
|
+
|
|
1384
|
+
Anyone who uses the environment can read its variables, and so can any
|
|
1385
|
+
command its sessions run. Claude's settings warn against keeping secrets
|
|
1386
|
+
there. Whoever holds the key can sign commits that GitHub shows as Verified
|
|
1387
|
+
for the agent, though pushing still needs the agent's GitHub connection,
|
|
1388
|
+
which PR identity checks. To revoke the key, delete it from the agent's
|
|
1389
|
+
signing keys. The platform's own git hooks may still add a `Co-authored-by`
|
|
1390
|
+
trailer for Claude.
|
|
1274
1391
|
|
|
1275
1392
|
The proxy refuses GitHub's GraphQL API, so the work rules and `reviews-due`
|
|
1276
1393
|
read only its REST API, here and everywhere else. The one exception is who
|
|
@@ -1455,7 +1572,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
|
|
|
1455
1572
|
once; nothing is built on install:
|
|
1456
1573
|
|
|
1457
1574
|
```bash
|
|
1458
|
-
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.
|
|
1575
|
+
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.24/veda-hq-niyam-0.6.24.tgz
|
|
1459
1576
|
```
|
|
1460
1577
|
|
|
1461
1578
|
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;
|