lua-cli 3.5.0-alpha.3 → 3.5.0-beta.1

package/dist/compiler/index.js

@@ -0,0 +1,42 @@
+/**
+ * @lua/compiler - Compiler for Lua AI agent primitives
+ *
+ * This package provides the compilation infrastructure for Lua agents.
+ * It transforms TypeScript source code into optimized, sandboxed artifacts.
+ *
+ * @example
+ * ```typescript
+ * import { compile } from '@lua/compiler';
+ *
+ * const result = await compile({
+ *   rootDir: process.cwd(),
+ *   outDir: 'dist',
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Compiled ${result.stats.totalPrimitives} primitives`);
+ * }
+ * ```
+ */
+// Main compiler
+export { Compiler, compile } from './compiler.js';
+// Plugin system
+export { pluginRegistry, PluginRegistry, getAllDefineFunctions, getPluginByDefineFunction, } from './plugins/registry.js';
+// Helper functions
+export { validResult, validationError, validationWarning, } from './plugins/base.js';
+// Built-in plugins
+export { ToolPlugin } from './plugins/tool.plugin.js';
+export { JobPlugin } from './plugins/job.plugin.js';
+export { WebhookPlugin } from './plugins/webhook.plugin.js';
+export { PreProcessorPlugin } from './plugins/preprocessor.plugin.js';
+export { PostProcessorPlugin } from './plugins/postprocessor.plugin.js';
+export { MCPServerPlugin } from './plugins/mcp-server.plugin.js';
+export { SkillPlugin } from './plugins/skill.plugin.js';
+// Utilities
+export { extractStringProperty, extractBooleanProperty, extractNumberProperty, extractObjectProperty, extractSchemaProperty, hasProperty, getPropertyNames, isFunction, getFunctionBody, findImportSource, } from './utils/ast-helpers.js';
+export { zodToJsonSchema, zodStringToJsonSchema, } from './utils/schema-converter.js';
+// Source writing (generic + convenience)
+export { updateAgentConfig, setAgentName, setAgentPersona, } from './source-writer.js';
+// File discovery
+export { findEntryPoint, findIndexFile, getEntryPointPriority, } from './utils/file-discovery.js';
+//# sourceMappingURL=index.js.map

