@veda-hq/niyam 0.6.23 → 0.6.25

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
@@ -180,7 +180,15 @@ any Markdown emphasis, or names an owner login, with or without `@`) must
180
180
  link a published page (`https://claude.ai/artifact/…` or
181
181
  `https://claude.ai/code/artifact/…`) and fit 500 characters; otherwise it is
182
182
  refused, naming the rule and the fix: publish the page, then post the
183
- question, the link and how to answer. A body the guard cannot read in full
183
+ question, the link and how to answer. In auto mode the classifier refuses
184
+ the publish as communication unless the repo's `.claude/settings.json`
185
+ allows it, so `onboard` adds `mcp__claude-artifacts__publish_version`,
186
+ `mcp__claude-artifacts__publish_files` and
187
+ `mcp__claude-artifacts__edit_version` to its `permissions.allow` (none
188
+ where `mcp__claude-artifacts` or `mcp__claude-artifacts__*` allows the whole
189
+ server), and `doctor` warns (`▲`) about each one an onboarded repo's file
190
+ lacks. A new page is private to its owner; a republish to a page already
191
+ shared changes what its readers see, with no prompt. A body the guard cannot read in full
184
192
  (a variable, a command substitution other than `cat`) is judged by what it
185
193
  spells out; where that asks the owner, or the body opens with the unknown
186
194
  part, it is refused with how to write it so the guard can read it; so is a comment with no body in the command, which gh would take from an editor, a prompt or the browser. Commands inside `$(…)`, backquotes and `sh -c` are read too. `propose`
@@ -388,16 +396,27 @@ on any platform without a token store, `niyam env` prints the lock alone.
388
396
  only a sign-in could tell which of the settings' owners runs it, a dry
389
397
  run asks you to name the owner. Without a terminal, `onboard` refuses
390
398
  unless given `--yes` or `--dry-run`. After the yes it shows one line per step, a
391
- spinner while it works, and ends with the pull request and a short "By
392
- hand:" list of what GitHub's and Claude's APIs cannot do. Each line there
393
- is one sentence on standard output saying the whole step: how often (now,
394
- once for the repository, once per claude.ai account), what to do, and its
395
- link. A first onboarding with the review routine ends:
399
+ spinner while it works, then a "By hand" group of what GitHub's and
400
+ Claude's APIs cannot do, and last the pull request. Each step there is
401
+ numbered and wrapped to 80 characters, where a link too long for a line
402
+ takes one of its own and may run past it. Each says the whole step: how
403
+ often (now, once for the repository, once per claude.ai account), what
404
+ to do, and its link where it has one. A first onboarding with the review
405
+ routine ends:
396
406
 
397
407
  ```
398
- By hand:
399
- Once for owner/repo: in Claude Code, run /schedule and create a weekly routine on it, with claude.ai's GitHub connected as AGENT and the prompt below the line in https://github.com/veda-hq/niyam/blob/v0.6.15/routines/review.md.
400
- Once per claude.ai account: sign in at https://claude.ai/code and connect GitHub as AGENT (or change it at https://claude.ai/customize/connectors); skip it if done.
408
+ │
409
+ ◇ By hand
410
+ │ 1. Once for owner/repo: in Claude Code, run /schedule and create a
411
+ │ weekly routine on it, with claude.ai's GitHub connected as AGENT and
412
+ │ the prompt below the line in
413
+ │ https://github.com/veda-hq/niyam/blob/v0.6.15/routines/review.md.
414
+ │
415
+ │ 2. Once per claude.ai account: sign in at https://claude.ai/code and
416
+ │ connect GitHub as AGENT (or change it at
417
+ │ https://claude.ai/customize/connectors); skip it if done.
418
+ │
419
+ └ https://github.com/owner/repo/pull/12 merges itself when checks pass
401
420
  ```
402
421
 
403
422
  It writes `.github/niyam.json`, adds to `.claude/settings.json`
@@ -408,8 +427,11 @@ on any platform without a token store, `niyam env` prints the lock alone.
408
427
  `.claude/sarathi.json`, below), and `permissions.allow` rules
409
428
  for `niyam review-thread` (replacing the rule under the old command) and for
410
429
  the app's `mcp__ccd_pr__bind_pr`, `mcp__ccd_pr__get_status` and
