@telorun/fs 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -0,0 +1,92 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/telorun/telo/main/assets/telo.png" alt="Telo" width="200" />
+</p>
+
+<h1 align="center">Telo</h1>
+
+<p align="center">Runtime for declarative backends.</p>
+
+<p align="center">
+  <a href="https://github.com/telorun/telo/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/telorun/telo/actions/workflows/test.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@telorun/cli"><img alt="node" src="https://img.shields.io/node/v/@telorun/cli" /></a>
+  <br />
+  <a href="https://github.com/telorun/telo/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/issues"><img alt="Issues" src="https://img.shields.io/github/issues/telorun/telo" /></a>
+  <a href="https://github.com/telorun/telo/pulls"><img alt="Pull requests" src="https://img.shields.io/github/issues-pr/telorun/telo" /></a>
+  <br />
+  <img alt="Changesets" src="https://img.shields.io/badge/maintained%20with-changesets-176de3" />
+</p>
+
+Telo is an execution engine (Micro-Kernel) that runs logic defined entirely in YAML manifests. Instead of writing imperative backend code, you define your routes, databases, schemas, and AI workflows as atomic, interconnected YAML documents. Telo takes those manifests and runs them.
+
+Built to be language-agnostic and infinitely extensible.
+
+```bash
+# Reconcile your manifest into a running backend
+$ telo ./examples/hello-api
+
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+```
+
+## Why use Telo?
+
+- **Open Standards:** Built on YAML, JSON Schema, and CEL — no proprietary DSL.
+- **Static Analysis:** CEL type checking, reference validation, and IDE diagnostics catch errors before runtime.
+- **Micro-Kernel Architecture:** Telo itself knows nothing about HTTP or SQL. Everything is a module you import, scope, and compose with typed variable and secret contracts.
+- **Language Agnostic:** Available as a Node.js runtime today, with a shared YAML runtime contract that allows for future Rust or Go implementations without changing your manifests.
+
+## What It Does
+
+- **Loads** YAML resources and compiles CEL expressions (`${{ }}`) into an in-memory registry.
+- **Resolves** resource dependencies via a multi-pass init loop, handling ordering automatically.
+- **Indexes** resources by Kind and Name for constant-time lookup.
+- **Dispatches** execution to the controller that owns each Kind.
+
+## Example manifest
+
+See [examples/](./examples/) for a list of working applications.
+
+## Status
+
+Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+
+## The Meaning of Telo
+
+The name Telo is derived from the Greek root Telos - meaning the "end goal", "purpose", or "final state". That is exactly the philosophy behind this runtime. In standard imperative programming, you have to write thousands of lines of code to tell a server exactly how to start. With Telo, you simply declare your desired final state.
+
+You define the end state. Telo makes it real.
+
+## Philosophy
+
+Modern platforms often spend disproportionate effort on technical mechanics-wiring frameworks, managing infrastructure, and negotiating toolchains-while the original business problem gets delayed or diluted. Telo pushes in the opposite direction: it treats kernel execution as a stable, predictable host so teams can concentrate on the **business logic and outcomes** instead of the plumbing.
+
+By separating "what the system should do" from "how it is hosted", the runtime reduces friction for domain‑level changes. Teams can move faster on product requirements, experiment more safely, and keep conversations centered on value delivered rather than implementation trivia.
+
+Telo also aims to **join forces across all programming language communities**, so the best ideas, patterns, and implementations can converge into a shared kernel truth without forcing everyone into a single stack.
+
+YAML also makes the system more **AI‑friendly** than traditional programming languages: it is explicit, structured, and easier for tools to generate, review, and transform without losing intent.
+
+## Modularity
+
+Telo is built around **modules** that own specific resource kinds. A module is loaded from a manifest, declares which kinds it implements, and then receives only the resources of those kinds. This keeps concerns isolated and lets teams compose systems from focused building blocks rather than monolithic services.
+
+At kernel execution time, execution is always routed by **Kind.Name**. The kernel resolves the Kind to its owning module and hands off execution. Modules can call back into the kernel to execute other resources, enabling composition without tight coupling.
+
+## Architecture
+
+The architecture is inspired by Kubernetes-style manifests: declarative resources, explicit kinds, and a control plane that routes work based on those definitions.
+Those manifests were taken to the next level by allowing them to run inside a standalone runtime host.
+
+## See more at
+
+- [Telo Kernel](./kernel/README.md)
+- [Telo SDK for module authors](sdk/README.md)
+- [Modules](modules/README.md)
+
+## License
+
+See [LICENSE](https://github.com/telorun/telo/blob/main/LICENSE).
+
+## Contribution Note
+
+By contributing, you agree that code and examples in this repository may be translated or re‑implemented in other programming languages (including by AI systems) to support the project’s polyglot goals.

package/dist/directory-creation-controller.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface DirectoryCreationInput {
+    path: string;
+    createParents?: boolean;
+}
+interface DirectoryCreationResult {
+    created: boolean;
+}
+declare class DirectoryCreationResource implements ResourceInstance<DirectoryCreationInput, DirectoryCreationResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: DirectoryCreationInput): Promise<DirectoryCreationResult>;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<DirectoryCreationResource>;
+export {};

