@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 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; so the board needs nothing done by
448
- hand. What the board lacks is known only once you have signed in, so the
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. A
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. It uses GitHub's REST API for Projects alone, so it works through a
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. When a pull request naming a slice merges into the default branch,
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
- A cloud session's git commits are authored and committed as Claude's own
1235
- account, `Claude <noreply@anthropic.com>`, and signed by it (Verified),
1236
- while the push is the agent's. PR identity checks only commits that claim
1237
- an agent, so these pass, and GitHub records the agent as having pushed
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.21/veda-hq-niyam-0.6.21.tgz
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
- function configVars(config) {
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
- ['GIT_AUTHOR_NAME', agent],
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
- ['gpg.format', 'ssh'],
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).map(([name, value]) => `export ${name}=${quote(value)}`),
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.map(([name, value]) => `export ${name}=${quote(value)}`),
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, and the names of its workflows that are off.
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 push does this, through GitHub's REST API alone,
592
- * as a cloud session's proxy refuses GraphQL. Returns what moved, as lines.
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;