@procedures/fs 0.0.0-stage → 0.2.0

package/src/procedures/fs/glob.ts

@@ -0,0 +1,92 @@
+/**
+ * glob procedure
+ *
+ * Find files matching glob pattern
+ *
+ * The matches are relative to `cwd` (or absolute with `absolute: true`), with "/" separators.
+ * `ignore` removes the matches of its patterns and does not enter the folders that they match.
+ *
+ * Before, `ignore` was stripped by the input schema, and `absolute` and `dot` had no effect:
+ * `node:fs` glob has no such options (deep dive DATA-7).
+ */
+
+import { glob as nodeGlob, readdir } from "node:fs/promises";
+import { posix, resolve } from "node:path";
+import type { GlobInput, GlobOutput } from "../../types.js";
+
+// A character that a file name cannot hold. It takes the place of a leading "." of a name, so
+// that "*" and "**" match dot entries when `dot` is true.
+const DOT = "\u0001";
+
+/** "a\\b" (Windows) becomes "a/b". */
+function toPosix(path: string): string {
+  return path.split("\\").join("/");
+}
+
+/** Each name of the path that starts with "." starts with DOT instead. */
+function hideDots(path: string): string {
+  return path
+    .split("/")
+    .map((name) => (name.startsWith(".") && name !== "." && name !== ".." ? DOT + name.slice(1) : name))
+    .join("/");
+}
+
+function ignored(path: string, ignore: readonly string[]): boolean {
+  return ignore.some((pattern) => posix.matchesGlob(path, pattern));
+}
+
+/** A folder is not entered when each path inside it is ignored. */
+function folderIgnored(path: string, ignore: readonly string[]): boolean {
+  return ignored(`${path}/${DOT}`, ignore) || ignored(path, ignore);
+}
+
+/** All the matches of `pattern` under `root`, dot entries included. */
+async function walkWithDots(root: string, pattern: string, ignore: readonly string[]): Promise<string[]> {
+  const hiddenPattern = hideDots(pattern);
+  const hiddenIgnore = ignore.map(hideDots);
+  const matches: string[] = [];
+
+  async function visit(relative: string): Promise<void> {
+    const entries = await readdir(relative ? resolve(root, relative) : root, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = relative ? `${relative}/${entry.name}` : entry.name;
+      const hidden = hideDots(path);
+      if (entry.isDirectory()) {
+        if (folderIgnored(hidden, hiddenIgnore)) continue;
+        if (posix.matchesGlob(hidden, hiddenPattern)) matches.push(path);
+        await visit(path);
+      } else if (posix.matchesGlob(hidden, hiddenPattern) && !ignored(hidden, hiddenIgnore)) {
+        matches.push(path);
+      }
+    }
+  }
+
+  await visit("");
+  return matches;
+}
+
+/**
+ * Find files matching glob pattern
+ */
+export async function glob(input: GlobInput): Promise<GlobOutput> {
+  const { pattern, absolute, dot } = input;
+  const ignore = input.ignore ?? [];
+  const root = resolve(input.cwd ?? process.cwd());
+
+  let relative: string[];
+  if (dot) {
+    relative = await walkWithDots(root, toPosix(pattern), ignore);
+  } else {
+    relative = [];
+    for await (const match of nodeGlob(pattern, { cwd: root, exclude: [...ignore] })) {
+      const path = toPosix(match);
+      // The exclude list of node:fs prunes folders. This check also covers the Node versions
+      // that ignore it.
+      if (!ignored(path, ignore)) relative.push(path);
+    }
+  }
+
+  relative.sort();
+  const matches = absolute ? relative.map((path) => resolve(root, path)) : relative;
+  return { pattern, matches };
+}

package/src/procedures/fs/index.ts

@@ -0,0 +1,11 @@
+export { read } from "./read.js";
+export { write } from "./write.js";
+export { exists } from "./exists.js";
+export { mkdir } from "./mkdir.js";
+export { rm } from "./rm.js";
+export { readdir } from "./readdir.js";
+export { stat } from "./stat.js";
+export { copy } from "./copy.js";
+export { move } from "./move.js";
+export { glob } from "./glob.js";
+export { readJson } from "./json.js";

package/src/procedures/fs/json.ts

