@procedures/fs 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @procedures/fs
 
+## 0.5.0
+
+### Minor Changes
+
+- a47bee6: The hosts can confine the file procedures to a root (roadmap R33).
+  
+  - `confineFsProcedures(registry, root)` of `@procedures/fs` replaces the handler of each `fs.*` procedure of a registry with the handler of `createFsModule({ root })`. It adds no procedure. A nested `fs.*` call of another procedure is confined too. The root must be a folder that exists.
+  - `mark --fs-root <folder>` confines the `fs.*` procedures of each mode and host of `mark`: a command, the REPL, `--server`, `serve` and `mcp`. Give the flag before the command.
+  - A `mark` command uses a CLI server only when the server has the same root. The lockfile of `@procedures/peer` has the new field `fsRoot`, and `findServer()` compares it.
+  - `procedure-server --fs-root <folder>` and `mark serve --fs-root <folder>` confine the procedures of the server.
+  - The MCP server reads `MCP_FS_ROOT`, and `mark mcp` has the flag `--fs-root`. `fs` is not a tool namespace, so the tools do not change.
+  - A path outside the root gives `FORBIDDEN` with the reason `outside-root`. A procedure that reads files with `node:fs`, or that starts a program, is not confined.
+  - `@procedures/lib/cli-flags` has the global flags `--fs-root` and `--events`, and the field `repeatable`.
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- 3d76cb7: `fs.copy` refuses an existing destination without `overwrite`: the error has the code `EEXIST`, and the copy changes nothing. This applies to a file and to a folder, with `recursive` true or false. Before, the default copy (`recursive: true`) kept an existing file, merged a folder into an existing folder, and reported success. With `overwrite`, the copy replaces the files at the destination, as before.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -117,6 +117,19 @@ const registry = createRegistry(createFsModule({ root: "/work/project" }), bundl
 
 `registerFsProcedures(registry, { root })` registers the procedures with the root in one registry.
 
+A host that has a registry already starts `confineFsProcedures(registry, root)`. The function replaces the handler of each `fs.*` procedure of the registry, and it adds no procedure:
+
+```ts
+import { confineFsProcedures } from "@procedures/fs/module";
+
+const { root, procedures } = confineFsProcedures(registry, "/work/project");
+```
+
+- A nested call of another procedure finds the new handler in the registry. Thus `lib.scan`, which calls `fs.readdir`, reads only the folders in the root.
+- The root must be a folder that exists. Otherwise the function throws, and the host does not start.
+- An `fs.*` procedure of another package is an error, because the root cannot confine it.
+- The hosts use this function: `mark --fs-root <folder>`, `procedure-server --fs-root <folder>` and `MCP_FS_ROOT` of the MCP server.
+
 ### Rules
 
 - A relative path starts at the root, not at the working folder of the process.
@@ -138,7 +151,7 @@ const registry = createRegistry(createFsModule({ root: "/work/project" }), bundl
 ### Limits
 
 - The check and the operation are two steps. The check does not see a symlink that a process changes between the two steps.
-- The root applies only to the `fs.*` procedures. A package that uses `node:fs` directly does not get the root. Examples are `git.*` and `lib.*`.
+- The root applies only to the `fs.*` procedures and their nested calls. A procedure that uses `node:fs` directly, or that starts a program, does not get the root. Examples are `git.*`, `archive.*`, `snapshot.*`, `sqlite.*`, the `existsSync` of `lib.*` and the TypeScript files of `lib.rename`.
 - The root does not replace the permissions of the operating system.
 
 ## API Reference
@@ -402,6 +415,8 @@ interface ReaddirEntry {
 
 Copy a file or directory.
 
+Without `overwrite`, an existing destination is an error with the code `EEXIST`, and the copy changes nothing. This applies to a file and to a folder. With `overwrite`, the copy replaces the files at the destination.
+
 ```typescript
 // Copy file
 await client.exec(
@@ -430,7 +445,7 @@ interface CopyInput {
   src: string;
   dest: string;
   recursive?: boolean;       // Default: true
-  overwrite?: boolean;       // Default: false
+  overwrite?: boolean;       // Default: false. Without it, an existing destination is an error (EEXIST)
 }
 ```