package/dist/compiler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gBAAgB;AAChB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAqDlD,gBAAgB;AAChB,OAAO,EACL,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,eAAe,EACf,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,mBAAmB;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,YAAY;AACZ,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,eAAe,EACf,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAErC,yCAAyC;AACzC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAEhB,MAAM,oBAAoB,CAAC;AAE5B,iBAAiB;AACjB,OAAO,EACL,cAAc,EACd,aAAa,EACb,qBAAqB,GACtB,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,264 @@
+/**
+ * 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 type { PrimitiveMetadata, CommonExtractedFields, ValidationResult, ValidationMessage, SchemaSet, BundledArtifact, CompiledPrimitive, ManifestPrimitive, ManifestContext, 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;
+    /**
+     * 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 context - Additional context (e.g., agent primitives, output directory)
+     * @returns The typed manifest entry for this primitive
+     */
+    toManifestEntry(compiled: CompiledPrimitive, context?: ManifestContext): 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[];
+}
+/**
+ * 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;
+    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>;
+    /**
+     * 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;
+    abstract toManifestEntry(compiled: CompiledPrimitive, context?: ManifestContext): 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;

package/dist/compiler/plugins/base.js

@@ -0,0 +1,307 @@
+/**
+ * Plugin Base
+ *
+ * Contains:
+ * - CompilationPlugin interface (contract)
+ * - BasePlugin abstract class (common implementation)
+ * - Helper functions
+ *
+ * Data types are in ../types.ts
+ */
+import { Node } from 'ts-morph';
+import { extractStringProperty } from '../utils/ast-helpers.js';
+// =============================================================================
+// BASE PLUGIN ABSTRACT CLASS
+// =============================================================================
+/**
+ * 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 class BasePlugin {
+    // ===========================================================================
+    // DETECTION (common implementation)
+    // ===========================================================================
+    /**
+     * Detect primitives in a source file.
+     * Handles both function-based (defineX) and class-based (new LuaX) patterns.
+     */
+    detect(sourceFile) {
+        const primitives = [];
+        // Pattern 1: Function-based - defineX({ ... })
+        this.detectFunctionBased(sourceFile, primitives);
+        // Pattern 2: Class-based - new LuaX({ ... })
+        this.detectClassBased(sourceFile, primitives);
+        return primitives;
+    }
+    /**
+     * Detect function-based definitions (defineX pattern):
+     *
+     * Supported patterns:
+     * - const/let/var x = defineX({ ... })
+     * - export const/let/var x = defineX({ ... })
+     * - export default defineX({ ... })
+     */
+    detectFunctionBased(sourceFile, primitives) {
+        // Pattern 1: Variable declarations - const/let/var x = defineX({ ... })
+        // Also covers: export const/let/var x = defineX({ ... })
+        sourceFile.getVariableDeclarations().forEach(varDecl => {
+            const initializer = varDecl.getInitializer();
+            if (!initializer || !Node.isCallExpression(initializer))
+                return;
+            const callee = initializer.getExpression();
+            if (callee.getText() !== this.defineFunction)
+                return;
+            const args = initializer.getArguments();
+            if (args.length === 0)
+                return;
+            const configArg = args[0];
+            if (!Node.isObjectLiteralExpression(configArg))
+                return;
+            const pos = sourceFile.getLineAndColumnAtPos(varDecl.getStart());
+            const metadata = this.extractFromConfig(configArg, varDecl.getName(), sourceFile.getFilePath(), pos, 'function');
+            if (metadata)
+                primitives.push(metadata);
+        });
+        // Pattern 2: Export default - export default defineX({ ... })
+        this.detectDefaultExport(sourceFile, primitives, 'function', (expr) => {
+            if (!Node.isCallExpression(expr))
+                return null;
+            const callee = expr.getExpression();
+            if (callee.getText() !== this.defineFunction)
+                return null;
+            const args = expr.getArguments();
+            if (args.length === 0 || !Node.isObjectLiteralExpression(args[0]))
+                return null;
+            return args[0];
+        });
+    }
+    /**
+     * 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({ ... })
+     */
+    detectClassBased(sourceFile, primitives) {
+        // Track which nodes we've already processed to avoid duplicates
+        const processedNodes = new Set();
+        // Pattern 1: Variable declarations - const/let/var x = new LuaX({ ... })
+        // Also covers: export const/let/var x = new LuaX({ ... })
+        sourceFile.getVariableDeclarations().forEach(varDecl => {
+            const initializer = varDecl.getInitializer();
+            if (!initializer || !Node.isNewExpression(initializer))
+                return;
+            const expression = initializer.getExpression();
+            const className = expression.getText();
+            if (!this.legacyClassNames.includes(className))
+                return;
+            const args = initializer.getArguments();
+            if (args.length === 0)
+                return;
+            const configArg = args[0];
+            if (!Node.isObjectLiteralExpression(configArg))
+                return;
+            processedNodes.add(initializer.getStart());
+            const pos = sourceFile.getLineAndColumnAtPos(varDecl.getStart());
+            const metadata = this.extractFromConfig(configArg, varDecl.getName(), sourceFile.getFilePath(), pos, 'class');
+            if (metadata)
+                primitives.push(metadata);
+        });
+        // Pattern 2: Export default - export default new LuaX({ ... })
+        this.detectDefaultExport(sourceFile, primitives, 'class', (expr) => {
+            if (!Node.isNewExpression(expr))
+                return null;
+            // Skip if already processed as variable declaration
+            if (processedNodes.has(expr.getStart()))
+                return null;
+            const expression = expr.getExpression();
+            const className = expression.getText();
+            if (!this.legacyClassNames.includes(className))
+                return null;
+            const args = expr.getArguments();
+            if (args.length === 0 || !Node.isObjectLiteralExpression(args[0]))
+                return null;
+            return args[0];
+        });
+    }
+    /**
+     * 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.
+     */
+    detectDefaultExport(sourceFile, primitives, pattern, extractConfig) {
+        sourceFile.forEachDescendant(node => {
+            if (!Node.isExportAssignment(node))
+                return;
+            const expr = node.getExpression();
+            const configArg = extractConfig(expr);
+            if (!configArg)
+                return;
+            const pos = sourceFile.getLineAndColumnAtPos(node.getStart());
+            const metadata = this.extractFromConfig(configArg, 'default', // Triggers isDefaultExport=true in extractCommonFields
+            sourceFile.getFilePath(), pos, pattern);
+            if (metadata)
+                primitives.push(metadata);
+        });
+    }
+    /**
+     * Helper to extract common fields (name, description) from config.
+     * Returns null if name is missing.
+     *
+     * Automatically sets `isDefaultExport: true` when `exportName === 'default'`.
+     */
+    extractCommonFields(config, exportName, sourcePath, position) {
+        const name = extractStringProperty(config, 'name');
+        if (!name)
+            return null;
+        return {
+            name,
+            description: extractStringProperty(config, 'description') || '',
+            exportName,
+            isDefaultExport: exportName === 'default',
+            sourcePath,
+            line: position.line,
+            column: position.column,
+        };
+    }
+    // ===========================================================================
+    // ENTRY POINT GENERATION (common implementation)
+    // ===========================================================================
+    /**
+     * 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) {
+        const extraFields = this.getEntryPointFields(metadata);
+        const extraFieldsStr = extraFields ? `\n  ${extraFields}` : '';
+        // Default exports use `import X from` syntax directly.
+        // Named exports use the __lua_target__ alias injected by the virtual source plugin.
+        const importStatement = metadata.isDefaultExport
+            ? `import __primitive__ from '${metadata.sourcePath}';`
+            : `import { __lua_target__ as __primitive__ } from '${metadata.sourcePath}';`;
+        return `
+// =============================================================================
+// AUTO-GENERATED ENTRY POINT
+// ${this.displayName}: ${metadata.name}
+// Source: ${metadata.sourcePath}
+// =============================================================================
+
+${importStatement}
+
+const __lua_primitive__ = {
+  version: '2.0.0',
+  kind: '${this.kind}',
+  name: ${JSON.stringify(metadata.name)},
+  description: ${JSON.stringify(metadata.description)},
+  exportName: ${JSON.stringify(metadata.exportName)},${extraFieldsStr}
+};
+
+export default {
+  __lua_primitive__,
+  primitive: __primitive__,
+};
+`;
+    }
+    /**
+     * Override to add extra fields to __lua_primitive__ object.
+     * Return a string like: `context: "some value",\n  tools: ["tool1"]`
+     */
+    getEntryPointFields(_metadata) {
+        return '';
+    }
+    // ===========================================================================
+    // SCHEMA EXTRACTION (default: no schemas)
+    // ===========================================================================
+    /**
+     * Extract schemas from the primitive.
+     * Override for primitives that have schemas (tools, webhooks).
+     */
+    async extractSchemas(_metadata, _project) {
+        return undefined;
+    }
+    // ===========================================================================
+    // POST PROCESSING (common implementation)
+    // ===========================================================================
+    /**
+     * Post-process bundled artifact with runtime validation wrapper.
+     */
+    postProcess(artifact, metadata) {
+        const extraValidation = this.getRuntimeValidation(metadata);
+        const extraValidationStr = extraValidation ? `\n  ${extraValidation}` : '';
+        const wrappedCode = `
+// =============================================================================
+// LUA RUNTIME WRAPPER - ${this.displayName}: ${metadata.name}
+// =============================================================================
+
+${artifact.code}
+
+(function() {
+  const mod = typeof module !== 'undefined' ? module.exports : {};
+  const primitive = mod.default;
+  
+  if (!primitive || !primitive.__lua_primitive__) {
+    throw new Error('[Lua] Invalid ${this.kind} artifact: missing __lua_primitive__ marker');
+  }
+  
+  if (primitive.__lua_primitive__.kind !== '${this.kind}') {
+    throw new Error('[Lua] Invalid ${this.kind} artifact: expected kind "${this.kind}"');
+  }${extraValidationStr}
+})();
+`;
+        return {
+            ...artifact,
+            code: wrappedCode,
+            size: Buffer.byteLength(wrappedCode, 'utf8'),
+        };
+    }
+    /**
+     * Override to add extra runtime validation in postProcess.
+     * Return JavaScript code to add to the validation IIFE.
+     */
+    getRuntimeValidation(_metadata) {
+        return '';
+    }
+}
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Creates a validation result with no errors or warnings.
+ */
+export function validResult() {
+    return { valid: true, errors: [], warnings: [] };
+}
+/**
+ * Creates a validation error.
+ */
+export function validationError(message, options) {
+    return { message, ...options };
+}
+/**
+ * Creates a validation warning.
+ */
+export function validationWarning(message, options) {
+    return { message, ...options };
+}
+//# sourceMappingURL=base.js.map

