vouchington-tooling 0.55.0 → 0.56.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 (30) hide show
  1. package/dist/gh-api-shell-quoting/logical-line.mjs +14 -74
  2. package/dist/mcp-server/policy-run.d.mts +2 -0
  3. package/dist/mcp-server/policy-run.mjs +6 -2
  4. package/dist/mcp-server/policy-spawn.d.mts +1 -0
  5. package/dist/mcp-server/policy-spawn.mjs +10 -2
  6. package/dist/retrospective-transcript/codex-records.mjs +4 -0
  7. package/dist/retrospective-transcript/command-prefix.d.mts +1 -0
  8. package/dist/retrospective-transcript/command-prefix.mjs +1 -1
  9. package/dist/retrospective-transcript/command-segments.d.mts +1 -1
  10. package/dist/retrospective-transcript/command-segments.mjs +3 -48
  11. package/dist/retrospective-transcript/escalations.d.mts +6 -0
  12. package/dist/retrospective-transcript/escalations.mjs +34 -0
  13. package/dist/retrospective-transcript/format.mjs +13 -0
  14. package/dist/retrospective-transcript/index.mjs +2 -1
  15. package/dist/retrospective-transcript/malformed-record.d.mts +1 -0
  16. package/dist/retrospective-transcript/malformed-record.mjs +13 -0
  17. package/dist/retrospective-transcript/shared.d.mts +2 -1
  18. package/dist/retrospective-transcript/shared.mjs +1 -12
  19. package/dist/shell-parse/index.d.mts +2 -0
  20. package/dist/shell-parse/index.mjs +2 -0
  21. package/dist/shell-parse/shell-command-segments.d.mts +6 -0
  22. package/dist/shell-parse/shell-command-segments.mjs +26 -0
  23. package/dist/shell-parse/shell-tokenizer-operators.d.mts +2 -4
  24. package/dist/shell-parse/shell-tokenizer-operators.mjs +14 -4
  25. package/dist/shell-parse/shell-tokenizer.d.mts +9 -5
  26. package/dist/shell-parse/shell-tokenizer.mjs +5 -1
  27. package/dist/shell-parse/shell-walk.d.mts +8 -0
  28. package/dist/shell-parse/shell-walk.mjs +62 -0
  29. package/package.json +1 -1
  30. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
@@ -1,3 +1,4 @@
1
+ import { walkUnquotedShell } from "../shell-parse/index.mjs";
1
2
  import { consumeArgumentCharacter } from "./argument-scan.mjs";
2
3
  const GH_API_BOUNDARY = /[\s;|&(){}]/;
3
4
  const GH_API_HEAD = /^gh[ \t]+api\b/;
@@ -7,84 +8,23 @@ function matchGhApiHead(text, index) {
7
8
  const match = GH_API_HEAD.exec(text.slice(index));
8
9
  return match ? match[0].length : 0;
9
10
  }
10
- function newFrame() {
11
- return { inSingleQuote: false, inDoubleQuote: false, scanningArgs: false, parenDepth: 0 };
12
- }
13
- function pushSubstitutionFrame(stack) {
14
- const frame = newFrame();
15
- frame.parenDepth = 1;
16
- stack.push(frame);
17
- }
18
11
  // Scans one already-joined logical line for `gh api` calls and returns at most one hit per call —
19
12
  // the first unquoted `?` or `&`, whichever comes first. `offsets[k]` maps character k of `text`
20
13
  // back to its absolute offset in the original source, so callers can report real line numbers.
