@veda-hq/niyam 0.6.17 → 0.6.18

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
@@ -797,7 +797,16 @@ be recorded is refused (exit 3). Every answer is kept in
797
797
  log), so GitHub is asked once per pushed commit. A session's hook reaches
798
798
  GitHub as the session's agent, with every check `as-agent` makes, and the
799
799
  watcher with the push's own token. Its own errors never fail a push or hold
800
- a session. The settings:
800
+ a session.
801
+
802
+ `refuse-retired --root <repo> --remote <name>`, which the pre-push hook runs
803
+ before its expensive checks with the same ref lines, refuses (exit 3) a push to
804
+ a branch whose pull request merged while none is open. Such a push recreates a
805
+ branch the merge retired, and the commits after the merge land in no pull
806
+ request. The refusal names the way out. A branch GitHub cannot answer for, or
807
+ one with a full page of pull requests (which may hide the open one), only
808
+ warns. Exit 4 means it could not check at all; a hook reports that as not
809
+ checked. The settings:
801
810
 
802
811
  ```json
803
812
  { "prAutocreate": { "base": "main", "draft": false, "protected": ["main", "master", "develop", "prod", "production"], "skip": ["mergify/", "gh-readonly-queue/"], "optOut": [], "describe": "`gh pr edit --body-file`" } }
@@ -806,7 +815,8 @@ a session. The settings:
806
815
  `optOut` names older opt-out variables read beside `NIYAM_PR_AUTOCREATE`;
807
816
  `describe` says how the pushing session writes the real description;
808
817
  `retired`, a link, explains why a merged pull request retires its branch;
809
- `footer` ends the placeholder body.
818
+ `retire`, a command with `{number}` for the merged pull request, is the way out
819
+ `refuse-retired` names; `footer` ends the placeholder body.
810
820
 
811
821
  **Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
812
822
  sends a session back while its branch has commits the base lacks and its
@@ -1319,15 +1329,21 @@ is a slice the owner approves.
1319
1329
 
1320
1330
  ### Releases and upgrading
1321
1331
 
1322
- Each release is a tag `vX.Y.Z` on `main`, matching `package.json`; the
1323
- Release workflow checks both, runs `pnpm check` and publishes the GitHub
1324
- release, attaching the CLI package it built and tested. From 0.6.16 the same
1332
+ A release is the merge of its version bump: a push to `main` whose
1333
+ `package.json` version has no tag `vX.Y.Z` yet (P-61). The Release workflow
1334
+ then runs `pnpm check`, makes that annotated tag (`niyam X.Y.Z`) on the
1335
+ merged commit itself, and publishes the GitHub release, attaching the CLI
1336
+ package it built and tested. Agents push no release tags. From 0.6.16 the same
1325
1337
  package is on npm as `@veda-hq/niyam`, with provenance, for a repository that
1326
- pins it as an exact version. Install the attached package on each machine with
1327
- pnpm, once; nothing is built on install:
1338
+ pins it as an exact version; it publishes from the `npm` environment, which
1339
+ only `main` may deploy to. A tag on any other commit is not a release:
1340
+ `niyam upgrade` and `niyam onboard` ask GitHub's compare API, with no token,
1341
+ whether the tag's commit is on `main`, and refuse one that is not, naming the
1342
+ tag and the commit. Install the attached package on each machine with pnpm,
1343
+ once; nothing is built on install:
1328
1344
 
1329
1345
  ```bash
1330
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.17/veda-hq-niyam-0.6.17.tgz
1346
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.18/veda-hq-niyam-0.6.18.tgz
1331
1347
  ```
1332
1348
 
1333
1349
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
@@ -1343,11 +1359,11 @@ niyam upgrade
1343
1359
  ```
1344
1360
 
1345
1361
  `upgrade` asks GitHub's public releases API for the newest release, with no