package/dist/compiler/plugins/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/compiler/plugins/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAuB,IAAI,EAA2B,MAAM,UAAU,CAAC;AAa9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAqJhE,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAgB,UAAU;IAa9B,8EAA8E;IAC9E,oCAAoC;IACpC,8EAA8E;IAE9E;;;OAGG;IACH,MAAM,CAAC,UAAsB;QAC3B,MAAM,UAAU,GAA2B,EAAE,CAAC;QAE9C,+CAA+C;QAC/C,IAAI,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAEjD,6CAA6C;QAC7C,IAAI,CAAC,gBAAgB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAE9C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;;;;;OAOG;IACO,mBAAmB,CAAC,UAAsB,EAAE,UAAkC;QACtF,wEAAwE;QACxE,yDAAyD;QACzD,UAAU,CAAC,uBAAuB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;YACrD,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;YAC7C,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC;gBAAE,OAAO;YAEhE,MAAM,MAAM,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,cAAc;gBAAE,OAAO;YAErD,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,SAAS,CAAC;gBAAE,OAAO;YAEvD,MAAM,GAAG,GAAG,UAAU,CAAC,qBAAqB,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CACrC,SAAS,EACT,OAAO,CAAC,OAAO,EAAE,EACjB,UAAU,CAAC,WAAW,EAAE,EACxB,GAAG,EACH,UAAU,CACX,CAAC;YAEF,IAAI,QAAQ;gBAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,8DAA8D;QAC9D,IAAI,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;YACpE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACpC,IAAI,MAAM,CAAC,OAAO,EAAE,KAAK,IAAI,CAAC,cAAc;gBAAE,OAAO,IAAI,CAAC;YAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC/E,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACO,gBAAgB,CAAC,UAAsB,EAAE,UAAkC;QACnF,gEAAgE;QAChE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;QAEzC,yEAAyE;QACzE,0DAA0D;QAC1D,UAAU,CAAC,uBAAuB,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE;YACrD,MAAM,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;YAC7C,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC;gBAAE,OAAO;YAE/D,MAAM,UAAU,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC;YAC/C,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAAE,OAAO;YAEvD,MAAM,IAAI,GAAG,WAAW,CAAC,YAAY,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,SAAS,CAAC;gBAAE,OAAO;YAEvD,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC;YAE3C,MAAM,GAAG,GAAG,UAAU,CAAC,qBAAqB,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CACrC,SAAS,EACT,OAAO,CAAC,OAAO,EAAE,EACjB,UAAU,CAAC,WAAW,EAAE,EACxB,GAAG,EACH,OAAO,CACR,CAAC;YAEF,IAAI,QAAQ;gBAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,+DAA+D;QAC/D,IAAI,CAAC,mBAAmB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACjE,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC7C,oDAAoD;YACpD,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAAE,OAAO,IAAI,CAAC;YACrD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YACxC,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC/E,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;QACjB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,mBAAmB,CACzB,UAAsB,EACtB,UAAkC,EAClC,OAA6B,EAC7B,aAA6D;QAE7D,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC;gBAAE,OAAO;YAE3C,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,SAAS;gBAAE,OAAO;YAEvB,MAAM,GAAG,GAAG,UAAU,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CACrC,SAAS,EACT,SAAS,EAAG,uDAAuD;YACnE,UAAU,CAAC,WAAW,EAAE,EACxB,GAAG,EACH,OAAO,CACR,CAAC;YAEF,IAAI,QAAQ;gBAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC;IAgBD;;;;;OAKG;IACO,mBAAmB,CAC3B,MAA+B,EAC/B,UAAkB,EAClB,UAAkB,EAClB,QAA0C;QAE1C,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QAEvB,OAAO;YACL,IAAI;YACJ,WAAW,EAAE,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE;YAC/D,UAAU;YACV,eAAe,EAAE,UAAU,KAAK,SAAS;YACzC,UAAU;YACV,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC;IACJ,CAAC;IAQD,8EAA8E;IAC9E,iDAAiD;IACjD,8EAA8E;IAE9E;;;;;;OAMG;IACH,kBAAkB,CAAC,QAA8B;QAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,cAAc,GAAG,WAAW,CAAC,CAAC,CAAC,OAAO,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE/D,uDAAuD;QACvD,oFAAoF;QACpF,MAAM,eAAe,GAAG,QAAQ,CAAC,eAAe;YAC9C,CAAC,CAAC,8BAA8B,QAAQ,CAAC,UAAU,IAAI;YACvD,CAAC,CAAC,oDAAoD,QAAQ,CAAC,UAAU,IAAI,CAAC;QAEhF,OAAO;;;KAGN,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,IAAI;aAC1B,QAAQ,CAAC,UAAU;;;EAG9B,eAAe;;;;WAIN,IAAI,CAAC,IAAI;UACV,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;iBACtB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACrC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,cAAc;;;;;;;CAOpE,CAAC;IACA,CAAC;IAED;;;OAGG;IACO,mBAAmB,CAAC,SAA+B;QAC3D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,8EAA8E;IAC9E,0CAA0C;IAC1C,8EAA8E;IAE9E;;;OAGG;IACH,KAAK,CAAC,cAAc,CAClB,SAA+B,EAC/B,QAAiB;QAEjB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,8EAA8E;IAC9E,0CAA0C;IAC1C,8EAA8E;IAE9E;;OAEG;IACH,WAAW,CAAC,QAAyB,EAAE,QAA8B;QACnE,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC5D,MAAM,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAC,OAAO,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3E,MAAM,WAAW,GAAG;;2BAEG,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,IAAI;;;EAG3D,QAAQ,CAAC,IAAI;;;;;;;qCAOsB,IAAI,CAAC,IAAI;;;8CAGA,IAAI,CAAC,IAAI;qCAClB,IAAI,CAAC,IAAI,6BAA6B,IAAI,CAAC,IAAI;KAC/E,kBAAkB;;CAEtB,CAAC;QAEE,OAAO;YACL,GAAG,QAAQ;YACX,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC;SAC7C,CAAC;IACJ,CAAC;IAED;;;OAGG;IACO,oBAAoB,CAAC,SAA+B;QAC5D,OAAO,EAAE,CAAC;IACZ,CAAC;CAUF;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,OAAmF;IAEnF,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,OAAmF;IAEnF,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;AACjC,CAAC"}

