buninu 0.4.18 → 0.4.20

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.20 - 2026-10-13
+
+- Sync bunmsh to 0.4.0:
+  * Add a pure JavaScript awk fallback, file diff with line alignment, cmp,
+    uniq, expr, and egrep/fgrep aliases; extend sed and other utility builtins
+    for configure scripts and compiler builds.
+  * Improve compound commands, here-documents, parameter expansion, function
+    and loop control, descriptor redirection, and pipeline/subshell state
+    transfer for Autoconf and GCC bootstrap workloads.
+  * In `set -o posix` mode, use plain ls output and pass only exported variables
+    and command-prefix assignments to external programs. Default mode retains
+    ls icons and its existing environment behavior.
+  * Preserve the existing background-process behavior and stable
+    `Bun.sha.procs` indices. POSIX and awk compatibility remain partial; see
+    the bundled bunmsh PORTING.md for limitations.
+- Sync jsgotty to 1.1.15: forward Kitty graphics to the terminal in `--client`
+  mode and avoid applying the corresponding cursor movement twice.
+
+## 0.4.19 - 2026-10-12
+
+- Sync bunmsh to 0.3.11: more POSIX syntax
+
 ## 0.4.18 - 2026-09-29
 
 - Sync jsgotty to 1.1.14: Kitty for Windows

package/apps/bunmsh/CHANGELOG.md

@@ -2,6 +2,137 @@
 
 All notable user-visible changes to bunmsh are documented here.
 
