@johannes.latzel/llm-chat-file 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Johannes B. Latzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,34 @@
+# LLM Chat File
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/@johannes.latzel/llm-chat-file)](https://www.npmjs.com/package/@johannes.latzel/llm-chat-file)
+[![version](https://img.shields.io/github/package-json/v/johanneslatzel/llm-chat-file)](https://github.com/johanneslatzel/llm-chat-file/releases)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/johanneslatzel/llm-chat-file/pulls)
+[![codecov](https://codecov.io/gh/johanneslatzel/llm-chat-file/graph/badge.svg)](https://codecov.io/gh/johanneslatzel/llm-chat-file)
+[![CI](https://github.com/johanneslatzel/llm-chat-file/actions/workflows/ci.yml/badge.svg)](https://github.com/johanneslatzel/llm-chat-file/actions/workflows/ci.yml)
+[![Socket Badge](https://badge.socket.dev/npm/package/@johannes.latzel/llm-chat-file/latest)](https://badge.socket.dev/npm/package/@johannes.latzel/llm-chat-file/latest)
+
+llm-chat tools for filesystem operations.
+
+## Prerequisites
+
+- Node.js >= 18
+
+## Installation
+
+```bash
+npm install @johannes.latzel/llm-chat-file
+```
+
+## Documentation
+
+Full documentation at **[johanneslatzel.github.io/llm-chat-file/](https://johanneslatzel.github.io/llm-chat-file/)**
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Contributing
+
+Issues and PRs welcome at [github.com/johanneslatzel/llm-chat-file](https://github.com/johanneslatzel/llm-chat-file).

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { SearchConfiguration, FileConfiguration, DirectoryConfiguration } from './lib/config.js';
+export { AccessType } from './lib/types.js';
+export type { Access, WalkEntry } from './lib/types.js';
+export { Workspace } from './lib/workspace.js';
+export { ReadFileTool } from './tools/read-file.js';
+export { WriteFileTool } from './tools/write-file.js';
+export { SearchEntriesTool } from './tools/search.js';
+export { ListDirectoryTool } from './tools/list-directory.js';
+export { CreateFolderTool } from './tools/create-folder.js';
+export { DeleteFileTool } from './tools/delete-file.js';
+export { MoveFileTool } from './tools/move-file.js';
+export { SwitchWorkspaceTool } from './tools/switch-workspace.js';
+export { FileAccessInfoTool } from './tools/file-access-info.js';
+export { EntryInfoTool } from './tools/entry-info.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { SearchConfiguration, FileConfiguration, DirectoryConfiguration } from './lib/config.js';
+export { AccessType } from './lib/types.js';
+export { Workspace } from './lib/workspace.js';
+export { ReadFileTool } from './tools/read-file.js';
+export { WriteFileTool } from './tools/write-file.js';
+export { SearchEntriesTool } from './tools/search.js';
+export { ListDirectoryTool } from './tools/list-directory.js';
+export { CreateFolderTool } from './tools/create-folder.js';
+export { DeleteFileTool } from './tools/delete-file.js';
+export { MoveFileTool } from './tools/move-file.js';
+export { SwitchWorkspaceTool } from './tools/switch-workspace.js';
+export { FileAccessInfoTool } from './tools/file-access-info.js';
+export { EntryInfoTool } from './tools/entry-info.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/lib/config.d.ts

@@ -0,0 +1,89 @@
+import { AccessType } from './types.js';
+/** Configuration for file search operations (content search, name search, timestamp search, etc.). */
+export declare class SearchConfiguration {
+    /**
+     * Maximum number of search results to return.
+     * Falls back to the `LLM_CHAT_FS_MAX_SEARCH_RESULTS` environment variable, or `50` if not set.
+     */
+    maxSearchResults: number;
+    /**
+     * Threshold above which results are returned as a count summary instead of individual paths.
+     * Falls back to `LLM_CHAT_FS_MAX_DISPLAY_ENTRIES` or `200`.
+     */
+    maxDisplayEntries: number;
+    /**
+     * Hard limit on total entries to traverse. Returns an error if exceeded.
+     * Falls back to `LLM_CHAT_FS_MAX_TOTAL_ENTRIES` or `5000`.
+     */
+    maxTotalEntries: number;
+    /**
+     * Total search timeout in milliseconds. The search returns partial results if this is exceeded.
+     * Falls back to `LLM_CHAT_FS_SEARCH_TIMEOUT` or `10000`.
+     */
+    timeoutMs: number;
+    /**
+     * @param maxSearchResults - Maximum results. Defaults to env `LLM_CHAT_FS_MAX_SEARCH_RESULTS` or `50`.
+     * @param maxDisplayEntries - Display threshold. Defaults to env `LLM_CHAT_FS_MAX_DISPLAY_ENTRIES` or `200`.
+     * @param maxTotalEntries - Hard traversal limit. Defaults to env `LLM_CHAT_FS_MAX_TOTAL_ENTRIES` or `5000`.
+     * @param timeoutMs - Total search timeout. Defaults to env `LLM_CHAT_FS_SEARCH_TIMEOUT` or `10000`.
+     */
+    constructor(maxSearchResults?: number, maxDisplayEntries?: number, maxTotalEntries?: number, timeoutMs?: number);
+}
+/** Configuration that defines which directories are accessible and at what permission level. */
+export declare class DirectoryConfiguration {
+    /** List of access entries. Must contain at least one entry. */
+    accesses: {
+        type: AccessType;
+        path: string;
+    }[];
+    /** Directory names to skip when walking directory trees (e.g. `node_modules`, `.git`). */
+    skipDirs: string[];
+    /**
+     * When `true`, resolves symlinks via `fs.realpathSync.native()` before access checks.
+     * This prevents symlink-based path traversal outside configured directories.
+     * Defaults to `false` (symlinks are followed as-is).
+     */
+    resolveSymlinks: boolean;
+    /** The default workspace path. Used as the initial `currentPath` in the Workspace. */
+    workspacePath?: string | undefined;
+    /**
+     * Constructs a directory configuration. When called with no arguments,
+     * all values are read from environment variables. Pass specific arguments
+     * to override individual values.
+     *
+     * @param accesses - Access entries. Omit or pass `undefined` to read from env vars.
+     * @param skipDirs - Directory names to skip. Defaults to `[]` when accesses are explicitly provided.
+     * @param resolveSymlinks - Resolve symlinks before access checks. Defaults to `false` when accesses are explicitly provided.
+     * @param workspacePath - Default workspace path. Defaults to resolved `LLM_CHAT_FS_WORKSPACE` or `cwd` when reading from env.
+     */
+    constructor(accesses?: {
+        type: AccessType;
+        path: string;
+    }[], skipDirs?: string[], resolveSymlinks?: boolean, workspacePath?: string);
+    /**
+     * Deduplicates directory accesses: for any path that appears multiple times,
+     * write access takes precedence over read access. Exact duplicates are removed.
+     *
+     * @returns A new directory configuration with deduplicated accesses.
+     */
+    deduplicate(): DirectoryConfiguration;
+}
+/** Configuration for file read/write operations (character limits, etc.). */
+export declare class FileConfiguration {
+    /**
+     * Maximum number of characters allowed per file read or write.
+     * Falls back to the `LLM_CHAT_FS_MAX_CHARS_PER_FILE` environment variable, or `10000` if not set.
+     */
+    maxCharsPerFile: number;
+    /**
+     * Maximum file size in bytes allowed for read operations.
+     * Falls back to the `LLM_CHAT_FS_MAX_FILE_SIZE` environment variable, or `10485760` (10 MB) if not set.
+     */
+    maxFileSize: number;
+    /**
+     * @param maxCharsPerFile - Maximum chars. Defaults to env `LLM_CHAT_FS_MAX_CHARS_PER_FILE` or `10000`.
+     * @param maxFileSize - Maximum file size in bytes. Defaults to env `LLM_CHAT_FS_MAX_FILE_SIZE` or `10485760` (10 MB).
+     */
+    constructor(maxCharsPerFile?: number, maxFileSize?: number);
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,sGAAsG;AACtG,qBAAa,mBAAmB;IAC5B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;gBAEC,gBAAgB,CAAC,EAAE,MAAM,EACzB,iBAAiB,CAAC,EAAE,MAAM,EAC1B,eAAe,CAAC,EAAE,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM;CAUzB;AAED,gGAAgG;AAChG,qBAAa,sBAAsB;IAC/B,+DAA+D;IAC/D,QAAQ,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAE/C,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IAEzB,sFAAsF;IACtF,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;OASG;gBAEC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,EAC/C,QAAQ,CAAC,EAAE,MAAM,EAAE,EACnB,eAAe,CAAC,EAAE,OAAO,EACzB,aAAa,CAAC,EAAE,MAAM;IA8B1B;;;;;OAKG;IACH,WAAW,IAAI,sBAAsB;CAgBxC;AAED,6EAA6E;AAC7E,qBAAa,iBAAiB;IAC1B;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;gBACS,eAAe,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAM7D"}

package/dist/lib/config.js

@@ -0,0 +1,155 @@
+import * as path from 'node:path';
+import { AccessType } from './types.js';
+/** Configuration for file search operations (content search, name search, timestamp search, etc.). */
+export class SearchConfiguration {
+    /**
+     * Maximum number of search results to return.
+     * Falls back to the `LLM_CHAT_FS_MAX_SEARCH_RESULTS` environment variable, or `50` if not set.
+     */
+    maxSearchResults;
+    /**
+     * Threshold above which results are returned as a count summary instead of individual paths.
+     * Falls back to `LLM_CHAT_FS_MAX_DISPLAY_ENTRIES` or `200`.
+     */
+    maxDisplayEntries;
+    /**
+     * Hard limit on total entries to traverse. Returns an error if exceeded.
+     * Falls back to `LLM_CHAT_FS_MAX_TOTAL_ENTRIES` or `5000`.
+     */
+    maxTotalEntries;
+    /**
+     * Total search timeout in milliseconds. The search returns partial results if this is exceeded.
+     * Falls back to `LLM_CHAT_FS_SEARCH_TIMEOUT` or `10000`.
+     */
+    timeoutMs;
+    /**
+     * @param maxSearchResults - Maximum results. Defaults to env `LLM_CHAT_FS_MAX_SEARCH_RESULTS` or `50`.
+     * @param maxDisplayEntries - Display threshold. Defaults to env `LLM_CHAT_FS_MAX_DISPLAY_ENTRIES` or `200`.
+     * @param maxTotalEntries - Hard traversal limit. Defaults to env `LLM_CHAT_FS_MAX_TOTAL_ENTRIES` or `5000`.
+     * @param timeoutMs - Total search timeout. Defaults to env `LLM_CHAT_FS_SEARCH_TIMEOUT` or `10000`.
+     */
+    constructor(maxSearchResults, maxDisplayEntries, maxTotalEntries, timeoutMs) {
+        this.maxSearchResults =
+            maxSearchResults ?? parseEnvInt('LLM_CHAT_FS_MAX_SEARCH_RESULTS', 50);
+        this.maxDisplayEntries =
+            maxDisplayEntries ?? parseEnvInt('LLM_CHAT_FS_MAX_DISPLAY_ENTRIES', 200);
+        this.maxTotalEntries =
+            maxTotalEntries ?? parseEnvInt('LLM_CHAT_FS_MAX_TOTAL_ENTRIES', 5000);
+        this.timeoutMs = timeoutMs ?? parseEnvInt('LLM_CHAT_FS_SEARCH_TIMEOUT', 10000);
+    }
+}
+/** Configuration that defines which directories are accessible and at what permission level. */
+export class DirectoryConfiguration {
+    /** List of access entries. Must contain at least one entry. */
+    accesses;
+    /** Directory names to skip when walking directory trees (e.g. `node_modules`, `.git`). */
+    skipDirs;
+    /**
+     * When `true`, resolves symlinks via `fs.realpathSync.native()` before access checks.
+     * This prevents symlink-based path traversal outside configured directories.
+     * Defaults to `false` (symlinks are followed as-is).
+     */
+    resolveSymlinks;
+    /** The default workspace path. Used as the initial `currentPath` in the Workspace. */
+    workspacePath;
+    /**
+     * Constructs a directory configuration. When called with no arguments,
+     * all values are read from environment variables. Pass specific arguments
+     * to override individual values.
+     *
+     * @param accesses - Access entries. Omit or pass `undefined` to read from env vars.
+     * @param skipDirs - Directory names to skip. Defaults to `[]` when accesses are explicitly provided.
+     * @param resolveSymlinks - Resolve symlinks before access checks. Defaults to `false` when accesses are explicitly provided.
+     * @param workspacePath - Default workspace path. Defaults to resolved `LLM_CHAT_FS_WORKSPACE` or `cwd` when reading from env.
+     */
+    constructor(accesses, skipDirs, resolveSymlinks, workspacePath) {
+        if (accesses) {
+            this.accesses = accesses;
+            this.skipDirs = skipDirs ?? [];
+            this.resolveSymlinks = resolveSymlinks ?? false;
+            this.workspacePath = workspacePath;
+        }
+        else {
+            const readDirs = parseDirs(process.env.LLM_CHAT_FS_READ_DIRS);
+            const writeDirs = parseDirs(process.env.LLM_CHAT_FS_WRITE_DIRS);
+            this.accesses = [];
+            for (const d of readDirs) {
+                this.accesses.push({ type: AccessType.Read, path: path.resolve(d) });
+            }
+            for (const d of writeDirs) {
+                this.accesses.push({ type: AccessType.Write, path: path.resolve(d) });
+            }
+            const wsPath = path.resolve(process.env.LLM_CHAT_FS_WORKSPACE ?? process.cwd());
+            const alreadyWrite = this.accesses.some((a) => a.type === AccessType.Write && a.path === wsPath);
+            if (!alreadyWrite) {
+                this.accesses.push({ type: AccessType.Write, path: wsPath });
+            }
+            this.skipDirs = parseDirs(process.env.LLM_CHAT_FS_SKIP_DIRS);
+            this.resolveSymlinks = parseEnvBool('LLM_CHAT_FS_RESOLVE_SYMLINKS', false);
+            this.workspacePath = wsPath;
+        }
+    }
+    /**
+     * Deduplicates directory accesses: for any path that appears multiple times,
+     * write access takes precedence over read access. Exact duplicates are removed.
+     *
+     * @returns A new directory configuration with deduplicated accesses.
+     */
+    deduplicate() {
+        const seen = new Map();
+        for (const a of this.accesses) {
+            const existing = seen.get(a.path);
+            if (existing === AccessType.Write)
+                continue;
+            if (a.type === AccessType.Write || !existing) {
+                seen.set(a.path, a.type);
+            }
+        }
+        return new DirectoryConfiguration(Array.from(seen.entries()).map(([path, type]) => ({ type, path })), this.skipDirs, this.resolveSymlinks, this.workspacePath);
+    }
+}
+/** Configuration for file read/write operations (character limits, etc.). */
+export class FileConfiguration {
+    /**
+     * Maximum number of characters allowed per file read or write.
+     * Falls back to the `LLM_CHAT_FS_MAX_CHARS_PER_FILE` environment variable, or `10000` if not set.
+     */
+    maxCharsPerFile;
+    /**
+     * Maximum file size in bytes allowed for read operations.
+     * Falls back to the `LLM_CHAT_FS_MAX_FILE_SIZE` environment variable, or `10485760` (10 MB) if not set.
+     */
+    maxFileSize;
+    /**
+     * @param maxCharsPerFile - Maximum chars. Defaults to env `LLM_CHAT_FS_MAX_CHARS_PER_FILE` or `10000`.
+     * @param maxFileSize - Maximum file size in bytes. Defaults to env `LLM_CHAT_FS_MAX_FILE_SIZE` or `10485760` (10 MB).
+     */
+    constructor(maxCharsPerFile, maxFileSize) {
+        this.maxCharsPerFile =
+            maxCharsPerFile ?? parseEnvInt('LLM_CHAT_FS_MAX_CHARS_PER_FILE', 10000);
+        this.maxFileSize =
+            maxFileSize ?? parseEnvInt('LLM_CHAT_FS_MAX_FILE_SIZE', 10 * 1024 * 1024);
+    }
+}
+function parseEnvInt(key, fallback, min = 1) {
+    const raw = process.env[key];
+    if (raw === undefined || raw === '')
+        return Math.max(min, fallback);
+    const parsed = parseInt(raw, 10);
+    return Number.isNaN(parsed) ? Math.max(min, fallback) : Math.max(min, parsed);
+}
+function parseDirs(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseEnvBool(key, fallback) {
+    const raw = process.env[key];
+    if (raw === undefined || raw === '')
+        return fallback;
+    return raw === 'true';
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}

package/dist/lib/helpers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks whether a file is binary by reading its header bytes.
+ * If the check fails (e.g. the file doesn't exist), it returns `true` to err on the side of caution.
+ *
+ * @param filePath - Path to the file to check.
+ * @returns `true` if the file is binary or the check fails, `false` if it appears to be text.
+ */
+export declare function isBinary(filePath: string): Promise<boolean>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/lib/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/lib/helpers.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMjE"}

package/dist/lib/helpers.js

@@ -0,0 +1,17 @@
+import { isBinaryFile } from 'isbinaryfile';
+/**
+ * Checks whether a file is binary by reading its header bytes.
+ * If the check fails (e.g. the file doesn't exist), it returns `true` to err on the side of caution.
+ *
+ * @param filePath - Path to the file to check.
+ * @returns `true` if the file is binary or the check fails, `false` if it appears to be text.
+ */
+export async function isBinary(filePath) {
+    try {
+        return await isBinaryFile(filePath);
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/lib/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/lib/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC3C,IAAI,CAAC;QACD,OAAO,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;AACL,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,23 @@
+import type { Dirent } from 'node:fs';
+/** Type of filesystem access (read or write). */
+export declare enum AccessType {
+    /** Read-only access — files can be listed and read but not modified. */
+    Read = "read",
+    /** Read-write access — files can be created, modified and deleted. */
+    Write = "write"
+}
+/** A single filesystem access entry granting a type of access to a directory. */
+export interface Access {
+    /** Whether this grants read or write access to the directory. */
+    type: AccessType;
+    /** Absolute path to the directory this access applies to. */
+    path: string;
+}
+/** An entry yielded when recursively walking a directory tree. */
+export interface WalkEntry {
+    /** Absolute path to the file or directory. */
+    filePath: string;
+    /** `fs.Dirent` from the directory read operation, providing type and name information. */
+    dirent: Dirent;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,iDAAiD;AACjD,oBAAY,UAAU;IAClB,wEAAwE;IACxE,IAAI,SAAS;IACb,sEAAsE;IACtE,KAAK,UAAU;CAClB;AAED,iFAAiF;AACjF,MAAM,WAAW,MAAM;IACnB,iEAAiE;IACjE,IAAI,EAAE,UAAU,CAAC;IACjB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACtB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/dist/lib/types.js

@@ -0,0 +1,9 @@
+/** Type of filesystem access (read or write). */
+export var AccessType;
+(function (AccessType) {
+    /** Read-only access — files can be listed and read but not modified. */
+    AccessType["Read"] = "read";
+    /** Read-write access — files can be created, modified and deleted. */
+    AccessType["Write"] = "write";
+})(AccessType || (AccessType = {}));
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAEA,iDAAiD;AACjD,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IAClB,wEAAwE;IACxE,2BAAa,CAAA;IACb,sEAAsE;IACtE,6BAAe,CAAA;AACnB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB"}

package/dist/lib/workspace.d.ts

@@ -0,0 +1,75 @@
+import { DirectoryConfiguration } from './config.js';
+/**
+ * Manages the current workspace path and enforces access control for all file operations.
+ *
+ * Tracks which directories are accessible (read and/or write) and provides methods
+ * to check permissions, resolve paths, and switch the active workspace directory.
+ * Uses a mutex to ensure thread-safe workspace switching.
+ */
+export declare class Workspace {
+    /** The currently active workspace directory (absolute path). */
+    currentPath: string;
+    private cfg;
+    private mutex;
+    /**
+     * @param config - Directory configuration defining accessible paths and their permission levels.
+     * @throws {Error} If the configuration contains no access entries.
+     */
+    constructor(config: DirectoryConfiguration);
+    /**
+     * Changes the current workspace path to a new directory, thread-safe with a mutex.
+     *
+     * @param target - Path to the new workspace directory (may be relative or absolute).
+     * @throws {Error} If the target is not within any configured accessible directory.
+     */
+    switchWorkspace(target: string): Promise<void>;
+    /**
+     * Resolves a path against the current workspace. If the input is already absolute, `path.resolve` returns it as-is.
+     *
+     * @param input - Path to resolve (relative or absolute).
+     * @returns The resolved absolute path.
+     */
+    normalize(input: string): string;
+    /**
+     * Checks whether the given absolute path is within any directory configured for read (or write) access.
+     *
+     * @param absPath - Absolute path to check.
+     * @returns `true` if the path is readable.
+     */
+    canRead(absPath: string): boolean;
+    /**
+     * Checks whether the given absolute path is within any directory configured for write access.
+     *
+     * @param absPath - Absolute path to check.
+     * @returns `true` if the path is writable.
+     */
+    canWrite(absPath: string): boolean;
+    /**
+     * Returns the list of configured directory accesses with their types.
+     */
+    getAccesses(): {
+        type: 'read' | 'write';
+        path: string;
+    }[];
+    /**
+     * Returns the list of directory names to skip when walking (e.g. `node_modules`, `.git`).
+     */
+    get skipDirs(): string[];
+    /** Whether symlink resolution is enabled for access checks. */
+    get resolveSymlinks(): boolean;
+    private resolvePath;
+    /**
+     * Recursively walks a directory, yielding entries for files and directories.
+     * Skips directories whose names are listed in `cfg.skipDirs`.
+     *
+     * @param dir - Directory to walk.
+     * @param onError - Optional callback invoked when a subdirectory cannot be read.
+     *   Receives the directory path and the error. The walk continues with other subtrees.
+     * @yields {WalkEntry} Entries for each file and subdirectory found.
+     */
+    walk(dir: string, onError?: (dirPath: string, error: Error) => void): AsyncGenerator<{
+        filePath: string;
+        dirent: import('node:fs').Dirent;
+    }>;
+}
+//# sourceMappingURL=workspace.d.ts.map

package/dist/lib/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/lib/workspace.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAarD;;;;;;GAMG;AACH,qBAAa,SAAS;IAClB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,GAAG,CAAyB;IACpC,OAAO,CAAC,KAAK,CAAQ;IAErB;;;OAGG;gBACS,MAAM,EAAE,sBAAsB;IAoB1C;;;;;OAKG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpD;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIhC;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAWjC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQlC;;OAEG;IACH,WAAW,IAAI;QAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;IAIzD;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,EAAE,CAEvB;IAED,+DAA+D;IAC/D,IAAI,eAAe,IAAI,OAAO,CAE7B;IAED,OAAO,CAAC,WAAW;IAUnB;;;;;;;;OAQG;IACI,IAAI,CACP,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,GAClD,cAAc,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAqB5E"}