# @effected/shell A tolerant shell-syntax lexer and segmenter: `ShellSyntax.parse(input)` returns a `ShellScript` of segments (simple commands split on `&&`, `||`, `;`, `|`, `|&`, `&`, the `case` terminators and newlines), each with its words, leading assignments and redirections, and words carrying their quoting provenance as typed parts. `ShellCommand.fromSegment` resolves a segment to its command name, unwrapping `sudo`, `env`, `command`, `exec`, `nohup` and `time`. `ShellScript.allCommands({ maxDepth })` parses every substitution body to the cap and records what lies past it as a `ShellTruncation`. Built for agent-hook guards that must know every command a Bash tool call would run. **Tier: pure.** `effect` is the only peer; no runtime dependency, no `node:` import, no service, no layer, `"sideEffects": false`. Never add a dependency: positions stay UTF-16 offsets, and a consumer that wants line/character uses `@effected/source` itself. `__test__/entrypoints.test.ts` pins the import set, the manifest and the export list. **Design doc:** `@./okf/modules/shell.md`. Why a package, why not core `CommandLine`, and the contract: `@./okf/decisions/shell-syntax-package.md`. Load when: changing the contract, the part kinds, the operator set, the wrapper list or the grammar's reach. ## The contract (load-bearing, never weaken) - **Never evaluate.** No expansion of any kind and no execution. An expansion is a marked part (`variable`, `commandSubstitution`, `arithmetic`, `processSubstitution`, `glob`, `brace`, `tilde`) with its span; bodies are opaque text. - **Never fail.** `ShellSyntax.parse` is total and synchronous; it returns a plain `ShellScript`, not a `Result`. Input the lexer cannot finish becomes an `opaque` part to the end of the input plus a `ShellDiagnostic`. No code path may throw on any input; the property test in `__test__/hostile.test.ts` holds it. - **Fail closed.** `ShellWord.literal` is `Some` only for bare, single-quoted, ANSI-C and expansion-free double-quoted parts. Adding a part kind means deciding whether it can be literal; the default is no. Where grammar is missing, over-split (report a command the shell might not run), never under-split. In particular never read a heredoc that may not be there: a spurious one hides the lines after it, a missed one only reports its body. A token whose meaning depends on an enclosing construct needs a test inside each construct, in both scanners, and the constructs come from the bash grammar, not from memory. For `<<` (a heredoc in command text, a shift in arithmetic) they are `(( ))`, `$(( ))`, `$[ ]` and the `[ ]` subscript of a command-position `NAME[` word; `let`'s operands are ordinary words, where `<<` is a heredoc. An argument `NAME=(`, `NAME+=(` or `NAME[…]=(` is a compound assignment only after a bare `declare`/`typeset`/`local`/`export`/`readonly`/`alias`/`eval`/`let` command word with no redirection since (`RawSegment.compoundAssignment`, bash's `PST_ASSIGNOK`); anywhere else bash rejects the `(` and the lexer splits it off as a subshell. bash reads on after an array's `)` into the same token, so `x=(a)#` holds no comment. Command position is bash's `reserved_word_acceptable`, not a local notion: the lexer's `Follows` states carry `time -p`, `time --`, `function NAME`, `coproc NAME`, `[[ … ]]`, `((…))` and `for NAME`. `\⏎` is gone before bash tokenizes, except in a comment, single quotes, after an escaping backslash or in a quoted heredoc body: every lookahead that joins two characters goes through `skipContinuations`, in both scanners and in `heredoc.ts`. A heredoc delimiter holding an expansion opener reads no body (`ExpansionInHeredocDelimiter`), since bash rebuilds `$( … )` from its parse. Any `$` or backtick that reaches `${…}`, arithmetic or a subscript (array keys included) quoted or escaped records `QuotedSubstitutionInExpansion`, whatever follows it: in a `'…'` run, in a `$'…'` run after decoding (`ansiCRunHoldsOpener`), as a literal `$` in a `"…"` run directly inside the frame (`"$"`, `"a$"`, not the `$` of `"$HOME"`), or after a backslash (`\$`, `` \` ``, in the frame or in such a `"…"` run). So does a bare `$` in the frame whose next character, through `\⏎`, is a backslash before `(` or a backtick: removing it leaves `$(` (`x=([$\(cmd\)]=1)` runs `cmd`; `$\n`, `$\{` and a top-level `echo $\(cmd\)` run nothing and record nothing). `$$` and the other special parameters in a `"…"` run are expansions, not literal `$`s (`"$$$"` is `$$` and then a literal `$`). bash honours the quoting to find the closer, then removes it and reads the text again in a double-quoted or heredoc `${…}`, in arithmetic and in an indexed array's key, so the `$` joins whatever follows it, the next run included: `echo "${x:-'$(cmd)'}"`, `"${x:-"$"(cmd)}"`, `"${x:-$'\x24'(cmd)}"`, `x=(['$'(cmd)]=1)` and `x=([\$\(cmd\)]=1)` each run `cmd`. Reported in every such frame, quoted or not, rather than placed as a substitution, since the operator and quoting that keep it literal, and what the `$` joins, are not modelled; a quoted `$` there is rare in real commands, and an over-report beats a hide. A top-level word is not read again, so `$'\x24(cmd)'`, `"$""(cmd)"` and `\$'(cmd)'` stay the literal `$(cmd)` with no diagnostic. Honouring the quote to find the closer is bash's default mode only: POSIX mode (`set -o posix`, `POSIXLY_CORRECT`) takes a `'` in a double-quoted `${…}` for a plain character, so `echo "${x:-'}"; cmd; echo "'}"` runs `cmd`. `nested.ts` tracks per frame whether it sits in double quotes (a `"` frame sets it, command text clears it, expansion frames inherit it, the root's comes from the lexer's `inDoubleQuotes`), and a run there that the POSIX reading leaves unbalanced (`posixReadingDiffers`: a stray `}`/`]`, or an open `"`/`${`/`$[`) records `QuotedCloserInExpansion`. - **Every substitution is reachable.** Any part that can hold a `$(…)`, backtick or `<(…)` carries `substitutions` (or `expansions`), and `ShellScript.substitutions()` names every part kind in an exhaustive switch. A new part kind that can hold one must join that switch. `ShellScript.allCommands` walks those bodies to `maxDepth` (default `ShellScript.defaultMaxDepth`, 16) and records each substitution past the cap as a `ShellTruncation` (reason `"depth"`), never dropping one: a guard refuses a walk whose `truncated` is `true`. `substitutions()` can list a substitution beside the substitutions inside it (a `$((a) …)` falling back to a command substitution in arithmetic, a subscript, `${…}` or `$[…]`), so the walk never trusts the listing for its cost: it parses each distinct substitution once, keyed by its span in its frame (breadth first, so the first sighting is the shallowest), and enforces a budget of `maxDepth` × the input in body characters, capped at `walkCharacterLimit` (64 MiB) and `walkRecordLimit` (10,000 scripts and truncations together) scripts, recording the body that would pass it as a `"budget"` truncation and stopping. Never dedupe overlapping parts to the outermost: an inner part can be one the outer body's parse never yields. The cost model and the measurements behind the default are a decision in `okf/modules/shell.md`; never change the default without re-measuring real nesting and hostile cost, never derive the bound instead of enforcing it, and never make the walk drop a substitution. The walk stays eager, and the package caps no input size: both were measured and ruled out in #1288 (the okf module's "Laziness and the size gate"), since an adversary moves a guard's first refusal to the deepest script and the affordable size is the consumer's hook timeout. - **Not `CommandLine.Word`.** The result types must never become core's execution vocabulary. ## Known limits This was checked against GNU bash 5.3 only, with the reviewed shapes, every position of a backslash-newline in them, and a random differential fuzz. That is evidence, not proof: dash and zsh were not tested, and POSIX-mode bash only for the quote rule above. A guard must not treat `commands()` as a complete gate until these are closed. Three parser modes hide a command with no diagnostic: under `shopt -s extglob` (or an inherited `BASHOPTS`), `echo @(<