package/dist/directory-creation-controller.js

@@ -0,0 +1,28 @@
+import { mkdir } from "node:fs/promises";
+import { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+class DirectoryCreationResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const target = resolveTarget(this.base, requirePath("Fs.DirectoryCreation", input?.path));
+        try {
+            if (input?.createParents) {
+                // Recursive mkdir returns the first created path, or undefined when the
+                // directory already existed — that's the created/no-op signal.
+                const first = await mkdir(target, { recursive: true });
+                return { created: first !== undefined };
+            }
+            await mkdir(target);
+            return { created: true };
+        }
+        catch (err) {
+            throw wrapFsError("Fs.DirectoryCreation: cannot create", target, err);
+        }
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new DirectoryCreationResource(resolveBase(resource.cwd));
+}

package/dist/directory-listing-controller.d.ts

@@ -0,0 +1,24 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface DirectoryListingInput {
+    path?: string;
+    recursive?: boolean;
+}
+interface Entry {
+    name: string;
+    path: string;
+    type: "file" | "directory" | "other";
+    size: number;
+}
+interface DirectoryListingResult {
+    entries: Entry[];
+}
+declare class DirectoryListingResource implements ResourceInstance<DirectoryListingInput, DirectoryListingResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: DirectoryListingInput): Promise<DirectoryListingResult>;
+    private walk;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<DirectoryListingResource>;
+export {};

package/dist/directory-listing-controller.js

@@ -0,0 +1,53 @@
+import { lstat, readdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+function classify(stats) {
+    if (stats.isFile())
+        return "file";
+    if (stats.isDirectory())
+        return "directory";
+    return "other";
+}
+class DirectoryListingResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const root = input?.path ? resolveTarget(this.base, input.path) : this.base;
+        const entries = [];
+        await this.walk(root, Boolean(input?.recursive), entries);
+        return { entries };
+    }
+    async walk(dir, recursive, out) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch (err) {
+            throw wrapFsError("Fs.DirectoryListing: cannot list", dir, err);
+        }
+        names.sort();
+        for (const name of names) {
+            const full = path.join(dir, name);
+            // lstat (not stat) so a broken or out-of-tree symlink is reported as
+            // "other" rather than throwing. Wrapped so a mid-walk race (entry removed
+            // after readdir) or permission error names the path like every other op.
+            let stats;
+            try {
+                stats = await lstat(full);
+            }
+            catch (err) {
+                throw wrapFsError("Fs.DirectoryListing: cannot stat", full, err);
+            }
+            const type = classify(stats);
+            out.push({ name, path: path.relative(this.base, full), type, size: stats.size });
+            if (recursive && type === "directory")
+                await this.walk(full, recursive, out);
+        }
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new DirectoryListingResource(resolveBase(resource.cwd));
+}

package/dist/file-controller.d.ts

@@ -0,0 +1,18 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface FileInput {
+    path: string;
+    encoding?: "utf8" | "base64";
+}
+interface FileResult {
+    content: string;
+    size: number;
+}
+declare class FileResource implements ResourceInstance<FileInput, FileResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: FileInput): Promise<FileResult>;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<FileResource>;
+export {};

