@veda-hq/niyam 0.6.16 → 0.6.17

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/dist/run.js CHANGED
@@ -8,6 +8,10 @@ import { guard } from './guard.js';
8
8
  import { issueType } from './issue-types.js';
9
9
  import { prIdentity } from './identity.js';
10
10
  import { machine, machineArgs } from './machine.js';
11
+ import { brief, briefArgs, handoff, handoffArgs } from './handoff.js';
12
+ import { cubicDismiss, dismissArgs } from './cubic-dismiss.js';
13
+ import { keepGoing } from './keep-going.js';
14
+ import { prAutocreate } from './pr-autocreate.js';
11
15
  import { prSignals, signalArgs } from './pr-signals.js';
12
16
  import { reviewsDue } from './reviews.js';
13
17
  import { reviewThread, threadArgs } from './review-thread.js';
@@ -33,7 +37,7 @@ Commands:
33
37
  throwaway gh sign-in. Steps: issue-types <org>;
34
38
  label <owner/repo> <number> <add|remove> <approved|do-not-merge>;
35
39
  required-checks <owner/repo> <ruleset id or name> [--check <name>]…
36
- cloud-setup Print the Setup snippet for a Claude cloud environment, pasted once
40
+ cloud-setup Print an optional Setup snippet that makes Claude cloud sessions start faster
37
41
  session-start Run by a client's SessionStart hook: the agent identity, or GitHub locked out
38
42
  guard Run by a client's PreToolUse hook: gh and git's remote commands only as the agent
39
43
  as-agent --session <session_id> -- <command> [args...]
@@ -59,7 +63,26 @@ Commands:
59
63
  pr-signals <pr> [--ci-only]
60
64
  A pull request's open review threads, failing checks (error lines only) and local
61
65
  review findings, as one JSON list without duplicates; exit 3 merged, 4 closed