411
- `mcp__ccd_pr__set_monitor`, which turn Auto-fix on (a rerun adds only
412
- the ones missing), and
430
+ `mcp__ccd_pr__set_monitor`, which turn Auto-fix on, and for
431
+ `mcp__claude-artifacts__publish_version`, `publish_files` and
432
+ `edit_version`, which publish the page an ask to the owner links (a
433
+ rerun adds only the ones missing; a file allowing a whole server gets
434
+ none of its rules), and
413
435
  writes `.github/workflows/niyam.yml`, which calls this repository's
414
436
  shared checks (`.github/workflows/checks.yml`) from two jobs: `niyam`
415
437
  on pull requests and pushes, read-only, and `niyam-weekly` on the
@@ -421,7 +443,17 @@ on any platform without a token store, `niyam env` prints the lock alone.
421
443
  every run (see Claude cloud sessions below); a cloud session with no
422
444
  niyam runs it from the SessionStart hook, so there is nothing to paste,
423
445
  and the first time, the plan lists the one connection of claude.ai's
424
- GitHub as the agent, once per claude.ai account. Where the
446
+ GitHub as the agent, once per claude.ai account. When the agent has no
447
+ signing key on GitHub titled `niyam cloud signing`, the plan's Claude
448
+ cloud group also lists one, "signing key for AGENT, on the clipboard":
449
+ as its last step, after the pull request opens, `onboard` makes it as
450
+ `niyam cloud-key` does (below), and "By hand:" starts with the paste
451
+ into each cloud environment's variables. The key is the agent's, not the
452
+ repository's, so onboarding a second repository finds it and says nothing
453
+ about it. A key that fails only warns, leaving the pull request and every
454
+ step before it in place, and "By hand:" names `niyam cloud-key <agent>`
455
+ instead; so does a run where `cloud-key` would refuse, in a Claude Code
456
+ or cloud session. A dry run plans no key. Where the
425
457
  repo still has `.github/process-rules/cloud-setup.sh`, which releases up
426
458
  to 0.6.10 wrote beside it, the pull request deletes it, but only where it
427
459
  leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
@@ -619,9 +651,18 @@ workflow passes it the app's client id and private key as the
619
651
  `NIYAM_BOARD_APP_ID` and `NIYAM_BOARD_APP_KEY` secrets. With `board` on,
620
652
  onboard writes them under the `niyam` job's secrets, the pull request job
621
653
  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 ▲.
654
+ and the owner runs onboard at their own terminal, onboard sets the app up as
655
+ the owner. If the organization has the app's secrets, onboard shares them,
656
+ and the app's installation, with the repository, with no click. If it does
657
+ not, the browser opens on GitHub's new-app page with the app filled in
658
+ (`niyam board <org>`, organization Projects read and write and Issues read,
659
+ no webhook). The owner clicks Create; onboard gets the client id and private
660
+ key back from GitHub on 127.0.0.1 and sets them as organization secrets
661
+ visible to the repository. The browser goes on to the install page, and the
662
+ owner clicks Install. The key is never printed or written to disk. Without a
663
+ terminal, in an agent's or a cloud session, or where GitHub refuses a step,
664
+ the by-hand list and the pull request say what is left. `niyam doctor` marks
665
+ a missing secret ▲.
625
666
  Without them, the job says so in one line and passes, as it does when the
626
667
  board refuses: the board never fails a pull request. When a pull request naming a slice merges into the default branch,
627
668
  the shared workflow comments on the slice, linking the pull request, and
@@ -923,6 +964,21 @@ checked. The settings:
923
964
  `retire`, a command with `{number}` for the merged pull request, is the way out
924
965
  `refuse-retired` names; `footer` ends the placeholder body.
925
966
 