@@ -0,0 +1,21 @@
+/**
+ * read.json procedure
+ *
+ * Read and parse JSON file
+ */
+
+import type { ReadJsonInput, ReadJsonOutput } from "../../types.js";
+import { read } from "./read.js";
+
+/**
+ * Read and parse JSON file
+ */
+export async function readJson(input: ReadJsonInput): Promise<ReadJsonOutput> {
+  const { path } = input;
+  const {
+    content,
+    stats
+  } = await read({path, encoding : 'utf8'})
+  const data = JSON.parse(content);
+  return { path, data, stats };
+}

package/src/procedures/fs/mkdir.ts

@@ -0,0 +1,43 @@
+/**
+ * mkdir procedure
+ *
+ * Create directory
+ */
+
+import { mkdir as fsMkdir } from "node:fs/promises";
+import { FileType, type MkdirInput, type MkdirOutput, type StatOutput } from "../../types.js";
+import { stat } from "./stat.js";
+
+/**
+ * Create directory
+ */
+export async function mkdir(input: MkdirInput): Promise<MkdirOutput> {
+  const { path, recursive } = input;
+
+  // Probe the existing path. Only a genuine "not found" (ENOENT) means we
+  // should proceed to create it; any other stat error (e.g. EACCES) must
+  // propagate rather than being masked by an mkdir attempt.
+  let existing: StatOutput | undefined;
+  try {
+    existing = await stat(input);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+
+  if (existing) {
+    // The path already exists. It's only a no-op success if it's a directory;
+    // an existing file (or other non-directory) is a real conflict, not a
+    // silently-"already created" directory.
+    if (existing.type === FileType.Directory) {
+      return { path, created: false };
+    }
+    const conflict = new Error(
+      `Cannot create directory: path already exists and is not a directory: ${path}`,
+    ) as NodeJS.ErrnoException;
+    conflict.code = "EEXIST";
+    throw conflict;
+  }
+
+  await fsMkdir(path, { recursive });
+  return { path, created: true };
+}

package/src/procedures/fs/move.ts

@@ -0,0 +1,47 @@
+/**
+ * move procedure
+ *
+ * Move or rename file/directory
+ */
+
+import { cp, rename } from "node:fs/promises";
+import type { MoveInput, MoveOutput } from "../../types.js";
+import { stat } from "./stat.js";
+import { rm } from "./rm.js";
+
+/**
+ * Move or rename file/directory
+ */
+export async function move(input: MoveInput): Promise<MoveOutput> {
+  const { src, dest, overwrite } = input;
+
+  if (!overwrite) {
+    try {
+      await stat({path : dest});
+      throw new Error(`Destination already exists: ${dest}`);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+    }
+  }
+
+  try {
+    await rename(src, dest);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EXDEV") {
+      // Cross-device move: copy then delete the source. When not overwriting,
+      // use errorOnExist so an already-present destination throws instead of
+      // being silently skipped by `cp` — otherwise the subsequent removal of
+      // `src` would lose the files that were never copied over.
+      await cp(src, dest, {
+        recursive: true,
+        force: overwrite,
+        errorOnExist: !overwrite,
+      });
+      await rm({ path: src, recursive: true, force: false });
+    } else {
+      throw err;
+    }
+  }
+
+  return { src, dest };
+}

package/src/procedures/fs/read.ts

@@ -0,0 +1,23 @@
+/**
+ * read procedure
+ *
+ * Read file contents
+ */
+
+import { readFile } from "node:fs/promises";
+import type { ReadInput, ReadOutput } from "../../types.js";
+import { stat } from "./stat.js";
+
+/**
+ * Read file contents
+ */
+export async function read(input: ReadInput): Promise<ReadOutput> {
+  const { path, encoding } = input;
+  const content = await readFile(path, { encoding: encoding as BufferEncoding });
+  const stats = await stat({path});
+  return {
+    content,
+    path,
+    stats
+  };
+}

package/src/procedures/fs/readdir.ts