package/dist/compiler/plugins/job.plugin.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Job compilation plugin.
+ *
+ * BACKWARD COMPATIBLE: Detects BOTH patterns:
+ * 1. Class-based (legacy): new LuaJob({ ... })
+ * 2. Function-based (new): const myJob = defineJob({ ... })
+ */
+import { ObjectLiteralExpression } from 'ts-morph';
+import { type JobMetadata, type JobMetadataFields, type ValidationResult, type ManifestContext, type CompiledPrimitive, type ManifestPrimitive } from '../types.js';
+import { BasePlugin } from './base.js';
+/**
+ * Plugin for compiling job primitives.
+ * Extends BasePlugin for common detection/entry point/postProcess logic.
+ */
+export declare class JobPlugin extends BasePlugin<JobMetadataFields> {
+    readonly kind = "job";
+    readonly displayName = "Job";
+    readonly defineFunction = "defineJob";
+    readonly legacyClassNames: string[];
+    /**
+     * Extract metadata from job config object.
+     */
+    protected extractFromConfig(config: ObjectLiteralExpression, exportName: string, sourcePath: string, position: {
+        line: number;
+        column: number;
+    }, pattern: 'function' | 'class'): JobMetadata | null;
+    validate(metadata: JobMetadata): ValidationResult;
+    /**
+     * Add runtime validation for executeFunction (LuaJob uses this internally).
+     */
+    protected getRuntimeValidation(): string;
+    toManifestEntry(compiled: CompiledPrimitive, _context?: ManifestContext): ManifestPrimitive;
+}