@a16njs/engine 0.4.0 → 0.6.0

package/dist/plugin-discovery.js

@@ -0,0 +1,161 @@
+import * as fs from 'fs/promises';
+import { statSync } from 'fs';
+import * as path from 'path';
+import { pathToFileURL, fileURLToPath } from 'url';
+/** Pattern used to match plugin package directory names. */
+const PLUGIN_PREFIX = 'a16n-plugin-';
+/**
+ * Scan search paths for installed `a16n-plugin-*` packages, dynamically import
+ * each one, validate its default export, and return the valid plugins along
+ * with error info for any that failed.
+ *
+ * @param options - Optional search path overrides
+ * @returns Discovered plugins and any load errors
+ */
+export async function discoverInstalledPlugins(options) {
+    const searchPaths = options?.searchPaths ?? getDefaultSearchPaths();
+    const plugins = [];
+    const errors = [];
+    const seenPluginIds = new Set();
+    for (const searchPath of searchPaths) {
+        // Read directory entries; skip if path doesn't exist
+        let entries;
+        try {
+            entries = await fs.readdir(searchPath);
+        }
+        catch {
+            // Non-existent or unreadable path — skip silently
+            continue;
+        }
+        // Filter for directories matching the plugin naming convention
+        const pluginDirs = entries.filter((name) => name.startsWith(PLUGIN_PREFIX));
+        for (const dirName of pluginDirs) {
+            const pkgPath = path.join(searchPath, dirName);
+            try {
+                // Resolve entry point from package.json main field, falling back to index.js
+                const entryFile = await resolvePluginEntry(pkgPath);
+                const moduleUrl = pathToFileURL(entryFile).href;
+                const mod = await import(moduleUrl);
+                // Extract default export (handles both `export default` and CJS interop)
+                const candidate = mod.default ?? mod;
+                if (isValidPlugin(candidate)) {
+                    if (seenPluginIds.has(candidate.id)) {
+                        errors.push({
+                            packageName: dirName,
+                            error: `Duplicate plugin id: ${candidate.id} — already discovered`,
+                        });
+                    }
+                    else {
+                        seenPluginIds.add(candidate.id);
+                        plugins.push(candidate);
+                    }
+                }
+                else {
+                    errors.push({
+                        packageName: dirName,
+                        error: `Invalid plugin export: missing or incorrect required fields (id, name, supports, discover, emit)`,
+                    });
+                }
+            }
+            catch (err) {
+                errors.push({
+                    packageName: dirName,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    return { plugins, errors };
+}
+/**
+ * Resolve the JavaScript entry point for a plugin package directory.
+ *
+ * Reads the `main` field from the package's `package.json` if it exists,
+ * otherwise falls back to `index.js` at the package root.
+ *
+ * @param pkgPath - Absolute path to the plugin package directory
+ * @returns Absolute path to the entry JavaScript file
+ */
+async function resolvePluginEntry(pkgPath) {
+    try {
+        const raw = await fs.readFile(path.join(pkgPath, 'package.json'), 'utf-8');
+        const pkg = JSON.parse(raw);
+        if (typeof pkg.main === 'string' && pkg.main.length > 0) {
+            return path.resolve(pkgPath, pkg.main);
+        }
+    }
+    catch {
+        // No package.json or unreadable — fall through to default
+    }
+    return path.join(pkgPath, 'index.js');
+}
+/**
+ * Type-guard that checks whether an unknown value satisfies the A16nPlugin interface.
+ *
+ * Validates presence and types of: id (string), name (string), supports (array),
+ * discover (function), emit (function).
+ *
+ * @param obj - The value to check
+ * @returns True if obj is a valid A16nPlugin
+ */
+export function isValidPlugin(obj) {
+    if (obj == null || typeof obj !== 'object') {
+        return false;
+    }
+    const candidate = obj;
+    return (typeof candidate.id === 'string' &&
+        typeof candidate.name === 'string' &&
+        Array.isArray(candidate.supports) &&
+        typeof candidate.discover === 'function' &&
+        typeof candidate.emit === 'function');
+}
+/**
+ * Compute the default search paths for plugin discovery.
+ *
+ * Returns paths where `a16n-plugin-*` packages might be installed:
+ * - The global npm `node_modules` directory (derived from this package's location)
+ * - The local `node_modules` in the current working directory
+ *
+ * In a global install, the engine lives inside node_modules:
+ *   .../lib/node_modules/@a16njs/engine/dist/plugin-discovery.js
+ * so walking up finds the node_modules parent directly.
+ *
+ * In a monorepo (e.g. pnpm workspace), the engine lives at:
+ *   <root>/packages/engine/dist/plugin-discovery.js
+ * so we also check for a node_modules child directory at each level.
+ *
+ * @returns Array of directory paths to scan
+ */
+export function getDefaultSearchPaths() {
+    const paths = [];
+    const thisFile = fileURLToPath(import.meta.url);
+    let dir = path.dirname(thisFile);
+    while (dir !== path.dirname(dir)) {
+        // Global install: this file is inside a node_modules tree
+        if (path.basename(dir) === 'node_modules') {
+            paths.push(dir);
+            break;
+        }
+        // Monorepo / local dev: check for a sibling node_modules directory.
+        // Don't stop — keep walking up to find all ancestor node_modules
+        // (e.g. packages/engine/node_modules AND root/node_modules).
+        const siblingNodeModules = path.join(dir, 'node_modules');
+        try {
+            const stat = statSync(siblingNodeModules);
+            if (stat.isDirectory()) {
+                paths.push(siblingNodeModules);
+            }
+        }
+        catch {
+            // Directory doesn't exist, keep walking
+        }
+        dir = path.dirname(dir);
+    }
+    // Local node_modules in cwd
+    const localNodeModules = path.join(process.cwd(), 'node_modules');
+    if (!paths.includes(localNodeModules)) {
+        paths.push(localNodeModules);
+    }
+    return paths;
+}
+//# sourceMappingURL=plugin-discovery.js.map

package/dist/plugin-discovery.js.map

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

package/dist/plugin-loader.d.ts

@@ -0,0 +1,96 @@
+import type { A16nPlugin } from '@a16njs/models';
+import type { PluginRegistrationInput } from './plugin-registry.js';
+import { PluginRegistry } from './plugin-registry.js';
+import { type PluginDiscoveryOptions } from './plugin-discovery.js';
+/**
+ * Strategy for resolving conflicts when a discovered plugin has the
+ * same ID as an already-registered plugin.
+ */
+export declare enum PluginConflictStrategy {
+    /** Keep the existing (bundled) plugin, skip the discovered one. This is the default and matches current behavior. */
+    PREFER_BUNDLED = "prefer-bundled",
+    /** Replace the existing plugin with the discovered (installed) one. */
+    PREFER_INSTALLED = "prefer-installed",
+    /** Throw an error when a conflict is detected. */
+    FAIL = "fail"
+}
+/**
+ * Information about a plugin that was skipped during conflict resolution.
+ */
+export interface SkippedPlugin {
+    /** The plugin that was skipped */
+    plugin: A16nPlugin;
+    /** Human-readable reason for skipping */
+    reason: string;
+    /** ID of the plugin it conflicted with */
+    conflictsWith: string;
+}
+/**
+ * Result of loading and resolving plugins.
+ */
+export interface PluginLoadResult {
+    /** Plugins that passed conflict resolution and are ready for registration */
+    loaded: PluginRegistrationInput[];
+    /** Plugins that were skipped due to conflicts */
+    skipped: SkippedPlugin[];
+    /** Errors encountered during discovery */
+    errors: Array<{
+        packageName: string;
+        error: string;
+    }>;
+}
+/**
+ * Orchestrates plugin loading by coordinating discovery and conflict
+ * resolution as separate, testable phases.
+ *
+ * Separates three distinct concerns:
+ * 1. **Discovery** - Finding plugins in node_modules (delegated to discoverInstalledPlugins)
+ * 2. **Conflict Resolution** - Deciding what to do when discovered plugins conflict with existing ones
+ * 3. **Registration** - Adding resolved plugins to the registry (done by the caller)
+ *
+ * @example
+ * ```typescript
+ * const loader = new PluginLoader(PluginConflictStrategy.PREFER_BUNDLED);
+ * const candidates = await loader.loadInstalled({ searchPaths: ['/path/to/node_modules'] });
+ * const resolved = loader.resolveConflicts(registry, candidates);
+ * for (const reg of resolved.loaded) {
+ *   registry.register(reg);
+ * }
+ * ```
+ */
+export declare class PluginLoader {
+    private readonly _conflictStrategy;
+    /**
+     * Create a new PluginLoader with the given conflict resolution strategy.
+     *
+     * @param conflictStrategy - How to handle plugin ID conflicts (default: PREFER_BUNDLED)
+     */
+    constructor(_conflictStrategy?: PluginConflictStrategy);
+    /**
+     * The conflict resolution strategy in use.
+     */
+    get conflictStrategy(): PluginConflictStrategy;
+    /**
+     * Discover installed plugins from node_modules and wrap them
+     * as PluginRegistrationInput candidates with source='installed'.
+     *
+     * This is Phase 1 (Discovery) of the loading pipeline.
+     *
+     * @param options - Plugin discovery options (search paths, etc.)
+     * @returns Load result with candidates ready for conflict resolution
+     */
+    loadInstalled(options?: PluginDiscoveryOptions): Promise<PluginLoadResult>;
+    /**
+     * Resolve conflicts between discovered plugin candidates and
+     * already-registered plugins using the configured strategy.
+     *
+     * This is Phase 2 (Conflict Resolution) of the loading pipeline.
+     * Pure function: does not modify the registry.
+     *
+     * @param existing - The current plugin registry to check for conflicts
+     * @param candidates - The load result from loadInstalled()
+     * @returns Resolved load result with loaded (ready to register) and skipped plugins
+     */
+    resolveConflicts(existing: PluginRegistry, candidates: PluginLoadResult): PluginLoadResult;
+}
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../src/plugin-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAsB,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,oBAAY,sBAAsB;IAChC,qHAAqH;IACrH,cAAc,mBAAmB;IACjC,uEAAuE;IACvE,gBAAgB,qBAAqB;IACrC,kDAAkD;IAClD,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,MAAM,EAAE,UAAU,CAAC;IACnB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,iDAAiD;IACjD,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,0CAA0C;IAC1C,MAAM,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IANpC;;;;OAIG;gBAEgB,iBAAiB,GAAE,sBAA8D;IAGpG;;OAEG;IACH,IAAI,gBAAgB,IAAI,sBAAsB,CAE7C;IAED;;;;;;;;OAQG;IACG,aAAa,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAahF;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,GAAG,gBAAgB;CAoC3F"}

package/dist/plugin-loader.js

@@ -0,0 +1,112 @@
+import { discoverInstalledPlugins, } from './plugin-discovery.js';
+/**
+ * Strategy for resolving conflicts when a discovered plugin has the
+ * same ID as an already-registered plugin.
+ */
+export var PluginConflictStrategy;
+(function (PluginConflictStrategy) {
+    /** Keep the existing (bundled) plugin, skip the discovered one. This is the default and matches current behavior. */
+    PluginConflictStrategy["PREFER_BUNDLED"] = "prefer-bundled";
+    /** Replace the existing plugin with the discovered (installed) one. */
+    PluginConflictStrategy["PREFER_INSTALLED"] = "prefer-installed";
+    /** Throw an error when a conflict is detected. */
+    PluginConflictStrategy["FAIL"] = "fail";
+})(PluginConflictStrategy || (PluginConflictStrategy = {}));
+/**
+ * Orchestrates plugin loading by coordinating discovery and conflict
+ * resolution as separate, testable phases.
+ *
+ * Separates three distinct concerns:
+ * 1. **Discovery** - Finding plugins in node_modules (delegated to discoverInstalledPlugins)
+ * 2. **Conflict Resolution** - Deciding what to do when discovered plugins conflict with existing ones
+ * 3. **Registration** - Adding resolved plugins to the registry (done by the caller)
+ *
+ * @example
+ * ```typescript
+ * const loader = new PluginLoader(PluginConflictStrategy.PREFER_BUNDLED);
+ * const candidates = await loader.loadInstalled({ searchPaths: ['/path/to/node_modules'] });
+ * const resolved = loader.resolveConflicts(registry, candidates);
+ * for (const reg of resolved.loaded) {
+ *   registry.register(reg);
+ * }
+ * ```
+ */
+export class PluginLoader {
+    _conflictStrategy;
+    /**
+     * Create a new PluginLoader with the given conflict resolution strategy.
+     *
+     * @param conflictStrategy - How to handle plugin ID conflicts (default: PREFER_BUNDLED)
+     */
+    constructor(_conflictStrategy = PluginConflictStrategy.PREFER_BUNDLED) {
+        this._conflictStrategy = _conflictStrategy;
+    }
+    /**
+     * The conflict resolution strategy in use.
+     */
+    get conflictStrategy() {
+        return this._conflictStrategy;
+    }
+    /**
+     * Discover installed plugins from node_modules and wrap them
+     * as PluginRegistrationInput candidates with source='installed'.
+     *
+     * This is Phase 1 (Discovery) of the loading pipeline.
+     *
+     * @param options - Plugin discovery options (search paths, etc.)
+     * @returns Load result with candidates ready for conflict resolution
+     */
+    async loadInstalled(options) {
+        const discovered = await discoverInstalledPlugins(options);
+        return {
+            loaded: discovered.plugins.map((plugin) => ({
+                plugin,
+                source: 'installed',
+            })),
+            skipped: [],
+            errors: discovered.errors,
+        };
+    }
+    /**
+     * Resolve conflicts between discovered plugin candidates and
+     * already-registered plugins using the configured strategy.
+     *
+     * This is Phase 2 (Conflict Resolution) of the loading pipeline.
+     * Pure function: does not modify the registry.
+     *
+     * @param existing - The current plugin registry to check for conflicts
+     * @param candidates - The load result from loadInstalled()
+     * @returns Resolved load result with loaded (ready to register) and skipped plugins
+     */
+    resolveConflicts(existing, candidates) {
+        const loaded = [];
+        const skipped = [...candidates.skipped];
+        for (const candidate of candidates.loaded) {
+            const existingReg = existing.get(candidate.plugin.id);
+            if (!existingReg) {
+                loaded.push(candidate);
+                continue;
+            }
+            switch (this._conflictStrategy) {
+                case PluginConflictStrategy.PREFER_BUNDLED:
+                    skipped.push({
+                        plugin: candidate.plugin,
+                        reason: `Conflict: ${existingReg.source} plugin '${existingReg.plugin.id}' already registered`,
+                        conflictsWith: candidate.plugin.id,
+                    });
+                    break;
+                case PluginConflictStrategy.PREFER_INSTALLED:
+                    loaded.push(candidate);
+                    break;
+                case PluginConflictStrategy.FAIL:
+                    throw new Error(`Plugin conflict: '${candidate.plugin.id}' is already registered`);
+            }
+        }
+        return {
+            loaded,
+            skipped,
+            errors: candidates.errors,
+        };
+    }
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/plugin-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.js","sourceRoot":"","sources":["../src/plugin-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,wBAAwB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAN,IAAY,sBAOX;AAPD,WAAY,sBAAsB;IAChC,qHAAqH;IACrH,2DAAiC,CAAA;IACjC,uEAAuE;IACvE,+DAAqC,CAAA;IACrC,kDAAkD;IAClD,uCAAa,CAAA;AACf,CAAC,EAPW,sBAAsB,KAAtB,sBAAsB,QAOjC;AA0BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,YAAY;IAOJ;IANnB;;;;OAIG;IACH,YACmB,oBAA4C,sBAAsB,CAAC,cAAc;QAAjF,sBAAiB,GAAjB,iBAAiB,CAAgE;IACjG,CAAC;IAEJ;;OAEG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAa,CAAC,OAAgC;QAClD,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAE3D,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC1C,MAAM;gBACN,MAAM,EAAE,WAAoB;aAC7B,CAAC,CAAC;YACH,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,QAAwB,EAAE,UAA4B;QACrE,MAAM,MAAM,GAA8B,EAAE,CAAC;QAC7C,MAAM,OAAO,GAAoB,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QAEzD,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAEtD,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACvB,SAAS;YACX,CAAC;YAED,QAAQ,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAC/B,KAAK,sBAAsB,CAAC,cAAc;oBACxC,OAAO,CAAC,IAAI,CAAC;wBACX,MAAM,EAAE,SAAS,CAAC,MAAM;wBACxB,MAAM,EAAE,aAAa,WAAW,CAAC,MAAM,YAAY,WAAW,CAAC,MAAM,CAAC,EAAE,sBAAsB;wBAC9F,aAAa,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE;qBACnC,CAAC,CAAC;oBACH,MAAM;gBAER,KAAK,sBAAsB,CAAC,gBAAgB;oBAC1C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACvB,MAAM;gBAER,KAAK,sBAAsB,CAAC,IAAI;oBAC9B,MAAM,IAAI,KAAK,CAAC,qBAAqB,SAAS,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC,CAAC;YACvF,CAAC;QACH,CAAC;QAED,OAAO;YACL,MAAM;YACN,OAAO;YACP,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC;CACF"}

package/dist/plugin-registry.d.ts

@@ -0,0 +1,94 @@
+import type { A16nPlugin } from '@a16njs/models';
+/**
+ * Full metadata for a registered plugin.
+ * Wraps the plugin instance with registration metadata such as
+ * source (bundled vs installed), registration timestamp, and
+ * optional diagnostic information.
+ */
+export interface PluginRegistration {
+    /** The plugin instance */
+    plugin: A16nPlugin;
+    /** Whether this plugin was bundled with the engine or installed from node_modules */
+    source: 'bundled' | 'installed';
+    /** When this plugin was registered */
+    registeredAt: Date;
+    /** Semantic version of the installed plugin (for installed plugins) */
+    version?: string;
+    /** Filesystem path where the plugin was installed from (for diagnostics) */
+    installPath?: string;
+}
+/**
+ * Input for registering a plugin. Omits `registeredAt` which is
+ * automatically set by the registry.
+ */
+export type PluginRegistrationInput = Omit<PluginRegistration, 'registeredAt'>;
+/**
+ * Unified plugin registry that serves as the single source of truth
+ * for all plugin metadata. Replaces the dual-Map pattern
+ * (plugins Map + pluginSources Map) with a single registry that
+ * tracks all plugin information in one place.
+ *
+ * @example
+ * ```typescript
+ * const registry = new PluginRegistry();
+ * registry.register({ plugin: cursorPlugin, source: 'bundled' });
+ * registry.register({ plugin: claudePlugin, source: 'installed', version: '1.0.0' });
+ *
+ * const cursor = registry.getPlugin('cursor');
+ * const installed = registry.listBySource('installed');
+ * ```
+ */
+export declare class PluginRegistry {
+    private registrations;
+    /**
+     * Register a plugin with the registry.
+     * If a plugin with the same ID is already registered, it will be overwritten.
+     *
+     * @param input - Plugin and metadata to register (registeredAt is set automatically)
+     */
+    register(input: PluginRegistrationInput): void;
+    /**
+     * Get the full registration for a plugin by its ID.
+     *
+     * @param id - The plugin ID to look up
+     * @returns The full PluginRegistration, or undefined if not found
+     */
+    get(id: string): PluginRegistration | undefined;
+    /**
+     * Get just the plugin instance by its ID.
+     * Convenience method equivalent to `registry.get(id)?.plugin`.
+     *
+     * @param id - The plugin ID to look up
+     * @returns The A16nPlugin instance, or undefined if not found
+     */
+    getPlugin(id: string): A16nPlugin | undefined;
+    /**
+     * Check whether a plugin with the given ID is registered.
+     *
+     * @param id - The plugin ID to check
+     * @returns true if the plugin is registered, false otherwise
+     */
+    has(id: string): boolean;
+    /**
+     * List all plugin registrations.
+     *
+     * @returns Array of all PluginRegistration objects in insertion order
+     */
+    list(): PluginRegistration[];
+    /**
+     * List plugin registrations filtered by source.
+     *
+     * @param source - The source to filter by ('bundled' or 'installed')
+     * @returns Array of matching PluginRegistration objects
+     */
+    listBySource(source: 'bundled' | 'installed'): PluginRegistration[];
+    /**
+     * The number of registered plugins.
+     */
+    get size(): number;
+    /**
+     * Remove all plugin registrations.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,qFAAqF;IACrF,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,sCAAsC;IACtC,YAAY,EAAE,IAAI,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,aAAa,CAA8C;IAEnE;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI;IAO9C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI/C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;OAIG;IACH,IAAI,IAAI,kBAAkB,EAAE;IAI5B;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,kBAAkB,EAAE;IAInE;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/plugin-registry.js

@@ -0,0 +1,89 @@
+/**
+ * Unified plugin registry that serves as the single source of truth
+ * for all plugin metadata. Replaces the dual-Map pattern
+ * (plugins Map + pluginSources Map) with a single registry that
+ * tracks all plugin information in one place.
+ *
+ * @example
+ * ```typescript
+ * const registry = new PluginRegistry();
+ * registry.register({ plugin: cursorPlugin, source: 'bundled' });
+ * registry.register({ plugin: claudePlugin, source: 'installed', version: '1.0.0' });
+ *
+ * const cursor = registry.getPlugin('cursor');
+ * const installed = registry.listBySource('installed');
+ * ```
+ */
+export class PluginRegistry {
+    registrations = new Map();
+    /**
+     * Register a plugin with the registry.
+     * If a plugin with the same ID is already registered, it will be overwritten.
+     *
+     * @param input - Plugin and metadata to register (registeredAt is set automatically)
+     */
+    register(input) {
+        this.registrations.set(input.plugin.id, {
+            ...input,
+            registeredAt: new Date(),
+        });
+    }
+    /**
+     * Get the full registration for a plugin by its ID.
+     *
+     * @param id - The plugin ID to look up
+     * @returns The full PluginRegistration, or undefined if not found
+     */
+    get(id) {
+        return this.registrations.get(id);
+    }
+    /**
+     * Get just the plugin instance by its ID.
+     * Convenience method equivalent to `registry.get(id)?.plugin`.
+     *
+     * @param id - The plugin ID to look up
+     * @returns The A16nPlugin instance, or undefined if not found
+     */
+    getPlugin(id) {
+        return this.registrations.get(id)?.plugin;
+    }
+    /**
+     * Check whether a plugin with the given ID is registered.
+     *
+     * @param id - The plugin ID to check
+     * @returns true if the plugin is registered, false otherwise
+     */
+    has(id) {
+        return this.registrations.has(id);
+    }
+    /**
+     * List all plugin registrations.
+     *
+     * @returns Array of all PluginRegistration objects in insertion order
+     */
+    list() {
+        return Array.from(this.registrations.values());
+    }
+    /**
+     * List plugin registrations filtered by source.
+     *
+     * @param source - The source to filter by ('bundled' or 'installed')
+     * @returns Array of matching PluginRegistration objects
+     */
+    listBySource(source) {
+        return this.list().filter((r) => r.source === source);
+    }
+    /**
+     * The number of registered plugins.
+     */
+    get size() {
+        return this.registrations.size;
+    }
+    /**
+     * Remove all plugin registrations.
+     */
+    clear() {
+        this.registrations.clear();
+    }
+}
+//# sourceMappingURL=plugin-registry.js.map

package/dist/plugin-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.js","sourceRoot":"","sources":["../src/plugin-registry.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,cAAc;IACjB,aAAa,GAAoC,IAAI,GAAG,EAAE,CAAC;IAEnE;;;;;OAKG;IACH,QAAQ,CAAC,KAA8B;QACrC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE;YACtC,GAAG,KAAK;YACR,YAAY,EAAE,IAAI,IAAI,EAAE;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,MAA+B;QAC1C,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF"}

package/dist/transformation.d.ts

@@ -0,0 +1,93 @@
+import type { AgentCustomization, A16nPlugin, EmitResult, Warning } from '@a16njs/models';
+/**
+ * Context provided to a content transformation during the conversion pipeline.
+ */
+export interface TransformationContext {
+    /** The items to transform */
+    items: AgentCustomization[];
+    /** The source plugin */
+    sourcePlugin: A16nPlugin;
+    /** The target plugin */
+    targetPlugin: A16nPlugin;
+    /** Root directory for source (discovery) */
+    sourceRoot: string;
+    /** Root directory for target (emission) */
+    targetRoot: string;
+    /**
+     * Perform a trial emission (dry-run) to discover file mapping.
+     * Only available when dryRun is false; stateful transformations
+     * like path rewriting use this to know target paths without
+     * actually writing files.
+     */
+    trialEmit: (items: AgentCustomization[]) => Promise<EmitResult>;
+}
+/**
+ * Result of applying a content transformation.
+ */
+export interface TransformationResult {
+    /** The transformed items */
+    items: AgentCustomization[];
+    /** Warnings produced by this transformation */
+    warnings: Warning[];
+}
+/**
+ * A composable content transformation in the conversion pipeline.
+ *
+ * Transformations receive discovered items and produce transformed items.
+ * They run in sequence between discovery and final emission, enabling
+ * composable, extensible processing without double emission.
+ *
+ * @example
+ * ```typescript
+ * const transform: ContentTransformation = {
+ *   id: 'path-rewriting',
+ *   name: 'Path Reference Rewriting',
+ *   transform: async (context) => {
+ *     // Transform items...
+ *     return { items: transformedItems, warnings: [] };
+ *   },
+ * };
+ * ```
+ */
+export interface ContentTransformation {
+    /** Unique identifier for this transformation */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /**
+     * Apply this transformation to the items.
+     * @param context - The transformation context with items, plugins, and trial emit
+     * @returns Transformed items and any warnings
+     */
+    transform(context: TransformationContext): Promise<TransformationResult>;
+}
+/**
+ * Path rewriting transformation.
+ *
+ * Rewrites file path references in content during format conversion.
+ * Uses a trial emission to discover the source-to-target path mapping,
+ * then rewrites all path references in content. Also detects orphan
+ * references (paths that weren't converted) using plugin-provided
+ * path patterns.
+ *
+ * This replaces the hardcoded path rewriting logic that was previously
+ * embedded in the engine's convert() method, eliminating the need for
+ * double emission and removing hardcoded plugin knowledge.
+ *
+ * @example
+ * ```typescript
+ * const transform = new PathRewritingTransformation();
+ * engine.convert({
+ *   source: 'cursor',
+ *   target: 'claude',
+ *   root: '/project',
+ *   transformations: [transform],
+ * });
+ * ```
+ */
+export declare class PathRewritingTransformation implements ContentTransformation {
+    readonly id = "path-rewriting";
+    readonly name = "Path Reference Rewriting";
+    transform(context: TransformationContext): Promise<TransformationResult>;
+}
+//# sourceMappingURL=transformation.d.ts.map