@veda-hq/niyam 0.6.16 → 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 +261 -48
- package/dist/agent.js +4 -0
- package/dist/as-agent.js +26 -18
- package/dist/board.js +3 -3
- package/dist/brief.js +370 -0
- package/dist/cloud.js +28 -11
- package/dist/cubic-dismiss.js +284 -0
- package/dist/doctor.js +3 -6
- package/dist/handoff.js +527 -0
- package/dist/issue-types.js +2 -2
- package/dist/keep-going.js +384 -0
- package/dist/onboard.js +45 -16
- package/dist/pr-autocreate.js +984 -0
- package/dist/release-tag.js +40 -0
- package/dist/run.js +55 -5
- package/dist/session-start.js +2 -2
- package/dist/sys.js +44 -1
- package/dist/upgrade.js +7 -0
- package/dist/work.js +4 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -329,8 +329,7 @@ Claude cloud sessions below).
|
|
|
329
329
|
◇ This Mac
|
|
330
330
|
│ pre-push hook new
|
|
331
331
|
│
|
|
332
|
-
◇ Claude cloud — by hand, once
|
|
333
|
-
│ Setup script niyam cloud-setup, first
|
|
332
|
+
◇ Claude cloud — by hand, once per claude.ai account
|
|
334
333
|
│ claude.ai's GitHub as AGENT
|
|
335
334
|
│
|
|
336
335
|
◇ Check
|
|
@@ -347,7 +346,16 @@ Claude cloud sessions below).
|
|
|
347
346
|
run asks you to name the owner. Without a terminal, `onboard` refuses
|
|
348
347
|
unless given `--yes` or `--dry-run`. After the yes it shows one line per step, a
|
|
349
348
|
spinner while it works, and ends with the pull request and a short "By
|
|
350
|
-
hand:" list of what GitHub's
|
|
349
|
+
hand:" list of what GitHub's and Claude's APIs cannot do. Each line there
|
|
350
|
+
is one sentence on standard output saying the whole step: how often (now,
|
|
351
|
+
once for the repository, once per claude.ai account), what to do, and its
|
|
352
|
+
link. A first onboarding with the review routine ends:
|
|
353
|
+
|
|
354
|
+
```
|
|
355
|
+
By hand:
|
|
356
|
+
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.
|
|
357
|
+
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.
|
|
358
|
+
```
|
|
351
359
|
|
|
352
360
|
It writes `.github/niyam.json`, adds to `.claude/settings.json`
|
|
353
361
|
the lock in `env`, a SessionStart hook running `niyam session-start`, a
|
|
@@ -366,14 +374,16 @@ Claude cloud sessions below).
|
|
|
366
374
|
`niyam / Work rules`. With identity alone `onboard` writes no workflow. It writes
|
|
367
375
|
`.github/niyam/cloud-setup.sh`, which installs the CLI in Claude
|
|
368
376
|
cloud sessions at the version the workflow pins, and writes it again on
|
|
369
|
-
every run (see Claude cloud sessions below);
|
|
370
|
-
|
|
377
|
+
every run (see Claude cloud sessions below); a cloud session with no
|
|
378
|
+
niyam runs it from the SessionStart hook, so there is nothing to paste,
|
|
379
|
+
and the first time, the plan lists the one connection of claude.ai's
|
|
380
|
+
GitHub as the agent, once per claude.ai account. Where the
|
|
371
381
|
repo still has `.github/process-rules/cloud-setup.sh`, which releases up
|
|
372
382
|
to 0.6.10 wrote beside it, the pull request deletes it, but only where it
|
|
373
383
|
leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
|
|
374
384
|
when GitHub names no sha256 for the release, keeps the old file too), and
|
|
375
|
-
the description says to
|
|
376
|
-
|
|
385
|
+
the description says to delete niyam's part of a Setup script pasted
|
|
386
|
+
before 0.6.10. It checks the agent can
|
|
377
387
|
push. With no access, or read access only (a public repo, or an
|
|
378
388
|
organisation's base permission), the plan gives it write access as you
|
|
379
389
|
and accepts the invitation as the agent; and `onboard` names
|
|
@@ -686,6 +696,153 @@ request does not change is dropped, as another branch's. A file whose
|
|
|
686
696
|
one. A bot's thread and the local finding at the same file and line are one
|
|
687
697
|
signal: the same review, posted twice.
|
|
688
698
|
|
|
699
|
+
**The hand-off gate.** A session working on one thing that trips over
|
|
700
|
+
another, not its fault, fixes the other thing worse than a session with no
|
|
701
|
+
stake would: it wants its own work unblocked. No program can see that
|
|
702
|
+
moment, so the gate prices two of its footprints. A push whose branch edits
|
|
703
|
+
the repository's shared plumbing, or whose push history shows one stage
|
|
704
|
+
failing three times across two working trees or more, needs a declaration
|
|
705
|
+
first:
|
|
706
|
+
|
|
707
|
+
```sh
|
|
708
|
+
niyam handoff --detect # what fires, as JSON
|
|
709
|
+
niyam handoff --record --disposition own-work --reason "the workflow change is this slice"
|
|
710
|
+
niyam handoff --record --disposition handed-off --reason "..." --open-brief .tmp/brief.md
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
`own-work` is one sentence. `handed-off` names a Brief issue (`--brief #N`,
|
|
714
|
+
or `--open-brief <draft.md>`, which lints the draft and opens it as one, on
|
|
715
|
+
the board `.github/niyam.json`'s `project` names). `carrying` also owes
|
|
716
|
+
`## What I verified` and `## Why I did not hand off`, and may blame a file
|
|
717
|
+
the branch changed. `dismissed` cites where the owner decided (`#123`, a
|
|
718
|
+
link, an id such as `ABC-123`, or a commit). `niyam pre-push` runs the gate
|
|
719
|
+
for an agent session, right after the identity check; `niyam handoff
|
|
720
|
+
--assert-fresh` runs it alone, for a hook of the client's own. It passes
|
|
721
|
+
when nothing fires, and otherwise only when the session's newest
|
|
722
|
+
declaration (`--call-site push-skill`, the default) covers this head, this
|
|
723
|
+
base and every trigger that fired. A blocking
|
|
724
|
+
brief handed off holds the push until a merged pull request saying
|
|
725
|
+
`Fixes #N` closes it and this branch has its merge commit, or it is closed as
|
|
726
|
+
not planned. Declarations and the gate's verdicts are JSON lines in
|
|
727
|
+
`.tmp/push/handoff-log.jsonl`. `niyam brief [--lint] <draft.md>` opens a
|
|
728
|
+
draft, or only checks it.
|
|
729
|
+
|
|
730
|
+
A brief draft has YAML frontmatter (`slug`, `title`, `discovered-on`: this
|
|
731
|
+
branch, `blocking: yes|no`, `status: open`, `blamed-paths`: a list of files,
|
|
732
|
+
none in the branch's own diff) and five sections: `## What happened`, with
|
|
733
|
+
the command and its output in a fence, `## Why this is not caused by the
|
|
734
|
+
originating branch`, `## Hypothesis (UNVERIFIED)`, `## What the receiving
|
|
735
|
+
session must verify first` and `## Sequencing`. The gate is on where the
|
|
736
|
+
repository names its plumbing; a folder ends in `/`, anything else is one
|
|
737
|
+
file by its whole path. The copy of the settings on the remote's default
|
|
738
|
+
branch (or the `--base` asked for) decides when it names one, the settings
|
|
739
|
+
file always counts as plumbing, and the base must be a remote-tracking
|
|
740
|
+
branch, so a branch cannot turn the gate off in the push the gate judges:
|
|
741
|
+
|
|
742
|
+
```json
|
|
743
|
+
{
|
|
744
|
+
"handoff": {
|
|
745
|
+
"plumbing": [".github/workflows/", ".husky/", "package.json"],
|
|
746
|
+
"history": ".tmp/performance/history.jsonl",
|
|
747
|
+
"ignoreStages": ["checking-incidental-handoff-declarations"],
|
|
748
|
+
"template": "docs/templates/brief.md",
|
|
749
|
+
"base": "origin/main"
|
|
750
|
+
}
|
|
751
|
+
}
|
|
752
|
+
```
|
|
753
|
+
|
|
754
|
+
`history` is the push history, one JSON line per hook run with its `kind`,
|
|
755
|
+
`exitCode`, `branch`, tree `fingerprint` and `stages` (`name`, `status`);
|
|
756
|
+
without one, only the plumbing trigger fires. A line that is not a whole run
|
|
757
|
+
is skipped, never counted.
|
|
758
|
+
|
|
759
|
+
**Dismissing a Cubic finding.** A wrong finding is the agent's call; a true
|
|
760
|
+
one left unfixed is the owner's. `niyam cubic-dismiss --evidence <proof>
|
|
761
|
+
--title <exact title> --reason <why>` records one the agent proves wrong:
|
|
762
|
+
the proof is a path at HEAD (a `#section` or `:line` may follow), a commit
|
|
763
|
+
HEAD contains by its full 40-hex id, or a title already dismissed, and one
|
|
764
|
+
that does not resolve is refused. `--decision <where the owner chose>`
|
|
765
|
+
records the owner's call; a reason, evidence or context that says
|
|
766
|
+
"pre-existing", "out of scope", "later" or "follow-up" is refused on
|
|
767
|
+
evidence. `--title`/`--reason` pair up in order and repeat, and `--from
|
|
768
|
+
<file.json>`, a file in the repository holding `[{"title", "reason"}]`,
|
|
769
|
+
carries titles a shell cannot. It appends a dated comment and the title to
|
|
770
|
+
the dismiss file, refuses one that already differs from HEAD, and commits
|
|
771
|
+
that file alone (`git commit --only`, every hook run) with a
|
|
772
|
+
`Dismissal-Basis: evidence` trailer, or the owner's word, so
|
|
773
|
+
`git log --grep "Dismissal-Basis: evidence" -p -- .cubic-dismiss` lists every
|
|
774
|
+
call the agent made alone. A failed commit restores the file. The settings:
|
|
775
|
+
|
|
776
|
+
```json
|
|
777
|
+
{ "cubicDismiss": { "file": ".cubic-dismiss", "subject": "chore(review): dismiss {count} Cubic finding{s}", "ownerBasis": "owner" } }
|
|
778
|
+
```
|
|
779
|
+
|
|
780
|
+
**A pushed branch gets its pull request.** git has no post-push hook, so
|
|
781
|
+
`niyam pr-autocreate` takes a push from three sides. `claude-hook`, Claude
|
|
782
|
+
Code's PostToolUse(Bash) and Stop hook, catches a session's foreground push
|
|
783
|
+
once the tracking ref moved (a background one at Stop), opens the pull
|
|
784
|
+
request, and tells the session once to switch Autofix on: in context after
|
|
785
|
+
the push, or by holding Stop (exit 2); a cloud session, which has no
|
|
786
|
+
Autofix, gets a `systemMessage` instead. `spawn-watchers --root <repo>
|
|
787
|
+
--remote <name>`, run by the pre-push hook with git's ref lines on stdin,
|
|
788
|
+
starts one detached `watch` per pushed branch, which waits for the remote to
|
|
789
|
+
hold the pushed commit, then opens the pull request, retrying GitHub for ten
|
|
790
|
+
minutes. Nothing opens for a protected or merge-queue branch, another remote,
|
|
791
|
+
a branch with no commits ahead of the base, one with a merged pull request
|
|
792
|
+
(it is retired) or a closed one (reopening is a person's call), or in CI.
|
|
793
|
+
`NIYAM_PR_AUTOCREATE=0` on a push opens none for the commit it sent: the
|
|
794
|
+
choice is recorded before git sends the refs, and a push whose choice cannot
|
|
795
|
+
be recorded is refused (exit 3). Every answer is kept in
|
|
796
|
+
`.tmp/pr-autocreate/` (one JSON record per branch, its opt-outs, the watch
|
|
797
|
+
log), so GitHub is asked once per pushed commit. A session's hook reaches
|
|
798
|
+
GitHub as the session's agent, with every check `as-agent` makes, and the
|
|
799
|
+
watcher with the push's own token. Its own errors never fail a push or hold
|
|
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:
|
|
810
|
+
|
|
811
|
+
```json
|
|
812
|
+
{ "prAutocreate": { "base": "main", "draft": false, "protected": ["main", "master", "develop", "prod", "production"], "skip": ["mergify/", "gh-readonly-queue/"], "optOut": [], "describe": "`gh pr edit --body-file`" } }
|
|
813
|
+
```
|
|
814
|
+
|
|
815
|
+
`optOut` names older opt-out variables read beside `NIYAM_PR_AUTOCREATE`;
|
|
816
|
+
`describe` says how the pushing session writes the real description;
|
|
817
|
+
`retired`, a link, explains why a merged pull request retires its branch;
|
|
818
|
+
`retire`, a command with `{number}` for the merged pull request, is the way out
|
|
819
|
+
`refuse-retired` names; `footer` ends the placeholder body.
|
|
820
|
+
|
|
821
|
+
**Started work runs to merge.** `niyam keep-going`, Claude Code's Stop hook,
|
|
822
|
+
sends a session back while its branch has commits the base lacks and its
|
|
823
|
+
pull request has not merged at this commit, saying what is left (push, open
|
|
824
|
+
the pull request, mark it ready, carry it to merge) and the count ("1 of
|
|
825
|
+
5"). It lets the session stop for a subagent; on the base, another trunk or
|
|
826
|
+
a detached HEAD; when another remote branch carries the commits; while a
|
|
827
|
+
background task, `git commit` or `git push` runs (its exit wakes the
|
|
828
|
+
session), except in print mode (`NIYAM_PRINT_MODE=1`), where the task dies
|
|
829
|
+
with the turn; for a desktop session with every commit on a ready pull
|
|
830
|
+
request, which Autofix wakes; when GitHub cannot say; and at a stop note for
|
|
831
|
+
this commit, which `niyam keep-going --stop "<why>"` writes when only the
|
|
832
|
+
owner can unblock the work or it is proven unneeded, and whose reason it
|
|
833
|
+
shows once. At the sixth stop at one commit it writes that note itself. A new
|
|
834
|
+
commit resets the count and voids the note. The pull request is read over
|
|
835
|
+
REST, as the session's agent; a cloud session is held the same way. Its
|
|
836
|
+
records are in `.tmp/keep-going/`. The settings:
|
|
837
|
+
|
|
838
|
+
```json
|
|
839
|
+
{ "keepGoing": { "trunks": [], "printMode": [], "owner": "the owner", "tag": "niyam keep-going" } }
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
`base`, when set, names the branch work merges into; otherwise it is
|
|
843
|
+
origin's default branch. `printMode` names older print-mode variables read beside `NIYAM_PRINT_MODE`;
|
|
844
|
+
`owner` is who the messages tell a session to tell; `tag` ends each message.
|
|
845
|
+
|
|
689
846
|
**Design frames** is the `figma` feature, an optional extension for clients
|
|
690
847
|
that design in Figma: with it on and two Actions secrets, `FIGMA_LIBRARY`
|
|
691
848
|
(the design library's file key) and `FIGMA_TOKEN`, each State of the slice
|
|
@@ -1015,30 +1172,42 @@ read only its REST API, here and everywhere else. The one exception is who
|
|
|
1015
1172
|
edited an owner's edited `Decision:` comment, which only GraphQL names; here
|
|
1016
1173
|
such a comment does not count.
|
|
1017
1174
|
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
`.github/workflows/niyam.yml` pins,
|
|
1025
|
-
run, so the pin bump that upgrades the checks
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
and
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1175
|
+
**Installing niyam there.** Claude Code has no API, CLI or repo file for a
|
|
1176
|
+
cloud environment's Setup script, but a repo's SessionStart hooks run in its
|
|
1177
|
+
cloud sessions. So when `CLAUDE_CODE_REMOTE=true` and the hook finds no
|
|
1178
|
+
niyam CLI, it runs the clone's `.github/niyam/cloud-setup.sh` (from
|
|
1179
|
+
`CLAUDE_PROJECT_DIR`, else the working folder), then `session-start` as
|
|
1180
|
+
usual, and says in one line that it installed niyam. `onboard` writes that
|
|
1181
|
+
file in its pull request at the version `.github/workflows/niyam.yml` pins,
|
|
1182
|
+
and writes it again on every run, so the pin bump that upgrades the checks
|
|
1183
|
+
upgrades cloud sessions too. The file unpacks Node and the CLI under
|
|
1184
|
+
`/opt/niyam`, each once it matches the sha256 the file pins (Node's from
|
|
1185
|
+
this release, the CLI's from GitHub's record of the release archive), and
|
|
1186
|
+
puts `niyam` in `/usr/local/bin`, leaving the image's own Node alone, so it
|
|
1187
|
+
needs root; the environment needs the network to reach nodejs.org and
|
|
1188
|
+
GitHub's release downloads, which the default Limited access allows. The
|
|
1189
|
+
install's own output is dropped. When it fails, the hook's line names its
|
|
1190
|
+
last error line and the user it ran as, and the STOP follows; a clone with
|
|
1191
|
+
no such file says to run `onboard`. On a Mac, or where a CLI is found, the
|
|
1192
|
+
hook does as before.
|
|
1193
|
+
|
|
1194
|
+
What a hook installs is not cached, so each such session downloads about
|
|
1195
|
+
50 MB first. Claude keeps a snapshot of what a Setup script installs, so
|
|
1196
|
+
`niyam cloud-setup` prints an optional snippet that makes sessions start
|
|
1197
|
+
faster: pasted at the top of the environment's Setup script, it finds the
|
|
1198
|
+
clone and runs the same file, with `NIYAM_SETUP` set. It names no version,
|
|
1199
|
+
so a new release needs no new paste. Its instructions are comment lines at
|
|
1200
|
+
the top of the snippet, on standard output with it, so `niyam cloud-setup
|
|
1201
|
+
| pbcopy` copies them too and nothing is left on standard error. A snippet
|
|
1202
|
+
pasted before 0.6.10 runs `.github/process-rules/cloud-setup.sh` alone,
|
|
1203
|
+
which `onboard` deletes since P-57: delete it, or paste the new snippet
|
|
1204
|
+
over it. The Setup script runs as root from the folder that holds the clone
|
|
1205
|
+
(the VM's home, the clone one folder down), so the snippet looks there and
|
|
1206
|
+
in each home. The Setup field holds one script, so the snippet runs in a
|
|
1207
|
+
shell of its own (`bash <<'NIYAM' … NIYAM`): a failed download, or a clone
|
|
1208
|
+
with no such file, says so on standard error and the commands after it
|
|
1209
|
+
still run. If the repo has its own Setup script, put this first, then the
|
|
1210
|
+
repo's own: a repo's script may end with `exit`, and nothing after that
|
|
1042
1211
|
runs.
|
|
1043
1212
|
|
|
1044
1213
|
Claude keeps a snapshot of the environment once its Setup script has run,
|
|
@@ -1049,8 +1218,9 @@ says so in one line; the session goes on with the new CLI, and the snapshot
|
|
|
1049
1218
|
catches up on its next build. When the repo has no `cloud-setup.sh` while
|
|
1050
1219
|
the workflow pins another release, or the file is not at the workflow's
|
|
1051
1220
|
pin, the line says to run `onboard` again. When the Setup script still
|
|
1052
|
-
installs a release of its own (an older paste), the line also says to
|
|
1053
|
-
the snippet over it
|
|
1221
|
+
installs a release of its own (an older paste), the line also says to
|
|
1222
|
+
delete niyam's part of it or paste the snippet over it. It only warns: the
|
|
1223
|
+
session works on.
|
|
1054
1224
|
|
|
1055
1225
|
claude.ai has one GitHub connection per account, so it is the agent's for
|
|
1056
1226
|
every cloud session that account starts.
|
|
@@ -1064,13 +1234,13 @@ reads, in the same layout and with the same exit codes as on a Mac:
|
|
|
1064
1234
|
◇ This cloud session
|
|
1065
1235
|
✗ .github/niyam/cloud-setup.sh installs 0.5.24, but .github/workflows/niyam.yml pins v0.5.25 → niyam onboard again
|
|
1066
1236
|
✓ niyam 0.5.24 runs here
|
|
1067
|
-
|
|
1237
|
+
✓ the SessionStart hook installs niyam from .github/niyam/cloud-setup.sh when a session has none; the Setup script does not run it, which only makes sessions start slower
|
|
1068
1238
|
│
|
|
1069
1239
|
◇ GitHub — as AGENT
|
|
1070
1240
|
✓ the proxy acts as AGENT, an agent the repo's settings name
|
|
1071
1241
|
✓ session-start gave this session AGENT's identity
|
|
1072
1242
|
│
|
|
1073
|
-
└
|
|
1243
|
+
└ 1 to fix
|
|
1074
1244
|
```
|
|
1075
1245
|
|
|
1076
1246
|
This cloud session checks that `cloud-setup.sh` opens with the comment
|
|
@@ -1078,8 +1248,9 @@ This cloud session checks that `cloud-setup.sh` opens with the comment
|
|
|
1078
1248
|
the workflow's pin (`✗`, fixed by running `onboard` again; a workflow that pins no one version is `▲`), that the CLI running is that
|
|
1079
1249
|
release (`▲`: `session-start` installs it, or `bash
|
|
1080
1250
|
.github/niyam/cloud-setup.sh` does), and that the Setup script
|
|
1081
|
-
runs the repo's file (
|
|
1082
|
-
|
|
1251
|
+
runs the repo's file, naming the file it ran (the mark
|
|
1252
|
+
`/opt/niyam/from-setup` holds its path), or that the SessionStart hook
|
|
1253
|
+
installs it, since the Setup script does not: both are `✓`. GitHub
|
|
1083
1254
|
checks that the account the proxy acts as is one of the settings' agents,
|
|
1084
1255
|
and that `session-start` gave the session that identity (`✗` otherwise:
|
|
1085
1256
|
`gh` and git stay locked out). This repo lists hooks that reach GitHub
|
|
@@ -1158,15 +1329,21 @@ is a slice the owner approves.
|
|
|
1158
1329
|
|
|
1159
1330
|
### Releases and upgrading
|
|
1160
1331
|
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
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
|
|
1164
1337
|
package is on npm as `@veda-hq/niyam`, with provenance, for a repository that
|
|
1165
|
-
pins it as an exact version
|
|
1166
|
-
|
|
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:
|
|
1167
1344
|
|
|
1168
1345
|
```bash
|
|
1169
|
-
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.
|
|
1346
|
+
pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.18/veda-hq-niyam-0.6.18.tgz
|
|
1170
1347
|
```
|
|
1171
1348
|
|
|
1172
1349
|
The package puts one command on `PATH`, `niyam`. Since P-57 a release
|
|
@@ -1182,11 +1359,11 @@ niyam upgrade
|
|
|
1182
1359
|
```
|
|
1183
1360
|
|
|
1184
1361
|
`upgrade` asks GitHub's public releases API for the newest release, with no
|
|
1185
|
-
token and no sign-in, and when it is newer than the CLI running
|
|
1186
|
-
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
|
|
1187
1364
|
runs. On the newest release it says so and installs nothing; it never moves
|
|
1188
1365
|
back to an older one. When GitHub cannot be reached, or a newer release has no
|
|
1189
|
-
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
|
|
1190
1367
|
nothing more. After an install, or when there was nothing to install, it walks
|
|
1191
1368
|
`PATH`, as `type -a niyam` does, reading an empty or relative entry
|
|
1192
1369
|
against the current folder as the shell does. It exits 0 when exactly one
|
|
@@ -1201,7 +1378,10 @@ newest release with the line above. `onboard`, when the repo pins a newer releas
|
|
|
1201
1378
|
CLI running, refuses and says to run `niyam upgrade` first.
|
|
1202
1379
|
|
|
1203
1380
|
`onboard` pins the client's workflow to one version, the release of the CLI
|
|
1204
|
-
that ran it
|
|
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
|
|
1205
1385
|
below it under `with:`, `niyam-ref: vX.Y.Z`, the one input `checks.yml`
|
|
1206
1386
|
declares; GitHub refuses a caller that passes an input the called workflow
|
|
1207
1387
|
does not declare, `process-rules-ref` too since P-57. Every job of
|
|
@@ -1237,6 +1417,39 @@ functions, 90% branches), builds `dist/` and runs it. `pnpm scan:secrets` runs
|
|
|
1237
1417
|
Gitleaks and TruffleHog over the working tree; CI runs both over the whole
|
|
1238
1418
|
history.
|
|
1239
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
|
+
|
|
1240
1453
|
## License
|
|
1241
1454
|
|
|
1242
1455
|
MIT
|
|
@@ -1264,7 +1477,7 @@ What P-57 removed for good, by hand where it is on a machine:
|
|
|
1264
1477
|
`doctor` marks either one still there ▲.
|
|
1265
1478
|
- `niyam onboard` deletes `.github/process-rules/cloud-setup.sh` wherever it
|
|
1266
1479
|
leaves `.github/niyam/cloud-setup.sh`, and writes and runs none under that
|
|
1267
|
-
name; a Setup snippet pasted before 0.6.10 needs the new one pasted once.
|
|
1480
|
+
name; a Setup snippet pasted before 0.6.10 needs the new one pasted once, or, since P-60, deleting.
|
|
1268
1481
|
- `niyam owner-step required-checks` takes each `process-rules / …` check out of
|
|
1269
1482
|
a ruleset: no workflow reports one since P-53, so it would hold every pull
|
|
1270
1483
|
request. The `niyam / …` check of the same job takes its place where the
|
package/dist/agent.js
CHANGED
|
@@ -21,6 +21,10 @@ export const API = GITHUB_API;
|
|
|
21
21
|
const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
|
|
22
22
|
/** The GitHub remotes `repoAt` accepts: HTTPS, scp-like SSH, or SSH URLs, on GitHub's host only. */
|
|
23
23
|
const GITHUB_REMOTE = new RegExp(`^(?:https://(?:[^@/\\s]+@)?${GITHUB_HOST_RE}/|git@${GITHUB_HOST_RE}:|ssh://git@(?:ssh\\.)?${GITHUB_HOST_RE}(?::\\d+)?/)([^/\\s]+/[^/\\s]+?)(?:\\.git)?/?$`);
|
|
24
|
+
/** The owner/name a GitHub remote's url names; undefined for any other url. */
|
|
25
|
+
export function githubSlug(url) {
|
|
26
|
+
return GITHUB_REMOTE.exec(url.trim())?.[1];
|
|
27
|
+
}
|
|
24
28
|
/** The classic-token scopes an agent account needs (docs/decisions.md). */
|
|
25
29
|
export const TOKEN_SCOPES = ['repo', 'workflow', 'read:org', 'project', 'write:ssh_signing_key'];
|
|
26
30
|
/** Broader scopes that include a needed one. */
|
package/dist/as-agent.js
CHANGED
|
@@ -37,32 +37,40 @@ export function asAgentArgs(args) {
|
|
|
37
37
|
* a fallback.
|
|
38
38
|
*/
|
|
39
39
|
export function asAgent(sys, io, parsed) {
|
|
40
|
-
const
|
|
41
|
-
|
|
40
|
+
const env = agentEnv(sys, parsed.sessionId);
|
|
41
|
+
if ('problem' in env) {
|
|
42
|
+
io.err(refusal(env.problem));
|
|
42
43
|
return LOCKED;
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
}
|
|
45
|
+
const result = sys.exec(parsed.command, parsed.args, { env: env.env, interactive: true });
|
|
46
|
+
// With standard error passed through, what is left is why the command could not start.
|
|
47
|
+
if (result.stderr)
|
|
48
|
+
io.err(`niyam as-agent: ${parsed.command}: ${result.stderr.trim()}`);
|
|
49
|
+
return result.code;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The environment `as-agent` gives its command for the session, with every
|
|
53
|
+
* check it makes: session-start recorded one of the repo settings' agents
|
|
54
|
+
* for this session, and the agent's token is in the store (or, in a cloud
|
|
55
|
+
* session, the proxy's). A hook that reaches GitHub itself, such as
|
|
56
|
+
* pr-autocreate's, takes its token from here.
|
|
57
|
+
*/
|
|
58
|
+
export function agentEnv(sys, sessionId, root) {
|
|
59
|
+
if (!sessionRecord(sys.home, sessionId))
|
|
60
|
+
return { problem: `"${sessionId}" is not a Claude Code session id` };
|
|
61
|
+
const recorded = recordedAgent(sys, sessionId);
|
|
47
62
|
if ('problem' in recorded)
|
|
48
|
-
return
|
|
63
|
+
return recorded;
|
|
49
64
|
let agents;
|
|
50
65
|
try {
|
|
51
|
-
agents = loadSettings(sys, repoRoot(sys)).agents;
|
|
66
|
+
agents = loadSettings(sys, root ?? repoRoot(sys)).agents;
|
|
52
67
|
}
|
|
53
68
|
catch (error) {
|
|
54
|
-
return
|
|
69
|
+
return { problem: message(error) };
|
|
55
70
|
}
|
|
56
71
|
if (!anyLogin(agents, recorded.agent))
|
|
57
|
-
return
|
|
58
|
-
|
|
59
|
-
if ('problem' in env)
|
|
60
|
-
return locked(env.problem);
|
|
61
|
-
const result = sys.exec(parsed.command, parsed.args, { env: env.env, interactive: true });
|
|
62
|
-
// With standard error passed through, what is left is why the command could not start.
|
|
63
|
-
if (result.stderr)
|
|
64
|
-
io.err(`niyam as-agent: ${parsed.command}: ${result.stderr.trim()}`);
|
|
65
|
-
return result.code;
|
|
72
|
+
return { problem: `session-start recorded ${recorded.agent}, and the repo's settings name the agents ${either(agents)}` };
|
|
73
|
+
return sys.env.CLAUDE_CODE_REMOTE === 'true' ? cloudEnv(sys, recorded.agent) : macEnv(sys, recorded.agent);
|
|
66
74
|
}
|
|
67
75
|
/**
|
|
68
76
|
* The agent's variable before P-55, which an older release's shell may still
|
package/dist/board.js
CHANGED
|
@@ -238,19 +238,19 @@ approved) {
|
|
|
238
238
|
if (!done.grouped) {
|
|
239
239
|
for (const line of viewsChecklist(project.url))
|
|
240
240
|
io.out(line);
|
|
241
|
-
byHand.push(`Type
|
|
241
|
+
byHand.push(`Once for the board: at ${project.url}, add the Type column to Needs you, group Work items by Step and Decisions by Decision, and set the Auto-archive items workflow to ${ARCHIVE_FILTER}, which GitHub's API cannot.`);
|
|
242
242
|
}
|
|
243
243
|
else {
|
|
244
244
|
if (reset.includes('Needs you')) {
|
|
245
245
|
// The column list sent could not name Type, so a Type the owner showed may be gone.
|
|
246
246
|
io.out(`Needs you's columns were set through GitHub's API, which cannot see a Type column, so one shown there may be gone; in ${project.url}: ${TYPE_STEP}`);
|
|
247
|
-
byHand.push(`
|
|
247
|
+
byHand.push(`Once for the board: at ${project.url}, add the Type column to Needs you again, which GitHub's API cannot.`);
|
|
248
248
|
}
|
|
249
249
|
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
250
|
}
|
|
251
251
|
if (done.off.length > 0) {
|
|
252
252
|
io.out(`Turn on the workflows ${done.off.join(', ')} in ${project.url} → Workflows (GitHub's API cannot)`);
|
|
253
|
-
byHand.push(`turn on
|
|
253
|
+
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.`);
|
|
254
254
|
}
|
|
255
255
|
return { url: project.url, byHand: [...typesByHand, ...byHand] };
|
|
256
256
|
}
|