lua-cli 3.15.3 → 3.16.0

package/dist/compiler/plugins/base.d.ts

@@ -1,334 +0,0 @@
-/**
- * Plugin Base
- *
- * Contains:
- * - CompilationPlugin interface (contract)
- * - BasePlugin abstract class (common implementation)
- * - Helper functions
- *
- * Data types are in ../types.ts
- */
-import { SourceFile, Project, ObjectLiteralExpression } from 'ts-morph';
-import { PrimitiveKind, type PrimitiveMetadata, type CommonExtractedFields, type ValidationResult, type ValidationMessage, type SchemaSet, type BundledArtifact, type CompiledPrimitive, type ManifestPrimitive, type BaseMetadataFields } from '../types.js';
-/**
- * Context for resolving references between primitives.
- * Passed to plugins when they need to resolve dependencies.
- */
-export interface ReferenceResolverContext {
-    /** The ts-morph project for AST analysis */
-    project: Project;
-    /** Resolve an import specifier to absolute path */
-    resolveImportPath: (specifier: string, fromFile: string) => string | null;
-    /** Get a plugin by kind */
-    getPlugin: (kind: string) => CompilationPlugin | undefined;
-    /** Debug logging */
-    log: (message: string) => void;
-}
-/**
- * Plugin for compiling a specific primitive type.
- *
- * Implement this interface to add support for a new primitive.
- * Each method has a single responsibility:
- *
- * - detect: Find primitives in source files
- * - validate: Check for errors/warnings
- * - generateEntryPoint: Create the bundler entry point
- * - extractSchemas: Convert Zod → JSON Schema
- * - postProcess: Transform the bundled output
- */
-export interface CompilationPlugin {
-    /**
-     * Unique identifier matching the primitive's 'kind' property.
-     * Must match exactly what users write in their code.
-     */
-    readonly kind: string;
-    /**
-     * Human-readable name for CLI output and error messages.
-     */
-    readonly displayName: string;
-    /**
-     * The function name that creates this primitive (e.g., 'defineTool').
-     * Used for detection in source files.
-     */
-    readonly defineFunction: string;
-    /**
-     * Detect primitives of this type in a source file.
-     *
-     * Called once per source file during the scanning phase.
-     * Should be fast - don't do heavy processing here.
-     *
-     * @param sourceFile - The ts-morph source file to scan
-     * @returns Array of detected primitives
-     */
-    detect(sourceFile: SourceFile): PrimitiveMetadata[];
-    /**
-     * Validate extracted metadata.
-     *
-     * Called after detection. Return errors for things that prevent
-     * compilation, warnings for things that might be problems.
-     *
-     * @param metadata - The primitive metadata to validate
-     * @returns Validation result with errors and warnings
-     */
-    validate(metadata: PrimitiveMetadata): ValidationResult;
-    /**
-     * Generate the entry point code for bundling.
-     *
-     * This creates a wrapper that:
-     * 1. Imports the user's primitive
-     * 2. Re-exports it in a standard format
-     * 3. Includes runtime metadata
-     *
-     * @param metadata - The primitive metadata
-     * @returns TypeScript code for the entry point
-     */
-    generateEntryPoint(metadata: PrimitiveMetadata): string;
-    /**
-     * Extract schemas and convert to JSON Schema format.
-     *
-     * Called after detection. Uses ts-morph to evaluate Zod
-     * schemas in the source code.
-     *
-     * @param metadata - The primitive metadata
-     * @param project - The ts-morph project
-     * @returns Schema set or undefined if no schemas
-     */
-    extractSchemas?(metadata: PrimitiveMetadata, project: Project): Promise<SchemaSet | undefined>;
-    /**
-     * Post-process the bundled artifact.
-     *
-     * Called after esbuild bundling. Can add runtime wrappers,
-     * validation code, or other transformations.
-     *
-     * @param artifact - The bundled artifact
-     * @param metadata - The primitive metadata
-     * @returns Transformed artifact
-     */
-    postProcess?(artifact: BundledArtifact, metadata: PrimitiveMetadata): BundledArtifact;
-    /**
-     * Optional: produce the artifact directly, bypassing esbuild.
-     *
-     * For primitives whose artifact is never loaded at runtime for a given
-     * metadata shape. When this returns an artifact, the compiler skips
-     * `generateEntryPoint → bundler.bundle → postProcess → extractSchemas`
-     * for that primitive and uses the returned artifact as-is. Return
-     * `undefined` (or omit the method) to fall back to the default esbuild
-     * path — useful for conditional opt-outs.
-     *
-     * Current implementers:
-     * - `SkillPlugin` — unconditional; skills have no executable code and
-     *   `SkillHandler.prepareForPush()` only loads tool artifacts, never the
-     *   skill's own.
-     *
-     * Candidate extensions (implement conditionally):
-     * - `AgentPlugin` — when `!hasModelResolver` (static `model: 'gpt-4o'`).
-     *   `AgentHandler` skips `loadArtifact` in that case
-     *   (`agent.handler.ts:95-107`).
-     * - `MCPServerPlugin` — when `!hasUrlResolver && !hasHeadersResolver`
-     *   (static URL + static headers). `MCPServerHandler.loadBundledServers`
-     *   skips `loadArtifact` in that case (`mcp-server.handler.ts:67-68`).
-     *
-     * @param metadata - The primitive metadata
-     * @returns Artifact to use, `undefined` to fall back to esbuild, or a
-     *   Promise of either
-     */
-    buildArtifact?(metadata: PrimitiveMetadata): BundledArtifact | undefined | Promise<BundledArtifact | undefined>;
-    /**
-     * Create the manifest entry for this primitive.
-     *
-     * Each plugin knows what fields its manifest entry needs.
-     * This keeps primitive-specific logic in the plugins.
-     * May be async for plugins that need additional processing (e.g., bundling resolvers).
-     *
-     * @param compiled - The compiled primitive data
-     * @param allPrimitives - All compiled primitives (for cross-referencing, e.g., skill → tool name resolution)
-     * @returns The typed manifest entry for this primitive
-     */
-    toManifestEntry(compiled: CompiledPrimitive, allPrimitives?: CompiledPrimitive[]): ManifestPrimitive | Promise<ManifestPrimitive>;
-    /**
-     * Resolve references to other primitives.
-     *
-     * Some primitives reference others (e.g., Skills reference Tools).
-     * This method allows plugins to resolve those references and return
-     * the additional primitives that should be compiled.
-     *
-     * @param metadata - The primitive that may have references
-     * @param sourceFile - The source file containing the primitive
-     * @param context - Context for resolving imports and getting plugins
-     * @returns Array of referenced primitives, empty if none
-     */
-    resolveReferences?(metadata: PrimitiveMetadata, sourceFile: SourceFile, context: ReferenceResolverContext): PrimitiveMetadata[];
-    /**
-     * Sanitize the primitive's `metadata` payload before it is written to
-     * disk (artifact code, sidecar JSON, or anywhere else that ends up
-     * committed or uploaded). Defaults to a passthrough.
-     *
-     * Used to strip build-machine-specific fields that shouldn't leak
-     * into deliverables — e.g. `SkillPlugin` strips `toolRefSourcePaths`
-     * because those are absolute paths that break hash reproducibility
-     * and expose the developer's filesystem layout.
-     *
-     * Implementations MUST NOT mutate the input; return a new object.
-     */
-    sanitizeForPersistence?(metadata: PrimitiveMetadata['metadata']): PrimitiveMetadata['metadata'];
-}
-/**
- * Abstract base class for plugins with common implementation.
- *
- * Provides default implementations for:
- * - detect() - Function-based and class-based detection
- * - generateEntryPoint() - Universal import pattern
- * - postProcess() - Runtime validation wrapper
- * - extractSchemas() - Returns undefined (override for tools/webhooks)
- *
- * Subclasses must implement:
- * - kind, displayName, defineFunction, legacyClassNames
- * - extractFromConfig() - Extract primitive-specific fields
- * - validate() - Validation rules
- * - toManifestEntry() - Manifest entry creation
- *
- * Subclasses can optionally override:
- * - getEntryPointFields() - Add extra fields to __lua_primitive__
- * - getRuntimeValidation() - Add runtime checks in postProcess
- * - resolveReferences() - Resolve dependencies (skills → tools)
- */
-export declare abstract class BasePlugin<T extends BaseMetadataFields = BaseMetadataFields> implements CompilationPlugin {
-    /** Unique identifier for this primitive type */
-    abstract readonly kind: string;
-    /** Human-readable name for CLI output */
-    abstract readonly displayName: string;
-    /** Function name for detection (e.g., 'defineTool') */
-    abstract readonly defineFunction: string;
-    /** Legacy class names for constructor-based detection (e.g., ['LuaJob']) */
-    abstract readonly legacyClassNames: string[];
-    /**
-     * Detect primitives in a source file.
-     * Handles both function-based (defineX) and class-based (new LuaX) patterns.
-     */
-    detect(sourceFile: SourceFile): PrimitiveMetadata<T>[];
-    /**
-     * Detect function-based definitions (defineX pattern):
-     *
-     * Supported patterns:
-     * - const/let/var x = defineX({ ... })
-     * - export const/let/var x = defineX({ ... })
-     * - export default defineX({ ... })
-     */
-    protected detectFunctionBased(sourceFile: SourceFile, primitives: PrimitiveMetadata<T>[]): void;
-    /**
-     * Detect class-based definitions (new LuaX pattern):
-     *
-     * Supported patterns:
-     * - const/let/var x = new LuaX({ ... })
-     * - export const/let/var x = new LuaX({ ... })
-     * - export default new LuaX({ ... })
-     */
-    protected detectClassBased(sourceFile: SourceFile, primitives: PrimitiveMetadata<T>[]): void;
-    /**
-     * Helper to detect export default patterns.
-     * Works for both function-based (defineX) and class-based (new LuaX) patterns.
-     *
-     * Sets exportName='default' which causes extractCommonFields to set isDefaultExport=true.
-     */
-    private detectDefaultExport;
-    /**
-     * Extract metadata from config object literal.
-     * Subclasses implement this to extract primitive-specific fields.
-     *
-     * Common fields (name, description) can use extractCommonFields().
-     */
-    protected abstract extractFromConfig(config: ObjectLiteralExpression, exportName: string, sourcePath: string, position: {
-        line: number;
-        column: number;
-    }, pattern: 'function' | 'class'): PrimitiveMetadata<T> | null;
-    /**
-     * Helper to extract common fields (name, description) from config.
-     * Returns null if name is missing.
-     *
-     * Automatically sets `isDefaultExport: true` when `exportName === 'default'`.
-     */
-    protected extractCommonFields(config: ObjectLiteralExpression, exportName: string, sourcePath: string, position: {
-        line: number;
-        column: number;
-    }): CommonExtractedFields | null;
-    /**
-     * Common validation: name required (error), description recommended (warning).
-     * Subclasses call this first, then add type-specific checks to the returned arrays.
-     */
-    protected baseValidation(metadata: PrimitiveMetadata<T>): {
-        errors: ValidationMessage[];
-        warnings: ValidationMessage[];
-    };
-    abstract validate(metadata: PrimitiveMetadata<T>): ValidationResult;
-    /**
-     * Generate entry point code for bundling.
-     *
-     * Uses `import { __lua_target__ as X }` which is provided by the compiler's
-     * virtual source plugin. This works uniformly regardless of how the primitive
-     * is exported (default, named, or not exported at all).
-     */
-    generateEntryPoint(metadata: PrimitiveMetadata<T>): string;
-    /**
-     * Override to add extra fields to __lua_primitive__ object.
-     * Return a string like: `context: "some value",\n  tools: ["tool1"]`
-     */
-    protected getEntryPointFields(_metadata: PrimitiveMetadata<T>): string;
-    /**
-     * Extract schemas from the primitive.
-     * Override for primitives that have schemas (tools, webhooks).
-     */
-    extractSchemas(_metadata: PrimitiveMetadata<T>, _project: Project): Promise<SchemaSet | undefined>;
-    /**
-     * Default: return the metadata unchanged. Subclasses override to
-     * strip build-machine-specific fields (absolute paths, local-only
-     * lookup tables) that shouldn't appear in artifacts or sidecars.
-     *
-     * MUST be pure — no mutation of the input.
-     */
-    sanitizeForPersistence(metadata: PrimitiveMetadata['metadata']): PrimitiveMetadata['metadata'];
-    /**
-     * Post-process bundled artifact with runtime validation wrapper.
-     */
-    postProcess(artifact: BundledArtifact, metadata: PrimitiveMetadata<T>): BundledArtifact;
-    /**
-     * Override to add extra runtime validation in postProcess.
-     * Return JavaScript code to add to the validation IIFE.
-     */
-    protected getRuntimeValidation(_metadata: PrimitiveMetadata<T>): string;
-    /**
-     * Common manifest fields shared by ALL primitive types.
-     * Subclasses spread this and add type-specific fields.
-     */
-    protected baseManifestFields(compiled: CompiledPrimitive): {
-        kind: PrimitiveKind;
-        name: string;
-        description: string;
-        path: string;
-        sourcePath: string;
-        hash: string;
-    };
-    abstract toManifestEntry(compiled: CompiledPrimitive, allPrimitives?: CompiledPrimitive[]): ManifestPrimitive | Promise<ManifestPrimitive>;
-}
-/**
- * Creates a validation result with no errors or warnings.
- */
-export declare function validResult(): ValidationResult;
-/**
- * Creates a validation error.
- */
-export declare function validationError(message: string, options?: {
-    line?: number;
-    column?: number;
-    suggestion?: string;
-    docsUrl?: string;
-}): ValidationMessage;
-/**
- * Creates a validation warning.
- */
-export declare function validationWarning(message: string, options?: {
-    line?: number;
-    column?: number;
-    suggestion?: string;
-    docsUrl?: string;
-}): ValidationMessage;
-//# sourceMappingURL=base.d.ts.map

