@veda-hq/niyam 0.7.0 → 0.7.1

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
@@ -157,6 +157,13 @@ In auto mode the classifier refuses those calls unless the repo's
157
157
  `mcp__ccd_pr__get_status` and `mcp__ccd_pr__set_monitor` to its
158
158
  `permissions.allow`, and `doctor` warns under "This repo" (`▲`) about each
159
159
  one an onboarded repo's file lacks. They reach the app only, not GitHub.
160
+ Claude Code applies deny before allow, so where the file's
161
+ `permissions.deny` matches one of the tools (by its name, `mcp__ccd_pr`,
162
+ `mcp__ccd_pr__*` or another glob after `mcp__ccd_pr__`, `mcp__*` or `*`),
163
+ `onboard` adds no rule for it and says so in its plan, and `doctor` marks it
164
+ denied on purpose (`✓`). A group denied whole leaves nothing to fix; in a
165
+ group denied in part, `doctor` still warns (`▲`) about each other rule the
166
+ file lacks.
160
167
 
161
168
  Before each Bash command, the client's PreToolUse hook runs `niyam
162
169
  guard`: a command running `gh` or a git command that reaches a remote (push,
@@ -187,7 +194,10 @@ allows it, so `onboard` adds `mcp__claude-artifacts__publish_version`,
187
194
  `mcp__claude-artifacts__edit_version` to its `permissions.allow` (none
188
195
  where `mcp__claude-artifacts` or `mcp__claude-artifacts__*` allows the whole
189
196
  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
197
+ lacks. A repo that publishes its pages another way may deny the artifacts
198
+ server on purpose. Where the file's `permissions.deny` matches one of the
199
+ three, as for the Auto-fix rules above, `onboard` adds no rule for it and
200
+ its plan says so, and `doctor` marks it denied on purpose (`✓`). A new page is private to its owner; a republish to a page already
191
201
  shared changes what its readers see, with no prompt. A body the guard cannot read in full
192
202
  (a variable, a command substitution other than `cat`) is judged by what it
193
203
  spells out; where that asks the owner, or the body opens with the unknown
@@ -431,7 +441,8 @@ on any platform without a token store, `niyam env` prints the lock alone.
431
441
  `mcp__claude-artifacts__publish_version`, `publish_files` and
432
442
  `edit_version`, which publish the page an ask to the owner links (a
433
443
  rerun adds only the ones missing; a file allowing a whole server gets
434
- none of its rules), and
444
+ none of its rules, and a rule the file's `permissions.deny` overrides is
445
+ left out, the plan saying so), and
435
446
  writes `.github/workflows/niyam.yml`, which calls this repository's
436
447
  shared checks (`.github/workflows/checks.yml`) from two jobs: `niyam`
437
448
  on pull requests and pushes, read-only, and `niyam-weekly` on the
@@ -1652,7 +1663,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
1652
1663
  once; nothing is built on install:
1653
1664
 
1654
1665
  ```bash