+## [0.4.0] - 2026-10-13
+
+### Added and fixed
+
+- Respect builtin cat output redirects in shell subprocesses, including AWK pipes.
+
+- Stream external stdout/stderr to the correct pipeline endpoint for `2>&1`,
+  `2>&1 >file` and `1>&2`, retaining downstream early-close handling.
+
+- Support `cp -p` for regular files, preserving ownership, mode and timestamps.
+
+- Evaluate `!` inside if/elif conditions with normal pipeline precedence,
+  including conditions joined with `&&` or `||`.
+
+- AWK supports parenthesized print lists, continued arguments and buffered
+  output command pipes through bunmsh. Correct function parameter scope and
+  preserve replacement backslashes; GCC option generators match mawk output.
+
+- Process mkdir operands in order so parent/child paths do not race.
+
+- Preserve here-document bodies when connecting commands to compound operands.
+
+- Distinguish backquoted brace groups from parameter expansions during tokenization.
+
+- Handle traditional set - as an option delimiter, preserving bare-call arguments.
+
+- Add byte-preserving adjacent-line uniq with -c/-d/-u and input/output files.
+- Ignore empty nonexistent filenames with rm -f, including libtool cleanup.
+
+- Recognize case/esac next to subshell parentheses, including nested groups.
+
+- Keep awk quoted operator strings as data, including install path concatenation.
+
+- Remove the backquote escape layer before parsing command substitutions.
+
+- Preserve short circuiting across comments before compounds and parse simple
+  pipeline stages before a trailing compound command.
+
+- Keep persistent read descriptors open and consume one line without read-ahead.
+- Expand positional parameter lengths such as libtool's ${#1}.
+
+- Support explicit-class chmod rwxX modes such as a-w and u+rw.
+
+- Recognize comments after else and loop-closing done as compound syntax.
+
+- Apply enclosing descriptor redirects to compound-producer pipeline output.
+
+- Add bytewise cmp, legacy egrep/fgrep names, and tr squeeze/delete combinations.
+- Adapt mv/rm -- for Bun Shell while protecting option-looking filenames.
+
+- Preserve multiline parameter expansion operands inside compound bodies.
+- Accept combined print flags such as Autoconf's -rn.
+- Preserve compound commands and function declarations after recipe continuations.
+
+- Match quoted literals and bracket patterns in parameter prefix/suffix removal.
+- Capture subshell state at execution time and scope its internal transport to
+  that command, preserving changes from earlier commands in the same list.
+- Treat interior ^ and $ as literals in basic regular expressions, including
+  GNU make build.sh object-extension substitutions.
+
+- Add a pure JavaScript awk fallback interpreter with fields, arrays, rules,
+  functions, loops, string/regex operations and file I/O. Input command pipes
+  and system() remain unsupported; full POSIX/GNU compatibility is not claimed.
+- Preserve multiline quoted operands after compound pipeline connectors, quoted
+  backslash-newlines, heredoc AND/OR continuations, and case terminators after groups.
+- Preserve ASCII control characters used as Autoconf awk separators during expansion.
+- Keep nested redirected compound operands when reconstructing pipelines.
+- Support sed r FILE, including end-of-cycle output and silently missing files.
+
+- Add offline system diff/sed reference fixtures so isolated tests can compare
+  output and exit status without depending on host executables in the guest.
+
+- Add file diff using the jsmdcui Myers line alignment, with separate insertion,
+  deletion and replacement hunks, binary notices and missing-final-newline markers.
+- Expand parameters and substitutions inside arithmetic, including Autoconf `$(( $* ))`.
+
+- In `set -o posix` mode, send only exported variables and command-prefix
+  assignments to external programs, while preserving complete internal state
+  for pipeline/subshell Bun children. Default mode still passes all variables.
+- Match newlines with case wildcards, including Autoconf POSIX-mode detection.
+- Keep heredoc contents out of subshell rewriting, support pipelines feeding
+  compound cases, accept operand-free rm -f, grep -e/-c, and sed -f.
+
+- Track command source lines, preserve quotes and argument boundaries in selected
+  parameter operands, and parse nested compound conditions and subshell cases.
+- Add expr and extend fallback sed with addresses, branches and hold-space edits.
+- Make `set -o posix` an observable option: only this mode removes fallback ls
+  icons and implicit directory suffixes. Normal ls and lsfancy retain icons.
+- Support ls inode/dereference options and sorting multiple file operands.
+- Transport large internal subprocess state through a private temporary file;
+  retain the full function AST and clean up after foreground execution.
+
+- Accept inline and next-line function braces, brace groups with redirects and
+  pipelines, multiline pipelines, and nested case clauses with here-documents.
+- Implement return and counted break/continue with function/source/loop boundaries.
+- Add persistent numeric fd bindings for exec, ordered duplication, scoped
+  restoration, and descriptor inheritance for external and subshell commands.
+- Add conditional errexit, nounset/noglob, xtrace, option queries, EXIT handlers
+  and deferred signal traps. See PORTING.md for the remaining POSIX boundaries.
+- Preserve the minimal background-command contract: original Bun.Subprocess
+  objects, append-only stable Bun.sha.procs indices, immediate return and unref;
+  no implicit waiting, killing or widening of accepted background syntax.
+
+## [0.3.11] - 2026-10-12
+
+### Fixed
+
+- Keep multiline quoted words, command substitutions and here-documents
+  together when parsing compound-command bodies, rather than treating their
+  continuation lines as separate commands or compound keywords.
+
+- Accept additional `if`/`elif` and `while`/`until` header layouts, including
+  `then` or `do` on the following line, and execute commands placed on the
+  same line after `then`.
+
+- Improve comment handling in compound keyword and case-arm scanning, and
+  include nearby source text in several compound-syntax error messages.
+
+### Added
+
+- Initial support for parenthesized subshell groups, executed in a child
+  bunmsh with inherited shell state, including groups embedded in command
+  sequences and leading groups followed by `&&`, `||` or `;`.
+  Subshell redirection is still limited: the leading-group path handles
+  discarding stdout/stderr to `/dev/null`, but does not yet implement
+  general file redirection or descriptor duplication.
+
+- Recognize general numeric output-descriptor duplication syntax such as
+  `3>&1`. Only the existing `1>&2` and `2>&1` handling is implemented for
+  ordinary commands; other numeric pairs are currently accepted but ignored.
+
 ## [0.3.10] - 2026-09-29
 
 ### Fixed

package/apps/bunmsh/PORTING.md

@@ -38,8 +38,28 @@ pseudo-terminal tests.
   Background pipelines, builtins, functions, and all redirections are rejected
   before files are opened. General asynchronous command lists, job control,
   and coprocesses are not implemented.
