threecode/shell

Search:
Group by:

Shell command analysis for the read cache.

Does NOT run any commands - pure parsing only. Tokenizes shell snippets and extracts the mutation target (if any) so the read cache can invalidate stale entries when a file is written via shell (sed -i, tee, cp, mv, etc.) rather than the write/patch tools.

Procs

proc bashMutationPath(cmd: string): string {....raises: [], tags: [], forbids: [].}

Best-effort: return the first file path that this bash command would mutate, or "" if no mutation pattern matches. Surfaces sed -i and similar so the read cache knows the file changed even when the model never emits a dedicated write action.

Recognised patterns (per top-level statement):

  • explicit redirect: > path, >> path, >path, >>path
  • sed -i, perl -i (file is the last positional)
  • tee [-a] path
  • cp/mv path... DEST (destination is the last positional)
  • rm path, touch path
proc bashReadPath(cmd: string): tuple[path: string, fullFile: bool] {.
    ...raises: [], tags: [], forbids: [].}
Best-effort: return the file path of a pure single-statement read command, with fullFile = true for cat path (the only form eligible for cache-dedupe of unchanged-since-last-read). Returns ("", false) on anything compound, piped, redirected, or unrecognised. Used to:
  • port the read-cache stale-write guard onto cat/sed-n (so patch after an external edit still errors)
  • dedupe a re-read of an unchanged file
proc shellTokens(s: string): seq[string] {....raises: [], tags: [], forbids: [].}
Tokenize a shell snippet by whitespace, honoring single + double quotes. Backslash-escapes the next character outside quotes. Not a real shell parser — used only for path extraction for the read cache.
proc splitStatements(cmd: string): seq[string] {....raises: [], tags: [],
    forbids: [].}
Split on top-level ;, &&, ||, | (not inside quotes). Pipeline stages count as separate statements so tee/sed -i mid-pipeline still get extracted. Background & is left alone.