@stablemodels/durable-bash 0.1.0

package/.claude/commands/final-review.md

@@ -0,0 +1,20 @@
+Review all changes in the current branch compared to main and automatically bump the package version.
+
+## Steps
+
+1. **Diff analysis**: Run `git diff main...HEAD` to see all changes in this branch. Also run `git log --oneline main..HEAD` to understand the commit history.
+
+2. **Determine version bump**:
+   - **patch** (e.g. 0.1.0 → 0.1.1): Bug fixes, documentation changes, refactors, test additions, CI changes — anything that doesn't change the public API.
+   - **minor** (e.g. 0.1.0 → 0.2.0): New features, new exports, new methods on public classes, new options added to existing methods — any additive change to the public API.
+   - Never bump major unless explicitly told to.
+
+3. **Review the changes**: Provide a concise summary of what changed, organized by category (features, fixes, docs, tests, CI, etc.). Flag any concerns.
+
+4. **Bump the version**: Run `npm version <patch|minor> --no-git-tag-version` to update package.json. Do NOT create a git tag — the version in package.json is what npm publish uses.
+
+5. **Verify**: Run `bun test && bun run check && bun run build` to make sure everything still passes.
+
+6. **Commit**: Stage the package.json change and commit with message: `chore: bump version to <new-version>`.
+
+7. **Report**: Show the old version, new version, bump type, and the reasoning for the bump decision.

package/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+      - run: bun run build
+      - run: bun test

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to NPM
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+      - run: bun run build
+      - run: bun test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,62 @@
+# durable-bash
+
+Cloudflare Durable Object-backed `IFileSystem` adapter for `just-bash`.
+
+## Architecture
+
+Two core classes, one adapter pattern:
+
+- **`FsObject`** (`src/fs-object.ts`) — Durable Object with SQLite storage. Single `files` table stores paths, content (BLOB), metadata, and optional symlink targets. All methods are **synchronous** and exposed via RPC. This is where all filesystem logic lives.
+- **`DurableFs`** (`src/durable-fs.ts`) — Thin adapter implementing `IFileSystem` from `just-bash`. Every method delegates to `FsObject` via a DO stub. Maintains a `Set<string>` cache for the synchronous `getAllPaths()` method. Use the static `DurableFs.create(namespace, name)` factory for construction — it handles stub creation and initial cache sync.
+- **`src/errors.ts`** — `FsError` class and factory functions: `ENOENT`, `EEXIST`, `EISDIR`, `ENOTDIR`, `ENOTEMPTY`.
+- **`src/types.ts`** — Wire-format types for RPC: `FsStatData`, `DirentData`.
+- **`src/index.ts`** — Public API re-exports. Two entry points: `durable-bash` (adapter + errors + types) and `durable-bash/object` (DO class).
+
+## Important Points
+
+- **`IFileSystem` uses boolean properties**, not methods: `stat.isFile`, not `stat.isFile()`. `FsStat` and `DirentEntry` in `durable-fs.ts` define these shapes.
+- **`getAllPaths()` is synchronous** but the DO is async. Solved with eager cache sync (handled by `DurableFs.create()`) + `Set` cache. `addToCache` walks ancestor dirs so auto-created parents are included.
+- **Auto-parent creation**: `writeFile("/a/b/c.txt", ...)` auto-creates `/a` and `/a/b` via `ensureParentDirs` using `INSERT OR IGNORE`.
+- **Symlinks**: stored as rows with `symlink_target` set. `resolveSymlinks()` follows chains up to 20 levels. `readFile`/`stat` follow symlinks; `lstat` does not.
+- **`link()` copies content** at call time (not POSIX shared-inode semantics). This is by design per `IFileSystem` contract.
+- **Content stored as BLOB** — `toBytes()` encodes strings to UTF-8 `Uint8Array`; binary is stored as-is.
+- Mode constants: `DIR_MODE = 0o755`, `FILE_MODE = 0o644`, `SYMLINK_MODE = 0o777`.
+
+## Commands
+
+```bash
+bun test                 # all tests (121 tests across 4 files)
+bun run test:unit        # unit tests only (fs-object + durable-fs)
+bun run test:integration # integration + smoke tests
+bun run build            # tsc → dist/
+bun run check            # biome lint
+bun run format           # biome format (tabs, write)
+```
+
+## Testing
+
+Tests use `bun:test` with `bun:sqlite` to simulate DO SQLite storage. The `cloudflare:workers` module is mocked via `tests/setup.ts` (preloaded in `bunfig.toml`).
+
+- `tests/helpers.ts` — shared `createMockState()`, `createTestFsObject()`, `createDirectStub()` (Proxy wrapping sync methods as Promises for RPC simulation)
+- `tests/fs-object.test.ts` — Unit tests for FsObject
+- `tests/durable-fs.test.ts` — Unit tests for DurableFs with mock stub
+- `tests/integration.test.ts` — DurableFs + FsObject wired together
+- `tests/just-bash.test.ts` — Bash commands through DurableFs
+
+## Extending the Package
+
+**Adding a new filesystem operation:**
+1. Add the synchronous method to `FsObject` in `src/fs-object.ts`
+2. Add the async wrapper in `DurableFs` in `src/durable-fs.ts` — resolve paths with `this.resolve()`, call `this.stub.<method>()`, update cache with `addToCache`/`removeFromCache` if paths change
+3. If new wire-format types are needed, add them to `src/types.ts`
+4. Export any new public types from `src/index.ts`
+5. Add tests to `tests/fs-object.test.ts` (unit) and `tests/integration.test.ts` (e2e)
+
+**Adding a new error code:**
+1. Add a factory function in `src/errors.ts` following the `ENOENT` pattern
+
+**Key conventions:**
+- Paths are always normalized (leading `/`, no trailing `/`, `.`/`..` resolved)
+- `FsObject` methods are synchronous — no async/await inside the DO
+- `DurableFs` cache must stay in sync: use `addToCache` for creates, `removeFromCache` for deletes, `sync()` for bulk operations like `cp`/`mv`
+- Biome enforces tab indentation and recommended lint rules

