@skill-toolbox/filesystem-source 0.0.1

package/README.md

@@ -0,0 +1,84 @@
+# @skill-toolbox/filesystem-source
+
+Filesystem source adapter for skill-toolbox. Enables loading skills from local directories and files.
+
+## Installation
+
+```bash
+npm install @skill-toolbox/filesystem-source
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { FilesystemSource } from '@skill-toolbox/filesystem-source';
+
+const source = new FilesystemSource();
+
+// Check if source can handle a path
+const canHandle = await source.canHandle('/path/to/skills');
+
+// Resolve path to metadata
+const meta = await source.resolve('/path/to/skills');
+
+// Fetch (validates path exists)
+const localPath = await source.fetch(meta);
+
+// Discover skills
+const skills = await source.discover(localPath, meta);
+```
+
+### With Custom Working Directory
+
+```typescript
+const source = new FilesystemSource({
+  cwd: '/base/directory'
+});
+
+// Now relative paths are resolved from cwd
+const meta = await source.resolve('./skills');
+```
+
+## Features
+
+- **Single Skill Loading**: Load a skill from a directory containing a SKILL.md file
+- **Multi-Skill Discovery**: Discover multiple skills in subdirectories
+- **Direct File Loading**: Load a skill directly from a SKILL.md file
+- **Relative Path Support**: Use relative paths with custom working directory
+
+## API
+
+### `FilesystemSource`
+
+#### Constructor
+
+```typescript
+constructor(options?: FilesystemSourceOptions)
+```
+
+**Options:**
+- `cwd` - Base directory for relative paths (default: `process.cwd()`)
+
+#### Methods
+
+##### `canHandle(source: string): Promise<boolean>`
+
+Check if the source string is a valid filesystem path.
+
+##### `resolve(source: string): Promise<SkillSourceMeta>`
+
+Resolve the source string to metadata.
+
+##### `fetch(meta: SkillSourceMeta, options?: FetchOptions): Promise<string>`
+
+Validate and return the path (no actual fetching needed for filesystem).
+
+##### `discover(localPath: string, meta: SkillSourceMeta): Promise<DiscoveredSkill[]>`
+
+Discover skills in the given path.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,39 @@
+import { SkillSource, SourceCategory, SourceInfo, SourceLoadResult } from '@skill-toolbox/utils';
+
+interface FilesystemSourceOptions {
+    /** Path to the skills directory or file */
+    path: string;
+    /** Display name for this source (used in skill names) */
+    name?: string;
+    /** Category override (defaults to 'global' if name is 'global', else 'local') */
+    category?: SourceCategory;
+}
+declare class FilesystemSource implements SkillSource {
+    private targetPath;
+    private name;
+    private category;
+    constructor(options: FilesystemSourceOptions);
+    getSourceInfo(): SourceInfo;
+    load(): Promise<SourceLoadResult>;
+    cleanup(): Promise<void>;
+    /**
+     * Load a single skill file
+     */
+    private loadSingleFile;
+    /**
+     * Load all skills from a directory
+     */
+    private loadDirectory;
+    /**
+     * Check if filename is a valid skill file name
+     */
+    private isSkillFileName;
+}
+
+/**
+ * @skill-toolbox/filesystem-source
+ * Filesystem source adapter for skill-toolbox
+ */
+declare const VERSION = "1.0.0";
+
+export { FilesystemSource, type FilesystemSourceOptions, VERSION };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { SkillSource, SourceCategory, SourceInfo, SourceLoadResult } from '@skill-toolbox/utils';
+
+interface FilesystemSourceOptions {
+    /** Path to the skills directory or file */
+    path: string;
+    /** Display name for this source (used in skill names) */
+    name?: string;
+    /** Category override (defaults to 'global' if name is 'global', else 'local') */
+    category?: SourceCategory;
+}
+declare class FilesystemSource implements SkillSource {
+    private targetPath;
+    private name;
+    private category;
+    constructor(options: FilesystemSourceOptions);
+    getSourceInfo(): SourceInfo;
+    load(): Promise<SourceLoadResult>;
+    cleanup(): Promise<void>;
+    /**
+     * Load a single skill file
+     */
+    private loadSingleFile;
+    /**
+     * Load all skills from a directory
+     */
+    private loadDirectory;
+    /**
+     * Check if filename is a valid skill file name
+     */
+    private isSkillFileName;
+}
+
+/**
+ * @skill-toolbox/filesystem-source
+ * Filesystem source adapter for skill-toolbox
+ */
+declare const VERSION = "1.0.0";
+
+export { FilesystemSource, type FilesystemSourceOptions, VERSION };

