Fixes for latest issues (#124)

* dofs: follow symbolic links in mkdir

mkdir walked the target path with a helper that read each dirent
directly and treated every node other than a directory as ENOTDIR, so
a symbolic link to a directory blocked directory creation rather than
resolving through it. Every other write path, writeFile included,
follows links and shares one forty-hop budget.

The parent walk now expands intermediate links the way writeFile's
does, tracking the resolved path so the new directory lands under the
directory the link points at and the read-only mount guard sees the
location actually written. Recursive creation places its missing
ancestors under that resolved parent. A resolved parent that is a file
still reports ENOTDIR, a dangling parent link reports ENOENT in both
modes rather than being materialised, and a chain beyond forty hops
reports ELOOP.

Closes #119.

* dofs, computer: add exclusion globs to find

The walker tested the inclusion glob before yielding an entry but
descended into every directory regardless, so a search in a workspace
holding node_modules, .git, or generated build output paid for those
trees even when the caller wanted nothing from them.

FindOptions gains exclude, a list of globs of the same shape as the
inclusion pattern and matched against the same directory-relative
path. An exclusion is decided before inclusion, so it always wins, and
before any child query, so an excluded directory takes its whole
subtree with it rather than being filtered out afterwards. Traversal
stays deterministic and limit and offset apply to what survives. The
option reaches the public find tool, whose schema now advertises it.

Closes #121.

* dofs, computer: expose rename on the public filesystem

The store has implemented transactional file, directory, and symbolic
link moves for some time, covering destination replacement, non-empty
directories, read-only mounts, tombstones, revision stamping, and
subtree tracking. None of that reached Workspace.fs, so a caller had
to copy the source and then delete it, and the Worker shell used that
fallback for mv. A failure between the two steps left the entry at
both paths or a directory half copied.

WorkspaceFilesystem now forwards rename, and WorkspaceFilesystemStub
mirrors it with the usual filesystem observation span, so the Workers
RPC surface matches the in-process one. The shell adapter calls it and
keeps copy-then-delete only for a destination rename refuses to
replace, which is what the shell expects when it merges a tree. No new
method crosses the Cap'n Web boundary: the existing synchronisation
protocol already carries the resulting live entries and tombstones.

Closes #120.

* docs: describe the shipped symbolic-link surface

The filesystem specification said symbolic links were an internal
primitive, that Workspace.fs exposed neither symlink nor readlink,
that there was no lstat, and that an existing file's mode could not be
changed. The shipped API contradicts all four: WorkspaceFilesystem
exposes symlink, readlink, lstat, and chmod, the stub mirrors them
across the Workers RPC boundary, and the Dynamic Worker filesystem
adapters rely on them for the node:fs behaviour a shell expects.
Removing the methods would be a breaking change and would leave those
adapters without a way to serve ln -s, readlink, or test -L, so the
document follows the code.

Each of the four methods gains a section with its return value and its
errors, the comparison with node:fs/promises maps them rather than
striking them out, and the note on symbolic links now states the two
rules that cover the surface: intermediate segments are always
followed, and a trailing link is followed by everything except lstat
and readlink. The rename and find entries added alongside are
documented in the same pass.

Closes #118.

---------

Co-authored-by: agent <agent@users.noreply.github.com>

Author: aron-cf

.changeset/document-symlink-surface.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/computer": patch
+---
+
+Document the symbolic-link filesystem surface. `docs/04_filesystem_interface.md` claimed that symbolic links were internal and that `Workspace.fs` had no `symlink`, `readlink`, `lstat`, or `chmod`, none of which matched the shipped API. Those four methods now have sections of their own covering return values and the `ENOENT`, `EINVAL`, and `ELOOP` cases, the comparison with `node:fs/promises` maps them, and the specification explains that `stat` follows a trailing link while `lstat` reports the link itself.

.changeset/expose-fs-rename.md

@@ -0,0 +1,6 @@
+---
+"@cloudflare/dofs": minor
+"@cloudflare/computer": minor
+---
+
+`Workspace.fs` gains `rename(oldPath, newPath)`, exposing the store's existing transactional move through the public surface and through `WorkspaceFilesystemStub`. An existing destination is replaced when the two ends agree on kind — a file or symbolic link for a file or symbolic link, an empty directory for a directory — and the operation reports `ENOENT`, `ENOTEMPTY`, `EISDIR`, `ENOTDIR`, `EINVAL`, and `EROFS` as documented in `docs/04_filesystem_interface.md`. The Worker shell's `mv` now calls it, so an interrupted move no longer leaves the entry at both paths or a directory half copied.

.changeset/find-exclude-globs.md

@@ -0,0 +1,12 @@
+---
+"@cloudflare/dofs": minor
+"@cloudflare/computer": minor
+---
+
+`find` accepts `exclude`, a list of glob patterns matched against the same directory-relative path as the inclusion glob. Exclusion is decided first, so it always wins, and an excluded directory is pruned during traversal: neither it nor anything below it is read. `limit` and `offset` apply to the matches that survive. The option travels through `WorkspaceFilesystem`, `WorkspaceFilesystemStub`, and the public find tool.
+
+```ts
+const sources = await workspace.fs.find("/workspace", "**/*.ts", {
+  exclude: ["node_modules", "node_modules/**", ".git", ".git/**"],
+});
+```

.changeset/mkdir-follows-symlinks.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/dofs": patch
+---
+
+`mkdir` now follows symbolic links in intermediate path segments, so a link to a directory resolves transparently instead of failing with `ENOTDIR`. Creating `/alias/new-directory` where `/alias` points at `/real` creates `/real/new-directory`, and recursive creation places its missing ancestors under the resolved parent. A resolved parent that is a file still reports `ENOTDIR`, a dangling parent link reports `ENOENT`, and a chain longer than the shared forty-hop budget reports `ELOOP`.

docs/04_filesystem_interface.md

@@ -190,8 +190,10 @@ stat(path: string): Promise<{
 `name` is the last segment of the canonicalized path. For the workspace
 root this is the empty string: `(await fs.stat("/")).name === ""`.
 
-`stat` follows symlinks transparently; there is no `lstat`. See the
-note on internal symlink support in the appendix.
+`stat` follows a trailing symbolic link, so it reports the file or
+directory the link points at. Use [`lstat`](#lstat) to inspect the link
+itself. A dangling link makes `stat` report `ENOENT` while `lstat`
+succeeds.
 
 > When a parent path segment is itself a file, `stat` reports `ENOENT`
 > (because resolution returns `null` for that case) rather than
@@ -203,6 +205,117 @@ const s = await fs.stat("/workspace/build/out.wasm");
 console.log(`${s.size} bytes, modified ${new Date(s.mtime).toISOString()}`);
 ```
 
+### `lstat`
+
+```ts
+lstat(path: string): Promise<{
+  name:            string;
+  mode:            number;
+  mtime:           number;   // ms since epoch
+  size:            number;
+  isFile:          boolean;
+  isDirectory:     boolean;
+  isSymbolicLink:  boolean;
+}>
+```
+
+Same shape as `stat`, but a trailing symbolic link is reported as the
+link rather than followed. `size` is then the byte length of the stored
+target string, and `isSymbolicLink` is true. Intermediate segments are
+still followed, so a link in the middle of the path resolves as usual.
+Throws `ENOENT` when the path does not exist and `ELOOP` when an
+intermediate chain exceeds 40 hops.
+
+```ts
+await fs.symlink("/workspace/real.txt", "/workspace/alias.txt");
+(await fs.stat("/workspace/alias.txt")).isSymbolicLink;   // false
+(await fs.lstat("/workspace/alias.txt")).isSymbolicLink;  // true
+```
+
+### `symlink`
+
+```ts
+symlink(target: string, path: string): Promise<void>
+```
+
+Creates a symbolic link at `path` pointing at `target`, with the
+argument order of `node:fs/promises`. The target is stored verbatim: it
+may be absolute or relative, and it is allowed to dangle. Reads and
+writes that walk through the link follow it, with the same 40-hop cap as
+every other resolution.
+
+Throws `EEXIST` when `path` already exists (the link is never replaced
+silently), `ENOENT` when the parent directory is missing, `ENOTDIR` when
+a parent segment is a file, and `EROFS` under a read-only mount.
+
+```ts
+await fs.symlink("../shared/config.json", "/workspace/app/config.json");
+```
+
+### `readlink`
+
+```ts
+readlink(path: string): Promise<string>
+```
+
+Returns the stored target of a symbolic link, exactly as it was
+written — relative targets are not resolved. Throws `EINVAL` when `path`
+is not a symbolic link and `ENOENT` when it does not exist.
+
+```ts
+await fs.readlink("/workspace/app/config.json"); // "../shared/config.json"
+```
+
+### `chmod`
+
+```ts
+chmod(path: string, mode: number): Promise<void>
+```
+
+Changes the permission bits of an existing path without rewriting its
+bytes. The mode is masked to twelve bits. Like POSIX `chmod`, a trailing
+symbolic link is followed, so the change lands on the target rather than
+the link. Throws `ENOENT` for a missing path and `EROFS` under a
+read-only mount.
+
+```ts
+await fs.chmod("/workspace/bin/run.sh", 0o755);
+```
+
+### `rename`
+
+```ts
+rename(oldPath: string, newPath: string): Promise<void>
+```
+
+Moves a file, directory, or symbolic link in a single transaction, so an
+interrupted call can never leave the entry at both paths or a directory
+partly copied. The moved entry keeps its inode, its bytes, and its mode;
+a directory move carries its whole subtree.
+
+Overwrite behavior follows POSIX `rename(2)`: an existing destination is
+replaced when the two ends agree on kind. A file or symbolic link
+replaces a file or symbolic link, and a directory replaces an *empty*
+directory. Nothing else is replaced.
+
+| Code | When |
+| --- | --- |
+| `ENOENT` | `oldPath` does not exist, or `newPath`'s parent directory is missing. |
+| `ENOTEMPTY` | `newPath` is a directory with children. |
+| `EISDIR` | `newPath` is a directory and `oldPath` is not. |
+| `ENOTDIR` | `oldPath` is a directory and `newPath` is not. |
+| `EINVAL` | Either end is the root, or a directory would be moved inside itself. |
+| `EROFS` | Either end falls under a read-only mount. |
+
+```ts
+// Publish a build atomically.
+await fs.writeFile("/workspace/site/index.html.tmp", html);
+await fs.rename("/workspace/site/index.html.tmp", "/workspace/site/index.html");
+
+// Move a whole tree.
+await fs.rename("/workspace/draft", "/workspace/published");
+```
+
 ### `find`
 
 ```ts
@@ -212,6 +325,7 @@ find(
   options?: {
     limit?: number;
     offset?: number;
+    exclude?: string[];
   },
 ): Promise<Array<{ path; type: "file" | "dir" }>>
 ```
@@ -225,12 +339,24 @@ its absolute path — so `**/*.ts` under `/workspace/src` matches
 The glob supports `*`, `**`, `**/`, and `?`. Character classes and
 brace expansions are matched literally.
 
+`exclude` takes globs of the same shape, matched against the same
+relative path. An exclusion is decided before the inclusion glob, so it
+always wins. When an excluded entry is a directory the walk prunes it:
+neither the directory nor anything beneath it is read, which is what
+makes skipping `node_modules` or `.git` cheap rather than merely quiet.
+`limit` and `offset` then paginate whatever survives.
+
 ```ts
 // Every TypeScript file in the project.
 const ts = await fs.find("/workspace/src", "**/*.ts");
 
 // Everything under a directory (no pattern).
 const all = await fs.find("/workspace/notes");
+
+// Skip generated trees without descending into them.
+const sources = await fs.find("/workspace", "**/*.ts", {
+  exclude: ["node_modules", "node_modules/**", ".git", ".git/**"],
+});
 ```
 
 ### `ls`
@@ -321,12 +447,12 @@ so handlers from Node code port over directly.
 | Code | When |
 | --- | --- |
 | `ENOENT` | Path does not exist and `force` is not true. Also raised by `stat` when a parent segment turns out to be a file. |
-| `ENOTEMPTY` | Path is a non-empty directory and `recursive` is not true. |
-| `ENOTDIR` | A parent path segment is a file (raised explicitly by `mkdir` and `writeFile`; `find` raises it when its `directory` argument is a file). |
-| `EISDIR` | Expected a file, got a directory (e.g. `readFile` on a dir, `writeFile` on `/`). |
-| `EEXIST` | `mkdir` without `recursive: true` on an existing path. |
-| `EINVAL` | Invalid path or unsupported options. |
-| `ELOOP` | Symlink traversal exceeded 40 hops. Thrown by the internal resolver when the `node:vfs` adapter wires up a cycle. |
+| `ENOTEMPTY` | Path is a non-empty directory and `recursive` is not true. Also raised by `rename` when the destination directory has children. |
+| `ENOTDIR` | A parent path segment is a file (raised explicitly by `mkdir` and `writeFile`; `find` raises it when its `directory` argument is a file; `rename` raises it when a directory would replace a non-directory). |
+| `EISDIR` | Expected a file, got a directory (e.g. `readFile` on a dir, `writeFile` on `/`, `rename` of a file onto a directory). |
+| `EEXIST` | `mkdir` without `recursive: true` on an existing path, or `symlink` onto an existing path. |
+| `EINVAL` | Invalid path or unsupported options: `readlink` on something that is not a symbolic link, `rename` of the root or of a directory into itself. |
+| `ELOOP` | Symbolic-link traversal exceeded 40 hops. Every path-walking method shares that budget, so a cycle surfaces from `stat`, `readFile`, `writeFile`, `mkdir`, and the rest alike. |
 | `EPERM` | Operation is forbidden, e.g. deleting the workspace root. |
 | `EIO` | Backing storage failed unexpectedly. |
 | `EACCES` | *Reserved for future mount layer (see [06. Mount Interface](./06_mount_interface.md)).* No code path in `workspace-fs` currently throws it. |
@@ -379,28 +505,35 @@ maps to `Workspace.fs`:
 | `rm` | `rm` | `{ recursive: true }` for non-empty dirs. |
 | `unlink` | `rm` | Same. |
 | `readdir` | `readdir` | Always returns dirent-shaped entries. |
-| `stat` / `lstat` | `stat` | No `lstat`; `stat` follows symlinks. See note below. |
+| `stat` / `lstat` | `stat` / `lstat` | `stat` follows a trailing symbolic link; `lstat` reports the link. |
 | `truncate` | — | Read, slice, write. |
-| `chmod` | — | Pass `mode` to `writeFile` / `mkdir` at create time. There is no way to chmod an existing file without rewriting its bytes. |
+| `chmod` | `chmod` | Mode masked to twelve bits; follows a trailing symbolic link. `mode` can also be passed to `writeFile` / `mkdir` at create time. |
 | `chown` | — | No ownership model. |
 | `utimes` | — | `mtime` is managed by the VFS. |
 | `cp` / `copyFile` | — | Read + write. |
-| `rename` | — | Read + write + delete. |
+| `rename` | `rename` | One transaction; replaces a destination of the same kind. |
 | `realpath` | — | Paths are already canonical. |
-| `symlink` / `readlink` | — | Not on the public surface; see note below. |
+| `symlink` / `readlink` | `symlink` / `readlink` | Same argument order as Node. Targets are stored verbatim and may dangle. |
 | `watch` | — | Low-level primitive in `fs/watch.ts` (`createWatcher`, `createWatchAsyncIterable`, `WatchHandle`, `WatchOptions`); not exposed on the `WorkspaceFilesystem` class. |
 | `open` / `FileHandle` | — | Use streams instead. |
-| `glob` | `find` | Limited glob support (`*`, `**`, `**/`, and `?`). |
+| `glob` | `find` | Limited glob support (`*`, `**`, `**/`, and `?`), plus `exclude` for pruning subtrees. |
 | — | `grep` | Not in `node:fs`; literal by default, with optional regular expressions. |
 | — | `find` | Recursive directory walk with an optional glob, relative-rooted. |
 | — | `ls` | Flat list of file paths under a directory (segment-aware). |
 
-### Note: symlinks
-
-Symlinks exist as an **internal primitive** used by the `node:vfs`
-adapter — the schema supports a `'symlink'` node type with a
-`link_target`, and the resolver in `fs/resolve.ts` follows them with a
-40-hop cap (throws `ELOOP` on overflow). They are **not** part of the
-public `WorkspaceFilesystem` surface: there are no `fs.symlink` or
-`fs.readlink` methods on `Workspace.fs`, and callers should treat all
-visible paths as if they pointed straight at real files.
+### Note: symbolic links
+
+Symbolic links are part of the public surface. The schema carries a
+`'symlink'` node type with a `link_target`, the resolver in
+`fs/resolve.ts` follows them with a 40-hop cap (throws `ELOOP` on
+overflow), and `Workspace.fs` exposes `symlink`, `readlink`, and
+`lstat` on top of that. `WorkspaceFilesystemStub` mirrors all three
+across the Workers RPC boundary, which is how the Dynamic Worker
+filesystem adapters provide the `node:fs` behavior a shell expects from
+`ln -s`, `readlink`, and `test -L`.
+
+Two rules cover the whole surface. Intermediate segments are always
+followed, so a link to a directory behaves like the directory for every
+method, `mkdir` included. A trailing link is followed by everything
+except `lstat` and `readlink`, which are the two methods whose purpose
+is to describe the link itself.

docs/09_tool_interface.md

@@ -166,15 +166,18 @@ Entries are in name order. A non-final page includes `nextOffset`; pass it as th
 
 ```ts
 {
-  path?: string;   // default /workspace
+  path?: string;      // default /workspace
   pattern: string;
-  limit?: number;  // default 200, maximum 1000
+  exclude?: string[];
+  limit?: number;     // default 200, maximum 1000
   offset?: number;
 }
 ```
 
 The pattern is relative to `path`. `*` stays within one path segment, `**` crosses directories, and `?` matches one non-separator character. Results contain `path` and `type`; a non-final page includes `nextOffset`. Pagination reaches `workspace.fs.find`, which walks directory children in fixed-size pages and stops after collecting the requested page instead of materializing every match.
 
+`exclude` takes globs of the same shape, matched against the same relative path, and beats the inclusion pattern. An excluded directory is pruned rather than filtered, so `exclude: ["node_modules", "node_modules/**"]` keeps the walk out of a package tree instead of walking it and discarding the results.
+
 ## `grep`
 
 ```ts

docs/12_worker_backend.md

@@ -223,7 +223,9 @@ policy. The backend does not own the external runtime's lifecycle.
 - **No hard links, no `utimes`.** The adapter throws `ENOSYS` on
   `link` (the store has no hard-link model) and no-ops on
   `utimes` (no atime column). `chmod`, `symlink`, `readlink`,
-  and `lstat` all work end-to-end against the DO's store.
+  `lstat`, and `rename` all work end-to-end against the DO's
+  store, so `mv` moves an entry in one operation instead of
+  copying and then deleting it.
 - **No cross-request reattach.** `ShellWorker.getExec` always
   returns ENOENT; `killExec` is a no-op. Each exec is scoped to
   its own call. The previous in-isolate event log shape didn't

packages/computer/src/backends/worker-shell/adapter.test.ts

@@ -275,6 +275,34 @@ describe("WorkspaceFsAdapter — composites", () => {
     expect(await workspace.fs.readFile("/dst", "utf8")).toBe("hello");
     await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
   });
+
+  it("mv moves through the store's rename rather than copy and delete", async () => {
+    await workspace.fs.writeFile("/src", "hello");
+    const rename = vi.spyOn(stub, "rename");
+    const writeFile = vi.spyOn(stub, "writeFile");
+    await adapter.mv("/src", "/dst");
+    expect(rename).toHaveBeenCalledWith("/src", "/dst");
+    expect(writeFile).not.toHaveBeenCalled();
+  });
+
+  it("mv moves a directory tree in one operation", async () => {
+    await workspace.fs.mkdir("/src/inner", { recursive: true });
+    await workspace.fs.writeFile("/src/inner/b", "b");
+    await adapter.mv("/src", "/dst");
+    expect(await workspace.fs.readFile("/dst/inner/b", "utf8")).toBe("b");
+    await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("mv falls back to copy and delete when rename cannot replace the destination", async () => {
+    await workspace.fs.mkdir("/src", { recursive: true });
+    await workspace.fs.writeFile("/src/a", "a");
+    await workspace.fs.mkdir("/dst", { recursive: true });
+    await workspace.fs.writeFile("/dst/keep", "keep");
+    await adapter.mv("/src", "/dst");
+    expect(await workspace.fs.readFile("/dst/a", "utf8")).toBe("a");
+    expect(await workspace.fs.readFile("/dst/keep", "utf8")).toBe("keep");
+    await expect(workspace.fs.stat("/src")).rejects.toMatchObject({ code: "ENOENT" });
+  });
 });
 
 describe("WorkspaceFsAdapter — pure utilities", () => {

packages/computer/src/backends/worker-shell/adapter.ts

@@ -3,8 +3,8 @@
 //
 // The adapter is a thin façade. Operations that map one-for-one
 // (writeFile, readdir, mkdir, rm, chmod, symlink, readlink, stat,
-// lstat) forward directly. Operations the stub doesn't expose —
-// appendFile, cp, mv, exists — synthesize from the available
+// lstat, rename) forward directly. Operations the stub doesn't
+// expose — appendFile, cp — synthesize from the available
 // primitives. Hard links and utimes aren't supported: link throws
 // ENOSYS so a script that depends on them fails loudly; utimes
 // is a documented no-op because the store has no atime column.
@@ -50,6 +50,7 @@ export interface WorkspaceFs {
   rm(path: string, options?: RmOptions): Promise<void>;
   chmod(path: string, mode: number): Promise<void>;
   symlink(target: string, path: string): Promise<void>;
+  rename(oldPath: string, newPath: string): Promise<void>;
 }
 
 // Matches the subset of just-bash's IFileSystem the adapter
@@ -213,10 +214,19 @@ export class WorkspaceFsAdapter {
   }
 
   async mv(src: string, dest: string): Promise<void> {
-    // The store doesn't have a native rename today, so model mv as
-    // copy+delete. POSIX mv is atomic when src and dest live on
-    // the same filesystem; this approach isn't, but it matches
-    // what just-bash's other adapters do.
+    // The store renames in one transaction, so an interrupted move can
+    // no longer leave the bytes at both paths or a directory half
+    // copied. A destination that rename refuses to replace — a
+    // non-empty directory, or a directory and a non-directory in
+    // either order — still falls back to copy-then-delete, which is
+    // what the shell's own `mv` expects when it merges a tree.
+    try {
+      await this.#fs.rename(src, dest);
+      return;
+    } catch (err) {
+      const code = (err as { code?: string }).code;
+      if (code !== "ENOTEMPTY" && code !== "EISDIR" && code !== "ENOTDIR") throw err;
+    }
     await this.cp(src, dest, { recursive: true });
     await this.#fs.rm(src, { recursive: true });
   }