1346
- token and no sign-in, and when it is newer than the CLI running, installs it
1347
- with the same `pnpm add -g`, printing old → new and the version the shell then
1362
+ token and no sign-in, and when it is newer than the CLI running and its tag's
1363
+ commit is on `main`, installs it with the same `pnpm add -g`, printing old → new and the version the shell then
1348
1364
  runs. On the newest release it says so and installs nothing; it never moves
1349
1365
  back to an older one. When GitHub cannot be reached, or a newer release has no
1350
- package attached yet, or pnpm fails, it says which and exits 1, checking
1366
+ package attached yet, or its tag is not on `main`, or pnpm fails, it says which and exits 1, checking
1351
1367
  nothing more. After an install, or when there was nothing to install, it walks
1352
1368
  `PATH`, as `type -a niyam` does, reading an empty or relative entry
1353
1369
  against the current folder as the shell does. It exits 0 when exactly one
@@ -1362,7 +1378,10 @@ newest release with the line above. `onboard`, when the repo pins a newer releas
1362
1378
  CLI running, refuses and says to run `niyam upgrade` first.
1363
1379
 
1364
1380
  `onboard` pins the client's workflow to one version, the release of the CLI
1365
- that ran it. Each job writes the pin twice, `checks.yml@vX.Y.Z` and, two lines
1381
+ that ran it, and writes `.github/niyam/cloud-setup.sh` at the same one. First
1382
+ it asks GitHub's compare API, with no token, whether that release's tag is on
1383
+ `main`; when it is not, or GitHub cannot say, it refuses and changes nothing.
1384
+ Each job writes the pin twice, `checks.yml@vX.Y.Z` and, two lines
1366
1385
  below it under `with:`, `niyam-ref: vX.Y.Z`, the one input `checks.yml`
1367
1386
  declares; GitHub refuses a caller that passes an input the called workflow
1368
1387
  does not declare, `process-rules-ref` too since P-57. Every job of
@@ -1398,6 +1417,39 @@ functions, 90% branches), builds `dist/` and runs it. `pnpm scan:secrets` runs
1398
1417
  Gitleaks and TruffleHog over the working tree; CI runs both over the whole
1399
1418
  history.
1400
1419
 
