@procedures/fs 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @procedures/fs
 
+## 0.3.0
+
+### Minor Changes
+
+- f23c7ad: Four file procedures (roadmap R44). `fs.write.json` writes a value as JSON through a file that it renames at the end. `fs.hash` gives the hash of a file. `fs.temp` makes a temporary folder. `fs.watch` gives the changes of a file or folder as a stream without an end. With `createFsModule({ root })`, each path stays in the root, and `fs.temp` makes its folders in the folder `.tmp` of the root.
+- bc70357: The file procedures can have a root (roadmap R33). `createFsModule({ root })` gives the procedures of `fsModule`, and each path of each input must be in the root folder. A relative path starts at the root. Without a root, the procedures operate as before.
+  
+  The procedures refuse a path that goes up with `..`, an absolute path outside the root and another drive. They also refuse a symlink or a junction that goes out of the root. The error has the code `FORBIDDEN` and the new reason `outside-root` (the type `ForbiddenReason` of `@procedures/client`). For a path that does not exist, the check uses the real path of the nearest existing folder. `registerFsProcedures(registry, { root })` takes the root too.
+
+### Patch Changes
+
+- 3c40d2d: The root of the file procedures accepts a path by its real path. On Windows, a folder can have a short 8.3 name (`RUNNER~1`) and a long real name. A path that used the short name was refused when the root was a link.
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [15e48cf]
+  - @procedures/client@0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -18,7 +18,7 @@ File system operations as RPC procedures. Read, write, copy, move, glob files an
 - **Zod validation**: Runtime type safety on all inputs
 
 The package has 11 procedures. Its register entry (`import "@procedures/fs/register"`) registers them:
-`fs.read`, `fs.write`, `fs.exists`, `fs.stat`, `fs.mkdir`, `fs.rm`, `fs.readdir`, `fs.copy`, `fs.move`, `fs.glob`, `fs.read.json`
+`fs.read`, `fs.write`, `fs.exists`, `fs.stat`, `fs.mkdir`, `fs.rm`, `fs.readdir`, `fs.copy`, `fs.move`, `fs.glob`, `fs.read.json`, `fs.write.json`, `fs.hash`, `fs.temp`, `fs.watch`
 
 ## Architecture
 
@@ -102,6 +102,45 @@ Since 0.2.0, an import of the package registers nothing. To register its procedu
 import "@procedures/fs/register";
 ```
 
+## Confine the paths to a root
+
+A host can give the file procedures a root folder. Then each path of each input must be in the root.
+
+```ts
+import { createRegistry } from "@procedures/client";
+import { createFsModule } from "@procedures/fs/module";
+import { bundleDevModule } from "@procedures/bundle-dev/module";
+
+// The module with the root comes first: it replaces the fsModule that the bundle requires
+const registry = createRegistry(createFsModule({ root: "/work/project" }), bundleDevModule);
+```
+
+`registerFsProcedures(registry, { root })` registers the procedures with the root in one registry.
+
+### Rules
+
+- A relative path starts at the root, not at the working folder of the process.
+- An absolute path in the root is correct.
+- The procedures refuse a path outside the root. The error has the code `FORBIDDEN` and the reason `outside-root`. A server sends the reason in the metadata key `reason`.
+- These paths are outside the root: a path that goes up with `..`, an absolute path in another folder and a path on another drive.
+- The procedures refuse a symlink or a junction that goes out of the root. The check uses the real path of the input (`fs.realpath`).
+- For a path that does not exist, the check uses the real path of the nearest folder above it. Thus a write or `fs.mkdir` cannot go out of the root through a symlinked folder.
+- The check follows a symlink to its target, also when the target does not exist, because a write follows the symlink too.
+- Each path input of each procedure gets the check: `path`, `src`, `dest` and the `cwd` of `fs.glob`.
+- `fs.glob` refuses an absolute pattern, a pattern that starts with a drive and a pattern with a `..` segment. It also removes each match whose real path is outside the root.
+- `fs.readdir` with `includeStats` gives no stats for an entry that goes out of the root.
+- The procedures get the absolute path, so the paths of the output are absolute.
+- On Windows, the check ignores the case of the letters, and `/` and `\` are equal.
+- A relative root starts at the working folder of the process when `createFsModule()` starts.
+- If the root does not exist, each procedure fails with the code `ENOENT`.
+- Without a root, the procedures operate on each path as before. `createFsModule()` gives `fsModule`.
+
+### 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 does not replace the permissions of the operating system.
+
 ## API Reference
 
 ### File Operations
@@ -539,6 +578,36 @@ const pkg = result.data as PackageJson;
 console.log(pkg.name, pkg.version);
 ```
 
+#### `fs.write.json`
+
+The procedure writes a value as a JSON file, with 2 spaces of indent and a line break at the end. It writes a file next to the target first, then renames it. Thus a reader sees the old file or the whole new file.
+
+```typescript
+await client.exec(["fs", "write.json"], { path: "./data.json", value: { a: 1 }, indent: 2 });
+```
+
+#### `fs.hash`
+
+The procedure gives the hash of a file as hexadecimal text: `sha256` (the default), `sha512`, `sha1` or `md5`. It reads the file as a stream.
+
+```typescript
+const { hash, size } = await client.exec(["fs", "hash"], { path: "./archive.tgz" });
+```
+
+#### `fs.temp`
+
+The procedure makes a new folder in the temporary folder of the system, and gives its path. With a root, the folder is in the folder `.tmp` of the root. The `prefix` has letters, digits, dots, underscores and hyphens only.
+
+#### `fs.watch`
+
+The procedure gives the changes of a file or folder as a stream. Each item has the `event` (`rename` or `change`) and the `filename`. The stream has no end: it stops when the reader stops or the call aborts. The platform decides the details, so one change can give two items.
+
+```typescript
+for await (const change of client.execStream(["fs", "watch"], { path: "./src", recursive: true })) {
+  console.log(change.event, change.filename);
+}
+```
+
 ## Usage Examples
 
 ### Basic File Operations
@@ -843,6 +912,9 @@ client-fs/
 │   ├── types.ts                  # Zod schemas + TypeScript types
 │   ├── register.ts               # Auto-registration
 │   ├── index.ts                  # Main entry point
+│   ├── module.ts                 # fsModule, createFsModule({ root })
+│   ├── root.ts                   # The check of a path against the root
+│   ├── handlers.ts               # The handlers with a root
 │   ├── procedures/
 │   │   ├── fs.ts                 # Barrel export
 │   │   └── fs/