{"_id":"@agent-smith/feat-fs","_rev":"8-031cc3349f4ecd20a09670a1f6c77c7a","name":"@agent-smith/feat-fs","dist-tags":{"latest":"0.0.8"},"versions":{"0.0.1":{"name":"@agent-smith/feat-fs","version":"0.0.1","license":"MIT","_id":"@agent-smith/feat-fs@0.0.1","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"fa2a04c2c72ec91fb4d5ba938fee5a629db983bf","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.1.tgz","fileCount":9,"integrity":"sha512-dpKh0ot6NJBjwnmwZ1tHZB2wyQOWq6I9NY4B44XSWA/HLGFZ6GV+EjScDj7gyxx2CMJbcm7wYC0C0f+Y1jETTw==","signatures":[{"sig":"MEUCIQDB3yPIluVslYmnrMNslilKl/cFY/c0+OVFtK6CS4pt8QIgKep3VERCvdikGl+eOxqEgFm6q1iEdeGN06te6hOSBV8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5473},"main":"dist/index.js","type":"module","gitHead":"0d26b1d71c542b88bf5019e47779b16795b4b488","scripts":{"build":"tsc"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.6.3","description":"Filesystem features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","dependencies":{"minimatch":"^10.1.1","parse-gitignore":"^2.0.0","@agent-smith/cli":"^0.0.95"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"2.8.1","ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.0.2","@locallm/types":"^0.6.4","@commander-js/extra-typings":"^14.0.0"},"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.1_1765813844248_0.7540701184612322","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@agent-smith/feat-fs","version":"0.0.2","license":"MIT","_id":"@agent-smith/feat-fs@0.0.2","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith#readme","bugs":{"url":"https://github.com/synw/agent-smith/issues"},"dist":{"shasum":"19832af79146a1de39daecdd7c6b6f94de46b0fa","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.2.tgz","fileCount":9,"integrity":"sha512-RiNnfPSqqIR/Bp/5RxqaxfGY6xGnhNWh2LTEeMX9IvWUMAO4mLF2wDqpvD0gfeIMkhNPS5ZObzXRKGinCeLqpw==","signatures":[{"sig":"MEQCIFCSM/xMMbvJ0Beb3F4sTovwL+iegaelZ2AvlUA5peE7AiBbZeMY4fffobrDXBzoGB83M8xFC5QvLPu2gAwbwuKcgg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":7405},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"6461102614051eb04c2e20de6cbf434d4e383719","scripts":{"build":"tsc"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith.git","type":"git"},"_npmVersion":"11.7.0","description":"Filesystem features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"2.8.1","typescript":"^5.9.3","@types/node":"^25.0.9"},"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.2_1769157357767_0.9358206208250435","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@agent-smith/feat-fs","version":"0.0.3","license":"MIT","_id":"@agent-smith/feat-fs@0.0.3","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith-plugins#readme","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"995d8a08b4e70bb6da44e0e57af71c0519da1025","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.3.tgz","fileCount":17,"integrity":"sha512-0pC/4kafCa7xQIrVOUujkw/B2b1tnEn+WXXwuIvAdVXdSNXDGOfa0fWP3PbU++u5cusPdPRoRPblq4tauGhIFg==","signatures":[{"sig":"MEQCHzJhfDYhUGUFS18kpwUoMirThcbNIb6ummkRD9LYoUICIQDTHaNBOhWXa0/HyTm2Jmsyx4Jz1ob6SaG636dxTn60eg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9154},"type":"module","types":"./dist/main.d.ts","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"f96185a47922f2f80e34368896be92fdf09488af","scripts":{"types":"tsc --declaration --emitDeclarationOnly"},"_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.7.0","description":"Filesystem features for Agent Smith cli","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"2.8.1","typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.3_1772727684241_0.07339150317222076","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@agent-smith/feat-fs","version":"0.0.4","license":"MIT","_id":"@agent-smith/feat-fs@0.0.4","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith-plugins#readme","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"715c9b2995a97aee6f25ced841e92c94cac9c4cd","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.4.tgz","fileCount":11,"integrity":"sha512-5cbdbMVwoNIksmrIf4SwYdK5tNUzfj1aRZo2oC9ufG4Os5h/G23M0idoLEzEPh/9fJ0ixXsSliQ6a9kuTNic+A==","signatures":[{"sig":"MEUCICmJFTMY9UaSzPR/vOtL/T9Bz9dX0OS2HZ+7DkNrzr0dAiEA6rDApulUJbkfekWjYa+X+/XJVzFpzBSwBEBohV2rpRc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18465},"type":"module","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"598cd4e880b064cb05fe0f318a33e683cc2985bb","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.13.0","description":"Filesystem features for Agent Smith","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.4_1781272044344_0.6182678495730727","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"name":"@agent-smith/feat-fs","version":"0.0.5","license":"MIT","_id":"@agent-smith/feat-fs@0.0.5","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith-plugins#readme","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"dcbd84950f6dad7843d0c51c04b73530c86bbd33","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.5.tgz","fileCount":11,"integrity":"sha512-VWG1ALiOgFPXfHs7H+Ld+ZvuoPvk6EAaTi97XXgPrJEMFtkb6Q7atcwhOIESbMsKQybuebijnWeoJVCiIPFwtg==","signatures":[{"sig":"MEUCIFGxdw7cU3ByF9qD8TzZ9c/odIMJDyQeFEEuJHD3no3AAiEAlWsWH2Rnwy9hgig8NBFM+FNg/BazffS799jN5VlK7jQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18458},"type":"module","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"b58a7c55dd44429c796dd4dab606d181d107bf7a","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.13.0","description":"Filesystem features for Agent Smith","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.5_1782038747202_0.37019160097607795","host":"s3://npm-registry-packages-npm-production"}},"0.0.6":{"name":"@agent-smith/feat-fs","version":"0.0.6","license":"MIT","_id":"@agent-smith/feat-fs@0.0.6","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith-plugins#readme","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"9d81b3ad5b5813cdc040a67d19f1f44ea4a56a81","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.6.tgz","fileCount":11,"integrity":"sha512-WqD0elyueMeK5tm3arKamK0qOlhaIkoO16f4S6+f8wdA1aHvTE9UjPU620Jx9a8OY9iBRKJ+TSiFFdaLLJoNbA==","signatures":[{"sig":"MEQCIAMN0hY7UOfxtRnvI/g46b4l/nV5uZNjO7eaSInzlV1sAiBd/jtu5nDHjILkgQ6IC/7wxpkMXIFjdflYy3VcFStf+w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20214},"type":"module","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"dcf1441aa4081a9564d3b9c1eabb16aeb4a59baf","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.18.0","description":"Filesystem features for Agent Smith","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.6_1785838558094_0.14619029971493336","host":"s3://npm-registry-packages-npm-production"}},"0.0.7":{"name":"@agent-smith/feat-fs","version":"0.0.7","license":"MIT","_id":"@agent-smith/feat-fs@0.0.7","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"homepage":"https://github.com/synw/agent-smith-plugins#readme","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"7cc33aedbc9bbb82fbbf05b018096d3387a6b5b8","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.7.tgz","fileCount":11,"integrity":"sha512-5WIZMKD4g1C8afLz6ZhUXPF6PtJYgAUJe6mfkB5TKZEqOaIfC+SYIoQa4RTyl5hpeJLnQaqD/7Jj7w1wG41crQ==","signatures":[{"sig":"MEUCIQCXlhF6m4FDFR2CEopdjCvuBQcLzwxxHscQvGXHfAlrlwIgOhnQXn9mvCUmsVGd0O25cCmBOxs/+26hhsUBSJQd0Do=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20176},"type":"module","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"5ea6a98a62f26045f26bfe59b61f573489bc0a11","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.18.0","description":"Filesystem features for Agent Smith","directories":{},"_nodeVersion":"24.11.0","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/feat-fs_0.0.7_1787313335963_0.9414580299333057","host":"s3://npm-registry-packages-npm-production"}},"0.0.8":{"_id":"@agent-smith/feat-fs@0.0.8","bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"dist":{"shasum":"9f51d521ead9200aa379ae0c506f512ba29e8e69","tarball":"https://registry.npmjs.org/@agent-smith/feat-fs/-/feat-fs-0.0.8.tgz","fileCount":10,"integrity":"sha512-B6HaMtsiLf3xCPDIx5bZ3OAQWrAY4X1Sh6CbnD5LKqguBo9NRWcHaYccqumr41g5Bc3JPcI7Wuf8LyZ3TIg3qg==","signatures":[{"sig":"MEUCIQCxWDDzPXdoVQEgdn6bS9Md/Bi0IDMuUqLp/Pq1OOF3swIgZNrEpP82pRTsXYUviYUfCqy2XKrkKa+s54eMEtNU5I4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDzN3ujPUxnMpCH9HkRrIN0WTBhD+Rx4nEWjSesphHelgIhAKZMoY/DGSQ1fLSaV9+3TTZJKZn33yn8hfWcm984zbLa"}],"unpackedSize":19946},"name":"@agent-smith/feat-fs","type":"module","module":"./dist/main.js","exports":{".":{"import":"./dist/main.js"}},"gitHead":"7d05e288313f7b193d070ea1601c7823ecbebea3","license":"MIT","version":"0.0.8","_npmUser":{"name":"synw","email":"synwx@protonmail.com"},"homepage":"https://github.com/synw/agent-smith-plugins#readme","repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"_npmVersion":"11.18.0","description":"Filesystem features for Agent Smith","directories":{},"maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"_nodeVersion":"24.11.0","dependencies":{"@xberg-io/xberg":"^1.0.14"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/feat-fs_0.0.8_1789560552872_0.36260037413552193"}}},"time":{"created":"2025-12-15T15:50:44.147Z","modified":"2026-09-16T12:09:13.174Z","0.0.1":"2025-12-15T15:50:44.415Z","0.0.2":"2026-01-23T08:35:57.914Z","0.0.3":"2026-03-05T16:21:24.377Z","0.0.4":"2026-06-12T13:47:24.490Z","0.0.5":"2026-06-21T10:45:47.341Z","0.0.6":"2026-08-04T10:15:58.234Z","0.0.7":"2026-08-21T11:55:36.100Z","0.0.8":"2026-09-16T12:09:12.960Z"},"bugs":{"url":"https://github.com/synw/agent-smith-plugins/issues"},"license":"MIT","homepage":"https://github.com/synw/agent-smith-plugins#readme","repository":{"url":"git+https://github.com/synw/agent-smith-plugins.git","type":"git"},"description":"Filesystem features for Agent Smith","maintainers":[{"name":"synw","email":"synwx@protonmail.com"}],"readme":"# @agent-smith/feat-fs\n\n[![pub package](https://img.shields.io/npm/v/@agent-smith/feat-fs)](https://www.npmjs.com/package/@agent-smith/feat-fs)\n\n**Filesystem features for Agent Smith CLI** — Manage files and directories with language models. Part of the [Agent Smith toolkit](https://github.com/lynxai-team/agent-smith).\n\n## ✨ Features\n\n- 📂 **Directory Operations** — List files and folders with `lsdir` and read all files content with `dirfiles`\n- 📄 **File Reading** — Read file contents securely with `read-file`\n- ✍️ **File Writing** — Write content to files safely with `write-file` and directory validation\n- 🔍 **File Editing** — Search and replace strings in files with `edit-search-replace`\n- 🤖 **AI Agents** — Pre-configured `fs-workspace-agent` for autonomous file operations\n- 🔒 **Path Authorization** — Built-in security layer that validates all file paths against allowed directories\n- ⚡ **Lightweight Agent** — Optimized agent configuration with configurable inference parameters\n\n## 📖 Documentation\n\n### For AI Agents\n- [Codebase Summary](.agents/documentation/codebase-summary.md) — Architecture, key files, and patterns for the @agent-smith/feat-fs plugin\n- [Filesystem Plugin](https://raw.githubusercontent.com/lynxai-team/agent-smith/refs/heads/main/docsite/public/doc/plugins/6.filesystem.md) — Complete plugin documentation with actions, tools, and agent examples\n\n### For Humans\n- [Filesystem Plugin](https://lynxai-team.github.io/agent-smith/plugins/filesystem) — Plugin overview, actions, and usage guide\n\n## 📦 Installation\n\n```bash\nnpm i -g @agent-smith/feat-fs\n```\n\nAdd the plugin to your `config.yml` file:\n\n```yaml\nplugins:\n  - \"@agent-smith/feat-fs\"\n```\n\nThen run the configuration command:\n\n```bash\nlm conf\n```\n\n## 🚀 Quick Start\n\n### Using the CLI with an AI Agent\n\nCreate a simple filesystem agent configuration:\n\n```yaml\ndescription: A filesystem agent\nmodel: qwen4b\ntoolsList:\n  - fs-workspace-agent  # lightweight filesystem agent\nvariables:\n  required:\n    workspace:\n      description: The local directory path where to operate\n```\n\nRun the agent:\n\n```bash\nlm myagent \"explain me what the code project in the current directory is doing\" --workspace /some/path\n```\n\nOr use `fs-workspace-agent` directly\n\n### Programmatic Usage\n\n```typescript\nimport { lsdir, readFile, writeToFile } from \"@agent-smith/feat-fs\";\n\n// List directory contents\nconst result = await lsdir(\"./src\");\nconsole.log(result.files); // Array of file paths\nconsole.log(result.dirs);  // Array of directory paths\n\n// Read a file\nconst content = await readFile(\"./README.md\");\nconsole.log(content);\n\n// Write to a file\nwriteToFile(\"./output.txt\", \"Hello, Agent Smith!\", true);\n```\n\n## 📝 Usage Patterns\n\n### Directory Operations\n\n**List files and directories:**\n```typescript\nimport { lsdir } from \"@agent-smith/feat-fs\";\n\n// List both files and directories\nconst result = await lsdir(\"./project\");\n// Returns: { files: string[], dirs: string[] }\n\n// List only files\nconst files = await lsdir(\"./project\", { files: true });\n\n// List only directories\nconst dirs = await lsdir(\"./project\", { dirs: true });\n\n// Debug mode\nawait lsdir(\"./project\", { debug: true });\n```\n\n### File Operations\n\n**Read a file:**\n```typescript\nimport { readFile } from \"@agent-smith/feat-fs\";\n\ntry {\n  const content = await readFile(\"./config.json\");\n  console.log(content);\n} catch (error) {\n  console.error(`Failed to read file: ${error.message}`);\n}\n```\n\n**Write to a file:**\n```typescript\nimport { writeToFile } from \"@agent-smith/feat-fs\";\n\ntry {\n  // Writes content to file, creates directory structure if needed\n  const result = await writeToFile(\n    \"./output/data.txt\",\n    \"File content here\",\n    true  // verbose mode\n  );\n  console.log(result); // \"Ok: file ./output/data.txt written\"\n} catch (error) {\n  console.error(`Write failed: ${error.message}`);\n}\n```\n\n**Edit a file with search and replace:**\n```typescript\n// The edit-search-replace tool is available as an action\n// It searches for old_content and replaces it with new_content in the specified file\n```\n\n### Security & Path Authorization\n\nAll file operations include built-in path authorization. The plugin validates requested paths against allowed directories configured via `options.variables.path`:\n\n```typescript\n// Authorized paths configuration\nconst options = {\n  variables: {\n    path: \"/workspace/project,/workspace/src\",  // Comma-separated authorized paths\n    workspace: \"/workspace/project\"\n  }\n};\n\n// Operations outside authorized paths will be rejected\nawait lsdir(\"/workspace/project/src\", options);  // ✅ Allowed\nawait readFile(\"/etc/passwd\", options);           // ❌ Unauthorized\n```\n\n## 🤖 Agent Configurations\n\n### fs-workspace-agent\n\nA lightweight read, write and explore filesystem agent:\n\n```yaml\ndescription: Filesystem lightweight read, write and explore agent\ncategory: \"system/filesystem\"\nmodel: qwen4b\nprompt: \"{prompt}\"\ntemplate:\n    system: |-\n        You are an AI filesystem assistant. You are equiped with tools to operate on the filesystem.\ninferParams:\n    top_k: 20\n    top_p: 0.7\n    min_p: 0\n    temperature: 0.2\nvariables:\n  required:\n    workspace:\n      description: The local directory path where to operate\ntoolsList:\n    - lsdir\n    - dirfiles?\n    - read-file?\n    - edit-search-replace?\n    - write-file?\n```\n\n**Available tools:**\n| Tool | Description |\n|------|-------------|\n| `lsdir` | List files and folders in a directory |\n| `dirfiles` | Read all files content in a directory (excludes hidden files) |\n| `read-file` | Read a file's content |\n| `write-file` | Write content to a file |\n| `edit-search-replace` | Search and replace strings in a file |\n\n## 📚 API Reference\n\n### Core Functions\n\n#### `lsdir(dirPath: string | string[], options?: object): Promise<object>`\n\nList files and folders in a directory.\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `dirPath` | `string` or `string[]` | The path of the directory to read |\n| `options.files` | `boolean` | If true, return only files |\n| `options.dirs` | `boolean` | If true, return only directories |\n| `options.debug` | `boolean` | Enable debug logging |\n\n**Returns:** `Promise<{ files: string[], dirs: string[] }>` or filtered arrays if `files` or `dirs` options are set.\n\n**Example:**\n```typescript\nconst result = await lsdir(\"./src\");\n// { files: ['./src/main.ts', './src/utils.ts'], dirs: ['./src/components'] }\n```\n\n#### `readFile(filePath: string): Promise<string>`\n\nRead a file's content with error handling.\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | `string` | The path of the file to read |\n\n**Returns:** `Promise<string>` — The file content as a UTF-8 string.\n\n**Example:**\n```typescript\nconst content = await readFile(\"./README.md\");\n```\n\n#### `writeToFile(filePath: string, content: string, isVerbose?: boolean): void`\n\nWrite content to a file with directory validation.\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | `string` | The path of the file to write |\n| `content` | `string` | The content to write |\n| `isVerbose` | `boolean` | If true, log confirmation message |\n\n**Example:**\n```typescript\nwriteToFile(\"./output.txt\", \"Hello!\", true);\n```\n\n### Entry Point Exports\n\nThe main module (`dist/main.js`) exports three core functions:\n\n```typescript\nimport { lsdir, readFile, writeToFile } from \"@agent-smith/feat-fs\";\n```\n\n## ⚠️ Important Notes\n\n- **Node.js Only** — This plugin requires Node.js and uses built-in `fs` and `path` modules. It is not compatible with browsers.\n- **Path Authorization** — All actions validate requested paths against authorized directories configured via `options.variables.path`. Operations on unauthorized paths will be rejected.\n- **Directory Creation** — The `write-file` action requires the target directory to already exist. Create directories before writing files.\n- **Agent Configuration** — When using agents, always specify authorized paths in the `variables.workspace` configuration to ensure secure file operations.\n\n## 🔗 Related Packages\n\n- [@agent-smith/core](https://www.npmjs.com/package/@agent-smith/core) — Main CLI framework that consumes this plugin's actions\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md"}