package/dist/file-controller.js

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+class FileResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const target = resolveTarget(this.base, requirePath("Fs.File", input?.path));
+        try {
+            const buffer = await readFile(target);
+            const content = input.encoding === "base64" ? buffer.toString("base64") : buffer.toString("utf8");
+            return { content, size: buffer.byteLength };
+        }
+        catch (err) {
+            throw wrapFsError("Fs.File: cannot read", target, err);
+        }
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new FileResource(resolveBase(resource.cwd));
+}

package/dist/file-edit-controller.d.ts

@@ -0,0 +1,19 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface FileEditInput {
+    path: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}
+interface FileEditResult {
+    replacements: number;
+}
+declare class FileEditResource implements ResourceInstance<FileEditInput, FileEditResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: FileEditInput): Promise<FileEditResult>;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<FileEditResource>;
+export {};

package/dist/file-edit-controller.js

@@ -0,0 +1,65 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+/** Byte offsets of every non-overlapping occurrence of `needle` in `haystack`. */
+function findAll(haystack, needle) {
+    const positions = [];
+    for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) {
+        positions.push(at);
+    }
+    return positions;
+}
+class FileEditResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const target = resolveTarget(this.base, requirePath("Fs.FileEdit", input?.path));
+        if (typeof input?.oldString !== "string" || input.oldString.length === 0) {
+            throw new Error("Fs.FileEdit: 'oldString' input is required and must be a non-empty string");
+        }
+        if (typeof input?.newString !== "string") {
+            throw new Error("Fs.FileEdit: 'newString' input is required and must be a string");
+        }
+        let buffer;
+        try {
+            buffer = await readFile(target);
+        }
+        catch (err) {
+            throw wrapFsError("Fs.FileEdit: cannot read", target, err);
+        }
+        // Operate on bytes, not decoded text: regions outside the match survive
+        // byte-for-byte (comments, !cel tags, and any non-UTF-8 content), and the
+        // literal search sidesteps regex / `$`-substitution.
+        const oldBytes = Buffer.from(input.oldString, "utf8");
+        const positions = findAll(buffer, oldBytes);
+        const count = positions.length;
+        if (count === 0) {
+            throw new Error(`Fs.FileEdit: oldString not found in '${target}'`);
+        }
+        if (count > 1 && !input.replaceAll) {
+            throw new Error(`Fs.FileEdit: oldString matches ${count} times in '${target}'; set 'replaceAll: true' or use a more specific string`);
+        }
+        const newBytes = Buffer.from(input.newString, "utf8");
+        const replacements = input.replaceAll ? count : 1;
+        const parts = [];
+        let cursor = 0;
+        for (let i = 0; i < replacements; i++) {
+            const at = positions[i];
+            parts.push(buffer.subarray(cursor, at), newBytes);
+            cursor = at + oldBytes.length;
+        }
+        parts.push(buffer.subarray(cursor));
+        try {
+            await writeFile(target, Buffer.concat(parts));
+        }
+        catch (err) {
+            throw wrapFsError("Fs.FileEdit: cannot write", target, err);
+        }
+        return { replacements };
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new FileEditResource(resolveBase(resource.cwd));
+}

package/dist/file-removal-controller.d.ts

@@ -0,0 +1,17 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface FileRemovalInput {
+    path: string;
+    recursive?: boolean;
+}
+interface FileRemovalResult {
+    removed: boolean;
+}
+declare class FileRemovalResource implements ResourceInstance<FileRemovalInput, FileRemovalResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: FileRemovalInput): Promise<FileRemovalResult>;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<FileRemovalResource>;
+export {};

package/dist/file-removal-controller.js

@@ -0,0 +1,23 @@
+import { rm } from "node:fs/promises";
+import { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+class FileRemovalResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const target = resolveTarget(this.base, requirePath("Fs.FileRemoval", input?.path));
+        try {
+            // force:false so a missing path is surfaced (ENOENT), not swallowed.
+            await rm(target, { recursive: Boolean(input?.recursive), force: false });
+            return { removed: true };
+        }
+        catch (err) {
+            throw wrapFsError("Fs.FileRemoval: cannot remove", target, err);
+        }
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new FileRemovalResource(resolveBase(resource.cwd));
+}

package/dist/file-write-controller.d.ts

