@procedures/fs 0.2.3 → 0.4.0

package/src/handlers.ts

@@ -0,0 +1,214 @@
+/**
+ * The handlers of the file procedures with a root (roadmap R33).
+ *
+ * `fsModule` has the plain handlers: they operate on each path. `createFsModule({ root })`
+ * replaces each handler with the handler of `rootedHandlers(root)`. That handler sends the paths
+ * of its input through `inRoot()`, then starts the plain handler with the absolute path.
+ */
+
+import { platform } from "node:process";
+import { isAbsolute, resolve } from "node:path";
+import type { ProcedurePath } from "@procedures/client";
+import { read } from "./procedures/fs/read.js";
+import { write } from "./procedures/fs/write.js";
+import { exists } from "./procedures/fs/exists.js";
+import { mkdir } from "./procedures/fs/mkdir.js";
+import { rm } from "./procedures/fs/rm.js";
+import { readdir } from "./procedures/fs/readdir.js";
+import { stat } from "./procedures/fs/stat.js";
+import { copy } from "./procedures/fs/copy.js";
+import { move } from "./procedures/fs/move.js";
+import { glob } from "./procedures/fs/glob.js";
+import { readJson } from "./procedures/fs/json.js";
+import { fsWriteJson } from "./procedures/fs/write-json.js";
+import { fsHash } from "./procedures/fs/hash.js";
+import { fsTemp } from "./procedures/fs/temp.js";
+import { fsWatch } from "./procedures/fs/watch.js";
+import { inRoot, isOutsideRoot, outsideRoot, realPathIsInside, resolveRoot, type ResolvedRoot } from "./root.js";
+import type {
+  ReadInput,
+  ReadOutput,
+  WriteInput,
+  WriteOutput,
+  ExistsInput,
+  ExistsOutput,
+  MkdirInput,
+  MkdirOutput,
+  RmInput,
+  RmOutput,
+  ReaddirInput,
+  ReaddirOutput,
+  StatInput,
+  StatOutput,
+  CopyInput,
+  CopyOutput,
+  MoveInput,
+  MoveOutput,
+  GlobInput,
+  GlobOutput,
+  ReadJsonInput,
+  ReadJsonOutput,
+  FsWriteJsonInput,
+  FsWriteJsonOutput,
+  FsHashInput,
+  FsHashOutput,
+  FsTempInput,
+  FsTempOutput,
+  FsWatchInput,
+  FsWatchOutput,
+} from "./types.js";
+
+/** One handler for each file procedure. */
+export interface FsHandlers {
+  read: (input: ReadInput) => Promise<ReadOutput>;
+  write: (input: WriteInput) => Promise<WriteOutput>;
+  exists: (input: ExistsInput) => Promise<ExistsOutput>;
+  mkdir: (input: MkdirInput) => Promise<MkdirOutput>;
+  rm: (input: RmInput) => Promise<RmOutput>;
+  readdir: (input: ReaddirInput) => Promise<ReaddirOutput>;
+  stat: (input: StatInput) => Promise<StatOutput>;
+  copy: (input: CopyInput) => Promise<CopyOutput>;
+  move: (input: MoveInput) => Promise<MoveOutput>;
+  glob: (input: GlobInput) => Promise<GlobOutput>;
+  readJson: (input: ReadJsonInput) => Promise<ReadJsonOutput>;
+  writeJson: (input: FsWriteJsonInput) => Promise<FsWriteJsonOutput>;
+  hash: (input: FsHashInput) => Promise<FsHashOutput>;
+  temp: (input: FsTempInput) => Promise<FsTempOutput>;
+  watch: (input: FsWatchInput, ctx?: { signal?: AbortSignal | undefined }) => AsyncGenerator<FsWatchOutput, void, undefined>;
+}
+
+/**
+ * The name of the handler of each procedure, by the key of the procedure. `createFsModule()`
+ * refuses a procedure that is not in this list, so a new procedure cannot skip the root.
+ */
+export const HANDLER_NAMES: Readonly<Record<string, keyof FsHandlers>> = {
+  "fs.read": "read",
+  "fs.write": "write",
+  "fs.exists": "exists",
+  "fs.mkdir": "mkdir",
+  "fs.rm": "rm",
+  "fs.readdir": "readdir",
+  "fs.stat": "stat",
+  "fs.copy": "copy",
+  "fs.move": "move",
+  "fs.glob": "glob",
+  "fs.read.json": "readJson",
+  "fs.write.json": "writeJson",
+  "fs.hash": "hash",
+  "fs.temp": "temp",
+  "fs.watch": "watch",
+};
+
+/**
+ * True for a glob pattern that can match outside its folder: an absolute pattern, a pattern that
+ * goes up with `..` (also in a brace or a group), or a pattern that starts with a drive on Windows.
+ * The handler also removes each match outside the root, so this check only gives a clear error.
+ */
+function patternLeavesFolder(pattern: string): boolean {
+  if (isAbsolute(pattern) || pattern.startsWith("/") || pattern.startsWith("\\")) return true;
+  if (platform === "win32" && /^[a-zA-Z]:/.test(pattern)) return true;
+  return pattern.split(/[\\/{},()|]/).includes("..");
+}
+
+/**
+ * This function gives the handlers that confine each path to `root`. The root is resolved
+ * against the working folder of the process when the function starts. It must exist when a
+ * procedure starts.
+ */
+export function rootedHandlers(root: string): FsHandlers {
+  const folder = resolve(root);
+  /** The root of one call (its real path can change between two calls), and the check of its paths. */
+  const check = async (procedure: string): Promise<{ root: ResolvedRoot; inside: (path: string) => Promise<string> }> => {
+    const resolved = await resolveRoot(folder);
+    const at: ProcedurePath = ["fs", procedure];
+    return { root: resolved, inside: (path) => inRoot(resolved, path, at) };
+  };
+
+  return {
+    read: async (input) => {
+      const { inside } = await check("read");
+      return read({ ...input, path: await inside(input.path) });
+    },
+    write: async (input) => {
+      const { inside } = await check("write");
+      return write({ ...input, path: await inside(input.path) });
+    },
+    exists: async (input) => {
+      const { inside } = await check("exists");
+      return exists({ ...input, path: await inside(input.path) });
+    },
+    mkdir: async (input) => {
+      const { inside } = await check("mkdir");
+      return mkdir({ ...input, path: await inside(input.path) });
+    },
+    rm: async (input) => {
+      const { inside } = await check("rm");
+      return rm({ ...input, path: await inside(input.path) });
+    },
+    stat: async (input) => {
+      const { inside } = await check("stat");
+      return stat({ ...input, path: await inside(input.path) });
+    },
+    readJson: async (input) => {
+      const { inside } = await check("read.json");
+      return readJson({ ...input, path: await inside(input.path) });
+    },
+    writeJson: async (input) => {
+      const { inside } = await check("write.json");
+      return fsWriteJson({ ...input, path: await inside(input.path) });
+    },
+    hash: async (input) => {
+      const { inside } = await check("hash");
+      return fsHash({ ...input, path: await inside(input.path) });
+    },
+    // The temporary folders of a root are in its folder .tmp, so they stay inside the root
+    temp: async (input) => {
+      const { inside } = await check("temp");
+      return fsTemp(input, await inside(".tmp"));
+    },
+    watch: async function* (input, ctx) {
+      const { inside } = await check("watch");
+      yield* fsWatch({ ...input, path: await inside(input.path) }, ctx?.signal);
+    },
+    copy: async (input) => {
+      const { inside } = await check("copy");
+      return copy({ ...input, src: await inside(input.src), dest: await inside(input.dest) });
+    },
+    move: async (input) => {
+      const { inside } = await check("move");
+      return move({ ...input, src: await inside(input.src), dest: await inside(input.dest) });
+    },
+    readdir: async (input) => {
+      const { inside } = await check("readdir");
+      // The stats of an entry follow a symlink: an entry whose target is outside the root gets no stats
+      const result = await readdir({ ...input, path: await inside(input.path), includeStats: false });
+      if (input.includeStats) {
+        for (const entry of result.entries) {
+          try {
+            await inside(entry.path);
+          } catch (error) {
+            if (isOutsideRoot(error)) continue;
+            throw error;
+          }
+          entry.stats = await stat({ path: entry.path });
+        }
+      }
+      return result;
+    },
+    glob: async (input) => {
+      const { root: resolved, inside } = await check("glob");
+      const cwd = await inside(input.cwd ?? ".");
+      if (patternLeavesFolder(input.pattern)) {
+        throw outsideRoot(["fs", "glob"], `the pattern ${JSON.stringify(input.pattern)} can match outside the folder ${cwd}`);
+      }
+      // A match through a symlink whose target is outside the root is left out
+      const found = await glob({ ...input, cwd, absolute: false });
+      const matches: string[] = [];
+      for (const match of found.matches) {
+        const absolute = resolve(cwd, match);
+        if (await realPathIsInside(resolved, absolute)) matches.push(input.absolute ? absolute : match);
+      }
+      return { pattern: input.pattern, matches };
+    },
+  };
+}

