@poe-platform/safe-bash 0.1.798 → 0.1.800

package/README.md

@@ -1,6 +1,6 @@
 # safe-bash
 
-Run shell scripts and command-line tools in your application against an explicit filesystem, without launching a host shell.
+Run shell scripts and command-line tools in your application against an explicit filesystem, without launching a host shell. The root `posixPath` export shares the portable safe-fs helpers; native POSIX paths remain available from the Node contract entries.
 
 Import `ffmpegCommands` from `@poe-platform/safe-bash` and register
 it with `shell.use(ffmpegCommands())` for in-memory media conversion and probing.
@@ -48,6 +48,8 @@ Creation modes use the filesystem's capabilities; advisory modes do not enforce
 physical permissions, and the host process mask remains unchanged.
 Core and shell imports install a portable `globalThis.Buffer` when it is absent;
 an existing host Buffer is preserved. Workers do not need `nodejs_compat` for this.
+AES ZIP encryption and decryption also work in browsers and Workers. The
+`@poe-platform/safe-bash/trap` entry selects the portable signal catalog there.
 
 For an application that selects its commands, import `Shell` and `CommandRegistry`
 from `@poe-platform/safe-bash/shell`, then compose plugins with `shell.use()`:
@@ -120,7 +122,7 @@ in workerd and reports cold runtime/setup, first use, repeat use and cleanup
 measurements. Python uses an injected asynchronous executor in this loader
 regression; LLM uses a synthetic provider, without external model calls.
 
-All private command plugins are available from `@poe-platform/safe-bash/core` in portable browser and workerd environments. Each command exposes its plugin, `create<Name>Commands`, `create<Name>Command`, `<Name>CommandsOptions`, and `<Name>Limits`; factories construct commands without registering them.
+All private command plugins are available from `@poe-platform/safe-bash/core` in portable browser and workerd environments. Each command exposes its plugin, `create<Name>Commands`, `create<Name>Command`, `<Name>CommandsOptions`, and `<Name>Limits`; factories construct commands without registering them. Standalone `sed`, `awk`, `find`, `diff`, `patch`, `tar`, `zip`, `unzip`, `gzip`, `curl`, and `wget` imports use `@poe-platform/safe-bash/commands/<name>`. Standalone network factories deny requests unless an `authorize` callback permits them.
 
 ### Shell syntax
 
@@ -134,7 +136,8 @@ All private command plugins are available from `@poe-platform/safe-bash/core` in
   redirection such as `2>&1`, here-documents, and here-strings. `<>` opens without
   truncation and requires a filesystem with descriptor support.
 - `if`/`elif`/`else`, `case`, `for name in …`, `while`, `until`, functions,
