@holmes-lab/holmes-kit 0.40.0 → 0.41.0

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.
Files changed (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-794.57, A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9, A-SPEC-794.42, A-SPEC-794.43, A-SPEC-794.45, A-SPEC-794.50
2
+ // @implements A-SPEC-794.83, A-SPEC-794.57, A-SPEC-777, A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781.1, A-SPEC-778.2, A-SPEC-790.3, A-SPEC-476.4, A-SPEC-792.1, A-SPEC-792.8, A-SPEC-792.9, A-SPEC-794.42, A-SPEC-794.43, A-SPEC-794.45, A-SPEC-794.50
3
3
  /**
4
4
  * @implements A-SPEC-777 — a refusal's kind, readable by a program. An orchestrator retries a `retryable` refusal,
5
5
  * pauses for a person on `needs_hitl`, and changes its plan on `permanent`. The prose stays for people; the line
@@ -49,6 +49,13 @@ exports.REFUSAL_CODES = [
49
49
  remediation: ['do not run this from the session — approval_ask cannot grant it', 'tell the person: recovering the spend lock is their act, outside any agent session'],
50
50
  test: /holmes-kit lock recover retires a lock|this command names holmes-kit lock recover/i,
51
51
  },
52
+ {
53
+ // @implements A-SPEC-794.83 — an autonomy command with an approval set in the command: nothing is filed, so no grant
54
+ // opens it; the same command without the variable files its own request
55
+ code: 'profile.own-request', class: 'permanent',
56
+ remediation: ['run the same autonomy command without setting the approval variable — it files its own request', 'call approval_ask with the id that request prints; the person decides in the session form'],
57
+ test: /runs an autonomy command with an out-of-band approval set in the command|is issued only through its own request/i,
58
+ },
52
59
  {
53
60
  // @implements A-SPEC-245.24 (item 1) — the pre-edit impact evidence gate under `block`: the analysis that backs an
54
61
  // edit is missing or does not cover it, so the plan changes (analyse, then edit), not the timing
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The refusal templates: each refusal text the gate writes, named by its own words — never by the paths, ids or values
3
+ * it carries. A gate-deny record stores `tpl:<id>` beside `code:<code>`, so a report keys a denial by (code, template)
4
+ * and a path inside the prose can never make a new key. Ordered, first match wins (a specific template before a general
5
+ * one); an unknown text is `unclassified`. The census in refusal-templates.test.ts maps every summary of the frozen
6
+ * corpus of 2026-11-09 to a named template. Pure: no I/O.
7
+ */
8
+ export interface RefusalTemplate {
9
+ id: string;
10
+ test: RegExp;
11
+ }
12
+ export declare const UNCLASSIFIED_TEMPLATE = "unclassified";
13
+ export declare const REFUSAL_TEMPLATES: readonly RefusalTemplate[];
14
+ /** The template a refusal text was written from, or `unclassified`. */
15
+ export declare function refusalTemplate(reason: string): string;
@@ -0,0 +1,71 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.REFUSAL_TEMPLATES = exports.UNCLASSIFIED_TEMPLATE = void 0;
4
+ exports.refusalTemplate = refusalTemplate;
5
+ exports.UNCLASSIFIED_TEMPLATE = 'unclassified';
6
+ exports.REFUSAL_TEMPLATES = [
7
+ // the reason after the spec-staging lead ("staging spec files is a person's decision … the gate's reading: X")
8
+ // is matched by the rows below; the lead itself is a route, so it has no row of its own until the end
9
+ { id: 'tspec-missing', test: /를 depends_on에 담은 T-SPEC이 없습니다/ },
10
+ { id: 'tspec-unapproved', test: /를 시험한다고 선언했으나 approved가 아닙니다/ },
11
+ { id: 'aspec-no-tspec', test: /의 approved T-SPEC이 없습니다/ },
12
+ { id: 'target-spec-unapproved', test: /Target specification .* is not approved/ },
13
+ { id: 'aspec-unapproved-ko', test: /구현 대상 A-SPEC.*approved가 아닙니다/ },
14
+ { id: 'claimed-spec-unapproved', test: /새로 주장하는 .*approved가 아닙니다/ },
15
+ { id: 'spec-sealed', test: /Approved Specification Modification Restricted/ },
16
+ { id: 'sealed-edit', test: /editing an already-approved spec breaks its content seal/ },
17
+ { id: 'spec-self-approve', test: /a spec cannot self-approve/ },
18
+ { id: 'integrity-config', test: /Direct Modification of .* Restricted/ },
19
+ { id: 'anchor-scope', test: /is anchored to \S+ but falls outside its 'Files to Touch' scope/ },
20
+ { id: 'wiring-gate', test: /is the wiring that loads this session.s gate/ },
21
+ { id: 'hook-config', test: /is a hook\/approval config|훅·승인 설정입니다|shell write to hook\/approval config|writing hook\/approval config/ },
22
+ { id: 'governance-state', test: /is this project.s governance state/ },
23
+ { id: 'constitution-debt', test: /constitution-debt outstanding/ },
24
+ { id: 'edit-target-unreadable', test: /cannot read the edit target path|편집 대상 경로를 읽을 수 없어/ },
25
+ { id: 'env-dump', test: /reads or dumps process environment/ },
26
+ { id: 'secret-env', test: /dumps out-of-band secret env/ },
27
+ { id: 'authority-config', test: /accesses Holmes authority or semantic-egress configuration/ },
28
+ { id: 'role-bypass', test: /HOLMES_ROLE\/HOLMES_GATE_BYPASS/ },
29
+ { id: 'agent-launch-gate-off', test: /launches an agent CLI with a setting that can switch its gate off/ },
30
+ { id: 'agent-launch', test: /launches an agent CLI/ },
31
+ { id: 'mcp-server-start', test: /starts the Holmes MCP server/ },
32
+ { id: 'lock-recover', test: /holmes-kit lock recover/ },
33
+ { id: 'profile-own-request', test: /runs an autonomy command with an out-of-band approval set in the command|is issued only through its own request/ }, // A-SPEC-794.83
34
+ { id: 'runtime-binding', test: /runtime-binding setup\/remove changes which Holmes build governs/ },
35
+ { id: 'push-spec-unstaged', test: /push refused: changes to the governance store.s specs/ },
36
+ { id: 'risk-classification-failed', test: /risk classification failed on a shell command/ },
37
+ { id: 'shell-code-write', test: /shell write to a project code file bypasses the No-Spec-No-Code gate/ },
38
+ { id: 'shell-write-unlocatable', test: /shell write to a relative path cannot be located/ },
39
+ { id: 'grant-consumed', test: /single-use approval already consumed/ },
40
+ { id: 'patch-unjudged', test: /mentions the patch tool or a patch marker/ },
41
+ { id: 'powershell-unjudgeable', test: /a PowerShell command that cannot be judged/ },
42
+ { id: 'hitl-powershell-remove', test: /PowerShell Remove-Item -Recurse\/-Force/ },
43
+ { id: 'hitl-push-publish', test: /a push or a publish is irreversible and outward/ },
44
+ { id: 'hitl-ddl', test: /hard-hitl risk: destructive DDL/ },
45
+ { id: 'hitl-ax-oneliner', test: /interpreter one-liner names a protected \.ax governance path/ },
46
+ { id: 'hitl-ax-redirect', test: /output redirection writes into a protected \.ax governance path/ },
47
+ { id: 'hitl-ax-file-write', test: /file-writing command .* targets a protected \.ax governance path/ },
48
+ { id: 'hitl-ax-remove', test: /removal(?:, move or copy)? command targets a protected \.ax governance path/ },
49
+ { id: 'hitl-ax-staging-unnamed', test: /staging command reaches changed files in the protected \.ax spec store without naming it/ },
50
+ { id: 'hitl-ax-not-readonly', test: /shell command over a protected \.ax governance path is not recognisably read-only/ },
51
+ { id: 'hitl-find-delete', test: /find -delete irreversibly removes/ },
52
+ { id: 'hitl-branch-force-delete', test: /git branch -D force-deletes/ },
53
+ { id: 'hitl-git-config', test: /git config changes what git runs/ },
54
+ { id: 'hitl-force-push', test: /git push --force\/-f rewrites remote history/ },
55
+ { id: 'hitl-reset-hard', test: /git reset --hard discards uncommitted work/ },
56
+ { id: 'hitl-mkfs', test: /mkfs formats a filesystem/ },
57
+ { id: 'hitl-pipe-shell', test: /pipe-to-shell executes remote code/ },
58
+ { id: 'hitl-rm-recursive', test: /recursive rm of a catastrophic/ },
59
+ { id: 'hitl-rm-glob', test: /rm of a whole-scope glob or root\/home target/ },
60
+ { id: 'hitl-shred', test: /shred irreversibly destroys/ },
61
+ { id: 'hitl-truncate', test: /truncate -s 0 irreversibly zeroes/ },
62
+ { id: 'spec-staging-person', test: /staging spec files is a person.s decision/ },
63
+ ];
64
+ /** The template a refusal text was written from, or `unclassified`. */
65
+ function refusalTemplate(reason) {
66
+ const text = typeof reason === 'string' ? reason.replace(/’/g, "'") : '';
67
+ for (const t of exports.REFUSAL_TEMPLATES)
68
+ if (t.test.test(text))
69
+ return t.id;
70
+ return exports.UNCLASSIFIED_TEMPLATE;
71
+ }
@@ -36,14 +36,36 @@ export declare function splitShellClauses(cmd: string): string[];
36
36
  /**
37
37
  * @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
38
38
  * escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
39
+ * A-SPEC-794.70: the shell lexer's raw split, which also ends a clause at a lone `&` and at `|&`.
39
40
  */
40
41
  export declare function splitUnquoted(cmd: string, atPipe?: boolean): string[] | null;
42
+ export interface Program {
43
+ name: string;
44
+ args: string[];
45
+ word: string;
46
+ unknown?: true;
47
+ }
48
+ /**
49
+ * The program a clause's words run, behind assignments, redirects and wrappers, with its arguments.
50
+ *
51
+ * @implements A-SPEC-728 (rule 34) — leading redirects (`2>/dev/null rm …` read the program as `null`), zsh precommands, a
52
+ * `case` arm's pattern, sudo's long valued options, `exec -a`, `env -S` (the command it holds) and `pnpm`/`yarn dlx|exec`;
53
+ * there is no word cap (a 64-word cap returned the 65th wrapper as the program — measured).
54
+ */
55
+ export declare function programOf(input: readonly string[]): Program | null;
56
+ /** Words of one clause with shell quotes removed (single, double, backslash). Nothing is expanded. */
57
+ export declare function clauseWords(clause: string): string[];
41
58
  /**
42
59
  * @implements A-SPEC-728.2 — the classifier's own read judgement of a whole shell text, loops included, for the identity
43
60
  * layer: a `for` loop whose body only reads its variable's files names no mutation target with its word list.
44
61
  */
45
62
  export declare function shellTextOnlyReads(text: string): boolean;
46
63
  export declare function stripCommitMessages(cmd: string): string;
64
+ /**
65
+ * @implements A-SPEC-792.13 — the clause as git sees it: `env` (its assignments and options), `command`, `builtin`,
66
+ * `exec`, `nohup`, `nice` and `time` taken off the front, and an absolute path to git read as `git`.
67
+ */
68
+ export declare function unwrapGitWords(words: string[]): string[];
47
69
  export declare function classifyReversibility(action: RiskAction): AxisVerdict;
48
70
  /**
49
71
  * The execution-surface key a `git config` in this command writes, `'--edit'` for an edit, or null. Every segment is
@@ -73,9 +95,3 @@ export declare function classifyBlastRadius(action: RiskAction, cfg?: RiskThresh
73
95
  * Pure function: no I/O, no clocks, no randomness — same input always yields the same output.
74
96
  */
75
97
  export declare function assessRisk(action: RiskAction, cfg?: RiskThresholds): RiskAssessment;
76
- /**
77
- * @implements A-SPEC-794.49, A-SPEC-794.50 — the outward acts a clause of this command runs, read with the readers above.
78
- * A comment or a here-document body is no clause, a control or grouping word is not the command, and a form with no
79
- * outward effect is no act. A runner's inner program, a substitution and a package script are not read.
80
- */
81
- export declare function outwardActsOf(command: string): Array<'push' | 'publish'>;
@@ -41,21 +41,23 @@ exports.verbWordRe = verbWordRe;
41
41
  exports.plainShellText = plainShellText;
42
42
  exports.splitShellClauses = splitShellClauses;
43
43
  exports.splitUnquoted = splitUnquoted;
44
+ exports.programOf = programOf;
45
+ exports.clauseWords = clauseWords;
44
46
  exports.shellTextOnlyReads = shellTextOnlyReads;
45
47
  exports.stripCommitMessages = stripCommitMessages;
48
+ exports.unwrapGitWords = unwrapGitWords;
46
49
  exports.classifyReversibility = classifyReversibility;
47
50
  exports.gitConfigExecWrite = gitConfigExecWrite;
48
51
  exports.classifyArchitectureReversal = classifyArchitectureReversal;
49
52
  exports.classifySecret = classifySecret;
50
53
  exports.classifyBlastRadius = classifyBlastRadius;
51
54
  exports.assessRisk = assessRisk;
52
- exports.outwardActsOf = outwardActsOf;
53
- // @implements A-SPEC-794.54, A-SPEC-794.52, A-SPEC-794.51, A-SPEC-794.50, A-SPEC-794.49, A-SPEC-794.45, A-SPEC-794.42, A-SPEC-794.40, A-SPEC-794.37, A-SPEC-794.35, A-SPEC-794.34, A-SPEC-794.33, A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5, A-SPEC-222.12
55
+ // @implements A-SPEC-794.70, A-SPEC-794.69, A-SPEC-794.68, A-SPEC-794.66, A-SPEC-794.65, A-SPEC-794.54, A-SPEC-794.52, A-SPEC-794.51, A-SPEC-794.50, A-SPEC-794.49, A-SPEC-794.45, A-SPEC-794.42, A-SPEC-794.40, A-SPEC-794.37, A-SPEC-794.35, A-SPEC-794.34, A-SPEC-794.33, A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5, A-SPEC-222.12
54
56
  const fs = __importStar(require("node:fs"));
55
57
  const path = __importStar(require("node:path"));
56
58
  const shell_argument_roles_1 = require("./shell-argument-roles");
57
59
  const write_target_1 = require("./write-target");
58
- const line_continuation_1 = require("./line-continuation");
60
+ const shell_lexer_1 = require("./shell-lexer");
59
61
  const unresolved_write_1 = require("./unresolved-write");
60
62
  const risk_types_1 = require("./risk-types");
61
63
  const linear_match_1 = require("./linear-match");
@@ -790,7 +792,7 @@ function splitShellClauses(cmd) {
790
792
  // @implements A-SPEC-747 — operators inside quotes or a substitution are text, not separators: `grep "a\|b" F`
791
793
  // was judged as the clause `b" F`, which is no known read (17 of 28 measured reads refused). An unclosed quote
792
794
  // keeps the quote-blind split — when the reader is unsure it cuts more, never less.
793
- const pieces = splitUnquoted(cmd) ?? cmd.split(/\|\||&&|;|\||\n/);
795
+ const pieces = splitUnquoted(cmd) ?? cmd.split(/\|\||&&|;|\||\n|(?<![<>&])&(?![&>])/);
794
796
  return pieces
795
797
  .map((c) => c.replace(/^[\s(]+/, '').trim())
796
798
  .filter((c) => c.length > 0);
@@ -798,83 +800,10 @@ function splitShellClauses(cmd) {
798
800
  /**
799
801
  * @implements A-SPEC-747 — split at `||`, `&&`, `;`, `|` and newline outside single quotes, double quotes, a backslash
800
802
  * escape, `$(…)`, `<(…)`, `>(…)` and backticks. `null` when a quote or substitution is left open.
803
+ * A-SPEC-794.70: the shell lexer's raw split, which also ends a clause at a lone `&` and at `|&`.
801
804
  */
802
805
  function splitUnquoted(cmd, atPipe = true) {
803
- const out = [];
804
- let cur = '';
805
- let quote = null;
806
- let depth = 0;
807
- let tick = false;
808
- for (let i = 0; i < cmd.length; i++) {
809
- const ch = cmd[i];
810
- if (quote === "'") {
811
- cur += ch;
812
- if (ch === "'")
813
- quote = null;
814
- continue;
815
- }
816
- if (ch === '\\' && i + 1 < cmd.length) {
817
- cur += ch + cmd[i + 1];
818
- i++;
819
- continue;
820
- }
821
- if (ch === '`') {
822
- tick = !tick;
823
- cur += ch;
824
- continue;
825
- }
826
- if ((ch === '$' || ch === '<' || ch === '>') && cmd[i + 1] === '(') {
827
- depth++;
828
- cur += ch + '(';
829
- i++;
830
- continue;
831
- }
832
- if (depth > 0 && ch === ')') {
833
- depth--;
834
- cur += ch;
835
- continue;
836
- }
837
- if (quote === '"') {
838
- cur += ch;
839
- if (ch === '"')
840
- quote = null;
841
- continue;
842
- }
843
- if (ch === '"' || ch === "'") {
844
- quote = ch;
845
- cur += ch;
846
- continue;
847
- }
848
- if (depth === 0 && !tick) {
849
- if (ch === '\n' || ch === ';') {
850
- out.push(cur);
851
- cur = '';
852
- continue;
853
- }
854
- if (ch === '|' && cmd[i + 1] === '|') {
855
- i++;
856
- out.push(cur);
857
- cur = '';
858
- continue;
859
- }
860
- if (ch === '|' && atPipe) {
861
- out.push(cur);
862
- cur = '';
863
- continue;
864
- }
865
- if (ch === '&' && cmd[i + 1] === '&') {
866
- i++;
867
- out.push(cur);
868
- cur = '';
869
- continue;
870
- }
871
- }
872
- cur += ch;
873
- }
874
- if (quote !== null || depth !== 0 || tick)
875
- return null;
876
- out.push(cur);
877
- return out;
806
+ return (0, shell_lexer_1.splitRawClauses)(cmd, atPipe);
878
807
  }
879
808
  /** @implements A-SPEC-747 — how deep command substitutions are followed before a clause stops counting as a read. */
880
809
  const MAX_SUBSTITUTION_DEPTH = 4;
@@ -2195,43 +2124,8 @@ function assessRisk(action, cfg) {
2195
2124
  const reasons = verdicts.filter((v) => v.level !== 'auto').flatMap((v) => v.reasons);
2196
2125
  return { level, verdicts, reasons };
2197
2126
  }
2198
- /** The options before a subcommand that take the next word as their value. */
2199
- const OPTION_TAKES_VALUE = {
2200
- git: new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace']),
2201
- npm: new Set(['--prefix', '-w', '--workspace', '--tag', '--registry']),
2202
- };
2203
- /** The options after the subcommand under which nothing leaves the machine. */
2204
- const NO_OUTWARD_EFFECT = {
2205
- git: new Set(['--help', '-h', '--dry-run', '-n']),
2206
- npm: new Set(['--help', '-h', '--dry-run']),
2207
- };
2208
- /**
2209
- * @implements A-SPEC-794.49, A-SPEC-794.50 — the outward acts a clause of this command runs, read with the readers above.
2210
- * A comment or a here-document body is no clause, a control or grouping word is not the command, and a form with no
2211
- * outward effect is no act. A runner's inner program, a substitution and a package script are not read.
2127
+ /*
2128
+ * A-SPEC-794.69 — the outward judgement (push and publish under a full profile's flags: A-SPEC-794.49–794.54,
2129
+ * 794.65, 794.66, 794.68, 794.69) lives in outward-acts.ts. This module exports the shared readers it uses:
2130
+ * programOf, clauseWords and unwrapGitWords.
2212
2131
  */
2213
- function outwardActsOf(command) {
2214
- const acts = new Set();
2215
- // A-SPEC-794.51, A-SPEC-794.52 — a line continuation vanishes in the shell, so it vanishes here, before any reader sees it
2216
- // A-SPEC-794.54 — a command the comment and body reader cannot finish is read whole
2217
- for (const clause of splitShellClauses((0, line_continuation_1.joinLineContinuations)((0, unresolved_write_1.readableText)(command)))) {
2218
- let words = clauseWords(clause).map((w) => w.replace(/^\(+|\)+$/g, '')).filter(Boolean);
2219
- while (words.length > 0 && (unresolved_write_1.KEYWORD.test(words[0]) || /^[A-Za-z_]\w*=/.test(words[0])))
2220
- words = words.slice(1);
2221
- words = unwrapGitWords(words);
2222
- const tool = words[0];
2223
- if (tool !== 'git' && tool !== 'npm')
2224
- continue;
2225
- let i = 1;
2226
- while ((words[i] ?? '').startsWith('-'))
2227
- i += OPTION_TAKES_VALUE[tool].has(words[i]) ? 2 : 1;
2228
- if (words[i] !== (tool === 'git' ? 'push' : 'publish'))
2229
- continue;
2230
- const rest = words.slice(i + 1);
2231
- const end = rest.indexOf('--');
2232
- if (rest.slice(0, end < 0 ? rest.length : end).some((w) => NO_OUTWARD_EFFECT[tool].has(w)))
2233
- continue;
2234
- acts.add(tool === 'git' ? 'push' : 'publish');
2235
- }
2236
- return [...acts];
2237
- }
@@ -0,0 +1,69 @@
1
+ /**
2
+ * One shell lexer (A-SPEC-794.70). It reads a command the way a POSIX shell (and bash/zsh, for the forms listed) splits
3
+ * it, without running anything:
4
+ * - clauses at `;`, newline, `&`, `&&`, `||`, `|`, `|&` (an `&` in `&>`, `>&`, `<&`, `2>&1` is a redirect);
5
+ * - words with their value after quote removal; inside double quotes an apostrophe is a character and `$(…)` and
6
+ * backticks still run;
7
+ * - substitutions `$(…)`, backticks, `<(…)` and `>(…)` as body texts, a here-document's body read from the lines after
8
+ * its operator (also inside `$(…)`), here-strings, and subshell groups `( … )`.
9
+ * Redirect operators are read only at an operator position: `->` inside a word is a word.
10
+ * `splitRawClauses` is the former `splitUnquoted` of risk-classifier (a line view of the command, here-document lines
11
+ * included, which the destructive-act readers judge conservatively), with `&` and `|&` added.
12
+ */
13
+ export interface ShellWord {
14
+ value: string;
15
+ raw: string;
16
+ literal: boolean;
17
+ }
18
+ export interface ShellRedirect {
19
+ op: string;
20
+ target: ShellWord | null;
21
+ }
22
+ export interface ShellHeredoc {
23
+ body: string;
24
+ quoted: boolean;
25
+ hereString: boolean;
26
+ }
27
+ export interface ShellSubstitution {
28
+ kind: '$(' | '`' | '<(' | '>(';
29
+ body: string;
30
+ }
31
+ export interface ShellClause {
32
+ words: ShellWord[];
33
+ redirects: ShellRedirect[];
34
+ heredocs: ShellHeredoc[];
35
+ substitutions: ShellSubstitution[];
36
+ /** The subshell groups this clause is inside, outermost first. */
37
+ groups: number[];
38
+ /** The separator after it ('' at the end). */
39
+ sep: string;
40
+ /** The index of the clause whose output is piped into this one. */
41
+ pipedFrom: number | null;
42
+ /** The clause's own text (here-document bodies not included). */
43
+ source: string;
44
+ }
45
+ export declare function lexShell(text: string): {
46
+ clauses: ShellClause[];
47
+ ok: boolean;
48
+ tooDeep?: boolean;
49
+ };
50
+ /** The command substitutions an unquoted here-document's body runs. */
51
+ export declare function heredocExpansions(body: string): string[];
52
+ /**
53
+ * @implements A-SPEC-794.92 — the substitutions an unquoted here-document runs, and whether every one was read: a
54
+ * substitution the lexer could not read ends the scan, and the rest of the body is unread (the caller closes it).
55
+ */
56
+ export declare function heredocExpansionsRead(body: string): {
57
+ bodies: string[];
58
+ ok: boolean;
59
+ tooDeep: boolean;
60
+ };
61
+ /** True when a word's value holds a substitution. */
62
+ export declare const holdsSubstitution: (v: string) => boolean;
63
+ /** The value a word holds where a substitution was (for display: removed). */
64
+ export declare const shownValue: (v: string) => string;
65
+ /**
66
+ * The raw text pieces between top-level separators; null for an unclosed quote, substitution or backtick. `atPipe`
67
+ * false keeps a pipeline whole (A-SPEC-747.3). Here-document lines are pieces (the line view).
68
+ */
69
+ export declare function splitRawClauses(cmd: string, atPipe?: boolean): string[] | null;