-- Brace command groups, `select`, arithmetic commands, and `[[ ... ]]` are
-  not implemented.
+  Compatibility invariant: keep the original `Bun.Subprocess` objects in an
+  append-only `Bun.sha.procs` array with stable indices, immediate return and
+  `unref()`. POSIX foreground work must not add implicit waiting, killing,
+  removal of completed entries, or a job-wrapper replacement.
+- Brace command groups run in the current shell, including scoped redirects
+  and group pipelines. `select`, arithmetic commands, and `[[ ... ]]` remain
+  unimplemented. Function opening braces may be on the same or next line;
+  inline bodies and nested case clauses are supported.
+- `return` stops at the function/source boundary; `break N` and `continue N`
+  unwind enclosing loops. Functions and sourced files establish their own
+  loop boundary, following mksh STOP_BRKCONT.
+- `set -e` uses a dynamically inherited error-ignore context for conditions,
+  non-final AND/OR commands and negation, following mksh XERROK. `set -u`,
+  `set -f`, `set -x`, option queries and corresponding CLI flags are supported.
+  `-v` currently prints initial CLI input only; it is not an incremental reader.
+  `set -o posix` is listed and stored as an option. It makes fallback `ls`
+  omit icons and automatic directory suffixes; `lsfancy` remains decorative.
+  External environments in this mode contain only inherited/exported names
+  and command-prefix assignments. Full variables and export attributes travel
+  with internal pipeline/subshell state, separately from the native environment.
+  Default mode continues passing all shell variables to external programs.
+  It does not imply full POSIX conformance.
 - Functions and subshells cover practical cases but do not yet reproduce every
   mksh scoping, local-variable, trap, and diagnostic edge case.
 - Pipelines isolate builtin/function state through subprocess copies. Changes
@@ -75,9 +95,17 @@ pseudo-terminal tests.
   pathname expansion, or tilde expansion, and a trailing newline is appended.
   It follows the same dash/`/bin/sh` comparison harness as everything else in
   this codebase, except `<<<` itself, since dash does not implement it.
-- Arbitrary descriptor allocation/manipulation, descriptor variables,
-  heredocs targeting a descriptor other than stdin, and every ordering edge
-  case remain incomplete.
+- Numeric file descriptors support file open, append, read/write (`<>`),
+  duplication and shell-level closure, with left-to-right redirect ordering.
+  `exec` without a command persists bindings. Compound/function redirections
+  restore only the descriptors they changed; native open handles retained by
+  another binding stay alive. External/pipeline children inherit extra fds
+  through Bun.spawn stdio. No native compiler or host shell is required.
+- Descriptor variables and heredocs targeting non-stdin fds are not implemented.
+  Closing a descriptor denies subsequent shell duplication/use, but Bun.spawn
+  maps a closed child stdio slot to `ignore` (/dev/null), not native EBADF.
+  Aliases of captured stdout/stderr passed as extra fds to an arbitrary external
+  program do not yet reproduce every pipe/capture ordering case.
 - External processes use `Bun.spawn`; regular and fallback builtins may execute
   in-process or in a self-spawned bunmsh pipeline child depending on streaming
   and state-isolation requirements.
@@ -96,13 +124,16 @@ pseudo-terminal tests.
 - Ctrl-D on an empty readline input sends EOF and exits the interactive shell.
   This is deliberately distinct from Ctrl-C, following the same high-level
   editor/main-loop separation used by mksh.
-- The current implementation handles SIGINT through readline while editing and
-  through a process signal listener while a foreground operation owns the
-  terminal. It does not yet have mksh's general pending-signal table and safe
-  trap checkpoints.
-- There is no `trap` builtin or support for user handlers for signals, `EXIT`,
-  or `ERR`. Signal handlers therefore cannot yet execute shell source, be
-  listed, ignored, reset, or inherited with POSIX/mksh semantics.
+- `trap` supports listing, reset (`-`), shell-local ignore (empty action),
+  EXIT/0 and catchable signal names/numbers. Signal callbacks enqueue handlers;
+  shell source runs at command boundaries, following mksh's pending-trap model.
+  Handlers preserve `$?`; EXIT runs once and can explicitly override status.
+  Shell finalization releases its fd resources and listeners, never background
+  subprocesses or Bun.sha.procs entries.
+- Complete native signal semantics are not claimed: ignored handlers do not
+  establish inherited SIG_IGN in external children, handlers waiting at an idle
+  interactive prompt run at the next command boundary, and there is no ERR trap,
+  process-group forwarding, `wait` integration or general builtin cancellation.
 - Status 130 is defined for an interrupted `serve`, and its SIGTERM path uses
   143. Signal-derived statuses are not yet normalised consistently for every
   external command, builtin, pipeline stage, and command substitution.