967
+ **On sarathi's Auto-fix list.** Outside a cloud session, `claude-hook` puts
968
+ the open pull request it opened or found on the session's sarathi Auto-fix
969
+ list (sarathi 0.6.15's `autofix-watch.sh`): an `opened` row
970
+ `{ "at", "pr": "owner/repo#N", "url", "event": "opened", "source": "niyam pr-autocreate" }`
971
+ in `<dir>/<session id>.jsonl`, where `<dir>` is `SARATHI_AUTOFIX_DIR`, else
972
+ `$XDG_STATE_HOME/sarathi/autofix`, else `~/.local/state/sarathi/autofix`. A
973
+ pull request the list names already gets no second row. With
974
+ `"autofixList": true`, for a repository whose sessions run that sarathi hook,
975
+ the instruction leaves out its `set_monitor` step, because sarathi's warning
976
+ repeats that call at every `wrap_up` until the app confirms Auto-fix. The
977
+ ToolSearch step, the `<pr-created>` tag and `bind_pr` stay: without them the
978
+ app refuses `set_monitor` for a pull request a hook opened. When the row
979
+ cannot be written, or the session id cannot name a list, the whole
980
+ instruction goes out.
981
+
926
982
  **Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
927
983
  sends a session back while its branch has commits the base lacks and its
928
984
  pull request has not merged at this commit, saying what is left (push, open
@@ -1320,25 +1376,35 @@ Once `session-start` confirms the login as the agent, it does four things:
1320
1376
  - checks that its signature verifies as that key's.
1321
1377
 
1322
1378
  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
1379
+ signing, all together to `CLAUDE_ENV_FILE`. `gpg.ssh.program` goes from the
1380
+ platform's own program to niyam's signer, `niyam ssh-sign`, through a small
1381
+ script next to the session's files. The hosted image has no `ssh-keygen`, so
1382
+ niyam reads the key and makes git's SSH signatures in Node. They are the same
1383
+ signatures `ssh-keygen -Y sign` makes, and it checks the probe's signature in
1384
+ Node too. The key must be an ed25519 key with no passphrase, as `cloud-key`
1385
+ makes. `niyam ssh-sign` only signs, so `git log --show-signature` in the
1386
+ session cannot check signatures; GitHub does. It also unsets the key's
1325
1387
  variable there, so commands do not carry it in their environment.
1326
1388
 
1327
1389
  When any step fails, nothing is set and the commits stay Claude's, which PR
1328
1390
  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;
1391
+ private key or not an ed25519 one with no passphrase, a key GitHub does not
1392
+ list, a lookup the proxy refuses, or a probe that does not verify. The
1393
+ session's line says why and the session works on as the agent. A commit
1394
+ claiming the agent without the agent's signature would fail PR identity, so
1395
+ it is all or nothing. Nothing is installed: signing needs no `ssh-keygen`, no
1396
+ network and no root, so no Setup script line either.
1397
+
1398
+ `niyam onboard` makes the key the first time it runs for an agent that has
1399
+ none (see Adopting above), so all that is left is the paste. To make one
1400
+ yourself, as when the line was lost, run `niyam cloud-key [agent]` in your own
1401
+ terminal on the Mac `niyam machine` set up for the agent (`--yes` skips its
1402
+ one question). One line serves every cloud environment the agent works in.
1403
+ `onboard` and `cloud-key` make the key alike, in three steps:
1404
+
1405
+ - makes a new ed25519 key in memory, with niyam's own code rather than `ssh-keygen`, never writing it to disk; it is for the agent's cloud sessions alone, apart from the Mac's signing key, so it can be revoked on its own;
1339
1406
  - 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.
1407
+ - puts `NIYAM_SIGNING_KEY=<the private key, base64>` on the clipboard, never on the screen.
1342
1408
 
1343
1409
  Paste the line into the cloud environment's variables (https://claude.ai/code →
1344
1410
  the environment's settings). Claude Code has no API for them, so this step stays
@@ -1358,8 +1424,18 @@ command its sessions run. Claude's settings warn against keeping secrets
1358
1424
  there. Whoever holds the key can sign commits that GitHub shows as Verified
1359
1425
  for the agent, though pushing still needs the agent's GitHub connection,
1360
1426
  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.
1427
+ signing keys.
1428
+
1429
+ **Trailers and hooks.** The cloud image's git config sets Claude's identity
1430
+ and signing and nothing else: no `core.hooksPath`, no hooks, no trailers.
1431
+ So the clone's own hooks run there as on a Mac, niyam's pre-push hook
1432
+ included, and git stores a commit message as it was written. The trailers
1433
+ a cloud session's commits carry come from Claude Code, which writes them
1434
+ into the message itself. The `Co-Authored-By: Claude …` line appears once,
1435
+ as on every machine. A cloud session's commits also carry a
1436
+ `Claude-Session: https://claude.ai/code/session_…` line, which links the
1437
+ commit to the session that made it. It names no co-author, and niyam leaves
1438
+ it alone (veda-hq/niyam#416).
1363
1439
 
1364
1440
  The proxy refuses GitHub's GraphQL API, so the work rules and `reviews-due`
1365
1441
  read only its REST API, here and everywhere else. The one exception is who
@@ -1448,7 +1524,7 @@ installs it, since the Setup script does not: both are `✓`. GitHub
1448
1524
  checks that the account the proxy acts as is one of the settings' agents,
1449
1525
  and that `session-start` gave the session that identity (`✗` otherwise:
1450
1526
  `gh` and git stay locked out). This repo lists hooks that reach GitHub
1451
- outside `as-agent` and the Auto-fix rules missing, as on a Mac. It installs nothing; on Linux outside a
1527
+ outside `as-agent` and the Auto-fix and artifact rules missing, as on a Mac. It installs nothing; on Linux outside a
1452
1528
  cloud session, `doctor` still refuses.
1453
1529
 
1454
1530
  ### Owner steps
@@ -1544,7 +1620,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
1544
1620
  once; nothing is built on install:
1545
1621
 
1546
1622
  ```bash
1547
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.23/veda-hq-niyam-0.6.23.tgz
1623
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.25/veda-hq-niyam-0.6.25.tgz
1548
1624
  ```
1549
1625
 
1550
1626
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
package/dist/agent.js CHANGED
@@ -367,7 +367,8 @@ export function sessionNames(script) {
367
367
  const id = /^export GIT_AUTHOR_EMAIL='(\d+)\+/m.exec(script)?.[1];
368
368
  return agent && id ? { agent, id: Number(id) } : undefined;
369
369
  }
370
- function quote(value) {
370
+ /** `value` as one shell word, in single quotes. */
371
+ export function quote(value) {
371
372
  return `'${value.replaceAll(`'`, `'\\''`)}'`;
372
373
  }
373
374
  /** The agent's token from this machine's token store, or undefined, as on a platform with none. */
@@ -0,0 +1,254 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ import { API } from './agent.js';
3
+ import { detail } from './doc-numbers.js';
4
+ import { GITHUB_WEB } from './host.js';
5
+ import { PRODUCT } from './names.js';
6
+ import { orgSecretNames, repoSecretNames, setOrgSecret, shareOrgSecret } from './secrets.js';
7
+ /**
8
+ * The board GitHub App (P-70, P-72): the Slice started job makes its board
9
+ * token from these two Actions secrets, the app's client id and its private
10
+ * key. onboard makes the app from a manifest, so the owner clicks Create and
11
+ * Install and copies nothing.
12
+ */
13
+ export const BOARD_SECRETS = ['NIYAM_BOARD_APP_ID', 'NIYAM_BOARD_APP_KEY'];
14
+ /** What each board app secret holds. */
15
+ const HOLDS = { NIYAM_BOARD_APP_ID: 'client id', NIYAM_BOARD_APP_KEY: 'private key' };
16
+ /** The permissions the app asks for, and no more: the Slice started job's token asks for the same. */
17
+ export const BOARD_APP_PERMISSIONS = { organization_projects: 'write', issues: 'read' };
18
+ /** The start of every board app's slug onboard makes: `niyam board <org>`, as GitHub makes a slug of it. */
19
+ const SLUG_START = 'niyam-board';
20
+ /** How long onboard waits for the owner to click Create, then Install, in the browser, each. */
21
+ export const BOARD_APP_WAIT_MS = 10 * 60_000;
22
+ /** How often onboard looks for the owner's click: the redirect back as it waits for Create, GitHub's installations as it waits for Install. */
23
+ const CREATE_TICK_MS = 500;
24
+ const INSTALL_TICK_MS = 3000;
25
+ /**
26
+ * The owner's steps, once per organization, to give `slug`'s Slice started
27
+ * job the board app's token by hand: make the app, install it, and set the
28
+ * secrets `missing`. `unknown` when GitHub would not list the secrets, so
29
+ * they may be set already.
30
+ */
31
+ export function boardAppSteps(slug, missing, unknown = false) {
32
+ const org = slug.split('/')[0];
33
+ const set = missing.map((name) => `its ${HOLDS[name]} as ${name}`).join(' and ');
34
+ return (`${unknown ? `Unless ${slug} has the Actions secrets ${BOARD_SECRETS.join(' and ')} already, once` : 'Once'} for ${org}: ` +
35
+ `make a GitHub App with organization Projects read and write and repository Issues read at ${GITHUB_WEB}/organizations/${org}/settings/apps/new, ` +
36
+ `install it on ${slug}, and set ${set}, Actions secrets of the organization or of ${GITHUB_WEB}/${slug}/settings/secrets/actions. ` +
37
+ 'Until then a slice moves to In Progress on the board only from a desktop push.');
38
+ }
39
+ /** The board app's name for `org`: GitHub takes at most 34 characters. */
40
+ export function boardAppName(org) {
41
+ return `niyam board ${org}`.slice(0, 34).trimEnd();
42
+ }
43
+ /** The manifest GitHub makes the board app from, sending the owner back to `redirect`. It has no webhook. */
44
+ export function boardAppManifest(org, redirect) {
45
+ return {
46
+ name: boardAppName(org),
47
+ url: `${GITHUB_WEB}/${PRODUCT}`,
48
+ description: 'Moves a slice to In Progress on the board when its pull request opens. Made by niyam onboard.',
49
+ hook_attributes: { url: `${GITHUB_WEB}/${PRODUCT}`, active: false },
50
+ redirect_url: redirect,
51
+ public: false,
52
+ default_permissions: BOARD_APP_PERMISSIONS,
53
+ default_events: [],
54
+ };
55
+ }
56
+ /** `text` safe inside an HTML attribute in double quotes. */
57
+ function attribute(text) {
58
+ return text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
59
+ }
60
+ /** The page that posts the manifest to GitHub's new-app page for `org` as it loads, carrying the run's `state`. */
61
+ export function startPage(org, manifest, state) {
62
+ const action = `${GITHUB_WEB}/organizations/${encodeURIComponent(org)}/settings/apps/new?state=${encodeURIComponent(state)}`;
63
+ return [
64
+ '<!doctype html><meta charset="utf-8"><title>niyam: the board app</title>',
65
+ `<form id="make" method="post" action="${attribute(action)}">`,
66
+ `<input type="hidden" name="manifest" value="${attribute(JSON.stringify(manifest))}">`,
67
+ '<p>Taking you to GitHub to make the board app. <button>Go on</button></p>',
68
+ '</form>',
69
+ '<script>document.getElementById("make").submit()</script>',
70
+ ].join('\n');
71
+ }
72
+ /** A plain page for the browser, saying `text`. */
73
+ function page(status, text) {
74
+ return { status, headers: { 'content-type': 'text/plain; charset=utf-8' }, body: `${text}\n` };
75
+ }
76
+ /** The app GitHub made, from the code its redirect carried; or why not. */
77
+ async function convert(sys, code) {
78
+ const made = await sys.http(`${API}/app-manifests/${encodeURIComponent(code)}/conversions`, { method: 'POST' });
79
+ const { slug, client_id: clientId, pem } = (made.json ?? {});
80
+ if (made.status !== 201 || typeof slug !== 'string' || typeof clientId !== 'string' || typeof pem !== 'string') {
81
+ return { problem: `GitHub did not give the app it made (HTTP ${made.status})` };
82
+ }
83
+ return { slug, clientId, pem };
84
+ }
85
+ /** The organization's installation of an app whose slug `is`; undefined while there is none. */
86
+ async function installationOf(sys, org, token, is) {
87
+ for (let page = 1;; page++) {
88
+ const listed = await sys.http(`${API}/orgs/${org}/installations?per_page=100&page=${page}`, { token });
89
+ const all = listed.json?.installations;
90
+ if (listed.status !== 200 || !Array.isArray(all))
91
+ return undefined;
92
+ const found = all.find((one) => typeof one?.app_slug === 'string' && is(one.app_slug));
93
+ if (found || all.length < 100)
94
+ return found;
95
+ }
96
+ }
97
+ /** Puts repository `repositoryId` on `installation` when it holds selected repositories alone; why not, as a step left by hand. */
98
+ async function includeRepository(sys, org, slug, token, installation, repositoryId) {
99
+ if (installation.repository_selection === 'all')
100
+ return undefined;
101
+ const put = await sys.http(`${API}/user/installations/${installation.id}/repositories/${repositoryId}`, { method: 'PUT', token });
102
+ if (put.status === 204)
103
+ return undefined;
104
+ return `Once for ${slug}: add it to the board app's installation at ${GITHUB_WEB}/organizations/${org}/settings/installations/${installation.id}, since GitHub would not (HTTP ${put.status}).`;
105
+ }
106
+ /**
107
+ * Sets up the board app for `slug`, as the owner `token` is, and returns
108
+ * what is left by hand, if anything. Where the organization has the app's
109
+ * secrets already, they and the app's installation are shared with the
110
+ * repository too. Otherwise the browser opens on GitHub's new-app page with
111
+ * the manifest filled in; the owner clicks Create, onboard sets the
112
+ * secrets, and the browser goes on to the install page, where the owner
113
+ * clicks Install. Never throws: a step GitHub refuses, or a click that does
114
+ * not come, is a step left by hand.
115
+ */
116
+ export async function setUpBoardApp(sys, out, slug, token) {
117
+ const org = slug.split('/')[0];
118
+ const byHand = (why) => [`${boardAppSteps(slug, BOARD_SECRETS)} onboard did not: ${why}.`];
119
+ try {
120
+ const repo = await sys.http(`${API}/repos/${slug}`, { token });
121
+ const repositoryId = repo.json?.id;
122
+ if (repo.status !== 200 || typeof repositoryId !== 'number')
123
+ return byHand(`GitHub did not give ${slug}'s id (HTTP ${repo.status})`);
124
+ // A repository's own secret hides the organization's of the same name, so one of its own is the owner's to remove.
125
+ const own = await repoSecretNames(sys, slug, token);
126
+ if (own === undefined)
127
+ return byHand(`GitHub would not list ${slug}'s own Actions secrets`);
128
+ const shadowing = BOARD_SECRETS.filter((name) => own.includes(name));
129
+ if (shadowing.length > 0) {
130
+ return [
131
+ `Once for ${slug}: delete its own ${shadowing.join(' and ')} at ${GITHUB_WEB}/${slug}/settings/secrets/actions, which would hide the organization's board app secrets, then run niyam onboard again at your own terminal.`,
132
+ ];
133
+ }
134
+ const names = await orgSecretNames(sys, org, token);
135
+ if (names === undefined)
136
+ return byHand(`GitHub would not list ${org}'s Actions secrets`);
137
+ const has = BOARD_SECRETS.filter((name) => names.includes(name));
138
+ if (has.length === BOARD_SECRETS.length)
139
+ return await share(sys, out, { org, slug, token, repositoryId });
140
+ // One of the two belongs to an app made before: a new app would overwrite it and leave that one installed.
141
+ if (has.length > 0) {
142
+ const settings = `${GITHUB_WEB}/organizations/${org}/settings/secrets/actions`;
143
+ return [
144
+ `Once for ${org}: it has the secret ${has.join(', ')} but not ${BOARD_SECRETS.filter((name) => !has.includes(name)).join(', ')}. Set the board app's other one at ${settings}, or delete it and its app, then run niyam onboard again at your own terminal.`,
145
+ ];
146
+ }
147
+ return await make(sys, out, { org, slug, token, repositoryId });
148
+ }
149
+ catch (error) {
150
+ // fail-open: the board app is the owner's to finish; nothing else in the run waits on it.
151
+ return byHand(detail(error));
152
+ }
153
+ }
154
+ /** The organization has the app already: share its secrets and its installation with the repository. */
155
+ async function share(sys, out, { org, slug, token, repositoryId }) {
156
+ const left = [];
157
+ for (const name of BOARD_SECRETS) {
158
+ const problem = await shareOrgSecret(sys, org, token, name, repositoryId);
159
+ if (problem)
160
+ left.push(`Once for ${slug}: share ${org}'s ${name} secret with it at ${GITHUB_WEB}/organizations/${org}/settings/secrets/actions/${name}, since ${problem}.`);
161
+ }
162
+ if (left.length === 0)
163
+ out.out(`✓ ${org}'s board app secrets shared with ${slug}`);
164
+ const installation = await installationOf(sys, org, token, (one) => one.startsWith(SLUG_START));
165
+ if (!installation)
166
+ left.push(`Once for ${slug}: install ${org}'s board app on it at ${GITHUB_WEB}/organizations/${org}/settings/installations.`);
167
+ else {
168
+ const problem = await includeRepository(sys, org, slug, token, installation, repositoryId);
169
+ if (problem)
170
+ left.push(problem);
171
+ else
172
+ out.out(`✓ ${org}'s board app installed on ${slug}`);
173
+ }
174
+ return left;
175
+ }
176
+ /** The organization has no board app: make one from the manifest, set its secrets, and install it. */
177
+ async function make(sys, out, { org, slug, token, repositoryId }) {
178
+ const state = randomBytes(16).toString('hex');
179
+ let made;
180
+ let asked = false;
181
+ const served = await sys.serve(async ({ path, query }) => {
182
+ if (path === '/start')
183
+ return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: startPage(org, boardAppManifest(org, redirect), state) };
184
+ if (path !== '/made')
185
+ return page(404, 'Not found.');
186
+ // Only GitHub's redirect for this run's manifest carries its state.
187
+ if (query.state !== state || !query.code)
188
+ return page(400, "This is not GitHub's answer to this run of niyam onboard.");
189
+ if (asked)
190
+ return page(409, 'niyam onboard has this answer already; go back to the terminal.');
191
+ asked = true;
192
+ try {
193
+ const app = await convert(sys, query.code);
194
+ if ('problem' in app) {
195
+ made = app;
196
+ return page(502, `niyam onboard could not get the app: ${app.problem}. The terminal says what is left.`);
197
+ }
198
+ // The key is set before anything else, as GitHub gives it once.
199
+ for (const [name, value] of [['NIYAM_BOARD_APP_ID', app.clientId], ['NIYAM_BOARD_APP_KEY', app.pem]]) {
200
+ const problem = await setOrgSecret(sys, org, token, name, value, [repositoryId]);
201
+ if (problem) {
202
+ made = { problem: `GitHub made the app ${app.slug} but ${problem}` };
203
+ return page(502, `The app is made, but niyam onboard could not set its secrets: ${problem}. The terminal says what is left.`);
204
+ }
205
+ }
206
+ made = app;
207
+ return { status: 302, headers: { location: `${GITHUB_WEB}/apps/${app.slug}/installations/new` } };
208
+ }
209
+ catch (error) {
210
+ // fail-open: GitHub may have made the app before the request failed, so the owner is told to look, not to make another.
211
+ made = { problem: `a request to GitHub failed once it had the code (${detail(error)})` };
212
+ return page(502, `niyam onboard could not finish: ${made.problem}. The terminal says what is left.`);
213
+ }
214
+ });
215
+ const redirect = `http://127.0.0.1:${served.port}/made`;
216
+ try {
217
+ sys.open(`http://127.0.0.1:${served.port}/start`);
218
+ for (let waited = 0; made === undefined && waited < BOARD_APP_WAIT_MS; waited += CREATE_TICK_MS)
219
+ await sys.sleep(CREATE_TICK_MS);
220
+ }
221
+ finally {
222
+ // The browser has its redirect by the time `made` is set; nothing else is served.
223
+ served.close();
224
+ }
225
+ if (made === undefined)
226
+ return [`${boardAppSteps(slug, BOARD_SECRETS)} onboard opened GitHub's page for it, but no app was made within ${BOARD_APP_WAIT_MS / 60_000} minutes.`];
227
+ if ('problem' in made) {
228
+ const settings = `${GITHUB_WEB}/organizations/${org}/settings/apps`;
229
+ return [`Once for ${org}: ${made.problem}. At ${settings}, delete the board app if it was made, then run niyam onboard again.`];
230
+ }
231
+ const app = made;
232
+ out.out(`✓ made the board app ${app.slug} and set ${BOARD_SECRETS.join(' and ')}, shared with ${slug}`);
233
+ // The browser is on the install page now; the owner clicks Install.
234
+ const install = `Once for ${org}: install the board app on ${slug} at ${GITHUB_WEB}/apps/${app.slug}/installations/new`;
235
+ try {
236
+ let installation;
237
+ for (let waited = 0; !installation && waited < BOARD_APP_WAIT_MS; waited += INSTALL_TICK_MS) {
238
+ installation = await installationOf(sys, org, token, (one) => one === app.slug);
239
+ if (!installation)
240
+ await sys.sleep(INSTALL_TICK_MS);
241
+ }
242
+ if (!installation)
243
+ return [`${install}.`];
244
+ const problem = await includeRepository(sys, org, slug, token, installation, repositoryId);
245
+ if (problem)
246
+ return [problem];
247
+ }
248
+ catch (error) {
249
+ // fail-open: the app and its secrets stand; only the install is left.
250
+ return [`${install}, if it is not there yet: onboard could not tell (${detail(error)}).`];
251
+ }
252
+ out.out(`✓ installed the board app on ${slug}`);
253
+ return [];
254
+ }