@veda-hq/niyam 0.7.14 → 0.7.15

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
@@ -1749,13 +1749,13 @@ the app's client id and private key are the `npm` environment's
1749
1749
  package is on npm as `@veda-hq/niyam`, with provenance, for a repository that
1750
1750
  pins it as an exact version; it publishes from the `npm` environment, which
1751
1751
  only `main` may deploy to. A tag on any other commit is not a release:
1752
- `niyam upgrade` and `niyam onboard` ask GitHub's compare API, with no token,
1753
- whether the tag's commit is on `main`, and refuse one that is not, naming the
1754
- tag and the commit. Install the attached package on each machine with pnpm,
1752
+ `niyam upgrade` and `niyam onboard` ask GitHub's compare API whether the
1753
+ tag's commit is on `main`, and refuse one that is not, naming the tag and the
1754
+ commit. `upgrade` asks with no token; `onboard` asks with the agent's. Install the attached package on each machine with pnpm,
1755
1755
  once; nothing is built on install:
1756
1756
 
1757
1757
  ```bash
1758
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.7.14/veda-hq-niyam-0.7.14.tgz
1758
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.7.15/veda-hq-niyam-0.7.15.tgz
1759
1759
  ```
1760
1760
 
1761
1761
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
@@ -1791,8 +1791,20 @@ CLI running, refuses and says to run `niyam upgrade` first.
1791
1791
 
1792
1792
  `onboard` pins the client's workflow to one version, the release of the CLI
1793
1793
  that ran it, and writes `.github/niyam/cloud-setup.sh` at the same one. First