-  groups `{ …; }`, subshells `( … )` (including adjacent nested subshells),
+  groups `{ …; }`, subshells `( … )` (including adjacent nested subshells and
+  `BASH_SUBSHELL` nesting levels),
   `[[ … ]]` (including file age/identity, special-file, mode and nameref
   predicates; ordering uses byte comparison in C/POSIX and host Intl collation
   in supported UTF-8 locales. Literal/glob and ASCII ERE comparisons also accept UTF-8 locales,
@@ -221,7 +224,7 @@ and other unsupported options remain unavailable.
 | Files | `mkdir`, `touch`, `cp`, `mv`, `rm`, `rmdir`, `ln`, `chmod`, `stat`, `mktemp`. `mkdir -m` accepts octal and symbolic permission modes; symbolic modes start from `0777` masked by the current umask. `rm --interactive=never` removes without prompting; `--interactive=always` / `-i` reads a confirmation from stdin for each removal. `--interactive=once` / `-I` prompts once for recursive removal or more than three operands. `cp -a` / `--archive` copies directory trees without dereferencing symbolic links (the virtual archive profile is `-RP`; add preservation flags for metadata and hard links). `cp -b` / `--backup[=simple\|numbered\|existing]` preserves replaced files; `-S` / `--suffix` sets the simple backup suffix. `cp -t DIR` / `--target-directory=DIR` copies sources into a directory; `-T` / `--no-target-directory` treats the destination as a single path. `mv -u` / `--update` moves files only when the destination is absent or older; directories retain normal move behavior. `mv -t DIR` / `--target-directory=DIR` moves sources into an existing directory; `-T` / `--no-target-directory` treats the destination as an exact path. `cp --remove-destination` removes destination entries before copying, preserving other hard links and leaving destination symlink referents untouched. `cp --preserve=mode` retains permissions; `-p` retains modes and access/modification times and requires matching reported owners. `-d` copies symlinks and preserves links between copied entries. `--attributes-only` leaves existing bytes intact and creates empty missing files; combine it with preservation flags to update metadata. Unsupported metadata operations fail explicitly; ownership changes and symlink timestamps are unavailable. `cp -v` reports paths using the original operand spelling, including relative paths. `ln -sr` / `--symbolic --relative` computes a relative symlink target from the link directory, resolving existing symlinks and allowing missing sources. `ln -v` / `--verbose` reports each successful link as 'target' => 'source' (hard) or 'target' -> 'source' (symbolic). `rmdir --ignore-fail-on-non-empty` leaves nonempty directories untouched without reporting a failure; with `-p`, removal stops at the first nonempty parent. `touch -h` / `--no-dereference` accepts ordinary files and reads reference symlink metadata; symlink targets fail explicitly because symlink timestamp mutation is unavailable. `touch -d` / `--date` accepts epoch seconds (`@0`), ISO/RFC dates and the virtual `date` relative-date profile; `-t [[CC]YY]MMDDhhmm[.ss]` sets a calendar timestamp. |
 | Filter/search | `cat`, `head`, `tail`, `wc`, `tee`, `cut`, `tr`, `sort`, `uniq`, `sed`, `awk`, `grep`, `rg`, `egrep`, `fgrep`, `fd`. `fd` finds virtual files and directories with regex/glob patterns, extension/type/size/time filters, ignore files, and literal command execution; see [fd usage](../safe-bash-command-fd/README.md). `awk` accepts `--field-separator` (`-F`), `--source` (`-e`), and `--characters-as-bytes` (`-b`); its strings and records are byte-oriented. `cut -c` selects raw bytes in C/POSIX locales (`LC_ALL`, then `LC_CTYPE`, then `LANG`); otherwise it selects UTF-8 characters, including when no locale is set. `head` and `tail` accept `-z` / `--zero-terminated` for NUL-delimited records. `tail --follow[=descriptor\|name]` follows retained files; `--retry` retries inaccessible files (`-F` combines name following and retry). `-s` / `--sleep-interval` sets polling seconds, and `--max-unchanged-stats` controls name reopening after unchanged polls; `--max-idle=0` emits only the initial selection. Following requires retained-read filesystem support. `uniq -D` / `--all-repeated[=none\|prepend\|separate]` prints every repeated record; `--group[=separate\|prepend\|append\|both]` prints all records with group separators. `wc -L` / `--max-line-length` counts display columns with eight-column tab stops; UTF-8 widths use the frozen GNU/Linux C.UTF-8 profile. |
 | Format/combine | `nl`, `seq`, `rev`, `tac`, `expand`, `unexpand`, `fold`, `fmt`, `strings`, `paste`, `comm`, `join`, `column`, `split`, `pr`. `pr --date-format=FORMAT` customizes the UTC header date using the virtual `date` format directives. |
-| Structured text | `jq`, `html-to-markdown`, `xq`, `xmllint`, `mdq`. `mdq` extracts Markdown sections and elements, with Markdown, JSON and plain output; see the [query syntax and limits](../safe-bash-command-mdq/README.md). `xq` converts XML to JSON and applies jq filters. `xmllint` supports `--xpath`, `--noout` well-formedness checks, `--format`, and `--c14n` with comments; DTDs and schema validation are unsupported. [XML modes and limits](docs/XML_QUERY.md). `jq` supports ASCII escapes (`-a`), indentation (`--indent`, `--tab`), explicit color (`-C` / `-M`), NUL-delimited raw output (`--raw-output0`), and unbuffered writes. `jq -S` / `--sort-keys` sorts object keys recursively in JSON output; `--stream` / `--stream-errors` emit path events, and `--seq` handles JSON sequences within the same resource limits. `--rawfile NAME FILE` binds virtual-file text; `--slurpfile NAME FILE` binds its JSON values as an array. `--args` and `--jsonargs` expose string or JSON arguments through `$ARGS.positional`. `jq -L DIRECTORY` loads virtual `.jq` modules with zero-argument definitions; see [jq options and limits](src/commands/structured/README.md). |
+| Structured text | `jq`, `html-to-markdown`, `xq`, `xmllint`, `mdq`. `mdq` extracts Markdown sections and elements, with Markdown, JSON and plain output; see the [query syntax and limits](../safe-bash-command-mdq/README.md). `xq` converts XML to JSON and applies jq filters. `xmllint` supports `--xpath`, `--noout` well-formedness checks, `--format`, `--noblanks`, `--output` / `-o`, `--recover`, `--encode`, and inclusive/exclusive canonicalization (`--c14n` / `--exc-c14n`) with comments; DTDs and schema validation are unsupported. [XML modes and limits](docs/XML_QUERY.md). `jq` supports ASCII escapes (`-a`), indentation (`--indent`, `--tab`), explicit color (`-C` / `-M`), NUL-delimited raw output (`--raw-output0`), and unbuffered writes. `jq -S` / `--sort-keys` sorts object keys recursively in JSON output; `--stream` / `--stream-errors` emit path events, and `--seq` handles JSON sequences within the same resource limits. `--rawfile NAME FILE` binds virtual-file text; `--slurpfile NAME FILE` binds its JSON values as an array. `--args` and `--jsonargs` expose string or JSON arguments through `$ARGS.positional`. `jq -L DIRECTORY` loads virtual `.jq` modules with zero-argument definitions; see [jq options and limits](src/commands/structured/README.md). |
 | Bytes/checksums | `base64`, `base32`, `xxd`, `od`, `md5sum`, `sha1sum`, `sha256sum`, `cksum`. `od -a` prints ASCII character names, `-f` prints IEEE single-precision floats, and `-i` / `-l` print signed four/eight-byte integers. Explicit float types are `-tf4` and `-tf8`. `od --strings[=MIN]` / `-S[MIN]` prints NUL-terminated strings with at least MIN characters (default 3). |
 | Archives | Tar extraction to the filesystem requires atomic backend confinement; MemoryFileSystem supports it, while backends without it refuse extraction. `tar -xO` remains available. `gzip`, `gunzip`, `zcat`, `tar`, `zip`, `unzip`. ZIP inspection supports `unzip -Z -1 ARCHIVE [FILES...]` for names only and `unzip -z ARCHIVE` for the archive comment, without extracting members. Other ZipInfo formats are unsupported. Tar supports gzip (`-z`), bzip2 (`-j`), xz (`-J`), suffix-selected creation (`-a`), and compression detection when reading. Creation accepts `--mtime=@SECONDS` or ISO/RFC dates, numeric `--owner`/`--group`, and octal `--mode`; `--atime-preserve[=replace]` restores source file and directory access times on timestamp-capable backends. Extraction accepts `--touch`/`-m`, `--same-permissions`/`--preserve-permissions`/`-p`, `--no-same-permissions` (virtual 022 mask), `--no-same-owner`, and directory restoration policies. Special permission bits remain stripped; ownership restoration (`--same-owner`), name lookup, symbolic modes and no-atime reads (`--atime-preserve=system`) are unsupported. `--full-time` shows UTC timestamps in verbose listings; `--utc` also enables verbose listing. `--record-size=SIZE` / `-b N` sets output record padding, `-B` accepts full-record reads, and `--ignore-zeros` / `-i` reads past zero blocks and concatenated archives. `--seek` / `-n`, `--no-seek`, and `--force-local` accept local VFS archives with sequential reads. `--quoting-style=literal\|escape\|c` controls displayed names; `--totals` reports archive byte counts on stderr. Extraction supports `-k` / `--keep-old-files` (preserve conflicts and return status 2), `--skip-old-files` (preserve silently), and `--overwrite` (default safe replacement); the last policy wins. Existing directories are merged. Path, symlink and input-archive safety checks apply to every policy. |
 | ZIP archives | `zip`, `unzip`. File extraction requires atomic ancestry verification; MemoryFileSystem supports it, while unsupported backends refuse extraction. `unzip -n` preserves existing regular files without prompting; `-j` flattens paths and skips directory entries. Selection uses original archive names. Overwrite, traversal, symlink and backend capability checks still apply. |
@@ -325,10 +328,12 @@ It preserves original UTF-8 byte offsets and supports case/word selection on ASC
 subjects, plus bounded ASCII globs for path and ignore filtering. Unicode case/word
 selection, Unicode regex syntax, escape extensions, lazy repetition and invalid
 UTF-8/NUL subjects require a configured regex executor; unsupported profiles fail
-explicitly. Literal replacement, trimming, file-size limits, depth aliases and
+explicitly. Replacement supports `$0`, numbered and named captures (`$1`, `${1}`,
+`$name`, `${name}`), and `$$` for a literal dollar sign. Unknown or unmatched groups
+expand to empty text. Replacement, trimming, file-size limits, depth aliases and
 explicit virtual ignore files are supported. `--threads` accepts a count while
-execution stays serial; `--multiline` admits line-compatible searches, with
-cross-line patterns still rejected by the bounded matcher.
+execution stays serial; `--multiline` supports cross-line patterns and capture
+replacement through the default portable matcher.
 
 Default `grep`, `egrep` and `fgrep` preserve arbitrary subject bytes for fixed
 matching and ASCII patterns without regex syntax, including NUL and invalid UTF-8
@@ -367,8 +372,9 @@ Portable plugins for media, PDFs, spreadsheets and text are available from both
 and option types. The `/commands/...` subpaths remain available for command-specific
 SDKs and helpers. Both main entry points share the portable `posixPath` API.
 
-`mikeYqCommands()` from `/commands/yq` enables bounded Mike-style format
-conversion: `yq -p csv -o json . records.csv` reads a table, and
+`mikeYqCommands()` is exported from the package root, core, and `/commands/yq`.
+It enables bounded Mike-style format conversion: `yq -p csv -o json . records.csv`
+reads a table, and
 `yq -o csv . records.yaml` writes one. Input and output support CSV, TSV,
 properties, XML, INI, TOML, base64 and URI; shell and Lua are output only.
 See the [format profile](src/commands/yq/FORMATS.md) for supported shapes and limits.
@@ -386,7 +392,7 @@ unqualified.
 | `dos2unix`, `unix2dos` | `lineEndingCommands({ limits?, replace? })` from `/commands/line-endings`: byte and UTF-16 line-ending conversion. Use `-e` / `--add-eol` to terminate the final line, `-O` / `--to-stdout` to convert without rewriting inputs, and `-i[FLAGS]` / `--info[=FLAGS]` to inspect line endings, BOM and text/binary status. `-v` prints conversion details. In-place conversion requires safe publication capabilities and preserves reported ownership; `--allow-chown` permits publication when ownership cannot be preserved, and `--no-allow-chown` restores the default. |
 | `curl`, `wget` | `networkCommands({ authorize, transport?, limits?, replace? })`: required authorization on every request, redirect, and retry. Curl's `-r/--range` requests byte ranges. Wget supports `--header 'NAME: VALUE'`, `--user-agent`, `--referer`, `--post-data`/`--post-file` and `--method` with `--body-data`/`--body-file`; body files come from the VFS and retain their bytes. Repeated wget headers replace earlier values by name; `--header=''` clears custom headers, and `NAME:` sends an empty value. Transport-controlled headers are rejected, and custom headers are dropped after crossing origins. Node uses the native HTTP transport and supports curl's `--connect-timeout` for DNS/TCP/TLS setup. Workers can inject `createFetchTransport()`, which cannot enforce a separate connection timeout. `createOriginAuthorizer([...])` provides exact origin/hostname policy; its omitted allowlist is deliberately `*` (allow all). [Options and limits](src/commands/network/types.ts). |
 | `node` | `nodeCommands({ runtime, limits?, replace? })`: runs JavaScript with an injected SafeJS runtime, virtual files, and shell streams. [Usage and supported subset](src/commands/node/README.md). |
-| `python`, `python3` | `pythonCommands({ createExecutor })` from `@poe-platform/safe-bash/commands/python`: supply an explicit executor for invocation-local Python, filesystem I/O and shell streams. Open-file, directory, worker-capacity, input-fragment, package-download and cache quotas are unlimited by default; configure individual budgets when needed. [Executor and ownership contract](src/contracts/python-executor.md). Invocation capabilities include `createPythonLlmCapability(context, service)` for the same authorized model service and `createPythonShellCapability(context)` for enabled commands. The bundled [Python LLM client](docs/python-llm.md) supports canonical streamed attachments, shared named templates and a typed saved-configuration snapshot. |
+| `python`, `python3` | `pythonCommands({ createExecutor })` from `@poe-platform/safe-bash/commands/python`: supply an explicit executor for invocation-local Python, filesystem I/O and shell streams. Open-file, directory, worker-capacity, input-fragment, package-download, cache and manifest-store quotas are unlimited by default; configure individual budgets when needed. [Executor and ownership contract](src/contracts/python-executor.md). Invocation capabilities include `createPythonLlmCapability(context, service)` for the same authorized model service and `createPythonShellCapability(context)` for enabled commands. The bundled [Python LLM client](docs/python-llm.md) supports canonical streamed attachments, shared named templates and a typed saved-configuration snapshot. |
 | `llm` | `llmCommands({ providers, defaultModel?, replace? })` or `llmCommands({ service, replace? })`: opt-in model routing, sandbox attachments and streamed text/binary output. Includes injected-transport OpenAI and ElevenLabs reference providers. [Configuration and provider contract](src/commands/llm/README.md). |
 | `pdfinfo` | `/commands/pdfinfo`: opt-in `pdfinfoCommands({ replace? })` registering `pdfinfo`, `pdftoppm`, `pdfimages`, `pdfunite`, and `pdfseparate` powered by `@poe-code/pdf-ast`. Supports Poppler metadata, page geometry, `-box`, `-isodates`/`-rawdates`, `-custom`, `-meta`, `-url`, `-js`, `-struct`/`-struct-text`, `-dests`, page rasterization (`pdftoppm`), image listing/extraction (`pdfimages`), PDF merging (`pdfunite`), and page splitting (`pdfseparate`). |
 | `pdftoppm` | `/commands/pdftoppm`: opt-in `pdftoppmPlugin({ replace? })` and `createPdftoppmCommand` powered by `@poe-code/pdf-ast`. Renders PDF pages to `.png`, `.ppm`, `.pgm`, `.pbm`, or `.svg` with configurable `-r`/`-rx`/`-ry` DPI, `-f`/`-l` page ranges, `-singlefile`, `-sep`, and `-x`/`-y`/`-W`/`-H`/`-cropbox` sub-region cropping. |
@@ -425,8 +431,10 @@ HTML projections preserve pinned separators and lazy first-match removals.
 Explicit engine limits and cancellation are required. Private implementation and
 types ship inside safe-bash. Full HTML5 recovery, selector grammar and Rust URL
 parity remain unqualified; modern `:is/:where/:has/:lang` are explicitly rejected.
-Use `--attributes` (plural) for attribute output; no-match succeeds with empty
-output. Scripts/styles remain inert and preserved; interior BOMs are retained
+Use `--attribute` (`--attributes` is also accepted) for attribute output, and
+`-w` (`-i` is also accepted) to ignore whitespace-only text. Multiple selector
+operands combine in document order; no-match succeeds with empty output.
+Scripts/styles remain inert and preserved; interior BOMs are retained
 regardless of input chunking, correcting the pinned upstream defect.
 Node.js 22+ is qualified; browser/workerd conditional graphs are checked
 in Node, while actual engines remain unverified. See the
@@ -635,12 +643,14 @@ Execution quotas are unlimited by default. Set individual `limits` to opt in;
 supplying one does not enable other quotas. Available quotas are `maxParseUnits`,
 `maxInputBytes`, `maxOutputBytes`, `maxCommands`, `maxFileSystemOperations`,
 `maxPathComponents`, `maxPathnameComponents`, `maxRedirects`, `maxPipelineStages`, `maxLoopIterations`,
-`maxSubstitutionDepth`, `maxSourceBytes`, `maxExpansionFields`, `maxExpansionBytes`,
+`maxSubstitutionDepth`, `maxFunctionDepth`, `maxSourceBytes`, `maxExpansionFields`, `maxExpansionBytes`,
 `maxWallClockMs`, and `maxCpuMs`. The CPU deadline measures elapsed time including
 waits at cooperative checkpoints. `pipeHighWaterMark` defaults to 64 KiB for
 streaming backpressure and does not cap total work. `cloudflareWorkerLimits` is
 an explicit restrictive preset. Background job quotas (`maxJobs`, `maxWaiters`,
-`maxCleanupsPerJob`) are also unlimited unless supplied.
+`maxCleanupsPerJob`) are also unlimited unless supplied. `maxFunctionDepth` limits
+simultaneously active shell functions independently of substitution depth; zero
+rejects function calls, and completed calls free their depth slot.
 
 Always call `dispose()` when finished. Shell failures normally produce an exit
 code and stderr; limit violations, cancellation, and host failures can reject `exec()`.
@@ -704,7 +714,8 @@ through `maxArguments`, `maxArgumentBytes`, and `maxOutputBytes`.
 `timeEnv.maxTimerMilliseconds` and `timeout.maxTimerMilliseconds` accept `Infinity`;
 host timer calls remain capped at 2147483647 ms and progress with frozen clocks.
 Use the [typed options and linked family interfaces](src/plugins/index.ts) for
-their individual limits and hooks, including clocks and schedulers. Family budgets
+their individual limits and hooks, including clocks and schedulers. Command and
+shell work quanta yield to the host even when its clock is frozen. Family budgets
 are separate from shell counters; `limits.commandLimits.archive` supplies
 invocation ceilings. Per-execution family overrides merge with the shell's
 profile, and non-Worker hosts can configure larger limits. `replace` applies
@@ -721,15 +732,20 @@ disables a limit. Shell helpers expose `maxCdWork`, `maxCdProbes`,
 `execution.envSplitLimits`; env shebangs use `maxEnvSplitBytes`, `maxEnvSplitArguments`, `maxEnvSplitExpansions`, and `maxEnvSplitWork` in Shell limits; truncate uses `metadata.limits.maxArguments`.
 Browser controller structural ceilings (configuration, snapshots, output files,
 recording, traces, routes and WebMCP) are also optional `limits`; WebMCP discovery uses the optional `webMCPDiscoveryTimeoutMs` deadline, disabled by default; viewport dimensions and operation receipt count/age use `maxViewportDimension`, `maxOperationOutcomes`, and `maxOperationOutcomeAgeMs`, also unlimited by default; network and