@@ -182,11 +213,11 @@ pseudo-terminal tests.
 
 ## Remaining major work
 
-1. Background jobs, process groups, complete signal-status handling, traps,
+1. General background jobs, process groups, complete signal/trap inheritance,
    general builtin cancellation, and `jobs`/`fg`/`bg`/`wait`.
-2. Shell options such as `errexit`, `nounset`, `pipefail`, `xtrace`, and POSIX
+2. Full shell-option edge cases, `pipefail`, incremental verbose input and POSIX
    mode, plus startup/login/restricted-shell files and modes.
-3. Brace groups, `[[ ... ]]`, arithmetic commands,
+3. `[[ ... ]]`, arithmetic commands,
    extended globs, process substitution, and fuller mksh expansion semantics.
 4. Arrays, associative arrays, namerefs, `typeset`/scope semantics, and more
    complete special builtins.
@@ -194,3 +225,90 @@ pseudo-terminal tests.
    `fc`, and automatic history policy.
 6. Broader POSIX conformance testing, mksh `check.t` coverage, exact diagnostics,
    and exit-status compatibility for edge cases.
+
+## Bootstrap compatibility verification (2026-10-13)
+
+Implementation reference: sibling `mksh/syn.c` (`function_body`/brace grammar),
+`exec.c` (TBRACE, XERROK, E_LOOP), `funcs.c` (c_exitreturn, c_brkcont, c_trap),
+and `histrap.c` (runtrap/cleartraps). The JavaScript execution and descriptor
+model is adapted to Bun; no C code or native signal/job-control layer is copied.
+
+`test/posix-bootstrap.test.js` covers finite control-flow, descriptor, trap,
+option and background-registry cases without requiring a reference shell.
+Tests were run with musl Bun 1.4.2 in `bunproot -r rfs1`. The guest's `/bin/sh`
+is itself bunmsh, so reference.test.js comparisons there would not constitute
+an independent POSIX oracle.
+
+The next configure compatibility batch adds physical source-line tracking for
+ordinary commands and nested function/case bodies, quoted parameter operands
+(including `${1+"$@"}`), compound conditions containing nested groups/if, and
+multiline subshells containing case clauses. LINENO handling is not yet complete
+for every condition, eval, subshell, or user-assignment edge case.
+
+The sed fallback now has addresses/ranges, labels/branches, pattern/hold-space
+operations, and text commands; expr provides arithmetic/comparison/BRE matching.
+File diff uses the jsmdcui Myers alignment and normal-format change hunks;
+directory comparison and unified/context output are not implemented.
+Subprocess state still includes the complete function AST. Large internal state
+uses a private temporary file cleaned by the spawning foreground process. This
+avoids the observed bunproot environment-string limit without changing the
+Bun.sha.procs registry or background process lifecycle.
+
+GNU make 4.4.1 configure validation is ongoing; no complete run is claimed.
+Its LINENO/re-exec blockers and large unexported test-source environment values
+have dedicated regressions. Autoconf's multiline case wildcard now detects the
+listed posix option and enables it. Further utility/parser blockers may remain.
+
+Independent utility references can be recorded outside the bootstrap guest with
+`node test/utility-reference-cases.mjs OUTPUT.json`, using `/usr/bin/diff` and
+`/usr/bin/sed`. Make only that JSON data accessible inside the guest, then run
+`BUNMSH_UTILITY_REFERENCE=/guest/OUTPUT.json bun test test/utility-reference.test.js`.
+The test compares status, stdout and stderr from explicit bunmsh builtins; it
+does not invoke or mount host reference executables. Without the environment
+variable, the reference fixture suite is skipped explicitly.
+
+The current 13 file-diff and 15 sed cases passed under musl Bun/bunproot against
+GNU diffutils 3.10 and GNU sed 4.9. They cover middle edits, repeated lines,
+newline boundaries, UTF-8, sed script files, addresses, branches, hold space and file reads.
+These are selected compatibility cases, not a claim of complete GNU behavior.
+
+The awk fallback is a JavaScript parser/interpreter in src/awk.js, with no
+native awk or FFI dependency. It supports BEGIN/END, pattern/action records,
+fields, associative arrays, functions/control flow, regex/string operations,
+getline and file redirection. Output command pipes run through bunmsh, with
+input buffered until close or program end; streaming and interactive pipe
+communication are not supported. Input command pipes and system() fail
+explicitly. JavaScript regex, string and numeric behavior imposes remaining
+locale/formatting limits; this is not full POSIX or GNU awk compatibility.
+The optional test/awk-reference.test.js suite compares a separately supplied
+BUNMSH_AWK_REFERENCE executable; it is never used by the builtin itself.
+
+### Additional Autoconf regressions
+
+Compound normalization removes only lexer-recognized line continuations; it
+preserves backslash-newlines inside single quotes and heredoc bodies. Case `;;`
+terminators remain adjacent after brace groups. AND/OR operators continue across
+heredoc bodies, and pipelines retain redirected compound operands. Expansion
+markers use reserved Unicode noncharacters instead of ASCII control bytes, so
+Autoconf's BEL separator reaches awk intact. Sed `r FILE` appends raw file data
+at the end of the cycle (including after `d`); missing files contribute nothing.
+
+GNU make build.sh additionally exercises bracket/quoted parameter trimming and
+subshell snapshots taken at execution time. Internal state transport is scoped
+to its command even outside POSIX mode; default user variable export behavior
+and the background process registry are unchanged. Basic regex anchors are
+context-sensitive so literal make variable references can be substituted.
+
+Binutils bootstrap coverage additionally includes multiline `${...}` operands
+inside compound bodies, legacy egrep/fgrep fallback names, bytewise cmp (normal
+and quiet modes), tr squeezing with optional translation/deletion, and an
+adapter for Bun Shell mv's missing `--` support. The adapter protects filenames
+beginning with `-` by prefixing `./` after removing the option delimiter. The
+cmp and tr subset has offline GNU command reference fixtures;
+unsupported extensions remain errors, not successful no-ops.
+
+The uniq fallback preserves byte comparisons and adjacent groups, supports
+-c/-d/-u, -- and input/output operands. Other GNU extensions are explicit
+errors. Twelve GNU reference fixtures cover ordering, flags, blank lines,
+missing final newlines and NUL bytes. rm -f discards empty nonexistent path
+operands before Bun Shell can incorrectly treat them as the current directory.