1794
- it asks GitHub's compare API, with no token, whether that release's tag is on
1795
- `main`; when it is not, or GitHub cannot say, it refuses and changes nothing.
1794
+ it asks GitHub's compare API whether that release's tag is on `main`; when it
1795
+ is not, or GitHub cannot say, it refuses and changes nothing.
1796
+
1797
+ onboard reads GitHub's public API (the release tag, who the owner and the
1798
+ agent are, whether an organisation owns the repository) with the agent's
1799
+ stored token (#546). Those reads then count against the token's 5,000 an hour.
1800
+ With no token they would share the 60 an hour every request from the Mac's
1801
+ address gets. Until the run knows its agent, it uses the agent named on the
1802
+ command line, else the agent the settings name, else any agent `machine` set
1803
+ up on the Mac. It never uses the owner's sign-in for these reads. When GitHub
1804
+ refuses the token (HTTP 401, and only then), the read is asked again with
1805
+ none, within the time the first ask had. When GitHub refuses a read for its
1806
+ rate limit (403 or 429 with `x-ratelimit-remaining: 0`), onboard names the
1807
+ limit, and when it resets if GitHub sends a valid `x-ratelimit-reset`.
1796
1808
  Each job writes the pin twice, `checks.yml@vX.Y.Z` and, two lines
1797
1809
  below it under `with:`, `niyam-ref: vX.Y.Z`, the one input `checks.yml`
1798
1810
  declares; GitHub refuses a caller that passes an input the called workflow
package/dist/agent.js CHANGED
@@ -407,18 +407,60 @@ export function quote(value) {
407
407
  export function readToken(sys, agent) {
408
408
  return tokenStore(sys)?.read(sys, agent);
409
409
  }
410
+ /**
411
+ * What GitHub's refusal says when it is its rate limit, a 403 or 429 with
412
+ * `x-ratelimit-remaining: 0`, whose limit ran out, with no token the 60 an
413
+ * hour every request from this address shares (#546), and when it resets,
414
+ * from `x-ratelimit-reset` in UTC epoch seconds. Undefined for any other
415
+ * answer. GitHub's REST docs, "Rate limits for the REST API", section
416
+ * "Exceeding the rate limit" (read 2026-11-22; the link is on #546's PR).
417
+ */
418
+ export function rateLimited(answer, token) {
419
+ const headers = answer.headers ?? {};
420
+ if ((answer.status !== 403 && answer.status !== 429) || headers['x-ratelimit-remaining'] !== '0')
421
+ return undefined;
422
+ const reset = Number(headers['x-ratelimit-reset']);
423
+ const until = Number.isInteger(reset) && reset > 0 ? ` until ${new Date(reset * 1000).toISOString().slice(11, 16)} UTC` : '';
424
+ const whose = token ? "GitHub's rate limit for the token" : "GitHub's limit for requests with no token, 60 an hour from this address,";
425
+ return `${whose} has run out${until} (HTTP ${answer.status})`;
426
+ }
427
+ /**
428
+ * A read of GitHub's public API asked with `token`, so it counts against the
429
+ * token's limit rather than the one this address shares with no token (#546),
430
+ * and asked again with none only when GitHub refuses the token (401): a
431
+ * public read is answered without one. A `timeoutMs` bounds both asks
432
+ * together, the second getting what the first left, and none left gives the
433
+ * 401. Gives the token the answer came with.
434
+ */
435
+ export async function publicRead(sys, url, token, options = {}) {
436
+ if (!token)
437
+ return { answer: await sys.http(url, options), token: undefined };
438
+ const started = sys.now().getTime();
439
+ const answer = await sys.http(url, { ...options, token });
440
+ if (answer.status !== 401)
441
+ return { answer, token };
442
+ if (options.timeoutMs === undefined)
443
+ return { answer: await sys.http(url, options), token: undefined };
444
+ const left = options.timeoutMs - (sys.now().getTime() - started);
445
+ return left > 0 ? { answer: await sys.http(url, { ...options, timeoutMs: left }), token: undefined } : { answer, token };
446
+ }
410
447
  /**
411
448
  * An account's numeric id and its login as GitHub spells it, from the public
412
449
  * API. Logins are case-insensitive; the stored token's item, the session file and
413
450
  * commits all use GitHub's spelling, whatever case the login was typed in.
414
451
  * A refusal or a passing failure (403, 429, 5xx) is asked again after each of
415
- * ACCOUNT_WAITS_MS; only a 404 says the account does not exist.
452
+ * ACCOUNT_WAITS_MS; only a 404 says the account does not exist, and a rate
453
+ * limit run out, which no wait of seconds fixes, is said at once.
416
454
  */
417
455
  export async function account(sys, login, token) {
418
456
  for (let tries = 0;; tries++) {
419
- const { status, json } = await sys.http(`${API}/users/${login}`, token ? { token } : {});
457
+ const { answer, token: used } = await publicRead(sys, `${API}/users/${login}`, token);
458
+ const { status, json } = answer;
420
459
  if (status === 404)
421
460
  throw new Error(`GitHub has no account "${login}" (HTTP 404)`);
461
+ const limited = rateLimited(answer, used);
462
+ if (limited)
463
+ throw new Error(`GitHub did not answer who account "${login}" is: ${limited}`);
422
464
  const wait = ACCOUNT_WAITS_MS[tries];
423
465
  if ((status === 403 || status === 429 || status >= 500) && wait !== undefined) {
424
466
  await sys.sleep(wait);
package/dist/doctor.js CHANGED
@@ -170,7 +170,7 @@ async function typesFindings(sys, token) {
170
170
  const approvals = typeof named === 'number' ? named : undefined;
171
171
  const org = slug.split('/')[0];
172
172
  try {
173
- return (await isOrganisation(sys, org)) ? [await typesDrift(sys, token, org, slug, approvals)] : [];
173
+ return (await isOrganisation(sys, org, token)) ? [await typesDrift(sys, token, org, slug, approvals)] : [];
174
174
  }
175
175
  catch (error) {
176
176
  return [{ mark: '✗', text: `issue types: cannot ask GitHub (${message(error)})`, fix: 'niyam doctor again' }];
@@ -189,7 +189,7 @@ async function boardAppFindings(sys, token) {
189
189
  return [];
190
190
  const { slug } = here;
191
191
  try {
192
- if (!(await isOrganisation(sys, slug.split('/')[0])))
192
+ if (!(await isOrganisation(sys, slug.split('/')[0], token)))
193
193
  return [];
194
194
  const names = await secretNames(sys, slug, token);
195
195
  if (names === undefined)
@@ -503,7 +503,7 @@ export async function issueType(sys, io) {
503
503
  const event = JSON.parse(sys.read(eventPath));
504
504
  const { approvals } = loadSettings(sys, sys.cwd);
505
505
  if (name === 'schedule' && event.schedule === HOURLY) {
506
- if (!(await isOrganisation(sys, slug.split('/')[0]))) {
506
+ if (!(await isOrganisation(sys, slug.split('/')[0], token))) {
507
507
  io.out('issue-type: GitHub has issue types for organisations only; nothing to do');
508
508
  return 0;
509
509
  }
package/dist/onboard.js CHANGED
@@ -1166,6 +1166,27 @@ export function claudeSettings(before, sarathiBefore) {
1166
1166
  }
1167
1167
  return { text, changes, labels, ...said };
1168
1168
  }
1169
+ /** The agents the checkout's settings name; none when it has none, or settings onboard refuses later with the reason. */
1170
+ function settingsAgents(sys, root) {
1171
+ if (!sys.exists(`${root}/${SETTINGS_PATH}`))
1172
+ return [];
1173
+ try {
1174
+ return loadSettings(sys, root).agents;
1175
+ }
1176
+ catch {
1177
+ // fail-open: the settings branch reads them again and refuses them with the reason; here they only suggest a token.
1178
+ return [];
1179
+ }
1180
+ }
1181
+ /** The token this Mac stores for the first of `agents` it has one for, or undefined. */
1182
+ function storedToken(sys, agents) {
1183
+ for (const agent of agents) {
1184
+ const token = readToken(sys, agent);
1185
+ if (token)
1186
+ return token;
1187
+ }
1188
+ return undefined;
1189
+ }
1169
1190
  /** Who the run's sign-in is, the owner's likely login; undefined when it failed. */
1170
1191
  async function signedInLogin(signIn) {
1171
1192
  const signed = await signIn().catch(() => undefined);
@@ -1300,9 +1321,18 @@ export async function onboard(sys, io, args = []) {
1300
1321
  const bar = paint.dim('│');
1301
1322
  const say = (line) => io.out(`${bar} ${line}`);
1302
1323
  const version = packageVersion();
1324
+ // The token onboard's public reads ask GitHub with, so they count against its limit and not the 60 an hour this
1325
+ // Mac's address shares with no token (#546), until the run knows its agent: the agent named, else the settings',
1326
+ // and only with neither any agent machine set up here. Never the owner's sign-in, whose scopes depend on whether an
1327
+ // organisation owns the repository.
1328
+ // The token's item is under the login as the session file spells it, whatever case it was typed or written in.
1329
+ const setUp = agentsSetUp(sys);
1330
+ const known = named[1] ? [named[1]] : settingsAgents(sys, root);
1331
+ const spelled = known.flatMap((login) => [login, ...setUp.filter((one) => one !== login && sameLogin(one, login))]);
1332
+ let readAs = storedToken(sys, known.length > 0 ? spelled : setUp);
1303
1333
  // Whether an organisation owns the repository, asked of GitHub once in this run.
1304
1334
  let organisation;
1305
- const byOrganisation = () => (organisation ??= isOrganisation(sys, slug.split('/')[0]));
1335
+ const byOrganisation = () => (organisation ??= isOrganisation(sys, slug.split('/')[0], readAs));
1306
1336
  const personal = `${slug} is owned by a personal account, and GitHub has issue types for organisations only`;
1307
1337
  // The repository's files are changed only through the agent's pull request at the end: until then each
1308
1338
  // change is held here, and read back from here, so the owner's checkout is never modified.
@@ -1339,7 +1369,7 @@ export async function onboard(sys, io, args = []) {
1339
1369
  if (aheadHere !== undefined)
1340
1370
  return refuseOlder(io, slug, aheadHere, version);
1341
1371
  // The workflow and cloud-setup.sh pin this release: a tag off main is not one (P-61).
1342
- const onMain = await tagOnMain(sys, version);
1372
+ const onMain = await tagOnMain(sys, version, readAs);
1343
1373
  if ('problem' in onMain) {
1344
1374
  io.err(`onboard: ${onMain.problem}; nothing changed`);
1345
1375
  return 1;
@@ -1421,8 +1451,9 @@ export async function onboard(sys, io, args = []) {
1421
1451
  notes.push(`- onboard signed in before showing its plan: ${SETTINGS_PATH} names several owners, and only the sign-in tells which one ran it.`);
1422
1452
  }
1423
1453
  // GitHub's spelling, which the keychain, the session file and commits use.
1424
- owner = (await account(sys, chosenOwner)).login;
1425
- agent = (await account(sys, here.agent)).login;
1454
+ owner = (await account(sys, chosenOwner, readAs)).login;
1455
+ agent = (await account(sys, here.agent, readAs)).login;
1456
+ readAs = readToken(sys, agent) ?? readAs;
1426
1457
  // Before any change, so a refused --add leaves the settings as they were.
1427
1458
  if (add && !features.includes(add) && NEEDS_ISSUE_TYPES.includes(add) && !(await byOrganisation())) {
1428
1459
  io.err(`onboard: ${personal}, so ${add} cannot run here`);
@@ -1499,8 +1530,9 @@ export async function onboard(sys, io, args = []) {
1499
1530
  if (!isLogin(login))
1500
1531
  throw new Error(`"${login}" is not a GitHub login`);
1501
1532
  }
1502
- owner = (await account(sys, namedOwner)).login;
1503
- agent = (await account(sys, namedAgent)).login;
1533
+ owner = (await account(sys, namedOwner, readAs)).login;
1534
+ agent = (await account(sys, namedAgent, readAs)).login;
1535
+ readAs = readToken(sys, agent) ?? readAs;
1504
1536
  if (sameLogin(owner, agent)) {
1505
1537
  io.err('onboard: the owner and the agent must be different accounts');
1506
1538
  return 1;
@@ -1552,7 +1584,7 @@ export async function onboard(sys, io, args = []) {
1552
1584
  io.err(`onboard: this Mac is not set up for ${agent} (${why}); run niyam machine ${agent}, then onboard again`);
1553
1585
  return 1;
1554
1586
  }
1555
- const { id } = await account(sys, agent);
1587
+ const { id } = await account(sys, agent, token);
1556
1588
  let reach = await access(sys, slug, token);
1557
1589
  if (reach.kind === 'refused') {
1558
1590
  io.err(`onboard: ${reach.reason}`);
@@ -1,4 +1,4 @@
1
- import { API, sameLogin } from './agent.js';
1
+ import { API, publicRead, rateLimited, sameLogin } from './agent.js';
2
2
  import { GITHUB_HOST } from './host.js';
3
3
  /**
4
4
  * The scopes beyond gh's own (repo, read:org, gist) that a run turning
@@ -10,13 +10,19 @@ export function ownerScopes(features, organisation) {
10
10
  return [];
11
11
  return organisation ? ['project', 'admin:org'] : ['project'];
12
12
  }
13
- /** Whether GitHub names the account an organisation; throws when GitHub will not say. */
14
- export async function isOrganisation(sys, login) {
15
- const { status, json } = await sys.http(`${API}/users/${login}`);
16
- const type = json?.type;
17
- if (status !== 200 || typeof type !== 'string')
18
- throw new Error(`cannot tell whether ${login} is an organisation (HTTP ${status})`);
19
- return type === 'Organization';
13
+ /**
14
+ * Whether GitHub names the account an organisation; throws when GitHub will
15
+ * not say, naming its rate limit when that is why. Asked with `token`, which
16
+ * every caller passes or says it has none of: with none, the read shares the
17
+ * 60 an hour every request from this address has (#546).
18
+ */
19
+ export async function isOrganisation(sys, login, token) {
20
+ const { answer, token: used } = await publicRead(sys, `${API}/users/${login}`, token);
21
+ const type = answer.json?.type;
22
+ if (answer.status === 200 && typeof type === 'string')
23
+ return type === 'Organization';
24
+ const limited = rateLimited(answer, used);
25
+ throw new Error(`cannot tell whether ${login} is an organisation${limited ? `: ${limited}` : ` (HTTP ${answer.status})`}`);
20
26
  }
21
27
  /** gh's lines from a sign-in that tell the owner nothing they need: its sign-in tips and the setup it did in the temporary folder. */
22
28
  const GH_CHATTER = [/Authentication complete/i, /git_protocol/, /Configured git protocol/i, /plain text/i, /Logged in as/i, /^Did you know/i, /^Tip\b/i];
@@ -1,4 +1,4 @@
1
- import { API } from './agent.js';
1
+ import { API, publicRead, rateLimited } from './agent.js';
2
2
  import { PRODUCT } from './names.js';
3
3
  /** How long GitHub gets to compare a release tag with main. */
4
4
  const COMPARE_MS = 15_000;
@@ -15,19 +15,25 @@ export const RELEASE_BRANCH = 'main';
15
15
  * is on main. Both refs are written in full, so a branch named like the
16
16
  * tag, or a tag named main, is never the one compared. Anything else is a
17
17
  * refusal: a tag off main, no such tag, or no answer, each with its own
18
- * words, so nothing is installed for want of one.
18
+ * words, so nothing is installed for want of one. `onboard` asks with the
19
+ * agent's token, so the compare does not share the 60 an hour this address
20
+ * has with no token (#546); a rate limit run out is named as one.
19
21
  */
20
- export async function tagOnMain(sys, version) {
22
+ export async function tagOnMain(sys, version, token) {
21
23
  const tag = `v${version}`;
22
- let answer;
24
+ let read;
23
25
  try {
24
- answer = await sys.http(`${API}/repos/${PRODUCT}/compare/refs/tags/${tag}...refs/heads/${RELEASE_BRANCH}?per_page=1`, { timeoutMs: COMPARE_MS });
26
+ read = await publicRead(sys, `${API}/repos/${PRODUCT}/compare/refs/tags/${tag}...refs/heads/${RELEASE_BRANCH}?per_page=1`, token, { timeoutMs: COMPARE_MS });
25
27
  }
26
28
  catch (error) {
27
29
  return { problem: `GitHub could not be asked whether the ${tag} tag is on ${RELEASE_BRANCH} (${error instanceof Error ? error.message : String(error)})` };
28
30
  }
31
+ const { answer } = read;
29
32
  if (answer.status === 404)
30
33
  return { problem: `${PRODUCT} has no ${tag} tag that GitHub can compare with ${RELEASE_BRANCH}` };
34
+ const limited = rateLimited(answer, read.token);
35
+ if (limited)
36
+ return { problem: `GitHub could not say whether the ${tag} tag is on ${RELEASE_BRANCH}: ${limited}` };
31
37
  if (answer.status !== 200)
32
38
  return { problem: `GitHub answered HTTP ${answer.status} when asked whether the ${tag} tag is on ${RELEASE_BRANCH}` };
33
39
  const json = answer.json;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veda-hq/niyam",
3
- "version": "0.7.14",
3
+ "version": "0.7.15",
4
4
  "description": "Work rules for repos that track work in GitHub Issues: setup, agent identity, push and PR checks.",
5
5
  "license": "MIT",
6
6
  "repository": {