@a16njs/models 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { CustomizationType, type AgentCustomization, type GlobalPrompt, type SimpleAgentSkill, type AgentSkill, // Deprecated alias for SimpleAgentSkill
 type AgentSkillIO, type FileRule, type AgentIgnore, type ManualPrompt, } from './types.js';
-export { type A16nPlugin, type DiscoveryResult, type EmitResult, type EmitOptions, type WrittenFile, } from './plugin.js';
+export { type A16nPlugin, type PluginPathPatterns, type DiscoveryResult, type EmitResult, type EmitOptions, type WrittenFile, } from './plugin.js';
 export { WarningCode, type Warning } from './warnings.js';
 export { isGlobalPrompt, isSimpleAgentSkill, isAgentSkill, // Deprecated alias for isSimpleAgentSkill
 isAgentSkillIO, isFileRule, isAgentIgnore, isManualPrompt, getUniqueFilename, createId, } from './helpers.js';
 export { type IRVersion, type ParsedIRVersion, CURRENT_IR_VERSION, parseIRVersion, areVersionsCompatible, getCurrentVersion, } from './version.js';
+export { type Workspace, type WorkspaceEntry, resolveRoot, LocalWorkspace, toWorkspace } from './workspace.js';
 export { type ParsedSkillFrontmatter, type ParsedSkill, parseSkillFrontmatter, readSkillFiles, writeAgentSkillIO, readAgentSkillIO, } from './agentskills-io.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAAE,wCAAwC;AACzD,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EAAE,0CAA0C;AACxD,cAAc,EACd,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAAE,wCAAwC;AACzD,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAG1D,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EAAE,0CAA0C;AACxD,cAAc,EACd,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG/G,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -8,6 +8,8 @@ export { isGlobalPrompt, isSimpleAgentSkill, isAgentSkill, // Deprecated alias f
 isAgentSkillIO, isFileRule, isAgentIgnore, isManualPrompt, getUniqueFilename, createId, } from './helpers.js';
 // Version utilities
 export { CURRENT_IR_VERSION, parseIRVersion, areVersionsCompatible, getCurrentVersion, } from './version.js';
+// Workspace abstraction
+export { resolveRoot, LocalWorkspace, toWorkspace } from './workspace.js';
 // AgentSkills.io utilities
 export { parseSkillFrontmatter, readSkillFiles, writeAgentSkillIO, readAgentSkillIO, } from './agentskills-io.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,QAAQ;AACR,OAAO,EACL,iBAAiB,GASlB,MAAM,YAAY,CAAC;AAWpB,WAAW;AACX,OAAO,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AAE1D,UAAU;AACV,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EAAE,0CAA0C;AACxD,cAAc,EACd,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,oBAAoB;AACpB,OAAO,EAGL,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,2BAA2B;AAC3B,OAAO,EAGL,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,QAAQ;AACR,OAAO,EACL,iBAAiB,GASlB,MAAM,YAAY,CAAC;AAYpB,WAAW;AACX,OAAO,EAAE,WAAW,EAAgB,MAAM,eAAe,CAAC;AAE1D,UAAU;AACV,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EAAE,0CAA0C;AACxD,cAAc,EACd,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,QAAQ,GACT,MAAM,cAAc,CAAC;AAEtB,oBAAoB;AACpB,OAAO,EAGL,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,wBAAwB;AACxB,OAAO,EAAuC,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE/G,2BAA2B;AAC3B,OAAO,EAGL,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC"}

package/dist/plugin.d.ts

@@ -1,5 +1,6 @@
 import type { AgentCustomization, CustomizationType } from './types.js';
 import type { Warning } from './warnings.js';
+import type { Workspace } from './workspace.js';
 /**
  * Result of discovering customizations from a project.
  */
@@ -46,6 +47,16 @@ export interface EmitOptions {
     /** If true, calculate what would be written without actually writing */
     dryRun?: boolean;
 }
+/**
+ * Path patterns for a plugin, used by transformations like path rewriting
+ * to identify and handle file references specific to this plugin's format.
+ */
+export interface PluginPathPatterns {
+    /** Directory prefixes used by this plugin (e.g., ['.cursor/rules/', '.cursor/skills/']) */
+    prefixes: string[];
+    /** File extensions used by this plugin (e.g., ['.mdc', '.md']) */
+    extensions: string[];
+}
 /**
  * The plugin interface that all a16n plugins must implement.
  * Plugins bridge between a16n's internal model and a specific tool's format.
@@ -57,19 +68,21 @@ export interface A16nPlugin {
     name: string;
     /** Which customization types this plugin supports */
     supports: CustomizationType[];