package/dist/index.js

@@ -0,0 +1,187 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FilesystemSource: () => FilesystemSource,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/FilesystemSource.ts
+var import_path = __toESM(require("path"));
+var import_fs_extra = __toESM(require("fs-extra"));
+var import_utils = require("@skill-toolbox/utils");
+var FilesystemSource = class {
+  targetPath;
+  name;
+  category;
+  constructor(options) {
+    this.targetPath = options.path;
+    if (options.name) {
+      this.name = options.name;
+    } else {
+      const resolved = import_path.default.resolve(options.path);
+      const dirName = import_path.default.basename(resolved);
+      this.name = dirName || "local";
+    }
+    if (options.category) {
+      this.category = options.category;
+    } else {
+      this.category = this.name === "global" ? "global" : "local";
+    }
+  }
+  getSourceInfo() {
+    return {
+      type: "filesystem",
+      category: this.category,
+      identifier: this.name
+    };
+  }
+  async load() {
+    const info = {
+      type: "filesystem",
+      category: this.category,
+      identifier: this.name,
+      path: ""
+      // Will be set below
+    };
+    const result = {
+      skills: [],
+      errors: [],
+      info
+    };
+    try {
+      const resolvedPath = import_path.default.resolve(this.targetPath);
+      result.info.path = resolvedPath;
+      if (!await import_fs_extra.default.pathExists(resolvedPath)) {
+        result.errors.push({
+          path: this.targetPath,
+          error: new Error(`Path does not exist: ${this.targetPath}`)
+        });
+        return result;
+      }
+      const stat = await import_fs_extra.default.stat(resolvedPath);
+      const isFile = stat.isFile();
+      if (isFile) {
+        await this.loadSingleFile(resolvedPath, result);
+      } else {
+        await this.loadDirectory(resolvedPath, result);
+      }
+    } catch (error) {
+      result.errors.push({
+        path: this.targetPath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+    return result;
+  }
+  async cleanup() {
+  }
+  /**
+   * Load a single skill file
+   */
+  async loadSingleFile(filePath, result) {
+    try {
+      const content = await import_fs_extra.default.readFile(filePath, "utf-8");
+      const dir = import_path.default.dirname(filePath);
+      const baseName = import_path.default.basename(dir);
+      result.skills.push({
+        name: `${this.name}/${baseName}`,
+        baseName,
+        source: this.name,
+        path: filePath,
+        directory: dir,
+        content
+      });
+    } catch (error) {
+      result.errors.push({
+        path: filePath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Load all skills from a directory
+   */
+  async loadDirectory(dirPath, result) {
+    try {
+      const entries = await import_fs_extra.default.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const entryPath = import_path.default.join(dirPath, entry.name);
+        if (entry.isFile() && this.isSkillFileName(entry.name)) {
+          await this.loadSingleFile(entryPath, result);
+        } else if (entry.isDirectory()) {
+          const skillFile = await (0, import_utils.findSkillFile)(entryPath);
+          if (skillFile) {
+            try {
+              const content = await import_fs_extra.default.readFile(skillFile, "utf-8");
+              result.skills.push({
+                name: `${this.name}/${entry.name}`,
+                baseName: entry.name,
+                source: this.name,
+                path: skillFile,
+                directory: entryPath,
+                content
+              });
+            } catch (error) {
+              result.errors.push({
+                path: skillFile,
+                error: error instanceof Error ? error : new Error(String(error))
+              });
+            }
+          }
+        }
+      }
+    } catch (error) {
+      result.errors.push({
+        path: dirPath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Check if filename is a valid skill file name
+   */
+  isSkillFileName(name) {
+    const lower = name.toLowerCase();
+    return lower === "skill.md";
+  }
+};
+
+// src/index.ts
+var VERSION = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FilesystemSource,
+  VERSION
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/FilesystemSource.ts"],"sourcesContent":["/**\n * @skill-toolbox/filesystem-source\n * Filesystem source adapter for skill-toolbox\n */\n\nexport const VERSION = '1.0.0';\n\nexport { FilesystemSource } from './FilesystemSource';\nexport type { FilesystemSourceOptions } from './FilesystemSource';\n","import path from 'path';\nimport fs from 'fs-extra';\nimport type { SkillSource, SourceInfo, SourceLoadResult, SourceCategory, LoadedSourceInfo } from '@skill-toolbox/utils';\nimport { findSkillFile } from '@skill-toolbox/utils';\n\nexport interface FilesystemSourceOptions {\n  /** Path to the skills directory or file */\n  path: string;\n  /** Display name for this source (used in skill names) */\n  name?: string;\n  /** Category override (defaults to 'global' if name is 'global', else 'local') */\n  category?: SourceCategory;\n}\n\nexport class FilesystemSource implements SkillSource {\n  private targetPath: string;\n  private name: string;\n  private category: SourceCategory;\n\n  constructor(options: FilesystemSourceOptions) {\n    this.targetPath = options.path;\n\n    // Generate name for skill names\n    if (options.name) {\n      this.name = options.name;\n    } else {\n      // Use directory name or 'local' for absolute paths\n      const resolved = path.resolve(options.path);\n      const dirName = path.basename(resolved);\n      this.name = dirName || 'local';\n    }\n\n    // Determine category\n    if (options.category) {\n      this.category = options.category;\n    } else {\n      this.category = this.name === 'global' ? 'global' : 'local';\n    }\n  }\n\n  getSourceInfo(): SourceInfo {\n    return {\n      type: 'filesystem',\n      category: this.category,\n      identifier: this.name,\n    };\n  }\n\n  async load(): Promise<SourceLoadResult> {\n    // Initialize info with default path (will be updated after resolution)\n    const info: LoadedSourceInfo = {\n      type: 'filesystem',\n      category: this.category,\n      identifier: this.name,\n      path: '', // Will be set below\n    };\n\n    const result: SourceLoadResult = {\n      skills: [],\n      errors: [],\n      info,\n    };\n\n    try {\n      // Resolve to absolute path\n      const resolvedPath = path.resolve(this.targetPath);\n\n      // Update info with resolved path\n      result.info.path = resolvedPath;\n\n      // Check if path exists\n      if (!(await fs.pathExists(resolvedPath))) {\n        result.errors.push({\n          path: this.targetPath,\n          error: new Error(`Path does not exist: ${this.targetPath}`),\n        });\n        return result;\n      }\n\n      const stat = await fs.stat(resolvedPath);\n      const isFile = stat.isFile();\n\n      if (isFile) {\n        // Single skill file\n        await this.loadSingleFile(resolvedPath, result);\n      } else {\n        // Directory with multiple skills\n        await this.loadDirectory(resolvedPath, result);\n      }\n    } catch (error) {\n      result.errors.push({\n        path: this.targetPath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n\n    return result;\n  }\n\n  async cleanup(): Promise<void> {\n    // Nothing to cleanup for filesystem sources\n  }\n\n  /**\n   * Load a single skill file\n   */\n  private async loadSingleFile(filePath: string, result: SourceLoadResult): Promise<void> {\n    try {\n      const content = await fs.readFile(filePath, 'utf-8');\n      const dir = path.dirname(filePath);\n      const baseName = path.basename(dir);\n\n      result.skills.push({\n        name: `${this.name}/${baseName}`,\n        baseName,\n        source: this.name,\n        path: filePath,\n        directory: dir,\n        content,\n      });\n    } catch (error) {\n      result.errors.push({\n        path: filePath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n  }\n\n  /**\n   * Load all skills from a directory\n   */\n  private async loadDirectory(dirPath: string, result: SourceLoadResult): Promise<void> {\n    try {\n      const entries = await fs.readdir(dirPath, { withFileTypes: true });\n\n      for (const entry of entries) {\n        // Skip hidden files/directories\n        if (entry.name.startsWith('.')) continue;\n\n        const entryPath = path.join(dirPath, entry.name);\n\n        if (entry.isFile() && this.isSkillFileName(entry.name)) {\n          // Skill file in root directory\n          await this.loadSingleFile(entryPath, result);\n        } else if (entry.isDirectory()) {\n          // Check if directory contains a skill file\n          const skillFile = await findSkillFile(entryPath);\n          if (skillFile) {\n            try {\n              const content = await fs.readFile(skillFile, 'utf-8');\n              result.skills.push({\n                name: `${this.name}/${entry.name}`,\n                baseName: entry.name,\n                source: this.name,\n                path: skillFile,\n                directory: entryPath,\n                content,\n              });\n            } catch (error) {\n              result.errors.push({\n                path: skillFile,\n                error: error instanceof Error ? error : new Error(String(error)),\n              });\n            }\n          }\n        }\n      }\n    } catch (error) {\n      result.errors.push({\n        path: dirPath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n  }\n\n  /**\n   * Check if filename is a valid skill file name\n   */\n  private isSkillFileName(name: string): boolean {\n    const lower = name.toLowerCase();\n    return lower === 'skill.md';\n  }\n}\n"],"mappings":"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","names":["path","fs"]}

package/dist/index.mjs

@@ -0,0 +1,149 @@
+// src/FilesystemSource.ts
+import path from "path";
+import fs from "fs-extra";
+import { findSkillFile } from "@skill-toolbox/utils";
+var FilesystemSource = class {
+  targetPath;
+  name;
+  category;
+  constructor(options) {
+    this.targetPath = options.path;
+    if (options.name) {
+      this.name = options.name;
+    } else {
+      const resolved = path.resolve(options.path);
+      const dirName = path.basename(resolved);
+      this.name = dirName || "local";
+    }
+    if (options.category) {
+      this.category = options.category;
+    } else {
+      this.category = this.name === "global" ? "global" : "local";
+    }
+  }
+  getSourceInfo() {
+    return {
+      type: "filesystem",
+      category: this.category,
+      identifier: this.name
+    };
+  }
+  async load() {
+    const info = {
+      type: "filesystem",
+      category: this.category,
+      identifier: this.name,
+      path: ""
+      // Will be set below
+    };
+    const result = {
+      skills: [],
+      errors: [],
+      info
+    };
+    try {
+      const resolvedPath = path.resolve(this.targetPath);
+      result.info.path = resolvedPath;
+      if (!await fs.pathExists(resolvedPath)) {
+        result.errors.push({
+          path: this.targetPath,
+          error: new Error(`Path does not exist: ${this.targetPath}`)
+        });
+        return result;
+      }
+      const stat = await fs.stat(resolvedPath);
+      const isFile = stat.isFile();
+      if (isFile) {
+        await this.loadSingleFile(resolvedPath, result);
+      } else {
+        await this.loadDirectory(resolvedPath, result);
+      }
+    } catch (error) {
+      result.errors.push({
+        path: this.targetPath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+    return result;
+  }
+  async cleanup() {
+  }
+  /**
+   * Load a single skill file
+   */
+  async loadSingleFile(filePath, result) {
+    try {
+      const content = await fs.readFile(filePath, "utf-8");
+      const dir = path.dirname(filePath);
+      const baseName = path.basename(dir);
+      result.skills.push({
+        name: `${this.name}/${baseName}`,
+        baseName,
+        source: this.name,
+        path: filePath,
+        directory: dir,
+        content
+      });
+    } catch (error) {
+      result.errors.push({
+        path: filePath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Load all skills from a directory
+   */
+  async loadDirectory(dirPath, result) {
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const entryPath = path.join(dirPath, entry.name);
+        if (entry.isFile() && this.isSkillFileName(entry.name)) {
+          await this.loadSingleFile(entryPath, result);
+        } else if (entry.isDirectory()) {
+          const skillFile = await findSkillFile(entryPath);
+          if (skillFile) {
+            try {
+              const content = await fs.readFile(skillFile, "utf-8");
+              result.skills.push({
+                name: `${this.name}/${entry.name}`,
+                baseName: entry.name,
+                source: this.name,
+                path: skillFile,
+                directory: entryPath,
+                content
+              });
+            } catch (error) {
+              result.errors.push({
+                path: skillFile,
+                error: error instanceof Error ? error : new Error(String(error))
+              });
+            }
+          }
+        }
+      }
+    } catch (error) {
+      result.errors.push({
+        path: dirPath,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Check if filename is a valid skill file name
+   */
+  isSkillFileName(name) {
+    const lower = name.toLowerCase();
+    return lower === "skill.md";
+  }
+};
+
+// src/index.ts
+var VERSION = "1.0.0";
+export {
+  FilesystemSource,
+  VERSION
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/FilesystemSource.ts","../src/index.ts"],"sourcesContent":["import path from 'path';\nimport fs from 'fs-extra';\nimport type { SkillSource, SourceInfo, SourceLoadResult, SourceCategory, LoadedSourceInfo } from '@skill-toolbox/utils';\nimport { findSkillFile } from '@skill-toolbox/utils';\n\nexport interface FilesystemSourceOptions {\n  /** Path to the skills directory or file */\n  path: string;\n  /** Display name for this source (used in skill names) */\n  name?: string;\n  /** Category override (defaults to 'global' if name is 'global', else 'local') */\n  category?: SourceCategory;\n}\n\nexport class FilesystemSource implements SkillSource {\n  private targetPath: string;\n  private name: string;\n  private category: SourceCategory;\n\n  constructor(options: FilesystemSourceOptions) {\n    this.targetPath = options.path;\n\n    // Generate name for skill names\n    if (options.name) {\n      this.name = options.name;\n    } else {\n      // Use directory name or 'local' for absolute paths\n      const resolved = path.resolve(options.path);\n      const dirName = path.basename(resolved);\n      this.name = dirName || 'local';\n    }\n\n    // Determine category\n    if (options.category) {\n      this.category = options.category;\n    } else {\n      this.category = this.name === 'global' ? 'global' : 'local';\n    }\n  }\n\n  getSourceInfo(): SourceInfo {\n    return {\n      type: 'filesystem',\n      category: this.category,\n      identifier: this.name,\n    };\n  }\n\n  async load(): Promise<SourceLoadResult> {\n    // Initialize info with default path (will be updated after resolution)\n    const info: LoadedSourceInfo = {\n      type: 'filesystem',\n      category: this.category,\n      identifier: this.name,\n      path: '', // Will be set below\n    };\n\n    const result: SourceLoadResult = {\n      skills: [],\n      errors: [],\n      info,\n    };\n\n    try {\n      // Resolve to absolute path\n      const resolvedPath = path.resolve(this.targetPath);\n\n      // Update info with resolved path\n      result.info.path = resolvedPath;\n\n      // Check if path exists\n      if (!(await fs.pathExists(resolvedPath))) {\n        result.errors.push({\n          path: this.targetPath,\n          error: new Error(`Path does not exist: ${this.targetPath}`),\n        });\n        return result;\n      }\n\n      const stat = await fs.stat(resolvedPath);\n      const isFile = stat.isFile();\n\n      if (isFile) {\n        // Single skill file\n        await this.loadSingleFile(resolvedPath, result);\n      } else {\n        // Directory with multiple skills\n        await this.loadDirectory(resolvedPath, result);\n      }\n    } catch (error) {\n      result.errors.push({\n        path: this.targetPath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n\n    return result;\n  }\n\n  async cleanup(): Promise<void> {\n    // Nothing to cleanup for filesystem sources\n  }\n\n  /**\n   * Load a single skill file\n   */\n  private async loadSingleFile(filePath: string, result: SourceLoadResult): Promise<void> {\n    try {\n      const content = await fs.readFile(filePath, 'utf-8');\n      const dir = path.dirname(filePath);\n      const baseName = path.basename(dir);\n\n      result.skills.push({\n        name: `${this.name}/${baseName}`,\n        baseName,\n        source: this.name,\n        path: filePath,\n        directory: dir,\n        content,\n      });\n    } catch (error) {\n      result.errors.push({\n        path: filePath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n  }\n\n  /**\n   * Load all skills from a directory\n   */\n  private async loadDirectory(dirPath: string, result: SourceLoadResult): Promise<void> {\n    try {\n      const entries = await fs.readdir(dirPath, { withFileTypes: true });\n\n      for (const entry of entries) {\n        // Skip hidden files/directories\n        if (entry.name.startsWith('.')) continue;\n\n        const entryPath = path.join(dirPath, entry.name);\n\n        if (entry.isFile() && this.isSkillFileName(entry.name)) {\n          // Skill file in root directory\n          await this.loadSingleFile(entryPath, result);\n        } else if (entry.isDirectory()) {\n          // Check if directory contains a skill file\n          const skillFile = await findSkillFile(entryPath);\n          if (skillFile) {\n            try {\n              const content = await fs.readFile(skillFile, 'utf-8');\n              result.skills.push({\n                name: `${this.name}/${entry.name}`,\n                baseName: entry.name,\n                source: this.name,\n                path: skillFile,\n                directory: entryPath,\n                content,\n              });\n            } catch (error) {\n              result.errors.push({\n                path: skillFile,\n                error: error instanceof Error ? error : new Error(String(error)),\n              });\n            }\n          }\n        }\n      }\n    } catch (error) {\n      result.errors.push({\n        path: dirPath,\n        error: error instanceof Error ? error : new Error(String(error)),\n      });\n    }\n  }\n\n  /**\n   * Check if filename is a valid skill file name\n   */\n  private isSkillFileName(name: string): boolean {\n    const lower = name.toLowerCase();\n    return lower === 'skill.md';\n  }\n}\n","/**\n * @skill-toolbox/filesystem-source\n * Filesystem source adapter for skill-toolbox\n */\n\nexport const VERSION = '1.0.0';\n\nexport { FilesystemSource } from './FilesystemSource';\nexport type { FilesystemSourceOptions } from './FilesystemSource';\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@skill-toolbox/filesystem-source",
+  "version": "0.0.1",
+  "description": "Filesystem source adapter for skill-toolbox",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@skill-toolbox/utils": "workspace:*",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "tsup": "^8.0.0",
+    "vitest": "^1.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Link-Reverie/skill-toolbox.git",
+    "directory": "packages/filesystem-source"
+  },
+  "bugs": {
+    "url": "https://github.com/Link-Reverie/skill-toolbox/issues"
+  },
+  "homepage": "https://github.com/Link-Reverie/skill-toolbox#readme",
+  "license": "MIT",
+  "keywords": [
+    "skill",
+    "ai-agent",
+    "claude",
+    "llm",
+    "typescript",
+    "filesystem",
+    "source"
+  ]
+}