14
+ // Quote, escape, comment, and `$(...)` nesting state comes from `walkUnquotedShell`, which keeps
15
+ // each substitution level independent (`VAR="$(gh api "…?a=1&b=2")"` is a common idiom) and, unlike
16
+ // the shell tokenizer, does not treat a quoted `${VAR}` as making a later `?` unquoted.
21
17
  export function scanLogicalLine(text, offsets) {
22
18
  const hits = [];
23
- const stack = [newFrame()];
24
- let i = 0;
25
- while (i < text.length) {
26
- const frame = stack[stack.length - 1];
27
- const char = text[i];
28
- if (frame.inSingleQuote) {
29
- if (char === "'")
30
- frame.inSingleQuote = false;
31
- i += 1;
32
- continue;
33
- }
34
- if (char === '\\') {
35
- i += 2;
36
- continue;
37
- }
38
- if (frame.inDoubleQuote) {
39
- if (char === '"') {
40
- frame.inDoubleQuote = false;
41
- i += 1;
42
- continue;
43
- }
44
- if (char === '$' && text[i + 1] === '(') {
45
- pushSubstitutionFrame(stack);
46
- i += 2;
47
- continue;
48
- }
49
- i += 1;
50
- continue;
51
- }
52
- if (char === '#' && (i === 0 || /\s/.test(text[i - 1])))
53
- break;
54
- if (char === "'") {
55
- frame.inSingleQuote = true;
56
- i += 1;
57
- continue;
58
- }
59
- if (char === '"') {
60
- frame.inDoubleQuote = true;
61
- i += 1;
62
- continue;
63
- }
64
- if (char === '$' && text[i + 1] === '(') {
65
- pushSubstitutionFrame(stack);
66
- i += 2;
67
- continue;
68
- }
69
- if (stack.length > 1 && (char === '(' || char === ')')) {
70
- frame.parenDepth += char === '(' ? 1 : -1;
71
- i += 1;
72
- if (frame.parenDepth === 0)
73
- stack.pop();
74
- continue;
75
- }
76
- const argumentIndex = consumeArgumentCharacter(text, i, frame, hits, offsets);
77
- if (argumentIndex !== undefined) {
78
- i = argumentIndex;
79
- continue;
80
- }
81
- const headLength = frame.scanningArgs ? 0 : matchGhApiHead(text, i);
82
- if (headLength > 0) {
83
- frame.scanningArgs = true;
84
- i += headLength;
85
- continue;
86
- }
87
- i += 1;
88
- }
19
+ walkUnquotedShell(text, () => ({ scanningArgs: false }), (index, frame) => {
20
+ const argumentIndex = consumeArgumentCharacter(text, index, frame, hits, offsets);
21
+ if (argumentIndex !== undefined)
22
+ return argumentIndex;
23
+ const headLength = frame.scanningArgs ? 0 : matchGhApiHead(text, index);
24
+ if (headLength === 0)
25
+ return undefined;
26
+ frame.scanningArgs = true;
27
+ return index + headLength;
28
+ });
89
29
  return hits;
90
30
  }
@@ -22,6 +22,8 @@ export type PolicyRun = {
22
22
  env: NodeJS.ProcessEnv;
23
23
  /** Test seam: replaces the real child process. */
24
24
  spawn?: PolicySpawner;
25
+ /** Test seam: replaces `process.execPath` as the Node binary to launch. */
26
+ nodePath?: string;
25
27
  };
26
28
  /**
27
29
  * Runs one export of the worktree's declared policy module in a fresh child process (never in
@@ -1,6 +1,7 @@
1
+ import { existsSync } from 'node:fs';
1
2
  import { fileURLToPath } from 'node:url';
2
3
  import { resolvePolicyModule } from "./policy-config.mjs";
3
- import { policyEnvironment, spawnPolicy, } from "./policy-spawn.mjs";
4
+ import { missingNodeError, policyEnvironment, spawnPolicy, } from "./policy-spawn.mjs";
4
5
  /** How long each policy export may run before its process is killed, in milliseconds. */