package/README.md

@@ -0,0 +1,97 @@
+# durable-bash
+
+Cloudflare Durable Object-backed [`IFileSystem`](https://www.npmjs.com/package/just-bash) adapter for [just-bash](https://www.npmjs.com/package/just-bash). Lets bash commands persist files in a Durable Object's SQLite storage.
+
+## Install
+
+```bash
+npm install @stablemodels/durable-bash
+```
+
+Peer dependencies: `just-bash`, `@cloudflare/workers-types`
+
+## Usage
+
+```typescript
+import { Bash } from "just-bash";
+import { DurableFs } from "@stablemodels/durable-bash";
+
+// In a Cloudflare Worker:
+const fs = await DurableFs.create(env.FS, "my-agent");
+const bash = new Bash({ fs, cwd: "/home" });
+const result = await bash.exec('echo "hello" > greeting.txt && cat greeting.txt');
+console.log(result.stdout); // "hello\n"
+```
+
+### Wrangler config
+
+```toml
+[[durable_objects.bindings]]
+name = "FS"
+class_name = "FsObject"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["FsObject"]
+```
+
+Re-export the DO class from your worker:
+
+```typescript
+export { FsObject } from "@stablemodels/durable-bash/object";
+```
+
+## API
+
+`DurableFs` implements `IFileSystem` from `just-bash`:
+
+- `readFile(path)` / `readFileBuffer(path)` — Read file contents
+- `writeFile(path, content)` / `appendFile(path, content)` — Write/append
+- `exists(path)` / `stat(path)` / `lstat(path)` — Check existence and metadata
+- `mkdir(path, opts?)` / `readdir(path)` / `readdirWithFileTypes(path)` — Directories
+- `rm(path, opts?)` / `cp(src, dest, opts?)` / `mv(src, dest)` — File operations
+- `chmod(path, mode)` / `utimes(path, atime, mtime)` — Metadata changes
+- `symlink(target, linkPath)` / `link(existing, new)` / `readlink(path)` / `realpath(path)` — Links
+- `static create(namespace, name, cwd?)` — Factory: creates stub, syncs cache, returns ready instance
+- `getAllPaths()` — Synchronous cached path list for glob matching
+
+## Exports
+
+| Export | Path | Description |
+|--------|------|-------------|
+| `DurableFs` | `@stablemodels/durable-bash` | `IFileSystem` adapter |
+| `FsObject` | `@stablemodels/durable-bash/object` | Durable Object class — re-export in your worker |
+| `FsError`, `ENOENT`, `EEXIST`, `EISDIR`, `ENOTDIR`, `ENOTEMPTY` | `@stablemodels/durable-bash` | POSIX-style errors |
+| `FsStatData`, `DirentData` | `@stablemodels/durable-bash` | RPC wire-format types |
+
+## Development
+
+```bash
+bun install
+bun test              # all 121 tests
+bun run test:unit     # unit tests only
+bun run test:integration  # integration + smoke tests
+bun run build         # tsc → dist/
+bun run check         # biome lint
+bun run format        # biome format
+```
+
+### Test structure
+
+| File | Scope |
+|------|-------|
+| `tests/fs-object.test.ts` | Unit tests for `FsObject` DO |
+| `tests/durable-fs.test.ts` | Unit tests for `DurableFs` (mock stub) |
+| `tests/integration.test.ts` | End-to-end: `DurableFs` + `FsObject` |
+| `tests/just-bash.test.ts` | Bash commands through `DurableFs` |
+
+Tests mock `cloudflare:workers` via a preload script (`tests/setup.ts`, configured in `bunfig.toml`) and use `bun:sqlite` to simulate DO SQLite storage.
+
+## CI/CD
+
+- **PR checks**: Lint, build, and tests run automatically on pull requests via GitHub Actions.
+- **NPM publishing**: Triggered automatically on merge to `main`. Requires an `NPM_TOKEN` secret in the repository/org settings.
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,25 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"files": {
+		"ignore": ["dist/**"]
+	},
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"suspicious": {
+				"noExplicitAny": "off"
+			},
+			"style": {
+				"noNonNullAssertion": "off"
+			}
+		}
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	}
+}