+    /** Path patterns for this plugin's file format (used by transformations) */
+    pathPatterns?: PluginPathPatterns;
     /**
      * Discover all agent customizations in a directory tree.
-     * @param root - The root directory to search
+     * @param rootOrWorkspace - The root directory path or Workspace to search
      * @returns All customizations found and any warnings
      */
-    discover(root: string): Promise<DiscoveryResult>;
+    discover(rootOrWorkspace: string | Workspace): Promise<DiscoveryResult>;
     /**
      * Emit customization models to disk in this plugin's format.
      * @param models - The customizations to emit
-     * @param root - The root directory to write to
+     * @param rootOrWorkspace - The root directory path or Workspace to write to
      * @param options - Optional emit options (e.g., dryRun)
      * @returns Info about what was written (or would be written) and any issues
      */
-    emit(models: AgentCustomization[], root: string, options?: EmitOptions): Promise<EmitResult>;
+    emit(models: AgentCustomization[], rootOrWorkspace: string | Workspace, options?: EmitOptions): Promise<EmitResult>;
 }
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC9F"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,iBAAiB,CAAC;IACxB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,yDAAyD;IACzD,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kEAAkE;IAClE,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAExE;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,EAAE,kBAAkB,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrH"}

package/dist/warnings.d.ts

@@ -17,7 +17,11 @@ export declare enum WarningCode {
     /** Sources have conflicting git status (some ignored, some tracked) */
     GitStatusConflict = "git-status-conflict",
     /** IR file version is incompatible with current reader version */
-    VersionMismatch = "version-mismatch"
+    VersionMismatch = "version-mismatch",
+    /** A path reference in content points to a source-format file not in the conversion set */
+    OrphanPathRef = "orphan-path-ref",
+    /** A post-conversion operation (e.g. gitignore cleanup) failed */
+    OperationFailed = "operation-failed"
 }
 /**
  * A warning about something that happened during conversion.

package/dist/warnings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,WAAW;IACrB,kDAAkD;IAClD,MAAM,WAAW;IACjB,yCAAyC;IACzC,YAAY,iBAAiB;IAC7B,4CAA4C;IAC5C,OAAO,YAAY;IACnB,iCAAiC;IACjC,WAAW,gBAAgB;IAC3B,0CAA0C;IAC1C,WAAW,iBAAiB;IAC5B,6DAA6D;IAC7D,gBAAgB,sBAAsB;IACtC,uEAAuE;IACvE,iBAAiB,wBAAwB;IACzC,kEAAkE;IAClE,eAAe,qBAAqB;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,WAAW;IACrB,kDAAkD;IAClD,MAAM,WAAW;IACjB,yCAAyC;IACzC,YAAY,iBAAiB;IAC7B,4CAA4C;IAC5C,OAAO,YAAY;IACnB,iCAAiC;IACjC,WAAW,gBAAgB;IAC3B,0CAA0C;IAC1C,WAAW,iBAAiB;IAC5B,6DAA6D;IAC7D,gBAAgB,sBAAsB;IACtC,uEAAuE;IACvE,iBAAiB,wBAAwB;IACzC,kEAAkE;IAClE,eAAe,qBAAqB;IACpC,2FAA2F;IAC3F,aAAa,oBAAoB;IACjC,kEAAkE;IAClE,eAAe,qBAAqB;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,0BAA0B;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC"}

package/dist/warnings.js

@@ -19,5 +19,9 @@ export var WarningCode;
     WarningCode["GitStatusConflict"] = "git-status-conflict";
     /** IR file version is incompatible with current reader version */
     WarningCode["VersionMismatch"] = "version-mismatch";
+    /** A path reference in content points to a source-format file not in the conversion set */
+    WarningCode["OrphanPathRef"] = "orphan-path-ref";
+    /** A post-conversion operation (e.g. gitignore cleanup) failed */
+    WarningCode["OperationFailed"] = "operation-failed";
 })(WarningCode || (WarningCode = {}));
 //# sourceMappingURL=warnings.js.map

package/dist/warnings.js.map