5
6
  export const POLICY_TIMEOUTS_MS = {
6
7
  validateRetrospective: 30_000,
@@ -83,9 +84,12 @@ async function runUnscrubbed(run, spawn) {
83
84
  const module = await resolvePolicyModule(run.worktree);
84
85
  if (module === undefined)
85
86
  return { status: 'no-policy' };
87
+ const node = run.nodePath ?? process.execPath;
88
+ if (!existsSync(node))
89
+ throw missingNodeError(node);
86
90
  const timeoutMs = POLICY_TIMEOUTS_MS[name];
87
91
  const outcome = await spawn({
88
- command: process.execPath,
92
+ command: node,
89
93
  args: [RUNNER, module],
90
94
  cwd: run.worktree,
91
95
  env: policyEnvironment(run.env),
@@ -16,6 +16,7 @@ export type PolicyOutcome = {
16
16
  overflowed: boolean;
17
17
  };
18
18
  export type PolicySpawner = (request: PolicyRequest) => Promise<PolicyOutcome>;
19
+ export declare function missingNodeError(node: string): Error;
19
20
  /**
20
21
  * The child's whole environment. Blackboard credentials and NODE_OPTIONS are never passed; GitHub
21
22
  * tokens are passed only when the server has them, for the checks that call `gh`.
@@ -1,6 +1,9 @@
1
1
  import { spawn } from 'node:child_process';
2
- import { accessSync, constants } from 'node:fs';
2
+ import { accessSync, constants, existsSync } from 'node:fs';
3
3
  import { delimiter, dirname, join } from 'node:path';
4
+ export function missingNodeError(node) {
5
+ return new Error(`The MCP server's Node binary (${node}) was removed, likely by a Node version upgrade. Reconnect the server: \`/mcp\` in Claude Code, or restart Codex.`);
6
+ }
4
7
  function isExecutable(path) {
5
8
  try {
6
9
  accessSync(path, constants.X_OK);
@@ -79,7 +82,12 @@ export const spawnPolicy = (request) => new Promise((resolve, reject) => {
79
82
  });
80
83
  child.on('error', (error) => {
81
84
  clearTimeout(timer);
82
- reject(error);
85
+ // ENOENT also means a missing cwd, so only a binary that is gone gets the reconnect message.
86
+ reject(error.code === 'ENOENT' &&
87
+ request.command === process.execPath &&
88
+ !existsSync(request.command)
89
+ ? missingNodeError(request.command)
90
+ : error);
83
91
  });
84
92
  // Reap anything the policy left running in its group as soon as the runner exits: a descendant
85
93
  // would otherwise keep the GitHub token it inherited, and one holding an inherited pipe would
@@ -1,4 +1,5 @@
1
1
  import { CodexMessageCounter } from "./codex-messages.mjs";
2
+ import { escalationOf } from "./escalations.mjs";
2
3
  import { commands, hasFailedOutcome } from "./codex-payload.mjs";
3
4
  import { applyCommand, asNumber, asRecord, emptyTokens, } from "./shared.mjs";
4
5
  function usage(record) {
@@ -75,6 +76,9 @@ export function applyRecords(records, facts, subagent, baseline = emptyTokens())
75
76
  calls.add(id);
76
77
  if (payload.name === 'advisor')
77
78
  facts.advisorCalls++;
79
+ const escalation = escalationOf(payload);
80
+ if (escalation)
81
+ facts.escalations.push(escalation);
78
82
  for (const rawCommand of commands(payload))
79
83
  applyCommand(rawCommand, facts);
80
84
  }
@@ -1 +1,2 @@
1
+ export declare function redactOverlongToken(token: string): string;
1
2
  export declare function normalizeCommandPrefix(command: string): string;
@@ -11,7 +11,7 @@ import { isPackageRunner, splitCommandSegments } from "./command-segments.mjs";
11
11
  // for a privacy boundary, over-redacting a legitimate token is the safe failure mode.
12
12
  const MAX_COMMAND_TOKEN_LENGTH = 40;
13
13
  const REDACTED_TOKEN = '…';
14
- function redactOverlongToken(token) {
14
+ export function redactOverlongToken(token) {
15
15
  return token.length > MAX_COMMAND_TOKEN_LENGTH ? REDACTED_TOKEN : token;
16
16
  }
17
17
  const ENV_ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
@@ -1,2 +1,2 @@
1
- export declare function splitCommandSegments(command: string): string[][];
1
+ export { splitCommandSegments } from '../shell-parse/index.mts';
2
2
  export declare function isPackageRunner(word: string | undefined): boolean;
@@ -1,51 +1,6 @@
1
- // Commands are matched by command position, not by scanning for words anywhere in
2
- // the string. The string is split into segments on unquoted `;`, `&`, `|` and
3
- // newlines (so `git push;gh pr view` splits even with no surrounding whitespace).
4
- // Quoted spans, including any whitespace inside them, are grouped into a single
5
- // word, mirroring real shell tokenization.
6
- export function splitCommandSegments(command) {
7
- const segments = [];
8
- let current = [];
9
- let word = '';
10
- let quote = null;
11
- const flushWord = () => {
12
- if (word) {
13
- current.push(word);
14
- word = '';
15
- }
16
- };
17
- const flushSegment = () => {
18
- flushWord();
19
- if (current.length) {
20
- segments.push(current);
21
- current = [];
22
- }
23
- };
24
- for (const char of command) {
25
- if (quote) {
26
- if (char === quote)
27
- quote = null;
28
- else
29
- word += char;
30
- continue;
31
- }
32
- if (char === '"' || char === "'") {
33
- quote = char;
34
- continue;
35
- }
36
- if (char === ';' || char === '&' || char === '|' || char === '\n' || char === '\r') {
37
- flushSegment();
38
- continue;
39
- }
40
- if (/\s/.test(char)) {
41
- flushWord();
42
- continue;
43
- }
44
- word += char;
45
- }
46
- flushSegment();
47
- return segments;
48
- }
1
+ // Commands are matched by command position, not by scanning for words anywhere in the string.
2
+ // Segmenting and quote handling belong to shell-parse.
3
+ export { splitCommandSegments } from "../shell-parse/index.mjs";
49
4
  const PACKAGE_RUNNERS = ['npx', 'pnpm', 'pnpx', 'yarn'];
50
5
  export function isPackageRunner(word) {
51
6
  if (!word)
@@ -0,0 +1,6 @@
1
+ export type SandboxEscalation = {
2
+ commandPrefix: string;
3
+ justification?: string;
4
+ prefixRule?: string[];
5
+ };
6
+ export declare function escalationOf(payload: Record<string, unknown>): SandboxEscalation | undefined;
@@ -0,0 +1,34 @@
1
+ import { normalizeCommandPrefix, redactOverlongToken } from "./command-prefix.mjs";
2
+ import { asRecord } from "./shared.mjs";
3
+ const MAX_JUSTIFICATION_LENGTH = 240;
4
+ // Only a parsed `exec_command` function_call whose JSON arguments request
5
+ // `sandbox_permissions: "require_escalated"` counts. Text that merely quotes the field
6
+ // (for example an auto-review prompt) never reaches here because it is not a call.
7
+ // The approval outcome is not recorded in a stable shape, so it is intentionally omitted.
8
+ export function escalationOf(payload) {
9
+ if (payload.type !== 'function_call' || payload.name !== 'exec_command')
10
+ return undefined;
11
+ if (typeof payload.arguments !== 'string')
12
+ return undefined;
13
+ let args;
14
+ try {
15
+ args = asRecord(JSON.parse(payload.arguments));
16
+ }
17
+ catch {
18
+ return undefined;
19
+ }
20
+ if (args?.sandbox_permissions !== 'require_escalated')
21
+ return undefined;
22
+ const command = args.cmd ?? args.command;
23
+ const justification = typeof args.justification === 'string'
24
+ ? args.justification.replace(/\s+/g, ' ').trim().slice(0, MAX_JUSTIFICATION_LENGTH)
25
+ : '';
26
+ const rule = Array.isArray(args.prefix_rule)
27
+ ? args.prefix_rule.filter((token) => typeof token === 'string')
28
+ : [];
29
+ return {
30
+ commandPrefix: typeof command === 'string' ? normalizeCommandPrefix(command) : '',
31
+ ...(justification ? { justification } : {}),
32
+ ...(rule.length ? { prefixRule: rule.map(redactOverlongToken) } : {}),
33
+ };
34
+ }
@@ -16,7 +16,20 @@ export function formatTranscriptFacts(sessionId, facts) {
16
16
  `Tokens: input=${facts.tokens.input} output=${facts.tokens.output} cache_read=${facts.tokens.cacheRead} cache_creation=${facts.tokens.cacheCreation}`,
17
17
  `Subagent tool calls: ${facts.subagentToolCalls}`,
18
18
  `Subagent tokens: input=${facts.subagentTokens.input} output=${facts.subagentTokens.output} cache_read=${facts.subagentTokens.cacheRead} cache_creation=${facts.subagentTokens.cacheCreation}`,
19
+ ...escalationLines(facts),
19
20
  '',
20
21
  ].join('\n');
21
22
  }
23
+ function escalationLines(facts) {
24
+ if (!facts.escalations.length)
25
+ return [];
26
+ return [
27
+ `Sandbox escalations: ${facts.escalations.length}`,
28
+ ...facts.escalations.map((item) => {
29
+ const rule = item.prefixRule ? ` prefix_rule=${JSON.stringify(item.prefixRule)}` : '';
30
+ const why = item.justification ? ` justification=${JSON.stringify(item.justification)}` : '';
31
+ return `- ${item.commandPrefix || '(unknown)'}${rule}${why}`;
32
+ }),
33
+ ];
34
+ }
22
35
  export const formatUnavailable = (reason) => `=== Transcript Facts ===\nStatus: unavailable (${reason.replace(/\s+/g, ' ').slice(0, 240)})\n`;
@@ -7,7 +7,8 @@ import { segmentCodex } from "./codex-segment.mjs";
7
7
  import { computeClaude } from "./claude.mjs";
8
8
  import { formatTranscriptFacts, formatUnavailable } from "./format.mjs";
9
9
  import { globFrom, resolveTranscriptFile, SESSION_ID, } from "./resolve-transcript-file.mjs";
10
- import { emptyFacts, hasMalformedInteriorRecord, parseLines, } from "./shared.mjs";
10
+ import { hasMalformedInteriorRecord } from "./malformed-record.mjs";
11
+ import { emptyFacts, parseLines } from "./shared.mjs";
11
12
  export { codexChildren, codexIdentity } from "./codex.mjs";
12
13
  export { formatTranscriptFacts, formatUnavailable } from "./format.mjs";
13
14
  export { resolveTranscriptFile } from "./resolve-transcript-file.mjs";
@@ -0,0 +1 @@
1
+ export declare function hasMalformedInteriorRecord(lines: string[]): boolean;
@@ -0,0 +1,13 @@
1
+ import { asRecord } from "./shared.mjs";
2
+ export function hasMalformedInteriorRecord(lines) {
3
+ const nonblank = lines.filter((line) => line.trim());
4
+ const complete = lines.at(-1)?.trim() ? nonblank.slice(0, -1) : nonblank;
5
+ return complete.some((line) => {
6
+ try {
7
+ return !asRecord(JSON.parse(line));
8
+ }
9
+ catch {
10
+ return true;
11
+ }
12
+ });
13
+ }
@@ -1,3 +1,4 @@
1
+ import type { SandboxEscalation } from './escalations.mts';
1
2
  export type TokenTotals = {
2
3
  input: number;
3
4
  output: number;
@@ -16,6 +17,7 @@ export type TranscriptFacts = {
16
17
  tokens: TokenTotals;
17
18
  subagentToolCalls: number;
18
19
  subagentTokens: TokenTotals;
20
+ escalations: SandboxEscalation[];
19
21
  };
20
22
  export type ParsedLine = Record<string, unknown>;
21
23
  export type CodexSegment = {
@@ -27,5 +29,4 @@ export declare const emptyFacts: () => TranscriptFacts;
27
29
  export declare function asRecord(value: unknown): ParsedLine | undefined;
28
30
  export declare const asNumber: (value: unknown) => number;
29
31
  export declare function parseLines(lines: string[]): ParsedLine[];
30
- export declare function hasMalformedInteriorRecord(lines: string[]): boolean;
31
32
  export declare function applyCommand(command: string, facts: TranscriptFacts): void;
@@ -16,6 +16,7 @@ export const emptyFacts = () => ({
16
16
  tokens: emptyTokens(),
17
17
  subagentToolCalls: 0,
18
18
  subagentTokens: emptyTokens(),
19
+ escalations: [],
19
20
  });
20
21
  export function asRecord(value) {
21
22
  return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -39,18 +40,6 @@ export function parseLines(lines) {
39
40
  }
40
41
  return records;
41
42
  }
42
- export function hasMalformedInteriorRecord(lines) {
43
- const nonblank = lines.filter((line) => line.trim());
44
- const complete = lines.at(-1)?.trim() ? nonblank.slice(0, -1) : nonblank;
45
- return complete.some((line) => {
46
- try {
47
- return !asRecord(JSON.parse(line));
48
- }
49
- catch {
50
- return true;
51
- }
52
- });
53
- }
54
43
  function hereDocs(tokens) {
55
44
  return tokens.flatMap((token, index) => {
56
45
  if (token.startsWith('<<<'))
@@ -18,3 +18,5 @@ export { stripUnquotedShellComments } from './shell-tokenizer-comments.mts';
18
18
  export { consumeShellSeparator } from './shell-tokenizer-operators.mts';
19
19
  export { tokenizeShellWords, tokenizeShellWordsDetailed } from './shell-tokenizer.mts';
20
20
  export type { ShellWord } from './shell-tokenizer.mts';
21
+ export { walkUnquotedShell } from './shell-walk.mts';
22
+ export { splitCommandSegments } from './shell-command-segments.mts';
@@ -13,3 +13,5 @@ export { commandSegmentStart, isShellAssignment, isShellCommandSeparator, nextSh
13
13
  export { stripUnquotedShellComments } from "./shell-tokenizer-comments.mjs";
14
14
  export { consumeShellSeparator } from "./shell-tokenizer-operators.mjs";
15
15
  export { tokenizeShellWords, tokenizeShellWordsDetailed } from "./shell-tokenizer.mjs";
16
+ export { walkUnquotedShell } from "./shell-walk.mjs";
17
+ export { splitCommandSegments } from "./shell-command-segments.mjs";
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Splits a command into segments on unquoted `;`, `&`, `&&`, `|`, `||`, and newlines, each segment
3
+ * being its already-unquoted words. Parentheses stay inside words (`$(git status)` is one word
4
+ * run, not a nested command), so only top-level command position is exposed.
5
+ */
6
+ export declare function splitCommandSegments(command: string): string[][];
@@ -0,0 +1,26 @@
1
+ import { tokenizeShellWordsDetailed } from "./shell-tokenizer.mjs";
2
+ /**
3
+ * Splits a command into segments on unquoted `;`, `&`, `&&`, `|`, `||`, and newlines, each segment
4
+ * being its already-unquoted words. Parentheses stay inside words (`$(git status)` is one word
5
+ * run, not a nested command), so only top-level command position is exposed.
6
+ */
7
+ export function splitCommandSegments(command) {
8
+ const segments = [];
9
+ let current = [];
10
+ for (const word of tokenizeShellWordsDetailed(command, {
11
+ keepParentheses: true,
12
+ markOperators: true,
13
+ })) {
14
+ if (word.operator === true) {
15
+ if (current.length > 0)
16
+ segments.push(current);
17
+ current = [];
18
+ }
19
+ else {
20
+ current.push(word.value);
21
+ }
22
+ }
23
+ if (current.length > 0)
24
+ segments.push(current);
25
+ return segments;
26
+ }
@@ -1,12 +1,10 @@
1
- import type { ShellWord } from './shell-tokenizer.mts';
1
+ import type { ShellTokenizeOptions, ShellWord } from './shell-tokenizer.mts';
2
2
  type SeparatorState = {
3
3
  char: string;
4
4
  command: string;
5
5
  expandable: boolean;
6
6
  index: number;
7
- options: {
8
- splitRedirections?: boolean;
9
- };
7
+ options: ShellTokenizeOptions;
10
8
  token: string;
11
9
  tokens: ShellWord[];
12
10
  };
@@ -29,17 +29,27 @@ export function consumeShellSeparator(state) {
29
29
  return state.index + redirectionOperator.length - 1;
30
30
  }
31
31
  const { char } = state;
32
- if (char === '&' || char === '|' || char === ';' || char === '(' || char === ')') {
32
+ const isParenthesis = char === '(' || char === ')';
33
+ if (char === '&' ||
34
+ char === '|' ||
35
+ char === ';' ||
36
+ (isParenthesis && !state.options.keepParentheses)) {
33
37
  pushStateToken(state);
34
- const previousToken = state.tokens.at(-1)?.value;
35
- if ((char === '&' && previousToken === '&') || (char === '|' && previousToken === '|')) {
38
+ const operator = state.options.markOperators ? { operator: true } : {};
39
+ const previous = state.tokens.at(-1);
40
+ const previousToken = previous?.value;
41
+ // With `markOperators` a quoted `"|"` argument is not an operator, so only operators merge.
42
+ const mergeable = state.options.markOperators !== true || previous?.operator === true;
43
+ if (mergeable &&
44
+ ((char === '&' && previousToken === '&') || (char === '|' && previousToken === '|'))) {
36
45
  state.tokens[state.tokens.length - 1] = {
37
46
  expandable: false,
47
+ ...operator,
38
48
  value: `${previousToken}${char}`,
39
49
  };
40
50
  }
41
51
  else {
42
- state.tokens.push({ expandable: false, value: char });
52
+ state.tokens.push({ expandable: false, ...operator, value: char });
43
53
  }
44
54
  return state.index;
45
55
  }
@@ -1,12 +1,16 @@
1
1
  import { stripUnquotedShellComments } from './shell-tokenizer-comments.mts';
2
2
  export type ShellWord = {
3
3
  expandable: boolean;
4
+ operator?: true;
4
5
  value: string;
5
6
  };
6
- export declare function tokenizeShellWordsDetailed(command: string, options?: {
7
+ export type ShellTokenizeOptions = {
8
+ /** Keep `(` and `)` inside words instead of emitting them as operator tokens. */
9
+ keepParentheses?: boolean;
10
+ /** Tag command-separator tokens (`;`, `&`, `&&`, `|`, `||`, `(`, `)`, newline) with `operator`. */
11
+ markOperators?: boolean;
7
12
  splitRedirections?: boolean;
8
- }): ShellWord[];
9
- export declare function tokenizeShellWords(command: string, options?: {
10
- splitRedirections?: boolean;
11
- }): string[];
13
+ };
14
+ export declare function tokenizeShellWordsDetailed(command: string, options?: ShellTokenizeOptions): ShellWord[];
15
+ export declare function tokenizeShellWords(command: string, options?: ShellTokenizeOptions): string[];
12
16
  export { stripUnquotedShellComments };
@@ -64,7 +64,11 @@ export function tokenizeShellWordsDetailed(command, options = {}) {
64
64
  }
65
65
  if (char === '\n') {
66
66
  pushToken();
67
- tokens.push({ expandable: false, value: '\n' });
67
+ tokens.push({
68
+ expandable: false,
69
+ value: '\n',
70
+ ...(options.markOperators ? { operator: true } : {}),
71
+ });
68
72
  continue;
69
73
  }
70
74
  if (/\s/.test(char)) {
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Calls `visit(index, state)` for every character outside quotes, escapes, comments, and the
3
+ * structural `$(` / `(` / `)` of a substitution. `state` belongs to the current `$(...)` level. The
4
+ * visitor returns the next index to consume from, or `undefined` to advance by one. Backslash
5
+ * escapes consume the following character, even inside double quotes, and a `#` at the start or
6
+ * after whitespace ends the text.
7
+ */
8
+ export declare function walkUnquotedShell<State>(text: string, createState: () => State, visit: (index: number, state: State) => number | undefined): void;
@@ -0,0 +1,62 @@
1
+ // A quote-aware walk over shell text for callers that need per-character positions rather than
2
+ // tokens (for example to report offsets). It tracks single and double quotes, backslash escapes,
3
+ // unquoted `#` comments, and `$(...)` nesting, giving each nesting level its own caller-defined
4
+ // state. Unlike `tokenizeShellWordsDetailed` it never classifies expansion or glob characters, so a
5
+ // quoted `"...${VAR}...?x=1"` yields no unquoted `?` to the visitor.
6
+ function newFrame(state, parenDepth) {
7
+ return { inSingleQuote: false, inDoubleQuote: false, parenDepth, state };
8
+ }
9
+ /**
10
+ * Calls `visit(index, state)` for every character outside quotes, escapes, comments, and the
11
+ * structural `$(` / `(` / `)` of a substitution. `state` belongs to the current `$(...)` level. The
12
+ * visitor returns the next index to consume from, or `undefined` to advance by one. Backslash
13
+ * escapes consume the following character, even inside double quotes, and a `#` at the start or
14
+ * after whitespace ends the text.
15
+ */
16
+ export function walkUnquotedShell(text, createState, visit) {
17
+ const stack = [newFrame(createState(), 0)];
18
+ let i = 0;
19
+ while (i < text.length) {
20
+ const frame = stack[stack.length - 1];
21
+ const char = text[i];
22
+ if (frame.inSingleQuote) {
23
+ if (char === "'")
24
+ frame.inSingleQuote = false;
25
+ i += 1;
26
+ continue;
27
+ }
28
+ if (char === '\\') {
29
+ i += 2;
30
+ continue;
31
+ }
32
+ if (char === '$' && text[i + 1] === '(') {
33
+ stack.push(newFrame(createState(), 1));
34
+ i += 2;
35
+ continue;
36
+ }
37
+ if (frame.inDoubleQuote) {
38
+ if (char === '"')
39
+ frame.inDoubleQuote = false;
40
+ i += 1;
41
+ continue;
42
+ }
43
+ if (char === '#' && (i === 0 || /\s/.test(text[i - 1])))
44
+ break;
45
+ if (char === "'" || char === '"') {
46
+ if (char === "'")
47
+ frame.inSingleQuote = true;
48
+ else
49
+ frame.inDoubleQuote = true;
50
+ i += 1;
51
+ continue;
52
+ }
53
+ if (stack.length > 1 && (char === '(' || char === ')')) {
54
+ frame.parenDepth += char === '(' ? 1 : -1;
55
+ i += 1;
56
+ if (frame.parenDepth === 0)
57
+ stack.pop();
58
+ continue;
59
+ }
60
+ i = visit(i, frame.state) ?? i + 1;
61
+ }
62
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.55.0",
3
+ "version": "0.56.0",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {