@poe-platform/safe-bash 0.1.800 → 0.1.802

package/README.md

@@ -75,6 +75,8 @@ the default registry’s GH/Git integration; add `ghCommands` explicitly where n
 The registry subpath supports ESM splitting without visiting the full aggregate.
 Its exports do not select the optional
 `op`, `node` or `safejs` plugins; add those only through their command entrypoints.
+Only registered commands are available; adding search commands does not enable unrelated tools.
+Use `agentCommands({ muscleMemory: true })` or individual command plugins to enable tools such as `bc`, `fd`, `sponge`, and `less`.
 Removing a registered command changes availability, while shared family code may
 remain bundled. Splitting dynamic
 imports changes initialization timing: every uploaded static chunk and Wasm asset
@@ -222,7 +224,7 @@ and other unsupported options remain unavailable.
 | --- | --- |
 | Browse | `pwd`, `ls` (including `-i`/`--inode` for provider-reported inode numbers, with `?` for unknown metadata; `-Q`/`--quote-name` and `--indicator-style=none/slash/file-type/classify`), `tree`, `find` (including `-H` to follow argument symlinks while keeping descendant links physical, and `-D tree` for virtual expression diagnostics; other debug modes are unsupported), `du`, `file`, `basename`, `dirname`, `realpath` (including lexical `-s`/`--strip`/`--no-symlinks`), `readlink` (including `-m`/`--canonicalize-missing`), `which` |
 | 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. |
+| 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 string indexes and records are byte-oriented. `sed` and `awk` regexes count UTF-8 characters by default and in UTF-8 locales; C/POSIX locales and `awk -b` select byte matching (locale precedence: `LC_ALL`, `LC_CTYPE`, `LANG`). `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`, `--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). |
@@ -390,7 +392,7 @@ unqualified.
 | Command | Plugin and configuration |
 | --- | --- |
 | `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). |
+| `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. Host, Connection, and Expect overrides are accepted; framing and proxy headers remain transport-controlled. 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 default to `createFetchTransport()`, which cannot enforce a separate connection timeout. Network registration without an authorizer denies requests. Quotas default to disabled in every runtime. `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, 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). |
@@ -639,6 +641,11 @@ one execution. `stdin` accepts a string, `Uint8Array`, or async byte source;
 `stdout`/`stderr` accept byte sinks. Results still buffer output when sinks are
 provided. Pass an `AbortSignal` as `signal` to cancel. [Option types](src/shell/types.ts).
 
+`RANDOM` produces values from 0 through 32767 and accepts a seed for repeatable
+sequences. `SECONDS` tracks elapsed whole seconds and accepts a new starting
+value. Assignments through arithmetic, `read`, and `printf -v` retain these
+behaviors; unsetting either variable removes its special behavior.
+
 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`,
@@ -725,7 +732,8 @@ time/environment commands, metadata, diff/patch, LLM providers, `yes`, `less`,
 `sponge`, `bc`, `htmlq`, `which`, `getopt`, `factor`, and `tsort`
 have unlimited resource budgets by default. Set individual family limits to opt
 in; setting one limit leaves the others unlimited. Explicit `Infinity` also
-disables a limit. Shell helpers expose `maxCdWork`, `maxCdProbes`,
+disables a limit. Standard and agent command factories accept `maxRecursiveDirectoryDepth`
+for recursive filesystem traversal; it defaults to unlimited. Shell helpers expose `maxCdWork`, `maxCdProbes`,
 `maxCdPathBytes`, `maxCdPathComponents`, `maxDirectoryStackEntries`,
 `maxDirectoryStackBytes`, `maxDirectoryDiagnosticBytes`, `maxDirectoryStackOutputBytes`, `maxSyntaxDepth`, `maxAdmittedHandles`, `maxDescriptorOperations`, `maxDescriptorReadBytes`, `maxGlobstarStates`, `maxGlobstarDepth` and
 `maxGlobstarEntries`. Env split limits are supplied through
@@ -737,7 +745,10 @@ 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
+the command-size quota. Without `-n`, argument count does not split `xargs` batches;
+command-size and explicit line limits still apply. `-I` followed by `-n 1` preserves
+replacement mode; `-L` and other `-n` values select the last requested batching mode.
+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.
@@ -803,7 +814,7 @@ and credential protections remain in effect.
   background jobs/job control, `exec`, process substitution,
   associative arrays, or C-style `for ((…))` loops. `shopt` supports `dotglob`,
   `globstar`, `nullglob`, `nocaseglob`, and `nocasematch`, plus `-o` for supported
-  `set` options. `extglob` can be queried, printed, or unset; enabling it is unsupported.
+  `set` options. `shopt -s extglob` enables extended patterns, including parameter trimming.
 - Utilities implement subsets of their native counterparts' flags and behavior.
   There is no `git`, `npm`, `npx`, or fallback to installed host programs.
   The opt-in `node` command is not a general Node.js runtime.