1420
+ ### Guard
1421
+
1422
+ The `guard` workflow (`.github/workflows/guard.yml`) runs on
1423
+ `pull_request_target`, so GitHub runs it from `main`'s copy, never the pull
1424
+ request's. Its job, `Guard`, checks out `main` alone, reads the pull
1425
+ request's changed files from GitHub's API as data, and runs
1426
+ `scripts/guard.mjs` (tested in `scripts/guard.test.mjs`). A change to a guard
1427
+ file passes only when the pull request's slice names it in a `**Guards:**`
1428
+ section, one already in the slice when the owner put `approved` on its Work
1429
+ item (for a slice added later, when the owner's `Decision:` settled it):
1430
+
1431
+ ```markdown
1432
+ **Guards:** `.github/workflows/ci.yml`, `scripts/*.mjs`, `.githooks/`
1433
+ ```
1434
+
1435
+ A name is a path, a folder ending in `/`, or a pattern where `*` matches
1436
+ within one folder and `**` across them. The guard files are everything under
1437
+ `.github/`, `.githooks/`, `.dvara.json`, `.dvara/records-baseline.json`,
1438
+ `.gitleaks.toml`, `.trufflehog-exclude`, the `scripts` of `package.json`,
1439
+ and `scripts/*.mjs`. A test file needs naming too when a pull request
1440
+ deletes it, leaves it fewer `test(`/`it(` calls than the merge base, or adds
1441
+ `.skip`, `.only` or `todo`.
1442
+
1443
+ Two changes pass unnamed: an onboard pull request
1444
+ (`chore(niyam): onboard at vX.Y.Z`) whose every changed line only moves the
1445
+ niyam version, and a sha256 with it, to that release, tagged on `main`; and a
1446
+ Dependabot pull request whose every changed line only moves a `uses:` to
1447
+ another full commit sha with its version comment. Whatever the slice says,
1448
+ Guard refuses a pull request that adds a job reporting a check the `main`
1449
+ ruleset requires, or `Guard`. It fails closed: a truncated file list, or any
1450
+ read GitHub does not answer, refuses. Each refusal names the file and how to
1451
+ pass. A slice edit does not run Guard again: edit or push the pull request.
1452
+
1401
1453
  ## License
1402
1454
 
1403
1455
  MIT
package/dist/onboard.js CHANGED
@@ -8,6 +8,7 @@ import { HOURLY } from './asks.js';
8
8
  import { DEFAULT_SCHEDULE, FEATURES, FIGMA_FILE_KEY, NEEDS_ISSUE_TYPES, featuresIn, parseFeatures, renamedLines, scheduleIn } from './features.js';
9
9
  import { CLOUD_SETUP_PATH, HOOKS_PATH, LEFTOVER_CLOUD_SETUP_PATH, ONBOARD_BRANCH, WORKFLOW_PATH, autoMerge, mergeQueue, openPull, remoteFile, } from './onboard-pull.js';
10
10
  import { cloudRepoScript, cloudScriptVersion, releaseSha256 } from './cloud.js';
11
+ import { tagOnMain } from './release-tag.js';
11
12
  import { setSecret } from './secrets.js';
12
13
  import { UPGRADE } from './upgrade.js';
13
14
  import { isNewer, packageVersion } from './version.js';
@@ -935,6 +936,12 @@ export async function onboard(sys, io, args = []) {
935
936
  const aheadHere = newerPinHere(fileAt, version);
936
937
  if (aheadHere !== undefined)
937
938
  return refuseOlder(io, slug, aheadHere, version);
939
+ // The workflow and cloud-setup.sh pin this release: a tag off main is not one (P-61).
940
+ const onMain = await tagOnMain(sys, version);
941
+ if ('problem' in onMain) {
942
+ io.err(`onboard: ${onMain.problem}; nothing changed`);
943
+ return 1;
944
+ }
938
945
  // The plan, by group, and the steps that carry it out after the yes.
939
946
  const pull = [];
940
947
  const github = [];
@@ -35,10 +35,10 @@ export function autocreateSettings(raw) {
35
35
  return { ...DEFAULTS };
36
36
  if (typeof value !== 'object' || value === null || Array.isArray(value))
37
37
  throw new Error(`${where} must be an object`);
38
- const { base = DEFAULTS.base, draft = DEFAULTS.draft, protected: guarded = DEFAULTS.protected, skip = DEFAULTS.skip, optOut = DEFAULTS.optOut, describe, retired, footer, ...rest } = value;
38
+ const { base = DEFAULTS.base, draft = DEFAULTS.draft, protected: guarded = DEFAULTS.protected, skip = DEFAULTS.skip, optOut = DEFAULTS.optOut, describe, retired, retire, footer, ...rest } = value;
39
39
  const extra = Object.keys(rest)[0];
40
40
  if (extra !== undefined)
41
- throw new Error(`${where} has an unknown key "${extra}"; it takes "base", "draft", "protected", "skip", "optOut", "describe", "retired" and "footer"`);
41
+ throw new Error(`${where} has an unknown key "${extra}"; it takes "base", "draft", "protected", "skip", "optOut", "describe", "retired", "retire" and "footer"`);
42
42
  if (typeof base !== 'string' || !BRANCH.test(base))
43
43
  throw new Error(`${where}.base must be a branch name`);
44
44
  if (typeof draft !== 'boolean')
@@ -54,8 +54,11 @@ export function autocreateSettings(raw) {
54
54
  const page = line(retired, 'retired');
55
55
  if (page !== undefined && !/^https:\/\/\S+$/.test(page))
56
56
  throw new Error(`${where}.retired must be an https link`);
57
+ const way = line(retire, 'retire');
58
+ if (way !== undefined && !way.includes('{number}'))
59
+ throw new Error(`${where}.retire must name the merged pull request as {number}`);
57
60
  const last = line(footer, 'footer');
58
- return { ...settings, ...(page === undefined ? {} : { retired: page }), ...(last === undefined ? {} : { footer: last }) };
61
+ return { ...settings, ...(page === undefined ? {} : { retired: page }), ...(way === undefined ? {} : { retire: way }), ...(last === undefined ? {} : { footer: last }) };
59
62
  }
60
63
  /** The settings in the repository at `root`; the defaults where it has no settings file. */
61
64
  export function settingsAt(sys, root) {
@@ -102,6 +105,19 @@ export function statePath(root, branch) {
102
105
  export function optoutPath(root, branch) {
103
106
  return statePath(root, branch).replace(/\.json$/, '.optout');
104
107
  }
108
+ /** How many pull requests one listing of a branch asks for. */
109
+ export const PR_LIST_LIMIT = 20;
110
+ /**
111
+ * The merged pull request that retired a branch, given its pull requests, or
112
+ * undefined. A branch with an open one is live whatever merged before it; one
113
+ * whose pull requests only closed unmerged was never retired. ensurePr opens
114
+ * none for a retired branch, and refuse-retired refuses a push to one.
115
+ */
116
+ export function retiredBy(pulls) {
117
+ if (pulls.some((pull) => pull.state === 'OPEN'))
118
+ return undefined;
119
+ return pulls.find((pull) => pull.state === 'MERGED');
120
+ }
105
121
  function loadState(sys, root, branch) {
106
122
  try {
107
123
  const value = JSON.parse(sys.read(statePath(root, branch)));
@@ -259,8 +275,17 @@ export class Pulls {
259
275
  }
260
276
  /** The branch's pull requests, newest first; a string says why they could not be listed. */
261
277
  async list(branch) {
278
+ const listed = await this.listing(branch);
279
+ return typeof listed === 'string' ? listed : listed.pulls;
280
+ }
281
+ /**
282
+ * The branch's pull requests, newest first, and whether GitHub's page was
283
+ * full (`PR_LIST_LIMIT` entries before any was dropped), so it may hold
284
+ * back more; a string says why they could not be listed.
285
+ */
286
+ async listing(branch) {
262
287
  const owner = this.slug.split('/')[0];
263
- const got = await this.call('GET', `pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&state=all&per_page=20`);
288
+ const got = await this.call('GET', `pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&state=all&per_page=${PR_LIST_LIMIT}`);
264
289
  if (typeof got === 'string')
265
290
  return got;
266
291
  if (got.status !== 200)
@@ -278,7 +303,7 @@ export class Pulls {
278
303
  if (head === branch)
279
304
  pulls.push(pull);
280
305
  }
281
- return pulls;
306
+ return { pulls, full: got.json.length >= PR_LIST_LIMIT };
282
307
  }
283
308
  /** Opens a pull request: it, or "none ahead" when the branch adds nothing, or why it could not. */
284
309
  async create(branch, base, title, body, draft) {
@@ -348,7 +373,7 @@ export async function ensurePr(sys, root, settings, branch, sha, pulls) {
348
373
  if (typeof listed === 'string')
349
374
  return { problem: `could not list PRs for ${branch} (${listed}); will retry` };
350
375
  const open = listed.find((pull) => pull.state === 'OPEN');
351
- const merged = listed.find((pull) => pull.state === 'MERGED');
376
+ const merged = retiredBy(listed);
352
377
  let pr = null;
353
378
  let created = false;
354
379
  const notes = [];
@@ -686,6 +711,98 @@ function flags(args, names) {
686
711
  }
687
712
  return found;
688
713
  }
714
+ /**
715
+ * The branches git's pre-push ref lines update on the remote, in order: each
716
+ * refs/heads/* destination with a real local commit. A deletion (an all-zero
717
+ * local sha), a tag and a line that is not a ref line name none. The branch
718
+ * is the remote ref, the pull request's head: `git push origin HEAD:x` pushes x.
719
+ */
720
+ export function pushedRefs(stdin) {
721
+ const refs = [];
722
+ for (const each of stdin.split('\n')) {
723
+ const parts = each.trim().split(/\s+/);
724
+ if (parts.length !== 4)
725
+ continue;
726
+ const [, localSha, remoteRef, remoteSha] = parts;
727
+ if (ZERO_SHA.test(localSha) || !remoteRef.startsWith('refs/heads/'))
728
+ continue;
729
+ refs.push({ localSha, branch: remoteRef.slice('refs/heads/'.length), remoteSha });
730
+ }
731
+ return refs;
732
+ }
733
+ /** refuse-retired's exits: a push to a retired branch, and a check that crashed. */
734
+ export const RETIRED_REFUSAL = 3;
735
+ export const RETIRED_UNCHECKED = 4;
736
+ /**
737
+ * The pre-push hook's check before its expensive ones, git's ref lines on
738
+ * stdin. A push to a branch whose pull request already merged, with none
739
+ * open, recreates a branch the merge retired, and its commits then sit in no
740
+ * pull request: RETIRED_REFUSAL names each such branch and the way out. A
741
+ * branch GitHub cannot answer for warns in one line and refuses nothing, as
742
+ * every other path here fails open; so does a listing as long as one page,
743
+ * which may hold back the open pull request that keeps the branch live.
744
+ */
745
+ export async function refuseRetired(sys, io, args, stdin, pullsOf = pullsFor) {
746
+ const unchecked = (why) => {
747
+ io.out(`⚠️ Could not check whether a pushed branch's PR already merged (${why}); not checked.`);
748
+ return RETIRED_UNCHECKED;
749
+ };
750
+ let root;
751
+ let remote;
752
+ try {
753
+ const given = flags(args, ['--root', '--remote']);
754
+ const named = given.get('--root');
755
+ if (!named)
756
+ throw new Error('refuse-retired needs --root <repository>');
757
+ root = named;
758
+ remote = given.get('--remote') ?? '';
759
+ }
760
+ catch (error) {
761
+ return unchecked(error instanceof Error ? error.message : String(error));
762
+ }
763
+ // A workflow's push is not a session reviving a branch, and its token answers for no worktree.
764
+ if (sys.env.CI || remote !== REMOTE)
765
+ return 0;
766
+ let settings;
767
+ try {
768
+ settings = settingsAt(sys, root);
769
+ }
770
+ catch (error) {
771
+ return unchecked(error instanceof Error ? error.message : String(error));
772
+ }
773
+ const branches = [...new Set(pushedRefs(stdin).map((ref) => ref.branch).filter((branch) => eligible(settings, branch)))];
774
+ if (branches.length === 0)
775
+ return 0;
776
+ const pulls = pullsOf(sys, root, undefined);
777
+ const retired = [];
778
+ const skip = (branch, why) => io.out(`⚠️ Could not ask GitHub whether ${branch}'s PR already merged (${why}); not checked.`);
779
+ for (const branch of branches) {
780
+ const listed = 'problem' in pulls ? pulls.problem : await pulls.listing(branch);
781
+ if (typeof listed === 'string') {
782
+ skip(branch, listed);
783
+ continue;
784
+ }
785
+ if (listed.full) {
786
+ skip(branch, `GitHub listed ${PR_LIST_LIMIT} or more PRs, more than one page shows`);
787
+ continue;
788
+ }
789
+ const pull = retiredBy(listed.pulls);
790
+ if (pull)
791
+ retired.push([branch, pull.number]);
792
+ }
793
+ for (const [branch, number] of retired) {
794
+ io.out(`❌ Error: ${branch} already has MERGED PR #${number} and no open PR. Pushing it`);
795
+ io.out(' recreates a branch the merge retired, and the commits after the merge land in no PR.');
796
+ if (settings.retire) {
797
+ io.out(' Retire it: move the commits missing from the PR head to a fresh branch, then push that:');
798
+ io.out(` ${settings.retire.replaceAll('{number}', String(number))}`);
799
+ }
800
+ else {
801
+ io.out(` Move the commits missing from the PR head to a fresh branch, then push that${settings.retired ? ` (${settings.retired})` : ''}.`);
802
+ }
803
+ }
804
+ return retired.length > 0 ? RETIRED_REFUSAL : 0;
805
+ }
689
806
  /**
690
807
  * The pre-push hook's half, git's ref lines on stdin: records each pushed
691
808
  * branch's opt-out before the refs are sent, then starts one detached watcher
@@ -720,14 +837,7 @@ export async function spawnWatchers(sys, io, args, stdin) {
720
837
  const opted = optedOutNow(sys, settings);
721
838
  const names = [OPT_OUT_VAR, ...settings.optOut].join(' or ');
722
839
  const started = [];
723
- for (const each of stdin.split('\n')) {
724
- const parts = each.trim().split(/\s+/);
725
- if (parts.length !== 4)
726
- continue;
727
- const [, localSha, remoteRef, remoteSha] = parts;
728
- if (ZERO_SHA.test(localSha) || !remoteRef.startsWith('refs/heads/'))
729
- continue;
730
- const branch = remoteRef.slice('refs/heads/'.length);
840
+ for (const { localSha, branch, remoteSha } of pushedRefs(stdin)) {
731
841
  if (!eligible(settings, branch))
732
842
  continue;
733
843
  // Written before the refs are sent, so no turn-end hook sees the push land without it.
@@ -846,7 +956,7 @@ export async function watch(sys, io, args, pullsOf = pullsFor) {
846
956
  await sys.sleep(parsed.retryInterval * 1000);
847
957
  }
848
958
  }
849
- /** `niyam pr-autocreate <claude-hook | spawn-watchers | watch> ...`: never a usage exit, which would hold a hook. */
959
+ /** `niyam pr-autocreate <claude-hook | spawn-watchers | refuse-retired | watch> ...`: never a usage exit, which would hold a hook. */
850
960
  export async function prAutocreate(sys, io, args) {
851
961
  const [mode, ...rest] = args;
852
962
  try {
@@ -854,13 +964,21 @@ export async function prAutocreate(sys, io, args) {
854
964
  return await claudeHook(sys, io, sys.readStdin());
855
965
  if (mode === 'spawn-watchers')
856
966
  return await spawnWatchers(sys, io, rest, sys.readStdin());
967
+ if (mode === 'refuse-retired')
968
+ return await refuseRetired(sys, io, rest, sys.readStdin());
857
969
  if (mode === 'watch')
858
970
  return await watch(sys, io, rest);
859
- io.err(`pr-autocreate: unknown mode "${mode ?? ''}"; it takes claude-hook, spawn-watchers or watch; nothing done`);
971
+ io.err(`pr-autocreate: unknown mode "${mode ?? ''}"; it takes claude-hook, spawn-watchers, refuse-retired or watch; nothing done`);
860
972
  return 0;
861
973
  }
862
974
  catch (error) {
863
- io.err(`pr-autocreate: unexpected error (${error instanceof Error ? error.message : String(error)}); nothing done`);
975
+ const why = error instanceof Error ? error.message : String(error);
976
+ // A crash is not "not retired": the hook reports RETIRED_UNCHECKED as not checked, never the 0 of a live branch.
977
+ if (mode === 'refuse-retired') {
978
+ io.out(`⚠️ Could not check whether a pushed branch's PR already merged (pr-autocreate crashed: ${why}); not checked.`);
979
+ return RETIRED_UNCHECKED;
980
+ }
981
+ io.err(`pr-autocreate: unexpected error (${why}); nothing done`);
864
982
  return 0;
865
983
  }
866
984
  }
@@ -0,0 +1,40 @@
1
+ import { API } from './agent.js';
2
+ import { PRODUCT } from './names.js';
3
+ /** How long GitHub gets to compare a release tag with main. */
4
+ const COMPARE_MS = 15_000;
5
+ /** The branch every release is cut from (P-61). */
6
+ export const RELEASE_BRANCH = 'main';
7
+ /**
8
+ * Whether release `version`'s tag names a commit on main, asked of GitHub's
9
+ * compare API with no token, as `upgrade` asks for the newest release: the
10
+ * repository is public. Since P-61 only main's Release workflow makes a
11
+ * `v*` tag, but GitHub lets anyone with write access push one, on any
12
+ * commit, so `upgrade` and `onboard` ask before they install or pin a
13
+ * release. Comparing the tag with main gives the tag's commit as the base,
14
+ * and says main is `ahead` of it, or `identical`, exactly when that commit
15
+ * is on main. Both refs are written in full, so a branch named like the
16
+ * tag, or a tag named main, is never the one compared. Anything else is a
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.
19
+ */
20
+ export async function tagOnMain(sys, version) {
21
+ const tag = `v${version}`;
22
+ let answer;
23
+ try {
24
+ answer = await sys.http(`${API}/repos/${PRODUCT}/compare/refs/tags/${tag}...refs/heads/${RELEASE_BRANCH}?per_page=1`, { timeoutMs: COMPARE_MS });
25
+ }
26
+ catch (error) {
27
+ return { problem: `GitHub could not be asked whether the ${tag} tag is on ${RELEASE_BRANCH} (${error instanceof Error ? error.message : String(error)})` };
28
+ }
29
+ if (answer.status === 404)
30
+ return { problem: `${PRODUCT} has no ${tag} tag that GitHub can compare with ${RELEASE_BRANCH}` };
31
+ if (answer.status !== 200)
32
+ return { problem: `GitHub answered HTTP ${answer.status} when asked whether the ${tag} tag is on ${RELEASE_BRANCH}` };
33
+ const json = answer.json;
34
+ const sha = typeof json?.base_commit?.sha === 'string' && /^[0-9a-f]{40}$/.test(json.base_commit.sha) ? json.base_commit.sha : undefined;
35
+ if (sha === undefined)
36
+ return { problem: `GitHub's comparison of the ${tag} tag with ${RELEASE_BRANCH} names no commit for the tag` };
37
+ if (json?.status === 'ahead' || json?.status === 'identical')
38
+ return { sha };
39
+ return { problem: `the ${tag} tag is on commit ${sha.slice(0, 12)}, which is not on ${PRODUCT}'s ${RELEASE_BRANCH} (GitHub's comparison: ${JSON.stringify(json?.status ?? null)}); a release comes only from ${RELEASE_BRANCH}, so this tag is not one` };
40
+ }
package/dist/upgrade.js CHANGED
@@ -3,6 +3,7 @@ import { tilde } from './layout.js';
3
3
  import { CLI, PRODUCT, tarballName } from './names.js';
4
4
  import { CLOUD_SETUP_PATH } from './onboard-pull.js';
5
5
  import { GITHUB_WEB } from './host.js';
6
+ import { tagOnMain } from './release-tag.js';
6
7
  import { isNewer, packageVersion } from './version.js';
7
8
  /** The command that updates this machine's CLI, as messages name it. */
8
9
  export const UPGRADE = `${CLI} upgrade`;
@@ -119,6 +120,12 @@ export async function upgrade(sys, io, running = packageVersion()) {
119
120
  io.err(`upgrade: the v${version} release has no ${tarballName(version)} yet; run ${UPGRADE} again once the Release workflow attaches it`);
120
121
  return 1;
121
122
  }
123
+ // A tag off main is not a release, whatever GitHub's releases list says (P-61).
124
+ const onMain = await tagOnMain(sys, version);
125
+ if ('problem' in onMain) {
126
+ io.err(`upgrade: ${onMain.problem}; nothing installed`);
127
+ return 1;
128
+ }
122
129
  io.out(`upgrade: ${CLI} ${running} → ${version}`);
123
130
  io.out(` pnpm add -g ${url}`);
124
131
  const installing = sys.spin(`Installing ${CLI} ${version}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veda-hq/niyam",
3
- "version": "0.6.17",
3
+ "version": "0.6.18",
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": {