@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/verdict/git-classifier.d.ts

@@ -1,3 +1,4 @@
+import type { ShellEffectRequirement } from '../effect-ir/shell-build.js';
 import type { VerdictEffect } from './types.js';
 export interface NormalizedGitInvocation {
     subcommand: string;
@@ -21,6 +22,17 @@ export interface GitCommandSemantics {
     normalizedKey: string;
     isReadOnly: boolean;
 }
+export interface DecodeGitEffectsParams {
+    tokens: string[];
+    cwd: string;
+    repoRoot: string;
+    segment: string;
+}
 export declare function normalizeGitInvocation(tokens: string[], baseCwd: string): NormalizedGitInvocation | null;
 export declare function isGitReadOnlyInvocation(tokens: string[], baseCwd: string): boolean;
 export declare function classifyGitCommand(tokens: string[], baseCwd: string): GitCommandSemantics | null;
+/**
+ * Decode git CLI grammar to typed effects without making an authorization
+ * decision. Legacy classification remains separate until the authority cutover.
+ */
+export declare function decodeGitEffects(params: DecodeGitEffectsParams): ShellEffectRequirement[] | null;

package/dist/core/verdict/git-classifier.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { parseNetworkEndpoint } from '../network-endpoint.js';
 import { extractRedirectTargets } from '../shell-tokenizer.js';
 const GIT_BRANCH_MUTATION_FLAGS = new Set([
     '--copy',
@@ -531,3 +532,322 @@ export function classifyGitCommand(tokens, baseCwd) {
         isReadOnly: false,
     };
 }
+/**
+ * Decode git CLI grammar to typed effects without making an authorization
+ * decision. Legacy classification remains separate until the authority cutover.
+ */
+export function decodeGitEffects(params) {
+    const normalized = normalizeGitInvocation(params.tokens, params.cwd);
+    if (!normalized) {
+        return null;
+    }
+    const { subcommand, args } = normalized;
+    const signals = [
+        `git.${subcommand.replaceAll(' ', '.')}`,
+        ...(subcommand === 'push' ? ['tier0_external'] : []),
+    ];
+    const effectiveCwd = normalized.effectiveCwd ?? params.cwd;
+    const workTreeRoot = normalized.workTree
+        ? path.resolve(normalized.effectiveCwd ?? params.cwd, normalized.workTree)
+        : (normalized.effectiveCwd ?? params.repoRoot);
+    const gitRefRoot = normalized.gitDir
+        ? path.resolve(effectiveCwd, normalized.gitDir)
+        : workTreeRoot;
+    const gitControlRoot = normalized.gitDir ? gitRefRoot : path.join(gitRefRoot, '.git');
+    const requirements = [];
+    if (subcommand === 'fetch' || subcommand === 'pull') {
+        const positionals = gitRemotePositionals(args);
+        if (subcommand === 'fetch' && args.includes('--all')) {
+            return [
+                gitRequirement('network.connect', 'network.connect', {
+                    kind: 'network',
+                    host: 'unknown',
+                    protocol: 'git-remote',
+                    mode: 'read',
+                    payload: 'none',
+                }, params.segment, [...signals, 'git.fetch_all_remotes_unknown']),
+                gitRequirement('git.ref.write', 'git.ref.write', { kind: 'git-ref', ref: 'refs/remotes/*', scope: 'local', repoPath: gitRefRoot }, params.segment, [...signals, 'git.ref.local']),
+                gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+                    ...signals,
+                    'git.fetch_all_remotes_unknown',
+                ]),
+            ];
+        }
+        const multiple = subcommand === 'fetch' && args.includes('--multiple');
+        const remoteTokens = multiple ? positionals : [positionals[0]];
+        for (const remoteToken of remoteTokens) {
+            const remote = gitRemoteResource(remoteToken);
+            requirements.push(gitRequirement('network.connect', 'network.connect', {
+                kind: 'network',
+                ...remote.endpoint,
+                mode: 'read',
+                payload: 'none',
+            }, params.segment, [...signals, 'git.network.read']), gitRequirement('git.ref.write', 'git.ref.write', {
+                kind: 'git-ref',
+                ref: remote.ref ? `refs/remotes/${remote.ref}/*` : 'refs/remotes/*',
+                scope: 'local',
+                repoPath: gitRefRoot,
+            }, params.segment, [...signals, 'git.ref.local']));
+        }
+        const hazardousFetchSignals = gitFetchControlSignals(params.tokens, args, remoteTokens);
+        if (hazardousFetchSignals.length > 0) {
+            requirements.push(gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+                ...signals,
+                ...hazardousFetchSignals,
+            ]));
+        }
+        if (multiple && positionals.length === 0) {
+            requirements.push(gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+                ...signals,
+                'git.fetch_multiple_remote_missing',
+            ]));
+        }
+        if (subcommand === 'pull') {
+            requirements.push(gitRequirement('fs.write', 'fs.write', { kind: 'path', path: workTreeRoot }, params.segment, [...signals, 'git.worktree.update']));
+        }
+        return requirements;
+    }
+    if (subcommand === 'push') {
+        const positionals = gitRemotePositionals(args);
+        const repositoryOption = gitOptionValue(args, '--repo');
+        const remote = gitRemoteResource(repositoryOption.value ?? positionals[0]);
+        const refs = repositoryOption.value ? positionals : positionals.slice(1);
+        const lowered = [
+            gitRequirement('network.connect', 'network.connect', {
+                kind: 'network',
+                ...remote.endpoint,
+                mode: 'mutate',
+                payload: 'present',
+            }, params.segment, [...signals, 'git.network.mutate']),
+        ];
+        for (const ref of refs.length > 0 ? refs : ['*']) {
+            lowered.push(gitRequirement('git.ref.write', 'git.ref.write', {
+                kind: 'git-ref',
+                ref: ref.startsWith('refs/') ? ref : `refs/heads/${ref}`,
+                scope: 'remote',
+            }, params.segment, [...signals, 'git.ref.remote']));
+        }
+        if (repositoryOption.missing) {
+            lowered.push(gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+                ...signals,
+                'git.push_repository_missing',
+            ]));
+        }
+        return lowered;
+    }
+    if (subcommand === 'reflog') {
+        const operation = args[0];
+        const mutationFlags = [
+            '--expire',
+            '--expire-unreachable',
+            '--rewrite',
+            '--stale-fix',
+            '--updateref',
+        ];
+        const mutating = operation === 'expire' ||
+            operation === 'delete' ||
+            operation === 'drop' ||
+            args.some((arg) => mutationFlags.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+        if (mutating) {
+            return [
+                gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'spawn' }, params.segment, [...signals, 'git_history_destructive', 'git.reflog.mutate']),
+                gitRequirement('control_plane.write', 'control_plane.write', { kind: 'path', path: path.join(gitControlRoot, 'logs') }, params.segment, [...signals, 'git_history_destructive', 'git.reflog.mutate']),
+            ];
+        }
+        if (isReadOnlyReflogInvocation(args)) {
+            return [
+                gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'inspect' }, params.segment, [...signals, 'git.inspect']),
+                gitRequirement('fs.read', 'fs.read', { kind: 'path', path: workTreeRoot }, params.segment, [
+                    ...signals,
+                    'git.repository.read',
+                ]),
+            ];
+        }
+        return [
+            gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'spawn' }, params.segment, signals),
+            gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+                ...signals,
+                'git.reflog.grammar_incomplete',
+            ]),
+        ];
+    }
+    const semantics = classifyGitCommand(params.tokens, params.cwd);
+    if (!semantics) {
+        return null;
+    }
+    if (semantics.isReadOnly) {
+        requirements.push(gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'inspect' }, params.segment, [...signals, 'git.inspect']), gitRequirement('fs.read', 'fs.read', { kind: 'path', path: workTreeRoot }, params.segment, [
+            ...signals,
+            'git.repository.read',
+        ]));
+        for (const operand of semantics.pathTargets) {
+            requirements.push(gitRequirement('fs.read', 'fs.read', { kind: 'path', path: path.resolve(workTreeRoot, operand) }, params.segment, [...signals, 'git.path.read']));
+        }
+        return requirements;
+    }
+    if (semantics.effect === 'local_mutation') {
+        requirements.push(gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'spawn' }, params.segment, signals), gitRequirement('git.ref.write', 'git.ref.write', {
+            kind: 'git-ref',
+            ref: localGitRef(subcommand, args),
+            scope: 'local',
+            repoPath: gitRefRoot,
+        }, params.segment, [...signals, 'git.ref.local']));
+        for (const operand of semantics.pathTargets) {
+            requirements.push(gitRequirement('fs.write', 'fs.write', { kind: 'path', path: path.resolve(workTreeRoot, operand) }, params.segment, [...signals, 'git.path.write']));
+        }
+        if (semantics.requiresAsk) {
+            requirements.push(gitRequirement('fs.write', 'fs.write', { kind: 'path', path: workTreeRoot }, params.segment, [...signals, ...semantics.requiresAsk.signals, 'git.destructive_worktree_write']), gitRequirement('control_plane.write', 'control_plane.write', { kind: 'path', path: gitControlRoot }, params.segment, [...signals, ...semantics.requiresAsk.signals, 'git.destructive_history_write']));
+        }
+        return requirements;
+    }
+    return [
+        gitRequirement('process.exec', 'process.exec', { kind: 'executable', command: 'git', operation: 'spawn' }, params.segment, signals),
+        gitRequirement('indeterminate', 'indeterminate', { kind: 'unknown' }, params.segment, [
+            ...signals,
+            'git.grammar_incomplete',
+        ]),
+    ];
+}
+function isReadOnlyReflogInvocation(args) {
+    if (args[0] === 'exists') {
+        return args.length === 2 && Boolean(args[1]) && !(args[1] ?? '').startsWith('-');
+    }
+    let index = args[0] === 'show' || args[0] === 'list' ? 1 : 0;
+    let positionalCount = 0;
+    while (index < args.length) {
+        const arg = args[index] ?? '';
+        if (arg === '--all' || /^-\d+$/.test(arg)) {
+            index += 1;
+            continue;
+        }
+        if (arg === '-n' || arg === '--max-count') {
+            const count = args[index + 1];
+            if (!count || !/^\d+$/.test(count)) {
+                return false;
+            }
+            index += 2;
+            continue;
+        }
+        if (/^-n\d+$/.test(arg) || /^--(?:max-count|date|format|pretty)=.+/.test(arg)) {
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return false;
+        }
+        positionalCount += 1;
+        if (args[0] !== 'show' && args[0] !== 'list') {
+            return false;
+        }
+        if (positionalCount > 1) {
+            return false;
+        }
+        index += 1;
+    }
+    return true;
+}
+const GIT_REMOTE_OPTIONS_WITH_VALUES = new Set([
+    '--depth',
+    '--exec',
+    '--filter',
+    '--jobs',
+    '--negotiation-tip',
+    '--push-option',
+    '--repo',
+    '--receive-pack',
+    '--recurse-submodules',
+    '--server-option',
+    '--shallow-exclude',
+    '--shallow-since',
+    '--upload-pack',
+    '-j',
+    '-o',
+]);
+function gitFetchControlSignals(tokens, args, remoteTokens) {
+    const signals = [];
+    if (tokens.some((token) => token === '-c' ||
+        (token.startsWith('-c') && token.length > 2) ||
+        token === '--config-env' ||
+        token.startsWith('--config-env=') ||
+        token === '--exec-path' ||
+        token.startsWith('--exec-path='))) {
+        signals.push('git.fetch.global_execution_override');
+    }
+    if (args.some((arg) => ['--exec', '--server-option', '--upload-pack'].some((option) => arg === option || arg.startsWith(`${option}=`)))) {
+        signals.push('git.fetch.caller_controlled_execution_or_payload');
+    }
+    if (remoteTokens.some((remote) => remote?.startsWith('ext::'))) {
+        signals.push('git.fetch.external_remote_helper');
+    }
+    return signals;
+}
+function gitOptionValue(args, option) {
+    const exactIndex = args.indexOf(option);
+    if (exactIndex >= 0) {
+        const value = args[exactIndex + 1];
+        return value && !value.startsWith('-') ? { value, missing: false } : { missing: true };
+    }
+    const prefix = `${option}=`;
+    const inline = args.find((arg) => arg.startsWith(prefix));
+    if (inline !== undefined) {
+        const value = inline.slice(prefix.length);
+        return value ? { value, missing: false } : { missing: true };
+    }
+    return { missing: false };
+}
+function gitRemotePositionals(args) {
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        if (arg === '--') {
+            positionals.push(...args.slice(index + 1));
+            break;
+        }
+        if (arg.startsWith('-')) {
+            if (GIT_REMOTE_OPTIONS_WITH_VALUES.has(arg) && !arg.includes('=')) {
+                index += args[index + 1] ? 1 : 0;
+            }
+            continue;
+        }
+        positionals.push(arg);
+    }
+    return positionals;
+}
+function gitRemoteResource(remoteToken) {
+    const token = remoteToken && !remoteToken.startsWith('-') ? remoteToken : undefined;
+    const endpoint = token
+        ? parseNetworkEndpoint(token, { allowHostedGitShorthand: true, allowScpStyle: true })
+        : null;
+    if (endpoint) {
+        return { endpoint };
+    }
+    const ref = token && !token.includes('/') ? token : undefined;
+    return {
+        endpoint: { host: ref ?? 'origin', protocol: 'git-remote' },
+        ...(ref ? { ref } : {}),
+    };
+}
+function localGitRef(subcommand, args) {
+    if (subcommand === 'branch') {
+        const name = args.find((arg) => arg && !arg.startsWith('-'));
+        return name ? `refs/heads/${name}` : 'refs/heads/*';
+    }
+    if (subcommand === 'tag') {
+        const name = args.find((arg) => arg && !arg.startsWith('-'));
+        return name ? `refs/tags/${name}` : 'refs/tags/*';
+    }
+    return 'refs/local/*';
+}
+function gitRequirement(tag, action, resource, segment, signals) {
+    return {
+        tag,
+        action,
+        resource,
+        evidence: {
+            level: tag === 'indeterminate' ? 'indeterminate' : 'certain',
+            signals: [...new Set(signals)].sort(),
+            basis: ['git_grammar'],
+        },
+        provenance: { segment },
+    };
+}