@@ -1 +1 @@
-{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,WAiBX;AAjBD,WAAY,WAAW;IACrB,kDAAkD;IAClD,gCAAiB,CAAA;IACjB,yCAAyC;IACzC,4CAA6B,CAAA;IAC7B,4CAA4C;IAC5C,kCAAmB,CAAA;IACnB,iCAAiC;IACjC,0CAA2B,CAAA;IAC3B,0CAA0C;IAC1C,2CAA4B,CAAA;IAC5B,6DAA6D;IAC7D,qDAAsC,CAAA;IACtC,uEAAuE;IACvE,wDAAyC,CAAA;IACzC,kEAAkE;IAClE,mDAAoC,CAAA;AACtC,CAAC,EAjBW,WAAW,KAAX,WAAW,QAiBtB"}
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../src/warnings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,WAqBX;AArBD,WAAY,WAAW;IACrB,kDAAkD;IAClD,gCAAiB,CAAA;IACjB,yCAAyC;IACzC,4CAA6B,CAAA;IAC7B,4CAA4C;IAC5C,kCAAmB,CAAA;IACnB,iCAAiC;IACjC,0CAA2B,CAAA;IAC3B,0CAA0C;IAC1C,2CAA4B,CAAA;IAC5B,6DAA6D;IAC7D,qDAAsC,CAAA;IACtC,uEAAuE;IACvE,wDAAyC,CAAA;IACzC,kEAAkE;IAClE,mDAAoC,CAAA;IACpC,2FAA2F;IAC3F,gDAAiC,CAAA;IACjC,kEAAkE;IAClE,mDAAoC,CAAA;AACtC,CAAC,EArBW,WAAW,KAAX,WAAW,QAqBtB"}

package/dist/workspace.d.ts

@@ -0,0 +1,126 @@
+/**
+ * A directory entry returned by workspace readdir.
+ */
+export interface WorkspaceEntry {
+    /** The entry name (not full path) */
+    name: string;
+    /** Whether this entry is a file */
+    isFile: boolean;
+    /** Whether this entry is a directory */
+    isDirectory: boolean;
+}
+/**
+ * Abstraction over file operations, enabling local filesystem,
+ * read-only (dry-run), and in-memory (testing) workspaces.
+ *
+ * All paths passed to workspace methods are relative to the workspace root.
+ * Implementations must handle path resolution internally.
+ *
+ * @example
+ * ```typescript
+ * // Local filesystem workspace
+ * const ws = new LocalWorkspace('source', '/project');
+ * const content = await ws.read('.cursor/rules/my-rule.mdc');
+ *
+ * // In-memory workspace for testing
+ * const mem = new MemoryWorkspace('test');
+ * await mem.write('file.md', '# Hello');
+ * const exists = await mem.exists('file.md'); // true
+ *
+ * // Read-only wrapper for dry-run
+ * const readOnly = new ReadOnlyWorkspace(ws);
+ * await readOnly.write('file.md', 'content'); // throws!
+ * ```
+ */
+export interface Workspace {
+    /** Unique identifier for this workspace */
+    readonly id: string;
+    /** The root path of the workspace (for path resolution and display) */
+    readonly root: string;
+    /**
+     * Resolve a relative path within this workspace to an absolute path.
+     * @param relativePath - Path relative to workspace root
+     * @returns Absolute path
+     */
+    resolve(relativePath: string): string;
+    /**
+     * Check if a path exists in this workspace.
+     * @param relativePath - Path relative to workspace root
+     * @returns true if the path exists
+     */
+    exists(relativePath: string): Promise<boolean>;
+    /**
+     * Read a file from this workspace.
+     * @param relativePath - Path relative to workspace root
+     * @returns File content as UTF-8 string
+     * @throws If the file does not exist
+     */
+    read(relativePath: string): Promise<string>;
+    /**
+     * Write a file to this workspace.
+     * Creates parent directories as needed.
+     * @param relativePath - Path relative to workspace root
+     * @param content - File content as UTF-8 string
+     * @throws If the workspace is read-only
+     */
+    write(relativePath: string, content: string): Promise<void>;
+    /**
+     * List entries in a directory.
+     * @param relativePath - Path relative to workspace root
+     * @returns Array of directory entries
+     * @throws If the directory does not exist
+     */
+    readdir(relativePath: string): Promise<WorkspaceEntry[]>;
+    /**
+     * Create a directory (and any missing parents).
+     * @param relativePath - Path relative to workspace root
+     */
+    mkdir(relativePath: string): Promise<void>;
+}
+/**
+ * Helper to extract the root path from a string or Workspace argument.
+ * Useful for plugins migrating to Workspace support.
+ *
+ * @param rootOrWorkspace - A string root path or Workspace instance
+ * @returns The root path string
+ */
+export declare function resolveRoot(rootOrWorkspace: string | Workspace): string;
+/**
+ * Workspace backed by the local filesystem.
+ *
+ * All operations delegate to Node.js fs/promises.
+ *
+ * @example
+ * ```typescript
+ * const ws = new LocalWorkspace('source', '/project');
+ * const content = await ws.read('.cursor/rules/my-rule.mdc');
+ * await ws.write('.claude/rules/my-rule.md', content);
+ * ```
+ */
+export declare class LocalWorkspace implements Workspace {
+    readonly id: string;
+    readonly root: string;
+    /**
+     * Create a new LocalWorkspace.
+     * @param id - Unique identifier for this workspace
+     * @param root - Absolute path to the workspace root directory
+     */
+    constructor(id: string, root: string);
+    resolve(relativePath: string): string;
+    exists(relativePath: string): Promise<boolean>;
+    read(relativePath: string): Promise<string>;
+    write(relativePath: string, content: string): Promise<void>;
+    readdir(relativePath: string): Promise<WorkspaceEntry[]>;
+    mkdir(relativePath: string): Promise<void>;
+}
+/**
+ * Convert a string root path or Workspace instance to a Workspace.
+ * If given a string, wraps it in a LocalWorkspace with the given id.
+ * If given a Workspace, returns it unchanged.
+ *
+ * @param rootOrWorkspace - A string root path or Workspace instance
+ * @param id - Workspace id to use when wrapping a string (default: 'default')
+ * @returns A Workspace instance
+ */
+export declare function toWorkspace(rootOrWorkspace: string | Workspace, id?: string): Workspace;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtC;;;;OAIG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;;;;OAKG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEzD;;;OAGG;IACH,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,YAAW,SAAS;aAO5B,EAAE,EAAE,MAAM;aACV,IAAI,EAAE,MAAM;IAP9B;;;;OAIG;gBAEe,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM;IAG9B,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAK/B,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS9C,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3C,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IASxD,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,GAAE,MAAkB,GAAG,SAAS,CAKlG"}

package/dist/workspace.js

@@ -0,0 +1,86 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+/**
+ * Helper to extract the root path from a string or Workspace argument.
+ * Useful for plugins migrating to Workspace support.
+ *
+ * @param rootOrWorkspace - A string root path or Workspace instance
+ * @returns The root path string
+ */
+export function resolveRoot(rootOrWorkspace) {
+    return typeof rootOrWorkspace === 'string' ? rootOrWorkspace : rootOrWorkspace.root;
+}
+/**
+ * Workspace backed by the local filesystem.
+ *
+ * All operations delegate to Node.js fs/promises.
+ *
+ * @example
+ * ```typescript
+ * const ws = new LocalWorkspace('source', '/project');
+ * const content = await ws.read('.cursor/rules/my-rule.mdc');
+ * await ws.write('.claude/rules/my-rule.md', content);
+ * ```
+ */
+export class LocalWorkspace {
+    id;
+    root;
+    /**
+     * Create a new LocalWorkspace.
+     * @param id - Unique identifier for this workspace
+     * @param root - Absolute path to the workspace root directory
+     */
+    constructor(id, root) {
+        this.id = id;
+        this.root = root;
+    }
+    resolve(relativePath) {
+        if (relativePath === '')
+            return this.root;
+        return path.join(this.root, relativePath);
+    }
+    async exists(relativePath) {
+        try {
+            await fs.access(this.resolve(relativePath));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async read(relativePath) {
+        return fs.readFile(this.resolve(relativePath), 'utf-8');
+    }
+    async write(relativePath, content) {
+        const fullPath = this.resolve(relativePath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, content, 'utf-8');
+    }
+    async readdir(relativePath) {
+        const dirents = await fs.readdir(this.resolve(relativePath), { withFileTypes: true });
+        return dirents.map((d) => ({
+            name: d.name,
+            isFile: d.isFile(),
+            isDirectory: d.isDirectory(),
+        }));
+    }
+    async mkdir(relativePath) {
+        await fs.mkdir(this.resolve(relativePath), { recursive: true });
+    }
+}
+/**
+ * Convert a string root path or Workspace instance to a Workspace.
+ * If given a string, wraps it in a LocalWorkspace with the given id.
+ * If given a Workspace, returns it unchanged.
+ *
+ * @param rootOrWorkspace - A string root path or Workspace instance
+ * @param id - Workspace id to use when wrapping a string (default: 'default')
+ * @returns A Workspace instance
+ */
+export function toWorkspace(rootOrWorkspace, id = 'default') {
+    if (typeof rootOrWorkspace === 'string') {
+        return new LocalWorkspace(id, rootOrWorkspace);
+    }
+    return rootOrWorkspace;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AA0FlC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,eAAmC;IAC7D,OAAO,OAAO,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC;AACtF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,cAAc;IAOP;IACA;IAPlB;;;;OAIG;IACH,YACkB,EAAU,EACV,IAAY;QADZ,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAQ;IAC3B,CAAC;IAEJ,OAAO,CAAC,YAAoB;QAC1B,IAAI,YAAY,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,YAAoB;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;YAC5C,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,YAAoB;QAC7B,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,YAAoB,EAAE,OAAe;QAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC5C,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,YAAoB;QAChC,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACtF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;YAClB,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE;SAC7B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,YAAoB;QAC9B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,eAAmC,EAAE,KAAa,SAAS;IACrF,IAAI,OAAO,eAAe,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,IAAI,cAAc,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a16njs/models",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Type definitions and plugin interface for a16n",
   "license": "AGPL-3.0",
   "author": "Texarkanine",