@warlock.js/ai-workspace 5.43.0 → 5.44.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@warlock.js/ai-workspace` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.44.0 - 2026-11-05
+
+### Added
+
+- Command rules: `shell.rules` is an ordered list of `{ match, effect: "allow" | "ask" | "deny", reason? }` (the last matching rule wins, a deny anywhere in a line refuses it) and `shell.onAsk({ command, asks, signal })` decides on commands that need approval. With `onAsk` set, commands no rule matches, syntax the parser cannot read (`reason: "unparsed"`) and runners the policy cannot see into (`"nested"`) ask too; `{ allow: true, remember: pattern }` allows later matching commands for the workspace's life (shared with `readonly()` and `scope()`, never over a deny). New refusal reasons `"approval-required"` (an ask rule and no `onAsk`) and `"approval-denied"`.
+- `workspace.shell.classify(line)` and `classifyShellCommand(line, policy?)` return the simple commands a line would run, or `opaque` with the reason when it cannot be read. `checkShellCommand` takes an options argument (`remembered`, `host`, `resolved`) and its result gains `asks`.
+- `shell.interpreter` accepts `"bash"`, `"powershell"`, `"cmd"` and `"auto"`, plus `shell.interpreterPath`. Each shell has its own parser feeding the same deny / allow / `denyPatterns` / `allowCommand` / rule and path-jail checks. PowerShell runs with `-NoLogo -NoProfile -NonInteractive -Command`; its dialect covers `;`, `&&`, `||`, pipelines, `$( )`, the call operator and the usual redirections, refuses script blocks, splatting, here-strings, `--%`, statements and dot-sourcing, treats `Invoke-Expression`, `Invoke-Command`, `Start-Process`, `Add-Type`, `Set-Alias` and `-EncodedCommand` as nested execution, keeps `Set-Location` / `cd` inside the jail, and checks `Remove-Item`, `Copy-Item`, `Move-Item`, `Get-ChildItem`, `Get-Content`, `Invoke-WebRequest`, `Stop-Process` and their aliases in a canonical `rm -rf`-style form as well. `"auto"` picks `bash` then `sh` on POSIX and `pwsh`, `powershell`, Git Bash, `cmd.exe` on Windows. `resolveShell()` is exported.
+- `run_shell`'s description names the resolved shell and its syntax rules; `run_tests` quotes its pattern for each shell.
+- New types `WorkspaceCommandRule`, `WorkspaceCommandDecision`, `WorkspaceShellOnAsk`, `WorkspaceShellAskRequest`, `WorkspaceShellAskDecision`, `WorkspaceShellAsk`, `WorkspaceShellAskReason` and `WorkspaceShellClassification`.
+- Tiered edit matching. `edit_file` and `multi_edit` now find `oldString` exactly first, then with line endings normalised, then with look-alike Unicode punctuation folded (`matchTier: "unicode"`), then line by line ignoring trailing whitespace (`matchTier: "whitespace"`). A loose match must be unique, even with `replaceAll`. Replacement text takes the file's dominant line ending, so CRLF files stay CRLF. New `policy.edit`: `matching` (`"tiered"` default, `"exact"` for the old behaviour), `missHintLines` and `lineEndings`.
+- A `not-found` edit error carries a `hint`: the closest file text (at most 12 lines of 200 characters) or a note that `newString` is already present.
+- `policy.hooks.afterEdit`: runs once after `write_file`, `edit_file`, `multi_edit` and `apply_patch` write files and returns its text as `diagnostics` between `[diagnostics]` lines. A throw or a timeout reports "diagnostics unavailable" and never fails the edit. `afterEditMaxChars` (default 4000) and `afterEditTimeoutMs` (default 10 s) bound it.
+- `policy.output`: with `spillDir`, oversized `run_shell`, `shell_output`, `grep`, `glob` and `read_file` output is saved to a `spill-<time>-<random>-<label>.txt` file and the result keeps its head and tail plus a `[showing lines … of …; full output saved to …]` marker. Results gain a `truncation` object beside the boolean `truncated`. `read_file` may open the spill directory; `retentionMs` (7 days) and `dispose()` clean up files named like spill files. `globResult()` is an optional `WorkspaceOps` method returning the paths with truncation data.
+
+### Changed
+
+- `resolveInJail()` takes an optional `access` argument (`"read"` also accepts the spill directory).
+
 ## 5.40.0 - 2026-10-29
 
 ### Added

package/README.md

@@ -126,7 +126,12 @@ for (const file of await ws.glob("src/models/**/*.ts")) {
 - **argv by default, shell on request** — commands run as one argv without a shell;
   a refusal names the operator and suggests the split. `shell.interpreter: "sh"`
   opts in to pipes, `&&` and redirections, with every command in the line checked
-  and redirections kept inside the jail.
+  and redirections kept inside the jail. `"bash"`, `"powershell"`, `"cmd"` and `"auto"`
+  pick a specific shell, each read by its own parser (`interpreterPath` overrides where
+  the shell lives).
+- **Allow / ask / deny rules** — `shell.rules` plus `shell.onAsk` put commands to the
+  host for approval (`remember` stores a session allow); `ws.shell.classify(line)` lists
+  the commands a line would run.
 - **Backends** — `local` (default; `@warlock.js/fs` + `node:child_process`) and
   `mock` (in-memory, for hermetic disk-free tests).
 - **Tools** under `ws.tools.*` — `read_file`, `edit_file`, `multi_edit`, `apply_patch`, `write_file`,
@@ -147,6 +152,14 @@ for (const file of await ws.glob("src/models/**/*.ts")) {
 - **Read-before-edit guard** — `read_file` returns a SHA-256 `hash`; `edit_file`
   requires an exact, unique `oldString` (or `replaceAll`) and rejects on an
   `expectHash` mismatch.
+- **Tiered edit matching** — `edit.matching` (default `"tiered"`) finds `oldString`
+  exactly, then with line endings normalised, Unicode punctuation folded and trailing
+  whitespace ignored; replacements keep the file's line endings, a loose match must be
+  unique, and a miss returns a `hint` with the closest text.
+- **`hooks.afterEdit`** — runs after a write and returns compiler or linter output as
+  `diagnostics` on the result; a throw or timeout never fails the edit.
+- **`output.spillDir`** — oversized `run_shell`, `shell_output`, `grep`, `glob` and
+  `read_file` output is saved to a file; the result keeps head and tail plus a pointer.
 - **Bounded reads** — `read.maxBytes` caps the UTF-8 bytes a read returns (line
   numbers included), cutting on a character boundary and flagging `bytesCapped`;
   the `hash` still covers the whole file.