@@ -0,0 +1,19 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { FsManifest } from "./fs-support.js";
+interface FileWriteInput {
+    path: string;
+    content: string;
+    encoding?: "utf8" | "base64";
+    createParents?: boolean;
+}
+interface FileWriteResult {
+    bytesWritten: number;
+}
+declare class FileWriteResource implements ResourceInstance<FileWriteInput, FileWriteResult> {
+    private readonly base;
+    constructor(base: string);
+    invoke(input: FileWriteInput): Promise<FileWriteResult>;
+}
+export declare function register(): void;
+export declare function create(resource: FsManifest): Promise<FileWriteResource>;
+export {};

package/dist/file-write-controller.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+class FileWriteResource {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async invoke(input) {
+        const target = resolveTarget(this.base, requirePath("Fs.FileWrite", input?.path));
+        if (typeof input?.content !== "string") {
+            throw new Error("Fs.FileWrite: 'content' input is required and must be a string");
+        }
+        const buffer = Buffer.from(input.content, input.encoding === "base64" ? "base64" : "utf8");
+        try {
+            if (input.createParents)
+                await mkdir(path.dirname(target), { recursive: true });
+            await writeFile(target, buffer);
+            return { bytesWritten: buffer.byteLength };
+        }
+        catch (err) {
+            throw wrapFsError("Fs.FileWrite: cannot write", target, err);
+        }
+    }
+}
+export function register() { }
+export async function create(resource) {
+    return new FileWriteResource(resolveBase(resource.cwd));
+}

package/dist/fs-support.d.ts

@@ -0,0 +1,19 @@
+/** A resource manifest as it reaches a controller's `create`: config fields sit
+ *  at the top level beside `metadata`. Every fs kind shares the optional `cwd`. */
+export interface FsManifest {
+    metadata: {
+        name: string;
+        module: string;
+    };
+    cwd?: string;
+}
+/** Resolve the base directory invoke paths are taken relative to. A relative
+ *  `cwd` (and the default) resolves against the process working directory. */
+export declare function resolveBase(cwd?: string): string;
+/** Resolve an invoke `path` against the resource base. An absolute input path is
+ *  used as-is. */
+export declare function resolveTarget(base: string, target: string): string;
+export declare function requirePath(kind: string, value: unknown): string;
+/** Turn a Node fs error into an actionable, path-naming message that preserves
+ *  the original code so callers (and tests) can branch on it. */
+export declare function wrapFsError(action: string, target: string, err: unknown): Error;