62
- help Show this text
66
+ handoff --detect | --record --disposition <own-work|handed-off|carrying|dismissed> --reason <text>
67
+ [--brief #N,...] [--open-brief <draft.md>] | --assert-fresh [--call-site <site>] [--base <ref>]
68
+ The hand-off gate, where .github/niyam.json names "handoff": a push that edits shared
69
+ plumbing, or keeps failing at one stage, needs a declaration first; --assert-fresh
70
+ is the gate, run by the pre-push hook
71
+ brief [--lint] <draft.md>
72
+ Open a hand-off brief draft as a Brief issue, or only check it
73
+ cubic-dismiss (--evidence <proof> | --decision <where the owner chose>)
74
+ ((--title <exact> --reason <why>)... | --from <file.json>) [--context <id>]
75
+ Record a Cubic finding as dismissed, committing the dismiss file alone with its basis
76
+ pr-autocreate claude-hook | spawn-watchers --root <repo> --remote <name>
77
+ | watch --root <repo> --branch <branch> --sha <commit>
78
+ A pushed branch gets its pull request: Claude Code's PostToolUse(Bash) and Stop
79
+ hook, the pre-push hook (git's ref lines on stdin) and the watcher it starts;
80
+ NIYAM_PR_AUTOCREATE=0 on a push opens none. Its own errors exit 0
81
+ keep-going [--stop <why>]
82
+ Claude Code's Stop hook: sends a session back while its branch has commits the base
83
+ lacks and its pull request has not merged, saying what is left ("1 of 5"); --stop
84
+ records why started work stops at this commit. The hook always exits 0
85
+ help Show this text
63
86
  version Print the installed version
64
87
 
65
88
  as-agent's command gets the session's agent identity, stdin, stdout and stderr, and its
@@ -100,17 +123,17 @@ export function proposeArgs(args) {
100
123
  /** Runs one command and returns its exit code: 0 done, 1 failed, 2 bad usage. */
101
124
  export async function run(args, io, sys) {
102
125
  const [command, ...rest] = args;
103
- const allowed = command === 'onboard' || command === 'machine' || command === 'review-thread' || command === 'as-agent' || command === 'propose' || command === 'owner-step' ? Infinity : command === 'pre-push' || command === 'pr-signals' ? 2 : command === 'doctor' ? 1 : 0;
126
+ const allowed = command === 'onboard' || command === 'machine' || command === 'review-thread' || command === 'as-agent' || command === 'propose' || command === 'owner-step' || command === 'handoff' || command === 'brief' || command === 'cubic-dismiss' || command === 'pr-autocreate' || command === 'keep-going' ? Infinity : command === 'pre-push' || command === 'pr-signals' ? 2 : command === 'doctor' ? 1 : 0;
104
127
  const extra = rest[allowed];
105
128
  if (extra !== undefined) {
106
129
  io.err(`niyam: unexpected argument "${extra}"`);
107
130
  io.err(USAGE);
108
131
  return 2;
109
132
  }
110
- if (command === 'onboard' || command === 'machine' || command === 'review-thread' || command === 'as-agent' || command === 'propose' || command === 'owner-step' || command === 'pr-signals') {
133
+ if (command === 'onboard' || command === 'machine' || command === 'review-thread' || command === 'as-agent' || command === 'propose' || command === 'owner-step' || command === 'pr-signals' || command === 'handoff' || command === 'brief' || command === 'cubic-dismiss') {
111
134
  // Their options are checked here, so a bad one is bad usage (exit 2).
112
135
  try {
113
- (command === 'onboard' ? onboardArgs : command === 'machine' ? machineArgs : command === 'as-agent' ? asAgentArgs : command === 'propose' ? proposeArgs : command === 'owner-step' ? ownerStepArgs : command === 'pr-signals' ? signalArgs : threadArgs)(rest);
136
+ (command === 'onboard' ? onboardArgs : command === 'machine' ? machineArgs : command === 'as-agent' ? asAgentArgs : command === 'propose' ? proposeArgs : command === 'owner-step' ? ownerStepArgs : command === 'pr-signals' ? signalArgs : command === 'handoff' ? handoffArgs : command === 'brief' ? briefArgs : command === 'cubic-dismiss' ? dismissArgs : threadArgs)(rest);
114
137
  }
115
138
  catch (error) {
116
139
  io.err(`niyam: ${error instanceof Error ? error.message : String(error)}`);
@@ -144,6 +167,24 @@ export async function run(args, io, sys) {
144
167
  io.err(`niyam guard: refused, because the check failed: ${error instanceof Error ? error.message : String(error)}`);
145
168
  return 2;
146
169
  }
170
+ case 'pr-autocreate':
171
+ // Its own errors never fail a push or hold a session: it says so and exits 0.
172
+ try {
173
+ return await prAutocreate(await sys(), io, rest);
174
+ }
175
+ catch (error) {
176
+ io.err(`pr-autocreate: unexpected error (${error instanceof Error ? error.message : String(error)}); nothing done`);
177
+ return 0;
178
+ }
179
+ case 'keep-going':
180
+ // The hook never holds a session on its own error; only --stop can fail.
181
+ try {
182
+ return await keepGoing(await sys(), io, rest);
183
+ }
184
+ catch (error) {
185
+ io.err(`niyam keep-going: ${error instanceof Error ? error.message : String(error)}`);
186
+ return rest[0] === '--stop' ? 1 : 0;
187
+ }
147
188
  case 'as-agent':
148
189
  // Any failure runs nothing and says so with the locked code, never the command's own.
149
190
  try {
@@ -168,6 +209,9 @@ export async function run(args, io, sys) {
168
209
  case 'propose':
169
210
  case 'review-thread':
170
211
  case 'pr-signals':
212
+ case 'handoff':
213
+ case 'brief':
214
+ case 'cubic-dismiss':
171
215
  case 'upgrade':
172
216
  case 'owner-step':
173
217
  try {
@@ -175,6 +219,12 @@ export async function run(args, io, sys) {
175
219
  return await upgrade(await sys(), io);
176
220
  if (command === 'pr-signals')
177
221
  return await prSignals(await sys(), io, rest);
222
+ if (command === 'handoff')
223
+ return await handoff(await sys(), io, rest);
224
+ if (command === 'brief')
225
+ return await brief(await sys(), io, rest);
226
+ if (command === 'cubic-dismiss')
227
+ return cubicDismiss(await sys(), io, rest);
178
228
  if (command === 'owner-step')
179
229
  return await ownerStep(await sys(), io, rest);
180
230
  if (command === 'review-thread')
@@ -62,7 +62,7 @@ function cloudDrift(sys) {
62
62
  if (scripted === undefined) {
63
63
  if (!pinned || pinned === installed)
64
64
  return undefined;
65
- return `niyam: this cloud session runs niyam ${installed}, but ${workflow} pins v${pinned}, and the repo has no ${CLOUD_SETUP_PATH} to install it from. Run niyam onboard again, which writes it; then paste what niyam cloud-setup prints into the cloud environment's Setup script, once.`;
65
+ return `niyam: this cloud session runs niyam ${installed}, but ${workflow} pins v${pinned}, and the repo has no ${CLOUD_SETUP_PATH} to install it from. Run niyam onboard again, which writes it.`;
66
66
  }
67
67
  if (pinned && pinned !== scripted) {
68
68
  return `niyam: ${script} installs niyam ${scripted}, but ${workflow} pins v${pinned}. Run niyam onboard again, which writes the file at the pin.`;
@@ -72,7 +72,7 @@ function cloudDrift(sys) {
72
72
  const ran = sys.exec('bash', [file], { input: '', timeoutMs: CLOUD_INSTALL_MS });
73
73
  const paste = ranFromSetup(sys)
74
74
  ? ''
75
- : ` The cloud environment's Setup script installs a release of its own: paste what niyam cloud-setup prints over its own part, once, and new releases then need no paste.`;
75
+ : ` The cloud environment's Setup script installs a release of its own: delete niyam's part of it, since sessions install niyam themselves, or paste what niyam cloud-setup prints over it.`;
76
76
  if (ran.code !== 0) {
77
77
  const why = ran.stderr.trim().split('\n').at(-1) || `exit ${ran.code}`;
78
78
  return `niyam: this cloud session runs niyam ${installed}, but ${script} installs ${scripted}, and running it failed (${why}); the session works on with ${installed}.${paste}`;
package/dist/sys.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { spawn, spawnSync } from 'node:child_process';
2
- import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
2
+ import { appendFileSync, chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from 'node:fs';
3
3
  import * as http from 'node:http';
4
4
  import { constants, homedir, tmpdir } from 'node:os';
5
5
  import { join } from 'node:path';
@@ -46,6 +46,49 @@ export function realSys() {
46
46
  list: (path) => (existsSync(path) ? readdirSync(path) : []),
47
47
  tempDir: (prefix) => mkdtempSync(prefix ?? join(tmpdir(), `${CLI}-`)),
48
48
  remove: (path) => rmSync(path, { recursive: true, force: true }),
49
+ claim(path) {
50
+ try {
51
+ closeSync(openSync(path, 'wx'));
52
+ return true;
53
+ }
54
+ catch (error) {
55
+ if (error.code === 'EEXIST')
56
+ return false;
57
+ throw error;
58
+ }
59
+ },
60
+ modified(path) {
61
+ try {
62
+ return statSync(path).mtime;
63
+ }
64
+ catch {
65
+ return undefined;
66
+ }
67
+ },
68
+ replace(path, data) {
69
+ const temp = `${path}.${process.pid}.tmp`;
70
+ const fd = openSync(temp, 'w');
71
+ try {
72
+ writeSync(fd, data);
73
+ fsyncSync(fd);
74
+ }
75
+ finally {
76
+ closeSync(fd);
77
+ }
78
+ renameSync(temp, path);
79
+ },
80
+ detach(command, args, options) {
81
+ const log = openSync(options.log, 'a');
82
+ try {
83
+ const child = spawn(command, args, { cwd: options.cwd, env: options.env ?? process.env, detached: true, stdio: ['ignore', log, log] });
84
+ // A command that cannot start says so later, as an event; it must not end this process.
85
+ child.on('error', () => undefined);
86
+ child.unref();
87
+ }
88
+ finally {
89
+ closeSync(log);
90
+ }
91
+ },
49
92
  async http(url, options = {}) {
50
93
  const method = (options.method ?? 'GET').toUpperCase();
51
94
  // One deadline for the call, a repeat included, so timeoutMs bounds all of it.
package/dist/work.js CHANGED
@@ -5,6 +5,7 @@ import { cloudToken } from './cloud.js';
5
5
  import { MOVED_FILES, ONBOARD_BRANCH, ONBOARD_FILES } from './onboard-pull.js';
6
6
  import { GITHUB_HOST_RE, GITHUB_WEB } from './host.js';
7
7
  import { boardStarted } from './board.js';
8
+ import { gate } from './handoff.js';
8
9
  import { ownersAlone, whyNotCounted } from './edits.js';
9
10
  import { batchAnswers } from './approvals.js';
10
11
  import { PAGE_LINK, askProblem } from './asks.js';
@@ -466,6 +467,9 @@ export async function prePush(sys, io, refLines, url) {
466
467
  io.err(`pre-push: refused; an agent session pushes to GitHub only as ${either(accounts.agents)}`);
467
468
  return 1;
468
469
  }
470
+ // The hand-off gate, where the repository names its plumbing: on its own setting, not a feature.
471
+ if ((await gate(sys, io, undefined)) !== 0)
472
+ return 1;
469
473
  if (!isOn(sys, root, 'work-rules')) {
470
474
  io.err(offLine('pre-push', 'work-rules'));
471
475
  return 0;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veda-hq/niyam",
3
- "version": "0.6.16",
3
+ "version": "0.6.17",
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": {