package/apps/bunmsh/help/awk.md

@@ -0,0 +1,38 @@
+## awk
+
+Scan records and evaluate AWK programs using a JavaScript interpreter.
+
+### Usage
+
+```sh
+awk [-F SEPARATOR] [-v NAME=VALUE] [-f SCRIPT_FILE] [PROGRAM] [FILE ...]
+```
+
+### Options and forms
+
+- `-F`: Set the field separator; `-v`: assign a variable before BEGIN.
+- `-f`: Read program text from a file; `-e`: append program text.
+- BEGIN/END, pattern/action rules, fields, variables, associative arrays,
+  functions, conditionals, loops, next/nextfile, exit and delete.
+- print/printf, arithmetic, comparisons, regular expressions, concatenation,
+  split, substr, index, length, match, sub/gsub and common numeric functions.
+- getline from input or files; file output with `>` and `>>`; close.
+- Parenthesized print/printf lists and continued arguments after commas.
+- Output pipes run through bunmsh, buffering input until close or program end.
+  They do not provide streaming or interactive communication. close returns
+  the command status; closing and reopening starts a fresh command.
+- This is a subset, not full POSIX/GNU compatibility. Input command pipes and
+  system() are unsupported and report errors. Text processing uses JavaScript strings
+  and regular expressions; locale and floating-point edge cases may differ.
+
+### Example
+
+```sh
+printf 'apple 2\npear 3\n' | awk '{total += $2} END {print total}'
+```
+
+Output:
+
+```text
+5
+```