package/src/index.ts

@@ -15,3 +15,5 @@
 
 export * from "./procedures/fs.js";
 export * from "./module.js";
+// The root that confines each path (roadmap R33)
+export { OUTSIDE_ROOT, isInside, isOutsideRoot } from "./root.js";

package/src/module.ts

@@ -5,9 +5,13 @@
  *
  * Registers fs.* procedures with the client system.
  * This file is referenced by package.json's client.procedures field.
+ *
+ * `fsModule` operates on each path. `createFsModule({ root })` gives the same procedures, and
+ * each path of their input must be in the root (roadmap R33, `root.ts`).
  */
 
-import { createProcedure, zodAdapter, defineModule, type Effects, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { createProcedure, zodAdapter, defineModule, type AnyProcedure, type Effects, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import { HANDLER_NAMES, rootedHandlers } from "./handlers.js";
 import { read } from "./procedures/fs/read.js";
 import { write } from "./procedures/fs/write.js";
 import { exists } from "./procedures/fs/exists.js";
@@ -65,6 +69,28 @@ import {
   GlobOutputSchema,
   ReadJsonOutputSchema,
 } from "./types.js";
+import { fsWriteJson } from "./procedures/fs/write-json.js";
+import { fsHash } from "./procedures/fs/hash.js";
+import { fsTemp } from "./procedures/fs/temp.js";
+import { fsWatch } from "./procedures/fs/watch.js";
+import {
+  FsWriteJsonInputSchema,
+  FsWriteJsonOutputSchema,
+  FsHashInputSchema,
+  FsHashOutputSchema,
+  FsTempInputSchema,
+  FsTempOutputSchema,
+  FsWatchInputSchema,
+  FsWatchOutputSchema,
+  type FsWriteJsonInput,
+  type FsWriteJsonOutput,
+  type FsHashInput,
+  type FsHashOutput,
+  type FsTempInput,
+  type FsTempOutput,
+  type FsWatchInput,
+  type FsWatchOutput,
+} from "./types.js";
 
 // =============================================================================
 // Procedure Definitions
@@ -178,7 +204,7 @@ const fsCopyProcedure = createProcedure()
   .input(zodAdapter<CopyInput>(CopyInputSchema))
   .output(zodAdapter<CopyOutput>(CopyOutputSchema))
   .meta({
-    description: "Copy file or directory",
+    description: "Copy file or directory. Without overwrite, it refuses an existing destination (EEXIST).",
     args: ["src", "dest"],
     shorts: { recursive: "r", overwrite: "o" },
     output: "json",
@@ -231,6 +257,68 @@ const fsReadJsonProcedure = createProcedure()
   .handler(readJson)
   .build();
 
+// fs.write.json, fs.hash, fs.temp and fs.watch (roadmap R44)
+
+const fsWriteJsonProcedure = createProcedure()
+  .path(["fs", "write.json"])
+  .input(zodAdapter<FsWriteJsonInput>(FsWriteJsonInputSchema))
+  .output(zodAdapter<FsWriteJsonOutput>(FsWriteJsonOutputSchema))
+  .meta({
+    description: "Write a value as a JSON file, with a rename at the end",
+    args: ["path"],
+    shorts: {},
+    output: "json",
+    // It replaces the file: destructive, and the same input gives the same file
+    effects: { reads: [], writes: ["fs"], destructive: true, idempotent: true },
+  })
+  .handler(fsWriteJson)
+  .build();
+
+const fsHashProcedure = createProcedure()
+  .path(["fs", "hash"])
+  .input(zodAdapter<FsHashInput>(FsHashInputSchema))
+  .output(zodAdapter<FsHashOutput>(FsHashOutputSchema))
+  .meta({
+    description: "The hash of a file",
+    args: ["path"],
+    shorts: { algorithm: "a" },
+    output: "json",
+    effects: READS_FILES,
+  })
+  .handler((input: FsHashInput) => fsHash(input))
+  .build();
+
+const fsTempProcedure = createProcedure()
+  .path(["fs", "temp"])
+  .input(zodAdapter<FsTempInput>(FsTempInputSchema))
+  .output(zodAdapter<FsTempOutput>(FsTempOutputSchema))
+  .meta({
+    description: "Make a temporary folder",
+    args: [],
+    shorts: {},
+    output: "json",
+    // It makes a new folder each time, and changes nothing that exists
+    effects: { reads: [], writes: ["fs"], destructive: false, idempotent: false },
+  })
+  .handler((input: FsTempInput) => fsTemp(input))
+  .build();
+
+const fsWatchProcedure = createProcedure()
+  .path(["fs", "watch"])
+  .input(zodAdapter<FsWatchInput>(FsWatchInputSchema))
+  .output(zodAdapter<FsWatchOutput>(FsWatchOutputSchema))
+  .meta({
+    description: "The changes of a file or folder, as a stream",
+    args: ["path"],
+    shorts: { recursive: "r" },
+    output: "streaming",
+    effects: READS_FILES,
+    // The stream has no end: it stops when the reader stops (roadmap R15)
+    stream: { unbounded: true },
+  })
+  .handler(((input: FsWatchInput, ctx?: { signal?: AbortSignal }) => fsWatch(input, ctx?.signal)) as never)
+  .build();
+
 // =============================================================================
 // Registration
 // =============================================================================
@@ -251,15 +339,50 @@ export const fsModule: ProcedureModule = defineModule("@procedures/fs", [
     fsMoveProcedure,
     fsGlobProcedure,
     fsReadJsonProcedure,
+    fsWriteJsonProcedure,
+    fsHashProcedure,
+    fsTempProcedure,
+    fsWatchProcedure,
   ]);
 
 export default fsModule;
 
+/** The options of `createFsModule()`. */
+export interface FsModuleOptions {
+  /**
+   * The folder that confines each path of the procedures (roadmap R33). A relative path of an
+   * input starts at the root. A path outside the root gives `FORBIDDEN` with the reason
+   * `outside-root`. A relative root starts at the working folder of the process. Without a root,
+   * the procedures operate on each path, as `fsModule` does.
+   */
+  root?: string | undefined;
+}
+
+/**
+ * This function gives the module of this package. Without `root`, it gives `fsModule`. With
+ * `root`, it gives a module with the same name and procedures, whose handlers confine each path
+ * of the input to the root. A host gives it to `createRegistry()` before its bundles, so it
+ * replaces the `fsModule` that the bundles require (the first module of a name counts).
+ */
+export function createFsModule(options: FsModuleOptions = {}): ProcedureModule {
+  if (options.root === undefined) return fsModule;
+  const handlers = rootedHandlers(options.root);
+  const procedures = fsModule.procedures.map((procedure): AnyProcedure => {
+    const key = procedure.path.join(".");
+    const name = HANDLER_NAMES[key];
+    // A procedure without a rooted handler would operate outside the root
+    if (name === undefined) throw new Error(`The root of @procedures/fs has no handler for ${key}: add it to rootedHandlers()`);
+    return { ...procedure, handler: handlers[name] as AnyProcedure["handler"] };
+  });
+  return defineModule("@procedures/fs", procedures);
+}
+
 /**
  * This function registers the procedures of @procedures/fs, and of the modules that it requires, in
  * a registry. The default is the global registry. Importing this file registers nothing: the
- * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9). With
+ * `options.root`, each path of an input must be in the root.
  */
-export function registerFsProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
-  registerModules(registry, [fsModule]);
+export function registerFsProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: FsModuleOptions = {}): void {
+  registerModules(registry, [createFsModule(options)]);
 }

package/src/procedures/fs/copy.ts

@@ -4,20 +4,43 @@
  * Copy file or directory
  */
 
-import { copyFile, cp, constants } from "node:fs/promises";
+import { copyFile, cp, constants, lstat } from "node:fs/promises";
 import type { CopyInput, CopyOutput } from "../../types.js";
 
+/** This function gives true when something exists at the path: a file, a folder or a link. */
+async function exists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 /**
- * Copy file or directory
+ * Copy file or directory.
+ *
+ * Without `overwrite`, an existing destination is an error with the code `EEXIST`, and the copy
+ * changes nothing. Before, the default copy (`recursive: true`) kept an existing file and
+ * reported success (roadmap R33). With `overwrite`, the copy replaces the files at the
+ * destination.
  */
 export async function copy(input: CopyInput): Promise<CopyOutput> {
   const { src, dest, recursive, overwrite } = input;
-  const flags = overwrite ? 0 : constants.COPYFILE_EXCL;
+
+  if (!overwrite && (await exists(dest))) {
+    throw Object.assign(new Error(`Destination already exists: ${dest}. Set overwrite to replace it.`), {
+      code: "EEXIST",
+      path: dest,
+    });
+  }
 
   if (recursive) {
-    await cp(src, dest, { recursive, force: overwrite });
+    // errorOnExist: a file that appears at the destination after the check is an error too
+    await cp(src, dest, { recursive, force: overwrite, errorOnExist: !overwrite });
   } else {
-    await copyFile(src, dest, flags);
+    await copyFile(src, dest, overwrite ? 0 : constants.COPYFILE_EXCL);
   }
 
   return { src, dest };

package/src/procedures/fs/hash.ts

@@ -0,0 +1,25 @@
+/**
+ * fs.hash procedure (roadmap R44)
+ *
+ * The hash of a file. The procedure reads the file as a stream, so a large file does not fill
+ * the memory.
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import type { FsHashInput, FsHashOutput } from "../../types.js";
+
+/**
+ * The hash of a file
+ */
+export async function fsHash(input: FsHashInput): Promise<FsHashOutput> {
+  const algorithm = input.algorithm ?? "sha256";
+  const hash = createHash(algorithm);
+  let size = 0;
+  for await (const chunk of createReadStream(input.path)) {
+    const bytes = chunk as Buffer;
+    size += bytes.length;
+    hash.update(bytes);
+  }
+  return { path: input.path, algorithm, hash: hash.digest("hex"), size };
+}

package/src/procedures/fs/index.ts

@@ -9,3 +9,7 @@ export { copy } from "./copy.js";
 export { move } from "./move.js";
 export { glob } from "./glob.js";
 export { readJson } from "./json.js";
+export { fsWriteJson } from "./write-json.js";
+export { fsHash } from "./hash.js";
+export { fsTemp } from "./temp.js";
+export { fsWatch } from "./watch.js";

package/src/procedures/fs/temp.ts

@@ -0,0 +1,22 @@
+/**
+ * fs.temp procedure (roadmap R44)
+ *
+ * Make a temporary folder with a name that no other folder has. Without a root, the folder is in
+ * the temporary folder of the system. With the root of `createFsModule({ root })`, it is in the
+ * folder `.tmp` of the root, so it stays inside the root.
+ */
+
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { FsTempInput, FsTempOutput } from "../../types.js";
+
+/**
+ * Make a temporary folder. `base` is the folder that holds it (default: the temporary folder of
+ * the system).
+ */
+export async function fsTemp(input: FsTempInput, base: string = tmpdir()): Promise<FsTempOutput> {
+  await mkdir(base, { recursive: true });
+  const path = await mkdtemp(join(base, input.prefix ?? "procedures-"));
+  return { path };
+}

package/src/procedures/fs/watch.ts

@@ -0,0 +1,26 @@
+/**
+ * fs.watch procedure (roadmap R44)
+ *
+ * The changes of a file or folder, as a stream: one item for each change that the platform
+ * reports. The stream has no end: it stops when the reader stops or the signal of the call
+ * aborts. The platform decides the details: a change can give two items, and some platforms
+ * give no file name.
+ */
+
+import { watch } from "node:fs/promises";
+import type { FsWatchInput, FsWatchOutput } from "../../types.js";
+
+/**
+ * The changes of a file or folder, as a stream
+ */
+export async function* fsWatch(input: FsWatchInput, signal?: AbortSignal): AsyncGenerator<FsWatchOutput, void, undefined> {
+  try {
+    for await (const change of watch(input.path, { recursive: input.recursive ?? false, ...(signal ? { signal } : {}) })) {
+      yield { event: change.eventType === "change" ? "change" : "rename", filename: change.filename ?? null };
+    }
+  } catch (error) {
+    // The abort of the call ends the stream without an error
+    if ((error as { name?: string }).name === "AbortError") return;
+    throw error;
+  }
+}

package/src/procedures/fs/write-json.ts

@@ -0,0 +1,32 @@
+/**
+ * fs.write.json procedure (roadmap R44)
+ *
+ * Write a value as a JSON file. The procedure writes a file next to the target, then renames it,
+ * so a reader sees the old file or the whole new file, never a half-written one.
+ */
+
+import { randomBytes } from "node:crypto";
+import { rename, rm, writeFile } from "node:fs/promises";
+import type { FsWriteJsonInput, FsWriteJsonOutput } from "../../types.js";
+
+/**
+ * Write a value as a JSON file, with a rename at the end
+ */
+export async function fsWriteJson(input: FsWriteJsonInput): Promise<FsWriteJsonOutput> {
+  const text = JSON.stringify(input.value ?? null, null, input.indent ?? 2);
+  if (text === undefined) throw new Error("fs.write.json: the value has no JSON form");
+  const content = `${text}\n`;
+  const temporary = `${input.path}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(temporary, content, "utf8");
+    await rename(temporary, input.path);
+  } catch (error) {
+    try {
+      await rm(temporary, { force: true });
+    } catch {
+      // The error of the write counts, not the error of the cleanup
+    }
+    throw error;
+  }
+  return { path: input.path, bytesWritten: Buffer.byteLength(content, "utf8") };
+}