-route-policy byte/count ceilings default to `Infinity`. `xargs -s Infinity` and `--max-chars=Infinity` explicitly remove
+route-policy byte/count ceilings default to `Infinity`. Browser action, snapshot,
+navigation, and code execution deadlines are disabled by default; configure
+`limits.actionTimeoutMs`, `limits.codeExecutionTimeoutMs`, or session timeouts
+to bound them. `Infinity` disables host deadlines and maps to the native
+Playwright timeout value `0`. `xargs -s Infinity` and `--max-chars=Infinity` explicitly remove
 the command-size quota. Stream chunk sizes and polling intervals control execution
 independently of these quotas. `diff -u /dev/null FILE` and its reverse produce
 creation/deletion patches; top-level readable character and FIFO inputs are
 read to EOF. Regular files retain identity-checked reads.
 
 The package root exports `createBoundedRegexProvider`, `BoundedRegexProvider`,
-and `BoundedRegexProviderOptions`. `agentCommands()` uses this provider by default;
-pass `regexExecutor` to configure its resource limits explicitly:
+and `BoundedRegexProviderOptions`. `portableSearchCommands()` and `agentCommands()`
+use this provider by default. Pass `regexExecutor` to `agentCommands()` to configure
+its resource limits explicitly:
 
 ```ts
 import { agentCommands, createBoundedRegexProvider } from "@poe-platform/safe-bash";