package/apps/bunmsh/help/break.md

@@ -0,0 +1,21 @@
+## break
+
+Leave N enclosing loops (default 1). N must be positive. Function calls establish their own loop boundary.
+
+### Usage
+
+```sh
+break [N]
+```
+
+### Example
+
+```sh
+for x in a b; do echo "$x"; break; done
+```
+
+Output:
+
+```text
+a
+```

package/apps/bunmsh/help/chmod.md

@@ -1,6 +1,6 @@
 ## chmod
 
-Change modes using octal values, +x, or a+x.
+Change file modes using octal values or symbolic permission changes.
 
 ### Usage
 
@@ -11,7 +11,13 @@ chmod MODE FILE ...
 ### Options and forms
 
 - Octal modes such as `755` set all permission bits.
-- `+x` and `a+x` add executable bits.
+- `+x` retains its existing shorthand for adding executable bits for everyone.
+- Explicit classes `u`, `g`, `o`, or `a` support `+`, `-`, and `=` with `rwxX`.
+- `X` adds execution only for directories or files already executable.
+- Comma-separated clauses and multiple operations are applied in order.
+- Examples: `a-w`, `u+rw`, `go=rx`, `u=rw,g=r,o=`.
+- Recursive mode, permission copying, `s`/`t`, and omitted classes other than
+  the existing `+x` shorthand are not implemented.
 
 ### Example
 

package/apps/bunmsh/help/cmp.md

@@ -0,0 +1,29 @@
+## cmp
+
+Compare two files byte by byte. Return 0 for identical data, 1 for differences,
+and 2 for errors. `-` reads standard input.
+
+### Usage
+
+```sh
+cmp [-s] [--] FILE1 FILE2
+```
+
+`-s` (also `--silent` or `--quiet`) suppresses difference and file-error messages.
+Without it, report the first differing byte and line, or which file ends first.
+Byte offsets, `-l`, and other GNU extensions are not implemented.
+
+### Example
+
+```sh
+printf same > first
+printf same > second
+cmp -s first second
+echo $?
+```
+
+Output:
+
+```text
+0
+```

package/apps/bunmsh/help/continue.md

@@ -0,0 +1,22 @@
+## continue
+
+Continue the Nth enclosing loop (default 1). N must be positive.
+
+### Usage
+
+```sh
+continue [N]
+```
+
+### Example
+
+```sh
+for x in a b; do echo "$x"; continue; echo skipped; done
+```
+
+Output:
+
+```text
+a
+b
+```

package/apps/bunmsh/help/cp.md

