@j-o-r/sh 1.1.29 → 1.1.32

package/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+# Project standard: tab indentation for JavaScript (STRUCT-3).
+# lib/** is fully conformant; some scenarios/*.js demos predate this
+# standard and are intentionally left as-is (no mass reformat there).
+[*]
+indent_style = tab
+indent_size = tab
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{json,yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false

package/README.md

@@ -13,7 +13,7 @@ Execute shell commands from JavaScript on Linux.
 - Utils: `sleep`, `retry`, `expBackoff`, `cd`, `parseArgs`, `userIn`, `readIn`.
 - Testing: `new Test().add('name', () => assert(...)).run()`.
 - Async leak detection: `AsyncTracker` via `async_hooks`.
-- Safe interpolation; `bashEscape`; full JSDoc.
+- Raw-by-default interpolation with explicit `bashEscape` quoting for untrusted argument values; full JSDoc.
 
 No runtime deps. ESM-only (ES2020+).
 
@@ -35,6 +35,35 @@ const out = await SH`ls -la`.run();
 console.log(out); // Captured stdout (trimmed)
 ```
 
+### Interpolation: raw by default
+
+Interpolated values are inserted into the shell command as raw shell source. This
+is convenient for trusted shell fragments such as flags, pipes, redirects, and
+compound expressions, but it is **not safe for untrusted input**.
+
+```js
+import { SH, bashEscape } from '@j-o-r/sh';
+
+const flags = ['-l', '-a'];
+await SH`ls ${flags}`.run();       // Executes: ls -l -a
+
+const fragment = 'printf ok; printf done';
+await SH`${fragment}`.run();       // Raw shell syntax is intentional
+
+const userInput = 'name; rm -rf /';
+await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
+// Prints the value literally instead of executing `rm`.
+```
+
+`bashEscape(value)` returns one POSIX-shell-quoted argument. It preserves empty
+strings, whitespace, quotes, semicolons, glob characters, tabs, and newlines.
+For arrays of untrusted values, quote each element yourself:
+
+```js
+const args = ['two words', 'semi;colon', "quote's"];
+await SH`printf '%s\n' ${args.map(bashEscape)}`.run();
+```
+
 ### Chaining & Options
 
 ```js
@@ -140,9 +169,9 @@ Full JSDoc in `lib/*.js`. Key exports:
 | `Test` | Test runner |
 | `AsyncTracker` | Async leak detector |
 | `parseArgs(argv)` | CLI parser |
-| `bashEscape(str)` | Shell-safe string |
+| `bashEscape(value)` | Quote one value as a POSIX shell argument for safe interpolation |
 
-See [types/index.d.ts](types/index.d.ts) for TS defs.
+See [types/SH.d.ts](types/SH.d.ts) for TS defs.
 
 ## Development
 

package/TODO.md

@@ -1,18 +1,355 @@
 # TODOs for @j-o-r/sh project
 
-## High Priority (pending)
-- [ ] Review and commit recent changes to lib/ files and types/ (from git status: modified AsyncTracker.js, SH.js, etc.)
-- [*] Generate or improve API documentation using types/*.d.ts files
+## lib/SH.js review findings (2026-06-26)
 
-## In Progress
-- [ ]
+Source: full code review of `lib/SH.js`, `lib/SHDispatch.js`, `lib/SHExecute.js`.
+Work through Pass 1 first (behavioral bugs), then Pass 2 (docs/typedefs), then Pass 3 (structure/style).
+Each item lists: file(s), problem, fix, acceptance criteria. Check the Decision Points section before
+implementing anything marked with a D-number.
+
+### Context for the implementing agent
+
+- Package: `@j-o-r/sh` v1.1.31, ESM (`"type": "module"`), Node >= 20, zero runtime dependencies.
+- Layering: `lib/SH.js` (public API: template tag, helpers, re-exports) → `lib/SHDispatch.js`
+  (per-command option merging, chaining) → `lib/SHExecute.js` (spawn/spawnSync wrapper).
+- Public typings are **generated from JSDoc**: `npm run types` runs `tsc -p tsc.json` into `types/`.
+  Any JSDoc error becomes a public API type error. Always regenerate types after doc changes.
+- Tests: `npm test` → `scenarios/sh.js`. Add scenario coverage for every Pass 1 fix.
+- Do not change public API signatures unless a Decision point explicitly approves it.
+
+---
+
+### Pass 1 — Behavioral fixes (ALL DONE 2026-07-28)
+
+#### FIX-1 (P1) — DONE 2026-07-28: `cd()` does not affect subsequent `SH` commands (stale cwd)
+
+- **Files:** `lib/SH.js` (`defaultOptions.cwd = process.cwd()` captured at module load; `cd()` only
+  calls `process.chdir()`), `lib/SHDispatch.js` (duplicated `defaultSHOptions` with a second snapshot).
+- **Symptom:** `cd('/tmp'); await SH`pwd`.run()` still executes in the directory the process was
+  started in.
+- **Root cause:** `process.cwd()` is snapshotted once at module load, and `mergeOptions` copies that
+  stale value into every dispatch instance.
+- **Fix:**
+  1. Create a single shared defaults source — new file `lib/internal.js` exporting `defaultOptions`
+     (see STRUCT-1). Delete the duplicated `defaultSHOptions` in `lib/SHDispatch.js`.
+  2. Make `cwd` lazy, so it reflects the cwd at command-creation time, not module-load time:
+     ```js
+     const defaultOptions = {
+       get cwd() { return process.cwd(); },
+       env: process.env,
+       shell: 'bash',
+       stdio: ['inherit', 'pipe', 'pipe'],
+       timeout: 0,
+     };
+     ```
+     Note: `SHDispatch.options()` spreads `{ ...options }`, which invokes the getter and freezes the
+     value per dispatch instance. That is correct and intended ("defaults captured when the command
+     was created") — a `new SHDispatch` is created per `SH`cmd`` evaluation, i.e. after any `cd()`.
+     Do not "optimize" this away.
+  3. Alternative (acceptable but less informative): omit `cwd` from defaults entirely; `spawn` then
+     uses the current process cwd at spawn time. If chosen, keep a `SH.cwd` readback working somehow.
+- **Acceptance:** new scenario: `cd(tmpdir)` then `await SH`pwd`.run()` resolves to that tmpdir.
+
+#### FIX-2 (P1) — DONE 2026-07-28: Rolling timeout is defeated by Node's native spawn timeout
+
+- **File:** `lib/SHExecute.js`, constructor: `const { maxBuffer, ...spawnOpts } = options ?? {};`
+  strips `maxBuffer` but leaves `timeout` inside `spawnOpts`, which is passed to `spawn()`.
+- **Root cause:** since Node 15.5, `spawn` accepts `timeout` and kills the process after an
+  *absolute* duration, regardless of output. This breaks the documented rolling timeout
+  (reset on stdout/stderr data) and produces a misleading `Command failed with code null` rejection.
+- **Fix:** also destructure `timeout` out of the options; store it in a private field (e.g.
+  `#timeout`) and use it exclusively for the rolling timer in `run()`. In `runSync()`, re-add
+  `timeout` to the `spawnSync` options (supported natively; semantics are absolute — document this
+  sync/async difference in the `SHOptions` typedef).
+- **Acceptance:** scenario with a command that emits output continuously for longer than `timeout`
+  and exits 0 → succeeds; a command that goes silent → killed ~`timeout` ms after its last output.
+
+#### FIX-3 (P1) — DONE 2026-07-28: Timeout rejection reports the wrong error message
+
+- **File:** `lib/SHExecute.js`, `run()` close handler: `this.#forcedKill` is checked **before**
+  `this.#timedOut`.
+- **Root cause:** the timeout path sets `#timedOut = true` and immediately calls `kill('SIGTERM')`,
+  which sets `#forcedKill = true` in the same tick. The forced-kill branch always wins, so
+  `Process timed out after ${ms}ms.` is unreachable — timeouts report `Process killed (forced).`.
+- **Fix:** check `#timedOut` before `#forcedKill` in the close handler.
+- **Acceptance:** timeout rejection message matches `/timed out after \d+ms/`.
+
+#### FIX-4 (P1) — DONE 2026-07-28: `childrenOf()` can hang `kill()` forever
+
+- **File:** `lib/SHExecute.js`, `childrenOf()`: the `close` handler resolves for pgrep exit codes
+  `0` and `1` only. Exit codes 2 (syntax error) / 3 (fatal error) never settle the promise, and
+  `SHDispatch.kill()` awaits it indefinitely.
+- **Fix:** add a final `else resolve([]);` (kill is already best-effort; an unexpected pgrep failure
+  should not wedge the library).
+- **Acceptance:** code inspection + comment; `kill()` is guaranteed to settle on all pgrep outcomes.
+
+#### FIX-5 (P1) — DONE 2026-07-28: Detached mode — null deref crash + incomplete detachment
+
+- **File:** `lib/SHExecute.js`, `run()` detached branch.
+- **Bug A:** the 1-second `setTimeout` callback calls `this.#proc.unref()` unguarded. If `kill()`
+  runs within that window, `#proc` is `null` → `TypeError` crashes the process.
+  **Fix:** `this.#proc?.unref();`.
+- **Bug B:** with the default piped stdio, the parent's pipe handles keep the event loop alive even
+  after `unref()`, so the parent cannot actually exit early. **Fix:** when `options.detached` is
+  true and the user did not explicitly provide `stdio`, force `stdio: 'ignore'`; if the user did
+  provide stdio, keep it and document that pipes keep the parent alive. Update the class JSDoc
+  ("Detached" bullet) accordingly.
+- **Acceptance:** detached + immediate `kill()` does not crash; JSDoc states the stdio behavior.
+
+#### FIX-6 (P2) — DONE 2026-07-28: `parseArgs` mishandles lone `-` and `--`
+
+- **File:** `lib/SH.js`. `isOptionArg('-')` is true → produces an empty-string key `''` and consumes
+  the next token as its value. `--` (conventional end-of-options marker) also becomes key `''`.
+- **Fix:** treat lone `-` as a positional (stdin convention). Treat `--` as end-of-options
+  terminator: all following tokens go into `_` (see D4). Update the `parseArgs` JSDoc.
+- **Acceptance:** `parseArgs(['-', '--port', '1'])` → `{ port: '1', _: ['-'] }`;
+  `parseArgs(['--', '--x'])` → `{ _: ['--x'] }`.
+
+---
+
+### Pass 2 — JSDoc / typedef correctness (ALL DONE 2026-07-28)
+
+- **DOC-1** — DONE 2026-07-28: Remove dead typedefs in `lib/SH.js`: `RejectCallback`, `ResolveCallback`, and the
+  `SHOptions` re-typedef. Repoint `lib/SHExecute.js`'s `SHExecuteOptions` to
+  `import('./SHDispatch.js').SHOptions` directly and drop the redundant `& { maxBuffer?: number }`
+  (`maxBuffer` is already optional in `SHOptions`). Regenerate types; grep for dangling references.
+- **DOC-2** — DONE 2026-07-28: Fix inaccurate typedefs in `lib/SH.js`: `ExpBackoffGenerator` — `expBackoff` only
+  yields numbers, so use `Generator<number, void, unknown>` (if string-yielding generators must stay
+  valid for `retry`, type retry's param as `Iterator<number|string>` explicitly instead);
+  `ArgsObject` — remove `string[]` (duplicates throw; arrays are never produced);
+  `SH` tag — `@param {...unknown[]} args` → `{...unknown}`.
+- **DOC-3** — DONE 2026-07-28: `jsType` (`lib/SH.js`): rename param `fn` → `value`, type `unknown`; fix the
+  null-prototype crash (`fn.constructor?.name ?? 'Object'`); fix the doc — `jsType(null)` returns
+  `'Null'`, and `undefined` is special-cased to `'undefined'`.
+- **DOC-4** — DONE 2026-07-28: `within` (`lib/SH.js`): implementation is `await callback()` (a no-op wrapper) but the
+  doc promises "a new async context (fresh callstack)". Reword the doc now; real isolation is
+  Decision D2.
+- **DOC-5** — DONE 2026-07-28: `maxBuffer` default doc drift: actual default is `512000` (`500 * 1024`). Fix
+  `lib/SHExecute.js` class JSDoc ("1MB default") and `SHExecuteOptions` typedef ("default 1MB") —
+  both wrong. Standardize on `512000 (500 KiB)` everywhere; ideally one constant in
+  `lib/internal.js` (STRUCT-1).
+- **DOC-6** — DONE 2026-07-28: `userIn` (`lib/SH.js`): document the non-obvious submit heuristics — 'line' event +
+  50 ms debounce auto-resolve, paste detection via `chunk.length > 4 && chunk.includes('\n')`,
+  multi-line accumulation, `abort()` resolving with `undefined`. Lift magic numbers into named
+  constants (e.g. `PASTE_MIN_CHUNK = 4`, `SUBMIT_DEBOUNCE_MS = 50`).
+- **DOC-7** — DONE 2026-07-28: `readIn` (`lib/SH.js`): document the side effect — permanently sets
+  `process.stdin` encoding to utf8 and switches it to flowing mode.
+- **DOC-8** — DONE 2026-07-28: `retry` (`lib/SH.js`): replace `{Function}` param types with explicit signatures
+  (e.g. `{() => (Promise<any>|any)}`); document delay precedence and that an exhausted generator
+  means "no further delay".
+- **DOC-9** — DONE 2026-07-28: `lib/SHDispatch.js`: remove the dead `SpawnSyncResponse` typedef; change constructor
+  error `'Undefined command'` → `'Invalid or empty command'`; document that `run()` replaces
+  `#proc`, so a second concurrent `run()` makes the first unkillable via `kill()`.
+- **DOC-10** — DONE 2026-07-28: `lib/SHExecute.js`: async `run()` says `@throws` — use "rejects with" wording;
+  document the `pgrep` (procps) runtime dependency of `kill()` and the direct-children-only
+  limitation (grandchildren survive); fix the failure message for signal kills (`code` is `null`,
+  printing "code null") — include `signal` in the message. Structured errors: see D3.
+- **DOC-11** — DONE 2026-07-28: `SH` tag JSDoc (`lib/SH.js`): the inline `` `SH.timeout = 5000; SH`cmd`` `` breaks
+  markdown rendering (nested backticks) — move it into an `@example` block; cross-link the
+  "defaults captured at creation time" note from `SHDispatch`.
+- **DOC-12** — DONE 2026-07-28: `hasProp` (`lib/SH.js`): replace "(code-safe)" with "safe for null-prototype objects
+  and objects shadowing `hasOwnProperty`". Optionally simplify to `Object.hasOwn` (Node >= 16.9;
+  engines require >= 20).
+
+---
+
+### Pass 3 — Structure & style
+
+- **STRUCT-1** — DONE 2026-07-28: Single source of truth — create `lib/internal.js` exporting `defaultOptions`
+  (with lazy `cwd`, see FIX-1) and one shared `parseDuration`. Import it from `SH.js`,
+  `SHDispatch.js`, `SHExecute.js`. This removes the duplicated `defaultSHOptions`
+  (`lib/SHDispatch.js`) and the divergent second `parseDuration` (`lib/SHExecute.js` — currently
+  accepts bare `'100'` and `null → 0`, while `lib/SH.js`'s throws). Unified semantics: finite
+  numbers >= 0 (ms); strings `'Nms'`, `'Ns'`, or bare `'N'` (= ms, preserving SHExecute's current
+  leniency — document it); descriptive errors from the SH.js version; `null`/`undefined` handled at
+  call sites (`timeout ?? 0`).
+- **STRUCT-2** — DONE 2026-08-05: Proxy symmetry (`lib/SH.js`): the `set` trap accepted any
+  property but `get` exposed only `defaultOptionKeys`, so `SH.foo = 1; SH.foo` === `undefined`.
+  Implemented D1 (throw). Aligned `defaultOptionKeys` with the defaults object by deriving it
+  from `defaultOptions` and initializing `maxBuffer`/`detached` in the defaults.
+- **STRUCT-3** — DONE 2026-08-05: Formatting unified: tabs everywhere in `lib/` (`SH.js` mixed
+  and `SHExecute.js` 2-space converted), semicolon drift fixed in `lib/SH.js`. `.editorconfig`
+  added (tabs for JS; 2-space for JSON/MD/YAML). One commit, **no** logic changes (proven by
+  `git diff -w`: only added semicolons). Scenario files intentionally not mass-reformatted.
+- **STRUCT-4** — DONE 2026-08-05: `@ts-ignore` audit: `parseArgs` return — replaced with an
+  `ArgsObject`-typed declaration; `cd`'s `@ts-ignore` on `process.chdir` — verified with tsc and
+  removed; reason comments added to every remaining `@ts-ignore` (lib + scenarios).
+
+---
+
+### Decision points (confirm with maintainer first)
 
-## Later (future tasks)
-- [ ] Create separate docs folder with full API reference
+- **D1 — proxy `set` for unknown keys:** (a) throw `TypeError` listing known keys (catches typos
+  like `SH.timout = 1`; breaking for anyone setting custom props), or (b) store custom keys in a
+  separate `Map` and read them back (function props like `name` must not be shadowed).
+  Recommended: (a).
+  **DECIDED 2026-08-05: (a)** — throw a TypeError listing the known keys (implemented in STRUCT-2).
+- **D2 — `within()`:** implement real isolation via `AsyncLocalStorage` (larger change; would also
+  enable per-call default scoping) or keep the wrapper and just fix the docs (DOC-4).
+  Recommended short-term: docs only.
+- **D3 — structured failure errors:** reject with an error carrying `code`/`signal`/`stdout`/
+  `stderr` (zx `ProcessOutput` precedent). Public API change — defer to next major. Minimal fix for
+  now is in DOC-10.
+- **D4 — `--` semantics in `parseArgs`:** standard end-of-options terminator (recommended) vs
+  treating `--` as a positional. Affects FIX-6.
+  **DECIDED 2026-07-28: terminator** (as encoded in the FIX-6 acceptance criteria).
+- **D5 — API-surface trim:** re-exporting `node:assert`, `Test`, `AsyncTracker`, plus generic utils
+  (`jsType`, `hasProp`, `parseArgs`) blurs the "lean shell bridge" mission stated in the file
+  header. Consider deprecating the `assert` re-export. Non-blocking.
+
+---
+
+### Verification checklist (run before moving items to Done)
+
+- [x] `npm test` passes, including new scenarios for FIX-1 … FIX-6 and STRUCT-2 (30/30; FIX-4 covered by code inspection per its acceptance criteria).
+- [x] `npm run types` regenerates `types/` with zero errors (new `types/internal.d.ts`).
+- [x] `grep -rn "RejectCallback\|ResolveCallback\|SpawnSyncResponse" lib/ types/` returns nothing
+      after DOC-1 / DOC-9 (verified 2026-07-28).
+- [x] Manual smoke: `cd` + `pwd`; chatty command with rolling timeout; timeout error message;
+      detached + immediate kill; `parseArgs` with `-` and `--` — all automated as the
+      FIX-1…FIX-6 scenario block in `scenarios/sh.js`.
+
+## In Progress
 
 ## Done
-- [x] Initial project setup from package.json and README.md inspection (2026-04-15)
-- [x] Update README.md to include documentation for recent changes in AsyncTracker and Test features (2026-04-15)
-- [x] Add more examples to README.md for SHDispatch methods and utilities like retry and expBackoff (2026-04-15)
-- [x] Reference general SSH example in README.md (demo-interactive-ssh.js not found in scenarios/) (2026-04-15)
-- [x] Reduce SHExecute maxBuffer default from 40MB to 1MB, update all docs/JSDoc mentioning it. Make sure global SH.maxBuffer works. (2026-04-15)
+
+### Pass 1 — completed 2026-07-28
+
+- **FIX-1** — `lib/internal.js` created as the single defaults source with a lazy `cwd`
+  getter. Design refinement vs the sketched getter-only snippet: a setter keeps `SH.cwd = dir`
+  working (a getter-only accessor would throw on assignment in strict mode), and `cd()` clears
+  the override via `clearCwdOverride()` — the most recent of `cd()` / `SH.cwd =`
+  always wins. Duplicated `defaultSHOptions` removed from `lib/SHDispatch.js`. Scenario 24.
+- **FIX-2** — `timeout` destructured out of the spawn options into `#timeout`
+  (`lib/SHExecute.js`), used only for the rolling timer in `run()`; `runSync()`
+  re-adds it to `spawnSync` (native, absolute). Sync/async difference documented in the
+  `SHOptions` typedef. Scenario 25 (chatty command ~2s survives a 500 ms rolling timeout).
+- **FIX-3** — `#timedOut` is checked before `#forcedKill` in the close handler.
+  Scenario 25 asserts `/timed out after 400ms/`.
+- **FIX-4** — `childrenOf()` gained a final `else resolve([])` (pgrep exit 2/3) with
+  comment; `kill()` settles on all pgrep outcomes. Acceptance was code inspection — no scenario.
+- **FIX-5** — `this.#proc?.unref()`; `SHDispatch.run()` forces `stdio: 'ignore'`
+  when `detached` and stdio was not explicitly provided (tracked via `#stdioProvided`);
+  JSDoc updated (`SHExecute` class bullet, `SHOptions.detached`). Scenarios 26–27.
+- **FIX-6** — `isOptionArg` requires length > 1 (lone `-` → positional / option value);
+  `--` terminates option parsing (D4: terminator). `parseArgs` JSDoc + examples updated.
+  Scenario 28; standalone `scenarios/parse_args.js` still passes (6/6).
+
+Validation run: `node --check` on all changed files OK; `npm test` 29/29;
+`npm run types` exit 0; `node scenarios/parse_args.js` 6/6.
+
+### Pass 2 — completed 2026-07-28
+
+- **DOC-1** — Dead `RejectCallback`/`ResolveCallback`/`SHOptions` re-typedefs removed from
+  `lib/SH.js`; `SHExecuteOptions` repointed to `import('./SHDispatch.js').SHOptions`
+  (redundant `& { maxBuffer?: number }` dropped).
+- **DOC-2** — `ArgsObject` no longer includes `string[]`; `ExpBackoffGenerator` is
+  `Generator<number, void, unknown>` (kept alive via `@returns` on `expBackoff`;
+  `retry` types its delay param as `Iterator<number|string>`); SH tag `{...unknown}`.
+- **DOC-3** — `jsType` param renamed `fn` → `value` (`unknown`), null-prototype
+  crash fixed (`constructor?.name ?? 'Object'`), docs cover `'Null'`/`'undefined'`.
+- **DOC-4** — `within` doc reworded: thin wrapper, no isolation; D2 referenced.
+- **DOC-5** — `DEFAULT_MAX_BUFFER` constant in `lib/internal.js` (500 * 1024); `SHExecute`
+  uses it; all docs standardized on `512000 (500 KiB)`.
+- **DOC-6** — `userIn` heuristics documented; `PASTE_MIN_CHUNK`/`SUBMIT_DEBOUNCE_MS` constants.
+- **DOC-7** — `readIn` stdin encoding/flowing side effect documented.
+- **DOC-8** — `retry` params typed with explicit signatures; delay precedence + exhausted-generator
+  semantics documented.
+- **DOC-9** — `SpawnSyncResponse` typedef removed; constructor error now `'Invalid or empty
+  command'`; `run()` documents the concurrent-run unkillable caveat.
+- **DOC-10** — async `run()` uses rejects-with wording; `kill()` documents the procps/`pgrep`
+  dependency and direct-children-only limit; signal kills now report `signal <SIG>` instead of
+  `code null`.
+- **DOC-11** — nested-backtick inline moved into `@example`; cross-link to `SHDispatch#options`.
+- **DOC-12** — `hasProp` doc reworded; body simplified to `Object.hasOwn`.
+
+Validation run: `node --check` OK on all changed files; `npm test` 29/29; `npm run types`
+exit 0; dead-typedef grep clean; `SH: any` in `types/SH.d.ts` unchanged (pre-existing).
+
+### STRUCT-1 (Pass 3) — completed 2026-07-28
+
+- **STRUCT-1** — `parseDuration` unified in `lib/internal.js` alongside `defaultOptions`.
+  The divergent copies in `lib/SH.js` (strict) and `lib/SHExecute.js` (lenient) were
+  deleted; both now import from `./internal.js` (`SHExecute`'s now-dead `isFinitePosInt`
+  helper removed too). Unified semantics as specified: finite numbers >= 0 (ms); strings
+  `'Nms'`, `'Ns'`, or bare `'N'` (= ms, leniency documented in the JSDoc); descriptive
+  SH.js-style errors; `null`/`undefined` handled at call sites (`SHExecute` already had
+  `timeout ?? 0`). Scenario 13 in `scenarios/sh.js` updated to the unified semantics —
+  it previously asserted the old strict SH.js behavior by rejecting bare `'5'`; renamed to
+  'duration parsing' and extended with bare-string acceptance coverage. Minor deviation:
+  the invalid-type error message uses `typeof` instead of `jsType` (avoids an
+  internal↔SH import cycle; e.g. 'boolean' instead of 'Boolean' — no test relied on it).
+
+Validation run: `node --check` on all changed files OK; `npm test` 29/29;
+`npm run types` exit 0 (`types/internal.d.ts` now exports `parseDuration`);
+`node scenarios/parse_args.js` 6/6.
+
+
+### STRUCT-2 (Pass 3) — completed 2026-08-05
+
+- **STRUCT-2** — D1 implemented as decided: the `SH` proxy `set` trap now throws a `TypeError`
+  listing the known option keys when an unknown key is assigned (typo guard, e.g.
+  `SH.timout = 1`), instead of silently storing it in `defaultOptions` — where the `get` trap
+  would not read it back (`SH.foo = 1; SH.foo` === `undefined`). Reads of unknown keys are
+  unchanged (they fall through to the function target, usually `undefined`). Key-set alignment:
+  the hard-coded `defaultOptionKeys` list in `lib/SH.js` was replaced by `defaultOptionKeys`
+  exported from `lib/internal.js`, derived as `new Set(Object.keys(defaultOptions))` so the set
+  can never drift from the defaults again; `maxBuffer` and `detached` are now initialized in
+  `defaultOptions` (`DEFAULT_MAX_BUFFER` and `false`). This is behavior-neutral: `SHExecute`
+  already fell back to the same maxBuffer constant for unset/invalid values and truthy-checks
+  `detached`. `DEFAULT_MAX_BUFFER` moved above `defaultOptions` to satisfy TDZ.
+  Scenario 29 in `scenarios/sh.js` ('STRUCT-2: SH proxy throws on unknown option keys (D1)').
+
+Validation run: `node --check` on all changed files OK; `npm test` 30/30;
+`npm run types` exit 0; `node scenarios/parse_args.js` 6/6; manual smoke of the TypeError
+message and the initialized `SH.maxBuffer`/`SH.detached` readbacks OK.
+
+### STRUCT-4 (Pass 3) — completed 2026-08-05
+
+- **STRUCT-4** — `@ts-ignore` audit. Method: every suppression was re-verified against
+  `tsc --noEmit --checkJs` (stricter than the project gate — `tsc.json` covers `lib/**` only
+  and does not set `checkJs`, so the project's `npm run types` never exercised these).
+  - `parseArgs` (`lib/SH.js`): the return-site suppression moved to the declaration with the
+    prescribed typing — `const result = /** @type {ArgsObject} */ ({ _: [] });`. Deviation from
+    the sketched fix: the plain annotation form only relocates TS2322 to the declaration,
+    because `_: string[]` is fundamentally incompatible with the `string|true` index
+    signature — `_` is the intended exception, so one reasoned `@ts-ignore` remains at the
+    declaration. Also annotated `/** @type {string|true} */ let value;` (the `true` literal
+    otherwise widens to `boolean`). Net checkJs effect: 3 pre-existing parseArgs errors
+    removed, zero introduced.
+  - Removed as unneeded (no error even under `checkJs`): both `userIn` readline suppressions
+    and `cd`'s `process.chdir` suppression.
+  - Kept with reason comments: the two `options.stdio = stdio` suppressions in
+    `lib/SHExecute.js` (the `['pipe', 'pipe', 'pipe']` literal widens to `string[]`, which
+    `StdioOptions` rejects).
+  - Reason comments added to the 7 suppressions in `scenarios/test.js` /
+    `scenarios/asynctracker.js` (beyond the TODO's lib-only wording; those files are not
+    covered by `tsc.json` at all).
+
+Validation run: `node --check` on all changed files OK; `npm test` 30/30; `npm run types`
+exit 0 (regenerated types byte-identical); `node scenarios/parse_args.js` 6/6;
+`node scenarios/asynctracker.js` 6/6; `node scenarios/test.js` shows its 2 intentional
+self-test errors (verified pre-existing on HEAD); `tsc --noEmit --checkJs` delta vs the
+pre-audit baseline: 0 errors introduced, 3 removed.
+
+### STRUCT-3 (Pass 3) — completed 2026-08-05
+
+- **STRUCT-3** — Formatting unified with **no logic changes**:
+  - `.editorconfig` added: tab indentation as the project standard for JS (2-space for
+    JSON/MD/YAML; trailing-whitespace trimming, final newline, LF, UTF-8).
+  - `lib/SHExecute.js`: 217 lines converted 2-space → tabs (whole file).
+  - `lib/SH.js`: 41 space-indented lines (userIn/hasProp regions) converted to tabs; 6 lines
+    trailing-whitespace trimmed; semicolon drift fixed — 2 imports and 7 closing braces
+    (`defaultOptionHandler`, `within`, `readIn`, `retry`, `sleep`, `cd`, export list).
+  - No-logic-change proof: `git diff -w lib/` shows only the added semicolons;
+    `git diff -w lib/SHExecute.js` is empty. Multi-line template literals (whose inner
+    whitespace is significant) exist only in scenario files, which were deliberately left
+    as-is.
+  - Deviation note: `scenarios/*.js` indentation drift (a few 2-space and 4-space demo files)
+    was left untouched — outside the TODO's lib-focused scope, and several scenarios launch
+    interactive programs so they can't be regression-tested here. `.editorconfig` governs
+    future edits.
+
+Validation run: `node --check` on all changed files OK; `npm test` 30/30; `npm run types`
+exit 0 (types byte-identical); `node scenarios/parse_args.js` 6/6;
+`node scenarios/asynctracker.js` 6/6; `node scenarios/test.js` 2 intentional self-test errors.