@procedures/fs 0.0.0-stage → 0.1.0

package/src/module.ts

@@ -0,0 +1,238 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for filesystem operations
+ *
+ * Registers fs.* procedures with the client system.
+ * This file is referenced by package.json's client.procedures field.
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule } 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 {
+  ReadInputSchema,
+  WriteInputSchema,
+  ExistsInputSchema,
+  MkdirInputSchema,
+  RmInputSchema,
+  ReaddirInputSchema,
+  StatInputSchema,
+  CopyInputSchema,
+  MoveInputSchema,
+  GlobInputSchema,
+  ReadJsonInputSchema,
+  type ReadInput,
+  type ReadOutput,
+  type WriteInput,
+  type WriteOutput,
+  type ExistsInput,
+  type ExistsOutput,
+  type MkdirInput,
+  type MkdirOutput,
+  type RmInput,
+  type RmOutput,
+  type ReaddirInput,
+  type ReaddirOutput,
+  type StatInput,
+  type StatOutput,
+  type CopyInput,
+  type CopyOutput,
+  type MoveInput,
+  type MoveOutput,
+  type GlobInput,
+  type GlobOutput,
+  type ReadJsonInput,
+  type ReadJsonOutput,
+  ReadOutputSchema,
+  WriteOutputSchema,
+  ExistsOutputSchema,
+  MkdirOutputSchema,
+  RmOutputSchema,
+  ReaddirOutputSchema,
+  StatOutputSchema,
+  CopyOutputSchema,
+  MoveOutputSchema,
+  GlobOutputSchema,
+  ReadJsonOutputSchema,
+} from "./types.js";
+
+// =============================================================================
+// Procedure Definitions
+// =============================================================================
+
+const fsReadProcedure = createProcedure()
+  .path(["fs", "read"])
+  .input(zodAdapter<ReadInput>(ReadInputSchema))
+  .output(zodAdapter<ReadOutput>(ReadOutputSchema))
+  .meta({
+    description: "Read file contents",
+    args: ["path"],
+    shorts: { encoding: "e" },
+    output: "json",
+  })
+  .handler(read)
+  .build();
+
+const fsWriteProcedure = createProcedure()
+  .path(["fs", "write"])
+  .input(zodAdapter<WriteInput>(WriteInputSchema))
+  .output(zodAdapter<WriteOutput>(WriteOutputSchema))
+  .meta({
+    description: "Write content to file",
+    args: ["path", "content"],
+    shorts: { encoding: "e", mode: "m" },
+    output: "json",
+  })
+  .handler(write)
+  .build();
+
+const fsExistsProcedure = createProcedure()
+  .path(["fs", "exists"])
+  .input(zodAdapter<ExistsInput>(ExistsInputSchema))
+  .output(zodAdapter<ExistsOutput>(ExistsOutputSchema))
+  .meta({
+    description: "Check if file or directory exists",
+    args: ["path"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(exists)
+  .build();
+
+const fsMkdirProcedure = createProcedure()
+  .path(["fs", "mkdir"])
+  .input(zodAdapter<MkdirInput>(MkdirInputSchema))
+  .output(zodAdapter<MkdirOutput>(MkdirOutputSchema))
+  .meta({
+    description: "Create directory",
+    args: ["path"],
+    shorts: { recursive: "r" },
+    output: "json",
+  })
+  .handler(mkdir)
+  .build();
+
+const fsRmProcedure = createProcedure()
+  .path(["fs", "rm"])
+  .input(zodAdapter<RmInput>(RmInputSchema))
+  .output(zodAdapter<RmOutput>(RmOutputSchema))
+  .meta({
+    description: "Remove file or directory",
+    args: ["path"],
+    shorts: { recursive: "r", force: "f" },
+    output: "json",
+  })
+  .handler(rm)
+  .build();
+
+const fsReaddirProcedure = createProcedure()
+  .path(["fs", "readdir"])
+  .input(zodAdapter<ReaddirInput>(ReaddirInputSchema))
+  .output(zodAdapter<ReaddirOutput>(ReaddirOutputSchema))
+  .meta({
+    description: "Read directory contents",
+    args: ["path"],
+    shorts: { recursive: "r", includeStats: "s" },
+    output: "json",
+  })
+  .handler(readdir)
+  .build();
+
+const fsStatProcedure = createProcedure()
+  .path(["fs", "stat"])
+  .input(zodAdapter<StatInput>(StatInputSchema))
+  .output(zodAdapter<StatOutput>(StatOutputSchema))
+  .meta({
+    description: "Get file or directory stats",
+    args: ["path"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(stat)
+  .build();
+
+const fsCopyProcedure = createProcedure()
+  .path(["fs", "copy"])
+  .input(zodAdapter<CopyInput>(CopyInputSchema))
+  .output(zodAdapter<CopyOutput>(CopyOutputSchema))
+  .meta({
+    description: "Copy file or directory",
+    args: ["src", "dest"],
+    shorts: { recursive: "r", overwrite: "o" },
+    output: "json",
+  })
+  .handler(copy)
+  .build();
+
+const fsMoveProcedure = createProcedure()
+  .path(["fs", "move"])
+  .input(zodAdapter<MoveInput>(MoveInputSchema))
+  .output(zodAdapter<MoveOutput>(MoveOutputSchema))
+  .meta({
+    description: "Move or rename file/directory",
+    args: ["src", "dest"],
+    shorts: { overwrite: "o" },
+    output: "json",
+  })
+  .handler(move)
+  .build();
+
+const fsGlobProcedure = createProcedure()
+  .path(["fs", "glob"])
+  .input(zodAdapter<GlobInput>(GlobInputSchema))
+  .output(zodAdapter<GlobOutput>(GlobOutputSchema))
+  .meta({
+    description: "Find files matching glob pattern",
+    args: ["pattern"],
+    shorts: { cwd: "c", absolute: "a", dot: "d" },
+    output: "json",
+  })
+  .handler(glob)
+  .build();
+
+const fsReadJsonProcedure = createProcedure()
+  .path(["fs", "read.json"])
+  .input(zodAdapter<ReadJsonInput>(ReadJsonInputSchema))
+  .output(zodAdapter<ReadJsonOutput>(ReadJsonOutputSchema))
+  .meta({
+    description: "Read and parse JSON file",
+    args: ["path"],
+    shorts: {},
+    output: "json",
+  })
+  .handler(readJson)
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const fsModule: ProcedureModule = defineModule("@procedures/fs", [
+    fsReadProcedure,
+    fsWriteProcedure,
+    fsExistsProcedure,
+    fsMkdirProcedure,
+    fsRmProcedure,
+    fsReaddirProcedure,
+    fsStatProcedure,
+    fsCopyProcedure,
+    fsMoveProcedure,
+    fsGlobProcedure,
+    fsReadJsonProcedure,
+  ]);
+
+export default fsModule;

package/src/procedures/fs/copy.ts

@@ -0,0 +1,24 @@
+/**
+ * copy procedure
+ *
+ * Copy file or directory
+ */
+
+import { copyFile, cp, constants } from "node:fs/promises";
+import type { CopyInput, CopyOutput } from "../../types.js";
+
+/**
+ * Copy file or directory
+ */
+export async function copy(input: CopyInput): Promise<CopyOutput> {
+  const { src, dest, recursive, overwrite } = input;
+  const flags = overwrite ? 0 : constants.COPYFILE_EXCL;
+
+  if (recursive) {
+    await cp(src, dest, { recursive, force: overwrite });
+  } else {
+    await copyFile(src, dest, flags);
+  }
+
+  return { src, dest };
+}

package/src/procedures/fs/exists.ts

@@ -0,0 +1,20 @@
+/**
+ * exists procedure
+ *
+ * Check if file or directory exists
+ */
+
+import { type ExistsInput, type ExistsOutput } from "../../types.js";
+import { stat } from "./stat.js";
+
+/**
+ * Check if file or directory exists
+ */
+export async function exists(input: ExistsInput): Promise<ExistsOutput> {
+  try {
+    const stats = await stat(input);
+    return { exists: true, stats };
+  } catch {
+    return { exists: false };
+  }
+}

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,17 @@
+/**
+ * Importing this file registers the procedures of @procedures/fs in the global registry
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as data
+ * are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+
+import { registerProcedures } from "@procedures/client";
+import { fsModule } from "./module.js";
+
+export * from "./module.js";
+
+export function registerFsProcedures(): void {
+  registerProcedures(fsModule.procedures);
+}
+
+// Auto-register when this module is loaded
+registerFsProcedures();