package/dist/fs-support.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+/** Resolve the base directory invoke paths are taken relative to. A relative
+ *  `cwd` (and the default) resolves against the process working directory. */
+export function resolveBase(cwd) {
+    return path.resolve(cwd ?? ".");
+}
+/** Resolve an invoke `path` against the resource base. An absolute input path is
+ *  used as-is. */
+export function resolveTarget(base, target) {
+    return path.resolve(base, target);
+}
+export function requirePath(kind, value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${kind}: 'path' input is required and must be a non-empty string`);
+    }
+    return value;
+}
+const REASONS = {
+    ENOENT: "no such file or directory",
+    EACCES: "permission denied",
+    EPERM: "operation not permitted",
+    EISDIR: "is a directory",
+    ENOTDIR: "not a directory",
+    EEXIST: "already exists",
+    ENOTEMPTY: "directory not empty",
+};
+/** Turn a Node fs error into an actionable, path-naming message that preserves
+ *  the original code so callers (and tests) can branch on it. */
+export function wrapFsError(action, target, err) {
+    const e = err;
+    const code = e?.code;
+    const reason = (code && REASONS[code]) ?? e?.message ?? String(err);
+    return new Error(`${action} '${target}': ${reason}${code ? ` (${code})` : ""}`, { cause: err });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+export type { FsManifest } from "./fs-support.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// Public surface of @telorun/fs. Controllers load via the per-kind subpath
+// exports (`#file`, `#file-edit`, …); this `.` entry exposes the shared path
+// and error primitives so a future filesystem driver or another module can
+// build on the same cwd-resolution and error contract — mirroring how
+// @telorun/shell exports its host helpers/types for driver reuse.
+export { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@telorun/fs",
+  "version": "0.1.0",
+  "description": "Telo fs module - local filesystem access via Node fs/promises.",
+  "keywords": [
+    "telo",
+    "fs",
+    "filesystem",
+    "file",
+    "directory"
+  ],
+  "author": "Bartosz Pasiński <bartosz.pasinski@codenet.pl>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/telorun/telo.git",
+    "directory": "modules/fs/nodejs"
+  },
+  "homepage": "https://github.com/telorun/telo#readme",
+  "bugs": {
+    "url": "https://github.com/telorun/telo/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./file": {
+      "bun": "./src/file-controller.ts",
+      "import": "./dist/file-controller.js"
+    },
+    "./file-write": {
+      "bun": "./src/file-write-controller.ts",
+      "import": "./dist/file-write-controller.js"
+    },
+    "./file-edit": {
+      "bun": "./src/file-edit-controller.ts",
+      "import": "./dist/file-edit-controller.js"
+    },
+    "./directory-listing": {
+      "bun": "./src/directory-listing-controller.ts",
+      "import": "./dist/directory-listing-controller.js"
+    },
+    "./directory-creation": {
+      "bun": "./src/directory-creation-controller.ts",
+      "import": "./dist/directory-creation-controller.js"
+    },
+    "./file-removal": {
+      "bun": "./src/file-removal-controller.ts",
+      "import": "./dist/file-removal-controller.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "@telorun/sdk": "0.38.0"
+  },
+  "peerDependencies": {
+    "@telorun/sdk": "*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}

package/src/directory-creation-controller.ts

@@ -0,0 +1,38 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { mkdir } from "node:fs/promises";
+import { FsManifest, requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface DirectoryCreationInput {
+  path: string;
+  createParents?: boolean;
+}
+
+interface DirectoryCreationResult {
+  created: boolean;
+}
+
+class DirectoryCreationResource implements ResourceInstance<DirectoryCreationInput, DirectoryCreationResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: DirectoryCreationInput): Promise<DirectoryCreationResult> {
+    const target = resolveTarget(this.base, requirePath("Fs.DirectoryCreation", input?.path));
+    try {
+      if (input?.createParents) {
+        // Recursive mkdir returns the first created path, or undefined when the
+        // directory already existed — that's the created/no-op signal.
+        const first = await mkdir(target, { recursive: true });
+        return { created: first !== undefined };
+      }
+      await mkdir(target);
+      return { created: true };
+    } catch (err) {
+      throw wrapFsError("Fs.DirectoryCreation: cannot create", target, err);
+    }
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<DirectoryCreationResource> {
+  return new DirectoryCreationResource(resolveBase(resource.cwd));
+}

package/src/directory-listing-controller.ts

@@ -0,0 +1,68 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { lstat, readdir } from "node:fs/promises";
+import path from "node:path";
+import { FsManifest, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface DirectoryListingInput {
+  path?: string;
+  recursive?: boolean;
+}
+
+interface Entry {
+  name: string;
+  path: string;
+  type: "file" | "directory" | "other";
+  size: number;
+}
+
+interface DirectoryListingResult {
+  entries: Entry[];
+}
+
+function classify(stats: { isFile(): boolean; isDirectory(): boolean }): Entry["type"] {
+  if (stats.isFile()) return "file";
+  if (stats.isDirectory()) return "directory";
+  return "other";
+}
+
+class DirectoryListingResource implements ResourceInstance<DirectoryListingInput, DirectoryListingResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: DirectoryListingInput): Promise<DirectoryListingResult> {
+    const root = input?.path ? resolveTarget(this.base, input.path) : this.base;
+    const entries: Entry[] = [];
+    await this.walk(root, Boolean(input?.recursive), entries);
+    return { entries };
+  }
+
+  private async walk(dir: string, recursive: boolean, out: Entry[]): Promise<void> {
+    let names: string[];
+    try {
+      names = await readdir(dir);
+    } catch (err) {
+      throw wrapFsError("Fs.DirectoryListing: cannot list", dir, err);
+    }
+    names.sort();
+    for (const name of names) {
+      const full = path.join(dir, name);
+      // lstat (not stat) so a broken or out-of-tree symlink is reported as
+      // "other" rather than throwing. Wrapped so a mid-walk race (entry removed
+      // after readdir) or permission error names the path like every other op.
+      let stats: Awaited<ReturnType<typeof lstat>>;
+      try {
+        stats = await lstat(full);
+      } catch (err) {
+        throw wrapFsError("Fs.DirectoryListing: cannot stat", full, err);
+      }
+      const type = classify(stats);
+      out.push({ name, path: path.relative(this.base, full), type, size: stats.size });
+      if (recursive && type === "directory") await this.walk(full, recursive, out);
+    }
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<DirectoryListingResource> {
+  return new DirectoryListingResource(resolveBase(resource.cwd));
+}

package/src/file-controller.ts

@@ -0,0 +1,34 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { readFile } from "node:fs/promises";
+import { FsManifest, requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface FileInput {
+  path: string;
+  encoding?: "utf8" | "base64";
+}
+
+interface FileResult {
+  content: string;
+  size: number;
+}
+
+class FileResource implements ResourceInstance<FileInput, FileResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: FileInput): Promise<FileResult> {
+    const target = resolveTarget(this.base, requirePath("Fs.File", input?.path));
+    try {
+      const buffer = await readFile(target);
+      const content = input.encoding === "base64" ? buffer.toString("base64") : buffer.toString("utf8");
+      return { content, size: buffer.byteLength };
+    } catch (err) {
+      throw wrapFsError("Fs.File: cannot read", target, err);
+    }
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<FileResource> {
+  return new FileResource(resolveBase(resource.cwd));
+}

package/src/file-edit-controller.ts

@@ -0,0 +1,83 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { readFile, writeFile } from "node:fs/promises";
+import { FsManifest, requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface FileEditInput {
+  path: string;
+  oldString: string;
+  newString: string;
+  replaceAll?: boolean;
+}
+
+interface FileEditResult {
+  replacements: number;
+}
+
+/** Byte offsets of every non-overlapping occurrence of `needle` in `haystack`. */
+function findAll(haystack: Buffer, needle: Buffer): number[] {
+  const positions: number[] = [];
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) {
+    positions.push(at);
+  }
+  return positions;
+}
+
+class FileEditResource implements ResourceInstance<FileEditInput, FileEditResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: FileEditInput): Promise<FileEditResult> {
+    const target = resolveTarget(this.base, requirePath("Fs.FileEdit", input?.path));
+    if (typeof input?.oldString !== "string" || input.oldString.length === 0) {
+      throw new Error("Fs.FileEdit: 'oldString' input is required and must be a non-empty string");
+    }
+    if (typeof input?.newString !== "string") {
+      throw new Error("Fs.FileEdit: 'newString' input is required and must be a string");
+    }
+
+    let buffer: Buffer;
+    try {
+      buffer = await readFile(target);
+    } catch (err) {
+      throw wrapFsError("Fs.FileEdit: cannot read", target, err);
+    }
+
+    // Operate on bytes, not decoded text: regions outside the match survive
+    // byte-for-byte (comments, !cel tags, and any non-UTF-8 content), and the
+    // literal search sidesteps regex / `$`-substitution.
+    const oldBytes = Buffer.from(input.oldString, "utf8");
+    const positions = findAll(buffer, oldBytes);
+    const count = positions.length;
+    if (count === 0) {
+      throw new Error(`Fs.FileEdit: oldString not found in '${target}'`);
+    }
+    if (count > 1 && !input.replaceAll) {
+      throw new Error(
+        `Fs.FileEdit: oldString matches ${count} times in '${target}'; set 'replaceAll: true' or use a more specific string`,
+      );
+    }
+
+    const newBytes = Buffer.from(input.newString, "utf8");
+    const replacements = input.replaceAll ? count : 1;
+    const parts: Buffer[] = [];
+    let cursor = 0;
+    for (let i = 0; i < replacements; i++) {
+      const at = positions[i];
+      parts.push(buffer.subarray(cursor, at), newBytes);
+      cursor = at + oldBytes.length;
+    }
+    parts.push(buffer.subarray(cursor));
+
+    try {
+      await writeFile(target, Buffer.concat(parts));
+    } catch (err) {
+      throw wrapFsError("Fs.FileEdit: cannot write", target, err);
+    }
+    return { replacements };
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<FileEditResource> {
+  return new FileEditResource(resolveBase(resource.cwd));
+}

package/src/file-removal-controller.ts

@@ -0,0 +1,33 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { rm } from "node:fs/promises";
+import { FsManifest, requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface FileRemovalInput {
+  path: string;
+  recursive?: boolean;
+}
+
+interface FileRemovalResult {
+  removed: boolean;
+}
+
+class FileRemovalResource implements ResourceInstance<FileRemovalInput, FileRemovalResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: FileRemovalInput): Promise<FileRemovalResult> {
+    const target = resolveTarget(this.base, requirePath("Fs.FileRemoval", input?.path));
+    try {
+      // force:false so a missing path is surfaced (ENOENT), not swallowed.
+      await rm(target, { recursive: Boolean(input?.recursive), force: false });
+      return { removed: true };
+    } catch (err) {
+      throw wrapFsError("Fs.FileRemoval: cannot remove", target, err);
+    }
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<FileRemovalResource> {
+  return new FileRemovalResource(resolveBase(resource.cwd));
+}

package/src/file-write-controller.ts

@@ -0,0 +1,40 @@
+import type { ResourceInstance } from "@telorun/sdk";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { FsManifest, requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+
+interface FileWriteInput {
+  path: string;
+  content: string;
+  encoding?: "utf8" | "base64";
+  createParents?: boolean;
+}
+
+interface FileWriteResult {
+  bytesWritten: number;
+}
+
+class FileWriteResource implements ResourceInstance<FileWriteInput, FileWriteResult> {
+  constructor(private readonly base: string) {}
+
+  async invoke(input: FileWriteInput): Promise<FileWriteResult> {
+    const target = resolveTarget(this.base, requirePath("Fs.FileWrite", input?.path));
+    if (typeof input?.content !== "string") {
+      throw new Error("Fs.FileWrite: 'content' input is required and must be a string");
+    }
+    const buffer = Buffer.from(input.content, input.encoding === "base64" ? "base64" : "utf8");
+    try {
+      if (input.createParents) await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, buffer);
+      return { bytesWritten: buffer.byteLength };
+    } catch (err) {
+      throw wrapFsError("Fs.FileWrite: cannot write", target, err);
+    }
+  }
+}
+
+export function register(): void {}
+
+export async function create(resource: FsManifest): Promise<FileWriteResource> {
+  return new FileWriteResource(resolveBase(resource.cwd));
+}

package/src/fs-support.ts

@@ -0,0 +1,46 @@
+import path from "node:path";
+
+/** A resource manifest as it reaches a controller's `create`: config fields sit
+ *  at the top level beside `metadata`. Every fs kind shares the optional `cwd`. */
+export interface FsManifest {
+  metadata: { name: string; module: string };
+  cwd?: string;
+}
+
+/** Resolve the base directory invoke paths are taken relative to. A relative
+ *  `cwd` (and the default) resolves against the process working directory. */
+export function resolveBase(cwd?: string): string {
+  return path.resolve(cwd ?? ".");
+}
+
+/** Resolve an invoke `path` against the resource base. An absolute input path is
+ *  used as-is. */
+export function resolveTarget(base: string, target: string): string {
+  return path.resolve(base, target);
+}
+
+export function requirePath(kind: string, value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${kind}: 'path' input is required and must be a non-empty string`);
+  }
+  return value;
+}
+
+const REASONS: Record<string, string> = {
+  ENOENT: "no such file or directory",
+  EACCES: "permission denied",
+  EPERM: "operation not permitted",
+  EISDIR: "is a directory",
+  ENOTDIR: "not a directory",
+  EEXIST: "already exists",
+  ENOTEMPTY: "directory not empty",
+};
+
+/** Turn a Node fs error into an actionable, path-naming message that preserves
+ *  the original code so callers (and tests) can branch on it. */
+export function wrapFsError(action: string, target: string, err: unknown): Error {
+  const e = err as NodeJS.ErrnoException;
+  const code = e?.code;
+  const reason = (code && REASONS[code]) ?? e?.message ?? String(err);
+  return new Error(`${action} '${target}': ${reason}${code ? ` (${code})` : ""}`, { cause: err });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// Public surface of @telorun/fs. Controllers load via the per-kind subpath
+// exports (`#file`, `#file-edit`, …); this `.` entry exposes the shared path
+// and error primitives so a future filesystem driver or another module can
+// build on the same cwd-resolution and error contract — mirroring how
+// @telorun/shell exports its host helpers/types for driver reuse.
+export { requirePath, resolveBase, resolveTarget, wrapFsError } from "./fs-support.js";
+export type { FsManifest } from "./fs-support.js";