@@ -6,12 +6,16 @@ Copy files and directories.
 
 ```sh
 cp [-rRv] SOURCE ... DESTINATION
+cp -p [-v] [--] FILE ... DESTINATION
 ```
 
 ### Options and forms
 
 - `-r`, `-R`: Copy directories recursively (`-r` is translated to Bun Shell's `-R`).
 - `-v`: Request verbose output.
+- `-p`: Preserve regular-file ownership, permissions and access/modification
+  times. Multiple sources require a directory destination; recursive `-p`
+  combinations are not yet supported and report an error.
 - `-n`: Accepted by Bun Shell but currently does not prevent overwriting.
 
 ### Example

package/apps/bunmsh/help/diff.md

@@ -0,0 +1,30 @@
+## diff
+
+Compare two files. Return 0 when identical, 1 when different, or 2 on error.
+
+### Usage
+
+```sh
+diff [-q] [--] FILE1 FILE2
+```
+
+Print normal-format changes, or use `-q`/`--brief` for a difference notice.
+Binary differences produce a notice. Text differences use Myers line alignment, preserving unchanged lines
+between separate additions, deletions, and replacements. Missing final
+newlines are reported explicitly. Directory comparison and unified/context formats are not supported.
+The default shell alias's `--color` option is accepted; output is plain text.
+
+### Example
+
+```sh
+printf 'first\nlast\n' > before
+printf 'first\nnew\nlast\n' > after
+diff before after
+```
+
+Output:
+
+```text
+1a2
+> new
+```

package/apps/bunmsh/help/egrep.md

@@ -0,0 +1,26 @@
+## egrep
+
+Search using extended regular expressions, equivalent to `grep -E`.
+
+### Usage
+
+```sh
+egrep [OPTIONS] PATTERN [FILE ...]
+```
+
+### Options and forms
+
+Accepts the same supported options as builtin `grep`.
+
+### Example
+
+```sh
+printf 'red\nblue\ngreen\n' | builtin egrep 'red|blue'
+```
+
+Output:
+
+```text
+red
+blue
+```

package/apps/bunmsh/help/export.md

@@ -1,11 +1,11 @@
 ## export
 
-Set or list environment variables.
+Mark variables for export, or list them. In `set -o posix` mode, external programs receive only inherited/exported variables and command-prefix assignments. Shell pipelines and subshells retain all shell variables through internal state transfer. Outside POSIX mode, bunmsh preserves its default of passing all variables to external programs.
 
 ### Usage
 
 ```sh
-export [NAME[=VALUE] ...]
+export [-p] [NAME[=VALUE] ...]
 ```
 
 ### Example

package/apps/bunmsh/help/expr.md

@@ -0,0 +1,30 @@
+## expr
+
+Evaluate integer, string, and basic regular-expression expressions.
+
+### Usage
+
+```sh
+expr [--] EXPRESSION
+```
+
+### Options and forms
+
+- Arithmetic: `+`, `-`, `*`, `/`, `%`, with parentheses and precedence.
+- Comparisons: `=`, `!=`, `<`, `<=`, `>`, `>=`.
+- `|` selects the first nonempty, nonzero operand; `&` requires both operands.
+- `STRING : BRE` returns the first capture, or the matched prefix length when there is no capture.
+- Status is 0 for a nonempty, nonzero result, 1 for empty or zero, and 2 for an error.
+- Quote operators that the shell would otherwise interpret.
+
+### Example
+
+```sh
+expr 2 + 3 '*' 4
+```
+
+Output:
+
+```text
+14
+```

package/apps/bunmsh/help/fgrep.md

@@ -0,0 +1,25 @@
+## fgrep
+
+Search for fixed strings, equivalent to `grep -F`.
+
+### Usage
+
+```sh
+fgrep [OPTIONS] PATTERN [FILE ...]
+```
+
+### Options and forms
+
+Accepts the same supported options as builtin `grep`.
+
+### Example
+
+```sh
+printf 'a.b\naxb\n' | builtin fgrep 'a.b'
+```
+
+Output:
+
+```text
+a.b
+```

package/apps/bunmsh/help/grep.md

@@ -32,3 +32,7 @@ Output:
 ```text
 beta
 ```
+
+Repeated `-e PATTERN` options combine patterns with OR. `-c` prints the number of selected lines per input file.
+
+The fallback names `egrep` and `fgrep` select `grep -E` and `grep -F`.

package/apps/bunmsh/help/ls.md

@@ -1,11 +1,11 @@
 ## ls
 
-Use the lsfancy emoji and terminal-width-aware listing.
+Use the lsfancy emoji and terminal-width-aware listing. With `set -o posix`, fallback `ls` omits icons and automatic directory suffixes. Explicit `-F` suffixes still apply; `lsfancy` always retains its icons.
 
 ### Usage
 
 ```sh
-ls [-aAdlhRtrS1F] [PATH ...]
+ls [-aAdilhLRtrS1F] [PATH ...]
 ```
 
 Because `-h` means human-readable sizes, use `--help` to display this page.
@@ -16,6 +16,8 @@ Because `-h` means human-readable sizes, use `--help` to display this page.
 - `-A`: Include hidden entries except `.` and `..`.
 - `-d`: List directories themselves rather than their contents.
 - `-l`: Use long format.
+- `-i`: Print inode numbers.
+- `-L`: Follow symbolic links.
 - `-h`: Show human-readable sizes; use `--help` for this page.
 - `-R`: Recurse into directories.
 - `-t`: Sort by modification time.