1655
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.7.0/veda-hq-niyam-0.7.0.tgz
1666
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.7.1/veda-hq-niyam-0.7.1.tgz
1656
1667
  ```
1657
1668
 
1658
1669
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
package/dist/doctor.js CHANGED
@@ -8,7 +8,7 @@ import { closing, findingLines, heading, painter, tilde } from './layout.js';
8
8
  import { exposure, exposureFindings, movedFindings, readDeclined, setAside } from './lockout.js';
9
9
  import { CLOUD_SETUP_PATH, HOOKS_PATH, SARATHI_PATH } from './onboard-pull.js';
10
10
  import { leftoverDir, leftoverToken } from './machine.js';
11
- import { BOARD_SECRETS, GUARD_COMMAND, HOOK_COMMAND, OLDER_GUARD_COMMANDS, OLDER_HOOK_COMMANDS, missingArtifactRules, missingAutoFixRules, sarathiRunner } from './onboard.js';
11
+ import { BOARD_SECRETS, GUARD_COMMAND, HOOK_COMMAND, OLDER_GUARD_COMMANDS, OLDER_HOOK_COMMANDS, ARTIFACT_RULES, AUTO_FIX_RULES, artifactRuleNeeds, autoFixRuleNeeds, sarathiRunner } from './onboard.js';
12
12
  import { secretNames } from './secrets.js';
13
13
  import { isOrganisation } from './owner-login.js';
14
14
  import { leftBehind } from './owner-step.js';
@@ -264,7 +264,8 @@ function twiceFindings(sys) {
264
264
  * Which of onboard's Auto-fix and artifact rules the repo's
265
265
  * `.claude/settings.json` lacks, so the auto-mode classifier refuses an agent
266
266
  * session turning Auto-fix on, or publishing the page an ask to the owner
267
- * links: checked in an onboarded repo whose file doctor can read.
267
+ * links: checked in an onboarded repo whose file doctor can read. A rule the
268
+ * file's `permissions.deny` overrides is denied on purpose, not missing.
268
269
  */
269
270
  function allowFindings(sys) {
270
271
  let settings;
@@ -279,11 +280,22 @@ function allowFindings(sys) {
279
280
  // Outside a clone, or a file doctor cannot read: onboard says what is wrong with it.
280
281
  return [];
281
282
  }
282
- const missing = missingAutoFixRules(settings);
283
- const unpublished = missingArtifactRules(settings);
284
283
  return [
285
- ...(missing.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${missing.join(', ')}, so agent sessions cannot turn Auto-fix on`, fix: ONBOARD }]),
286
- ...(unpublished.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${unpublished.join(', ')}, so agent sessions cannot publish the page an ask to the owner links`, fix: ONBOARD }]),
284
+ ...groupFindings(autoFixRuleNeeds(settings), AUTO_FIX_RULES, 'agent sessions cannot turn Auto-fix on', 'agent sessions do not turn Auto-fix on'),
285
+ ...groupFindings(artifactRuleNeeds(settings), ARTIFACT_RULES, 'agent sessions cannot publish the page an ask to the owner links', 'agent sessions do not publish pages'),
286
+ ];
287
+ }
288
+ /**
289
+ * One group's findings: ▲ for the rules it lacks, and ✓ for those its deny
290
+ * rules override, which the owner chose and onboard leaves out, so nothing
291
+ * there is to fix. A whole group denied says what sessions then do not do;
292
+ * a part of one names the tools denied, since the others still work.
293
+ */
294
+ function groupFindings(needs, rules, cannot, chosen) {
295
+ const so = needs.denied.length === rules.length ? chosen : `agent sessions do not use ${needs.denied.join(', ')}`;
296
+ return [
297
+ ...(needs.missing.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${needs.missing.join(', ')}, so ${cannot}`, fix: ONBOARD }]),
298
+ ...(needs.denied.length === 0 ? [] : [{ mark: '✓', text: `${HOOKS_PATH} denies ${needs.deniedBy.join(', ')} on purpose, so ${so}` }]),
287
299
  ];
288
300
  }
289
301
  /** Prints the findings, grouped, and closes; exit 1 when any is broken. */