package/dist/core/verdict/launcher-resolve.js

@@ -34,17 +34,6 @@ const PNPM_BUILTIN_COMMANDS = new Set([
     'up',
     'why',
 ]);
-const PNPM_EXEC_LIKE_HEADS = new Set([
-    'vitest',
-    'vite',
-    'biome',
-    'eslint',
-    'jest',
-    'mocha',
-    'tsc',
-    'tsx',
-    'node',
-]);
 function readPackageJson(dir) {
     const packagePath = path.join(dir, 'package.json');
     if (!existsSync(packagePath)) {
@@ -134,32 +123,47 @@ function resolveNpmRecipe(cwd, repoRoot, scriptName, extraArgs) {
     if (!scripts || typeof scripts !== 'object') {
         return { recipes: [], opaque: true, reason: 'package_scripts_missing' };
     }
-    const recipe = scripts[scriptName];
+    const scriptMap = scripts;
+    const recipe = scriptMap[scriptName];
     if (!recipe || typeof recipe !== 'string') {
         if (/deploy|publish|release|ship|prod/i.test(scriptName)) {
             return { recipes: [], opaque: true, reason: 'external_script' };
         }
         return { recipes: [], opaque: true, reason: 'npm_script_undefined' };
     }
-    if (/\$\(/.test(recipe) || /\$\{/.test(recipe)) {
-        return { recipes: [], opaque: true, reason: 'npm_script_dynamic' };
+    const lifecycleRecipes = [
+        scriptMap[`pre${scriptName}`],
+        applyForwardedArgs(recipe, extraArgs),
+        scriptMap[`post${scriptName}`],
+    ].filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+    if (lifecycleRecipes.some((entry) => /\$\(/.test(entry) || /\$\{/.test(entry))) {
+        return { recipes: lifecycleRecipes, opaque: true, reason: 'npm_script_dynamic' };
     }
     return {
-        recipes: [applyForwardedArgs(recipe, extraArgs)],
+        recipes: lifecycleRecipes,
         opaque: false,
         reason: 'npm_script_resolved',
     };
 }
 function parseMakefileRecipes(makefilePath) {
-    const recipes = new Map();
+    const targets = new Map();
     try {
         const content = readFileSync(makefilePath, 'utf8');
         const lines = content.split('\n');
         let currentTarget = null;
         let recipeLines = [];
         const flush = () => {
-            if (currentTarget && recipeLines.length > 0) {
-                recipes.set(currentTarget, recipeLines.map((line) => line.trim()).filter((line) => line.length > 0));
+            if (currentTarget) {
+                const current = targets.get(currentTarget) ?? {
+                    prerequisites: [],
+                    recipes: [],
+                    opaquePrerequisites: false,
+                };
+                targets.set(currentTarget, {
+                    prerequisites: current.prerequisites,
+                    recipes: recipeLines.map((line) => line.trim()).filter((line) => line.length > 0),
+                    opaquePrerequisites: current.opaquePrerequisites,
+                });
             }
             currentTarget = null;
             recipeLines = [];
@@ -168,13 +172,26 @@ function parseMakefileRecipes(makefilePath) {
             if (line.trim().startsWith('#')) {
                 continue;
             }
-            const targetMatch = /^([A-Za-z0-9_.-]+)\s*:(?!=)/.exec(line);
+            const targetMatch = /^([A-Za-z0-9_.-]+)\s*:(?!=)\s*([^#]*)/.exec(line);
             if (targetMatch) {
                 flush();
                 currentTarget = targetMatch[1] ?? null;
-                const inline = line.slice(targetMatch[0].length).trim();
-                if (inline && !inline.startsWith('#')) {
-                    recipeLines.push(inline);
+                if (currentTarget) {
+                    const targetBody = (targetMatch[2] ?? '').trim();
+                    const inlineRecipeIndex = targetBody.indexOf(';');
+                    const prerequisiteText = inlineRecipeIndex >= 0 ? targetBody.slice(0, inlineRecipeIndex).trim() : targetBody;
+                    const inlineRecipe = inlineRecipeIndex >= 0 ? targetBody.slice(inlineRecipeIndex + 1).trim() : '';
+                    const prerequisiteTokens = prerequisiteText
+                        .split(/\s+/)
+                        .filter((token) => token && token !== '|');
+                    targets.set(currentTarget, {
+                        prerequisites: prerequisiteTokens.filter((token) => !token.includes('$(') && !token.includes('${')),
+                        recipes: [],
+                        opaquePrerequisites: prerequisiteTokens.some((token) => token.includes('$(') || token.includes('${')),
+                    });
+                    if (inlineRecipe) {
+                        recipeLines.push(inlineRecipe);
+                    }
                 }
                 continue;
             }
@@ -185,9 +202,9 @@ function parseMakefileRecipes(makefilePath) {
         flush();
     }
     catch {
-        return recipes;
+        return targets;
     }
-    return recipes;
+    return targets;
 }
 function resolveMakeRecipe(cwd, repoRoot, target) {
     const candidates = ['Makefile', 'makefile', 'GNUmakefile'];
@@ -210,16 +227,48 @@ function resolveMakeRecipe(cwd, repoRoot, target) {
     if (!makefilePath) {
         return { recipes: [], opaque: true, reason: 'unknown_local_effect' };
     }
-    const recipes = parseMakefileRecipes(makefilePath);
-    const recipeLines = recipes.get(target);
-    if (!recipeLines || recipeLines.length === 0) {
+    const targets = parseMakefileRecipes(makefilePath);
+    if (!targets.has(target)) {
         return { recipes: [], opaque: true, reason: 'make_target_undefined' };
     }
+    const recipeLines = [];
+    const visiting = new Set();
+    const visited = new Set();
+    let opaquePrerequisites = false;
+    const collect = (name) => {
+        if (visited.has(name)) {
+            return true;
+        }
+        if (visiting.has(name)) {
+            return false;
+        }
+        const entry = targets.get(name);
+        if (!entry) {
+            return true;
+        }
+        visiting.add(name);
+        opaquePrerequisites ||= entry.opaquePrerequisites;
+        for (const prerequisite of entry.prerequisites) {
+            if (targets.has(prerequisite) && !collect(prerequisite)) {
+                return false;
+            }
+        }
+        recipeLines.push(...entry.recipes);
+        visiting.delete(name);
+        visited.add(name);
+        return true;
+    };
+    if (!collect(target)) {
+        return { recipes: recipeLines, opaque: true, reason: 'make_dependency_cycle' };
+    }
     for (const line of recipeLines) {
         if (/\$\(/.test(line) || /\$\{/.test(line)) {
-            return { recipes: [], opaque: true, reason: 'make_recipe_dynamic' };
+            return { recipes: recipeLines, opaque: true, reason: 'make_recipe_dynamic' };
         }
     }
+    if (opaquePrerequisites) {
+        return { recipes: recipeLines, opaque: true, reason: 'make_prerequisite_dynamic' };
+    }
     return { recipes: recipeLines, opaque: false, reason: 'make_recipe_resolved' };
 }
 export function resolveLauncherRecipe(params) {
@@ -232,12 +281,12 @@ export function resolveLauncherRecipe(params) {
         const resolution = resolveNpmRecipe(params.cwd, params.repoRoot, scriptName, forwardedArgs(tokens));
         if (tokens[0] === 'pnpm' &&
             tokens[1] &&
-            PNPM_EXEC_LIKE_HEADS.has(tokens[1]) &&
+            !PNPM_BUILTIN_COMMANDS.has(tokens[1]) &&
             resolution.reason === 'npm_script_undefined') {
             return {
                 recipes: [tokens.slice(1).join(' ')],
                 opaque: false,
-                reason: 'pnpm_exec_like',
+                reason: 'pnpm_exec_shorthand',
             };
         }
         return resolution;
@@ -252,13 +301,6 @@ export function resolveLauncherRecipe(params) {
             reason: 'pnpm_exec',
         };
     }
-    if (tokens[0] === 'pnpm' && tokens[1] && PNPM_EXEC_LIKE_HEADS.has(tokens[1])) {
-        return {
-            recipes: [tokens.slice(1).join(' ')],
-            opaque: false,
-            reason: 'pnpm_exec_like',
-        };
-    }
     return null;
 }
 const READ_ONLY_LAUNCHER_SUFFIXES = new Set(['--version', '-v', '--help', '-h']);

package/dist/core/verdict/parser.d.ts

@@ -15,7 +15,9 @@ export declare function extractEvalBody(tokens: string[]): string | null;
 export declare function extractRecursiveScript(tokens: string[]): string | null;
 export declare function isBareInterpreter(tokens: string[]): boolean;
 export declare function splitTopLevelSegments(command: string): string[];
+export declare function splitStructuralShellSegments(command: string): string[];
 export declare function parseSegment(command: string): ParsedSegment;
 export declare function segmentOpacity(command: string): VerdictOpacity;
 export declare function substitutionInners(command: string): string[];
+export declare function structuralSubstitutionInners(command: string): string[];
 export declare function redactCommand(command: string): string;

package/dist/core/verdict/parser.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { findCommandSubstitutions } from '../shell-substitution.js';
+import { findCommandSubstitutions, findStructuralCommandSubstitutions, } from '../shell-substitution.js';
 import { commandKey, tokenizeShell } from '../shell-tokenizer.js';
 import { detectUnparseableShell } from '../shell-unparseable.js';
 const ENV_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S+)$/;
@@ -174,6 +174,97 @@ export function splitTopLevelSegments(command) {
     flush();
     return segments.filter((segment) => segment.trim().length > 0);
 }
+export function splitStructuralShellSegments(command) {
+    const segments = [];
+    let current = '';
+    const outer = { quote: null, escaping: false, backtick: false };
+    const substitutions = [];
+    const flush = () => {
+        const segment = current.trim();
+        if (segment) {
+            segments.push(segment);
+        }
+        current = '';
+    };
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index] ?? '';
+        const next = command[index + 1] ?? '';
+        const frame = substitutions.at(-1) ?? outer;
+        if (frame.escaping) {
+            current += char;
+            frame.escaping = false;
+            continue;
+        }
+        if (char === '\\' && frame.quote !== "'") {
+            current += char;
+            frame.escaping = true;
+            continue;
+        }
+        if (frame.quote === "'") {
+            current += char;
+            if (char === "'") {
+                frame.quote = null;
+            }
+            continue;
+        }
+        if (char === '`') {
+            frame.backtick = !frame.backtick;
+            current += char;
+            continue;
+        }
+        if (frame.backtick) {
+            current += char;
+            continue;
+        }
+        if (char === '$' && next === '(') {
+            current += '$(';
+            substitutions.push({ quote: null, escaping: false, backtick: false });
+            index += 1;
+            continue;
+        }
+        if (frame.quote) {
+            current += char;
+            if (char === frame.quote) {
+                frame.quote = null;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            frame.quote = char;
+            current += char;
+            continue;
+        }
+        if (substitutions.length > 0 && char === ')') {
+            substitutions.pop();
+            current += char;
+            continue;
+        }
+        if (substitutions.length > 0) {
+            current += char;
+            continue;
+        }
+        if (char === '&' &&
+            (command[index - 1] === '>' || command[index - 1] === '<' || next === '>')) {
+            current += char;
+            continue;
+        }
+        const twoCharacterOperator = (char === '&' && next === '&') ||
+            (char === '|' && next === '|') ||
+            (char === '|' && next === '&');
+        if (twoCharacterOperator) {
+            flush();
+            index += 1;
+            continue;
+        }
+        if (char === ';' || char === '|' || char === '&' || char === '\n' || char === '\r') {
+            flush();
+            continue;
+        }
+        current += char;
+    }
+    flush();
+    return segments;
+}
 export function parseSegment(command) {
     const tokens = tokenizeShell(command);
     const { tokens: peeled } = peelTransparentWrappers(tokens);
@@ -210,6 +301,9 @@ export function segmentOpacity(command) {
 export function substitutionInners(command) {
     return findCommandSubstitutions(command);
 }
+export function structuralSubstitutionInners(command) {
+    return findStructuralCommandSubstitutions(command);
+}
 export function redactCommand(command) {
     return command
         .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [REDACTED]')