package/dist/compiler/plugins/base.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/compiler/plugins/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAQ,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAEL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAOrB;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC1E,2BAA2B;IAC3B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,iBAAiB,GAAG,SAAS,CAAC;IAC3D,oBAAoB;IACpB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAMD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,iBAAiB,EAAE,CAAC;IAEpD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAExD;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC;IAExD;;;;;;;;;OASG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IAE/F;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,GAAG,eAAe,CAAC;IAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,iBAAiB,GAAG,eAAe,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;IAEhH;;;;;;;;;;OAUG;IACH,eAAe,CACb,QAAQ,EAAE,iBAAiB,EAC3B,aAAa,CAAC,EAAE,iBAAiB,EAAE,GAClC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,CAChB,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,EAAE,CAAC;IAEvB;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;CACjG;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8BAAsB,UAAU,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CAAE,YAAW,iBAAiB;IAC9G,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAE/B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEzC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAM7C;;;OAGG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,iBAAiB,CAAC,CAAC,CAAC,EAAE;IAYtD;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IAiC/F;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI;IA0C5F;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAClC,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,EAAE,UAAU,GAAG,OAAO,GAC5B,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAE9B;;;;;OAKG;IACH,SAAS,CAAC,mBAAmB,CAC3B,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GACzC,qBAAqB,GAAG,IAAI;IAmB/B;;;OAGG;IACH,SAAS,CAAC,cAAc,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG;QACxD,MAAM,EAAE,iBAAiB,EAAE,CAAC;QAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;KAC/B;IAYD,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,gBAAgB;IAMnE;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM;IAkC1D;;;OAGG;IACH,SAAS,CAAC,mBAAmB,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM;IAQtE;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAQxG;;;;;;OAMG;IACH,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAAC,UAAU,CAAC;IAI9F;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,eAAe;IAgCvF;;;OAGG;IACH,SAAS,CAAC,oBAAoB,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM;IAQvE;;;OAGG;IACH,SAAS,CAAC,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB;cAEjC,aAAa;;;;;;;IASpC,QAAQ,CAAC,eAAe,CACtB,QAAQ,EAAE,iBAAiB,EAC3B,aAAa,CAAC,EAAE,iBAAiB,EAAE,GAClC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAClD;AAMD;;GAEG;AACH,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAClF,iBAAiB,CAEnB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAClF,iBAAiB,CAEnB"}