package/dist/onboard.js CHANGED
@@ -225,22 +225,61 @@ export const ARTIFACT_RULES = ['mcp__claude-artifacts__publish_version', 'mcp__c
225
225
  /** The rules that allow every tool of the artifacts server, ARTIFACT_RULES among them. */
226
226
  const ARTIFACT_SERVER_RULES = ['mcp__claude-artifacts', 'mcp__claude-artifacts__*'];
227
227
  /**
228
- * Which of `rules` a settings file's `permissions.allow` lacks, in their
229
- * order: none when it allows the whole server, by one of `server`.
228
+ * Whether deny rule `by` matches MCP tool `tool` of the server named `bare`
229
+ * (`mcp__<server>`), as Claude Code's permissions page says rules match: the
230
+ * tool's own name, the bare server, `*` and `mcp__*` (every tool, every MCP
231
+ * tool), and a glob in the tool name after a literal `mcp__<server>__`, such
232
+ * as `mcp__<server>__*` or `mcp__<server>__publish_*`. A glob in the server's
233
+ * own name the page does not describe, so it matches nothing here.
230
234
  */
231
- function missingRules(settings, rules, server) {
232
- const allow = settings?.permissions?.allow;
233
- if (Array.isArray(allow) && allow.some((rule) => server.includes(rule)))
234
- return [];
235
- return rules.filter((rule) => !Array.isArray(allow) || !allow.includes(rule));
235
+ function deniesTool(by, tool, bare) {
236
+ if (by === tool || by === bare || by === '*' || by === 'mcp__*')
237
+ return true;
238
+ const prefix = `${bare}__`;
239
+ if (!by.startsWith(prefix) || !by.includes('*') || !tool.startsWith(prefix))
240
+ return false;
241
+ const glob = by.slice(prefix.length).split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*');
242
+ return new RegExp(`^${glob}$`).test(tool.slice(prefix.length));
243
+ }
244
+ /**
245
+ * Which of `rules` a settings file lacks, in their order: none lacks when
246
+ * its `permissions.allow` allows the whole server, by one of `server`. Claude
247
+ * Code applies deny before allow, so a rule that `permissions.deny` overrides
248
+ * (`deniesTool`) is denied, not missing: an allow rule for it would do
249
+ * nothing. A deny or allow that is not an array names nothing.
250
+ */
251
+ function ruleNeeds(settings, rules, server) {
252
+ const permissions = settings?.permissions;
253
+ const listed = (value) => (Array.isArray(value) ? value.filter((rule) => typeof rule === 'string') : []);
254
+ const allow = listed(permissions?.allow);
255
+ const deny = listed(permissions?.deny);
256
+ const bare = server[0];
257
+ const deniedBy = deny.filter((by) => rules.some((rule) => deniesTool(by, rule, bare)));
258
+ const denied = rules.filter((rule) => deny.some((by) => deniesTool(by, rule, bare)));
259
+ if (allow.some((rule) => server.includes(rule)))
260
+ return { missing: [], denied, leftOut: [], deniedBy, leftOutBy: [] };
261
+ const lacking = rules.filter((rule) => !allow.includes(rule));
262
+ const leftOut = lacking.filter((rule) => denied.includes(rule));
263
+ const leftOutBy = deniedBy.filter((by) => leftOut.some((rule) => deniesTool(by, rule, bare)));
264
+ return { missing: lacking.filter((rule) => !denied.includes(rule)), denied, leftOut, deniedBy, leftOutBy };
265
+ }
266
+ /** Which of AUTO_FIX_RULES a settings file lacks, and which its deny rules override. */
267
+ export function autoFixRuleNeeds(settings) {
268
+ return ruleNeeds(settings, AUTO_FIX_RULES, PR_SERVER_RULES);
236
269
  }
237
- /** Which of AUTO_FIX_RULES a settings file's `permissions.allow` lacks. */
238
- export function missingAutoFixRules(settings) {
239
- return missingRules(settings, AUTO_FIX_RULES, PR_SERVER_RULES);
270
+ /** Which of ARTIFACT_RULES a settings file lacks, and which its deny rules override. */
271
+ export function artifactRuleNeeds(settings) {
272
+ return ruleNeeds(settings, ARTIFACT_RULES, ARTIFACT_SERVER_RULES);
240
273
  }
241
- /** Which of ARTIFACT_RULES a settings file's `permissions.allow` lacks. */
242
- export function missingArtifactRules(settings) {
243
- return missingRules(settings, ARTIFACT_RULES, ARTIFACT_SERVER_RULES);
274
+ /**
275
+ * What a group's left-out rules come to, in a line for onboard's plan: the
276
+ * group's name when the deny leaves all of it out, else the rules it does.
277
+ * A denied rule the file allows already is not left out, and goes unsaid.
278
+ */
279
+ function deniedLines(needs, rules, group) {
280
+ if (needs.leftOut.length === 0)
281
+ return [];
282
+ return [`${needs.leftOut.length === rules.length ? group : needs.leftOut.join(', ')} left out: ${HOOKS_PATH} denies ${needs.leftOutBy.join(', ')}`];
244
283
  }
245
284
  /** The hook commands older releases wrote, which onboard replaces with this release's. */
246
285
  export const OLDER_HOOK_COMMANDS = [
@@ -833,6 +872,8 @@ function handlersOf(sarathi, event) {
833
872
  * entry an older release wrote swapped where it stands, a missing one added,
834
873
  * the lock's variables set in `env`, and REVIEW_THREAD_RULE, AUTO_FIX_RULES and ARTIFACT_RULES allowed. Every edit is made in the text, so
835
874
  * the rest of the file keeps its layout. Says what changed, for the question.
875
+ * A rule the file's `permissions.deny` overrides is not allowed, since the
876
+ * allow would do nothing; `denied` says which, for the plan, only when any is.
836
877
  *
837
878
  * Where the project keeps `.claude/sarathi.json` (`sarathiBefore`) and the
838
879
  * settings run sarathi for an event, with a matcher that lets niyam's hook
@@ -850,6 +891,7 @@ export function claudeSettings(before, sarathiBefore) {
850
891
  let moved = false;
851
892
  let timed = false;
852
893
  const labels = [];
894
+ const denied = [];
853
895
  const parsed = () => JSON.parse(text);
854
896
  const first = parsed();
855
897
  if (typeof first !== 'object' || first === null || Array.isArray(first))
@@ -985,18 +1027,22 @@ export function claudeSettings(before, sarathiBefore) {
985
1027
  text = appendToArray(text, ['permissions'], 'allow', REVIEW_THREAD_RULE);
986
1028
  changes.push('allow niyam review-thread without a prompt, so agent sessions answer review threads on their own pull requests');
987
1029
  }
988
- const lacking = missingAutoFixRules(parsed());
1030
+ const autoFix = autoFixRuleNeeds(parsed());
1031
+ const lacking = autoFix.missing;
989
1032
  for (const rule of lacking)
990
1033
  text = appendToArray(text, ['permissions'], 'allow', rule);
991
1034
  if (lacking.length > 0) {
992
1035
  changes.push(`allow ${lacking.join(', ')} without a prompt, so agent sessions turn Auto-fix on for their own pull requests`);
993
1036
  }
994
- const unpublished = missingArtifactRules(parsed());
1037
+ const artifacts = artifactRuleNeeds(parsed());
1038
+ const unpublished = artifacts.missing;
995
1039
  for (const rule of unpublished)
996
1040
  text = appendToArray(text, ['permissions'], 'allow', rule);
997
1041
  if (unpublished.length > 0) {
998
1042
  changes.push(`allow ${unpublished.join(', ')} without a prompt, so agent sessions publish the page an ask to the owner links`);
999
1043
  }
1044
+ // A rule the file denies is the owner's choice: an allow rule for it would do nothing, so the plan says so instead.
1045
+ denied.push(...deniedLines(autoFix, AUTO_FIX_RULES, 'Auto-fix rules'), ...deniedLines(artifacts, ARTIFACT_RULES, 'artifact rules'));
1000
1046
  // One group's own word, or one word for several, so the plan's line stays short.
1001
1047
  const groups = [review || renamed.replaced > 0 ? 'review rule' : '', lacking.length > 0 ? 'Auto-fix rules' : '', unpublished.length > 0 ? 'artifact rules' : ''].filter(Boolean);
1002
1048
  if (groups.length > 0)
@@ -1005,14 +1051,15 @@ export function claudeSettings(before, sarathiBefore) {
1005
1051
  catch (error) {
1006
1052
  throw new Error(`${HOOKS_PATH}: ${error.message}`);
1007
1053
  }
1054
+ const said = denied.length > 0 ? { denied } : {};
1008
1055
  if (sarathi !== undefined && sarathi.changes.length > 0) {
1009
1056
  if (handlersChanged)
1010
1057
  sarathi.labels.push(`hooks ${handlersChanged}`);
1011
1058
  if (handlersTimed)
1012
1059
  sarathi.labels.push('timeout');
1013
- return { text, changes, labels, sarathi };
1060
+ return { text, changes, labels, ...said, sarathi };
1014
1061
  }
1015
- return { text, changes, labels };
1062
+ return { text, changes, labels, ...said };
1016
1063
  }
1017
1064
  /** Who the run's sign-in is, the owner's likely login; undefined when it failed. */
1018
1065
  async function signedInLogin(signIn) {
@@ -1370,6 +1417,7 @@ export async function onboard(sys, io, args = []) {
1370
1417
  const existing = fileAt(HOOKS_PATH);
1371
1418
  // Worked out before the plan, so a file onboard cannot edit is refused before any question.
1372
1419
  const claude = claudeSettings(existing, fileAt(SARATHI_PATH));
1420
+ warnings.push(...(claude.denied ?? []));
1373
1421
  if (claude.changes.length > 0) {
1374
1422
  pull.push({ label: 'settings.json', detail: existing === undefined ? 'new' : claude.labels.join(', ') });
1375
1423
  change(HOOKS_PATH, claude.text, claude.changes.join('; '));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veda-hq/niyam",
3
- "version": "0.7.0",
3
+ "version": "0.7.1",
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": {