@@ -0,0 +1,44 @@
+/**
+ * readdir procedure
+ *
+ * Read directory contents
+ */
+
+import { readdir as fsReaddir } from "node:fs/promises";
+import { join } from "node:path";
+import { type ReaddirInput, type ReaddirOutput, type ReaddirEntry, FileType } from "../../types.js";
+import { stat } from "./stat.js";
+
+/**
+ * Read directory contents
+ */
+export async function readdir(input: ReaddirInput): Promise<ReaddirOutput> {
+  const { path, recursive, includeStats } = input;
+  const entries: ReaddirEntry[] = [];
+
+  async function readDir(dir: string): Promise<void> {
+    const items = await fsReaddir(dir, { withFileTypes: true });
+    for (const item of items) {
+      const fullPath = join(dir, item.name);
+
+      let type: FileType = FileType.Other;
+      if (item.isFile()) type = FileType.File;
+      else if (item.isDirectory()) type = FileType.Directory;
+
+      const entry: ReaddirEntry = { name: item.name, path: fullPath, type };
+
+      if (includeStats) {
+        entry.stats = await stat({path : fullPath});
+      }
+
+      entries.push(entry);
+
+      if (recursive && item.isDirectory()) {
+        await readDir(fullPath);
+      }
+    }
+  }
+
+  await readDir(path);
+  return { path, entries };
+}

package/src/procedures/fs/rm.ts

@@ -0,0 +1,31 @@
+/**
+ * rm procedure
+ *
+ * Remove file or directory
+ */
+
+import { rm as fsRm } from "node:fs/promises";
+import type { RmInput, RmOutput } from "../../types.js";
+
+/**
+ * Remove file or directory
+ */
+export async function rm(input: RmInput): Promise<RmOutput> {
+  const { path, recursive, force } = input;
+  // Always call with force:false so Node reports a missing path via ENOENT
+  // (letting us distinguish "removed" from "didn't exist"). Node's `force`
+  // option only suppresses ENOENT anyway, so replicating it here keeps the
+  // exact same behavior while still surfacing EPERM/ENOTEMPTY/EBUSY/etc.
+  try {
+    await fsRm(path, { recursive, force: false });
+    return { path, removed: true };
+  } catch (err) {
+    // With force:true a non-existent path is not an error — report it as
+    // "nothing removed". Every other error (permissions, non-empty, busy) must
+    // propagate rather than being silently swallowed.
+    if (force && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      return { path, removed: false };
+    }
+    throw err;
+  }
+}

package/src/procedures/fs/stat.ts

@@ -0,0 +1,30 @@
+/**
+ * stat procedure
+ *
+ * Get file or directory stats
+ */
+
+import { stat as fsStat } from "node:fs/promises";
+import { FileType, type StatInput, type StatOutput } from "../../types.js";
+
+/**
+ * Get file or directory stats
+ */
+export async function stat(input: StatInput): Promise<StatOutput> {
+  const { path } = input;
+  const stats = await fsStat(path);
+
+  let type: FileType = FileType.Other;
+  if (stats.isFile()) type = FileType.File;
+  else if (stats.isDirectory()) type = FileType.Directory;
+
+  return {
+    path,
+    type,
+    size: stats.size,
+    mtime: stats.mtime.toISOString(),
+    ctime: stats.ctime.toISOString(),
+    atime: stats.atime.toISOString(),
+    mode: stats.mode,
+  };
+}

package/src/procedures/fs/write.ts

@@ -0,0 +1,27 @@
+/**
+ * write procedure
+ *
+ * Write content to file
+ */
+
+import { writeFile, appendFile } from "node:fs/promises";
+import type { WriteInput, WriteOutput } from "../../types.js";
+
+/**
+ * Write content to file
+ */
+export async function write(input: WriteInput): Promise<WriteOutput> {
+  const { path, content, encoding, mode } = input;
+  const writeOptions = { encoding: encoding as BufferEncoding };
+
+  if (mode === "append") {
+    await appendFile(path, content, writeOptions);
+  } else {
+    await writeFile(path, content, writeOptions);
+  }
+
+  return {
+    path,
+    bytesWritten: Buffer.byteLength(content, encoding as BufferEncoding),
+  };
+}

package/src/procedures/fs.ts

@@ -0,0 +1,5 @@
+/**
+ * Filesystem procedures barrel export
+ */
+
+export * from "./fs/index.js";

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/fs, and of the modules that it
+ * requires, in the global registry: `import "@procedures/fs/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerFsProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerFsProcedures();