Refactor 26 (#5)

* claude

* refactor

* refactor

* refactor-ifs

* lint

* knip

* build-before

Author: cramforce

.github/workflows/lint.yml

@@ -25,3 +25,6 @@ jobs:
 
       - name: Lint
         run: pnpm lint
+
+      - name: Knip
+        run: pnpm knip

.github/workflows/unit-tests.yml

@@ -23,5 +23,8 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Build
+        run: pnpm build
+
       - name: Run unit tests
         run: pnpm test:unit

AGENTS.md

@@ -10,6 +10,7 @@
 - Commands must handle unknown arguments correctly
 - Always ensure all tests pass in the end and there are no compile and lint errors
 - Use `pnpm lint:fix`
+- Always also run `pnpm knip`
 - Strongly prefer running a temporary comparison test or unit test over an ad-hoc script to figure out the behavior of some bash script or API.
 - The implementation should align with the real behavior of bash, not what is convenient for TS or TE tests.
 - Always make sure to build before using dist

CLAUDE.md

@@ -32,8 +32,41 @@ pnpm test:run src/spec-tests/spec.test.ts -t "array-basic.test.sh"
 # Interactive shell
 pnpm shell                 # Full network access
 pnpm shell --no-network    # No network
+
+# Sandboxed CLI (read-only by default)
+node ./dist/cli/bash-env.js -c 'ls -la' --root .
+node ./dist/cli/bash-env.js -c 'cat package.json' --root .
+node ./dist/cli/bash-env.js -c 'grep -r "TODO" src/' --root .
 ```
 
+### Sandboxed Shell Execution with `bash-env`
+
+The `bash-env` CLI provides a secure, sandboxed bash environment using OverlayFS:
+
+```bash
+# Execute inline script (read-only by default)
+node ./dist/cli/bash-env.js -c 'ls -la && cat README.md | head -5' --root .
+
+# Execute with JSON output
+node ./dist/cli/bash-env.js -c 'echo hello' --root . --json
+
+# Allow writes (writes stay in memory, don't affect real filesystem)
+node ./dist/cli/bash-env.js -c 'echo test > /tmp/file.txt && cat /tmp/file.txt' --root . --allow-write
+
+# Execute script file
+node ./dist/cli/bash-env.js script.sh --root .
+
+# Exit on first error
+node ./dist/cli/bash-env.js -e -c 'false; echo "not reached"' --root .
+```
+
+Options:
+- `--root <path>` - Root directory (default: current directory)
+- `--cwd <path>` - Working directory in sandbox (default: /home/user/project)
+- `--allow-write` - Enable write operations (writes stay in memory)
+- `--json` - Output as JSON (stdout, stderr, exitCode)
+- `-e, --errexit` - Exit on first error
+
 ### Debug with `pnpm dev:exec`
 
 Reads script from stdin, executes it, shows output. Prefer this over ad-hoc test files.

PROJECT.md

@@ -277,3 +277,7 @@ Woohoo
 - Make a binary called `bash-env` which takes a root path (default to .) and accepts a shell script via argument or STDIN and then executes it with an OverlayFS from the path
 - The idea is that this can be used as a secure alternative to `sh` or `bash` by AI agents
 - Should be a bin in `package.json`. Should be globally installable.
+
+## Implementation phase 21
+
+Build binaries with esbuild

knip.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "project": ["src/**/*.ts"],
+  "ignore": ["src/**/*.test.ts", "src/spec-tests/**"],
+  "ignoreBinaries": ["tsx"],
+  "rules": {
+    "unlisted": "off",
+    "unresolved": "off",
+    "optionalPeerDependencies": "off",
+    "types": "off"
+  }
+}

package.json

@@ -40,6 +40,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "knip": "knip",
     "test": "vitest",
     "test:run": "vitest run",
     "test:unit": "vitest run --config vitest.unit.config.ts",
@@ -56,6 +57,7 @@
     "@types/sprintf-js": "^1.1.4",
     "@types/turndown": "^5.0.6",
     "ai": "^6.0.3",
+    "knip": "^5.41.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
     "zod": "^4.2.1"