@specverse/engine-realize 3.5.3

package/dist/types/unified-mappings.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Unified Two-Level Mapping System (v3.6+)
+ *
+ * Simplifies factory mappings with a clear two-level system:
+ * - Level 1: defaults (sugar syntax for common cases)
+ * - Level 2: overrides (explicit with optional configuration)
+ *
+ * @module realize/types/unified-mappings
+ * @version 3.6.0
+ */
+/**
+ * Default Mappings (Level 1)
+ *
+ * Simple category → factory alias mappings.
+ * Uses sugar syntax for convenience.
+ *
+ * @example
+ * ```yaml
+ * defaults:
+ *   orm: "prisma"      # All storage.database → PrismaPostgres
+ *   api: "fastify"     # All api.rest → FastifyRoutes
+ *   cache: "redis"     # All storage.cache → RedisCache
+ * ```
+ */
+export interface DefaultMappingsV2 {
+    /** ORM/Database factory (maps to storage.database.*) */
+    orm?: string;
+    /** API framework factory (maps to api.rest.*) */
+    api?: string;
+    /** Cache factory (maps to storage.cache.*) */
+    cache?: string;
+    /** Queue/Message broker factory (maps to messaging.queue.*) */
+    queue?: string;
+    /** Authentication factory (maps to security.authentication.*) */
+    auth?: string;
+    /** Email service factory (maps to communication.email.*) */
+    email?: string;
+    /** File storage factory (maps to storage.files.*) */
+    storage?: string;
+    /** Search engine factory (maps to storage.search.*) */
+    search?: string;
+    /** Logging factory (maps to observability.logging.*) */
+    logging?: string;
+    /** Monitoring factory (maps to observability.monitoring.*) */
+    monitoring?: string;
+    /** Additional custom categories */
+    [category: string]: string | undefined;
+}
+/**
+ * Override Mapping (Level 2)
+ *
+ * Explicit mapping with optional instance-specific configuration.
+ * Can target either:
+ * - A capability pattern (e.g., "storage.database.postgres")
+ * - An instance name (e.g., "primary-db" from deployment)
+ *
+ * @example
+ * ```yaml
+ * overrides:
+ *   # Capability override
+ *   - target: "storage.database.postgres"
+ *     factory: "PrismaPostgres"
+ *
+ *   # Instance override with config
+ *   - target: "primary-db"
+ *     factory: "PrismaPostgres"
+ *     configuration:
+ *       url: "${DATABASE_URL}"
+ *       poolSize: 20
+ * ```
+ */
+export interface OverrideMapping {
+    /**
+     * Target to override
+     *
+     * Can be:
+     * - Capability pattern: "storage.database", "api.rest.crud"
+     * - Instance name: "primary-db", "cache-cluster"
+     */
+    target: string;
+    /**
+     * Factory name to use
+     *
+     * Must match a factory declared in instanceFactories section.
+     */
+    factory: string;
+    /**
+     * Instance-specific configuration (optional)
+     *
+     * Only applies when target is an instance name.
+     */
+    configuration?: Record<string, any>;
+    /**
+     * Version constraint (optional)
+     *
+     * Overrides the version from instanceFactories declaration.
+     */
+    version?: string;
+    /**
+     * Namespace for grouping (optional)
+     */
+    namespace?: string;
+}
+/**
+ * Target type discrimination
+ */
+export type TargetType = 'capability' | 'instance';
+/**
+ * Resolved override with type information
+ */
+export interface ResolvedOverride extends OverrideMapping {
+    /** Whether target is a capability or instance name */
+    targetType: TargetType;
+    /** Original target before resolution */
+    originalTarget: string;
+}
+/**
+ * Helper functions
+ */
+/**
+ * Determine if a target is a capability pattern
+ *
+ * Capability patterns contain dots (e.g., "storage.database")
+ * Instance names typically don't (e.g., "primary-db")
+ *
+ * @param target - Target string to check
+ * @returns True if target looks like a capability
+ */
+export declare function isCapabilityTarget(target: string): boolean;
+/**
+ * Determine if a target is an instance name
+ *
+ * @param target - Target string to check
+ * @returns True if target looks like an instance name
+ */
+export declare function isInstanceTarget(target: string): boolean;
+/**
+ * Resolve target type for an override
+ *
+ * @param override - Override mapping to analyze
+ * @returns Resolved override with type information
+ */
+export declare function resolveOverrideType(override: OverrideMapping): ResolvedOverride;
+/**
+ * Expand defaults to capability mappings
+ *
+ * Converts sugar syntax to explicit capability patterns.
+ *
+ * @param defaults - Default mappings
+ * @returns Map of capability patterns to factory aliases
+ */
+export declare function expandDefaults(defaults: DefaultMappingsV2): Map<string, string>;
+/**
+ * Validate override references
+ *
+ * Checks that overrides reference declared factories.
+ *
+ * @param overrides - Override mappings to validate
+ * @param declaredFactories - Set of declared factory names
+ * @returns Validation errors (empty if valid)
+ */
+export declare function validateOverrides(overrides: OverrideMapping[], declaredFactories: Set<string>): string[];
+//# sourceMappingURL=unified-mappings.d.ts.map

package/dist/types/unified-mappings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-mappings.d.ts","sourceRoot":"","sources":["../../src/types/unified-mappings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,mCAAmC;IACnC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,sDAAsD;IACtD,UAAU,EAAE,UAAU,CAAC;IAEvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,gBAAgB,CAU/E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA4B/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,eAAe,EAAE,EAC5B,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC7B,MAAM,EAAE,CAqBV"}

package/dist/types/unified-mappings.js

@@ -0,0 +1,110 @@
+/**
+ * Unified Two-Level Mapping System (v3.6+)
+ *
+ * Simplifies factory mappings with a clear two-level system:
+ * - Level 1: defaults (sugar syntax for common cases)
+ * - Level 2: overrides (explicit with optional configuration)
+ *
+ * @module realize/types/unified-mappings
+ * @version 3.6.0
+ */
+/**
+ * Helper functions
+ */
+/**
+ * Determine if a target is a capability pattern
+ *
+ * Capability patterns contain dots (e.g., "storage.database")
+ * Instance names typically don't (e.g., "primary-db")
+ *
+ * @param target - Target string to check
+ * @returns True if target looks like a capability
+ */
+export function isCapabilityTarget(target) {
+    // Capability patterns have dots and match capability naming convention
+    // storage.database, api.rest.crud, security.authentication
+    return /^[a-z]+\.[a-z]+(\.[a-z]+)*$/.test(target);
+}
+/**
+ * Determine if a target is an instance name
+ *
+ * @param target - Target string to check
+ * @returns True if target looks like an instance name
+ */
+export function isInstanceTarget(target) {
+    return !isCapabilityTarget(target);
+}
+/**
+ * Resolve target type for an override
+ *
+ * @param override - Override mapping to analyze
+ * @returns Resolved override with type information
+ */
+export function resolveOverrideType(override) {
+    const targetType = isCapabilityTarget(override.target)
+        ? 'capability'
+        : 'instance';
+    return {
+        ...override,
+        targetType,
+        originalTarget: override.target
+    };
+}
+/**
+ * Expand defaults to capability mappings
+ *
+ * Converts sugar syntax to explicit capability patterns.
+ *
+ * @param defaults - Default mappings
+ * @returns Map of capability patterns to factory aliases
+ */
+export function expandDefaults(defaults) {
+    const expanded = new Map();
+    // Predefined category → capability mappings
+    const categoryMappings = {
+        orm: ['storage.database'],
+        api: ['api.rest', 'api.rest.crud'],
+        cache: ['storage.cache'],
+        queue: ['messaging.queue'],
+        auth: ['security.authentication', 'security.authorization'],
+        email: ['communication.email'],
+        storage: ['storage.files', 'storage.objects'],
+        search: ['storage.search'],
+        logging: ['observability.logging'],
+        monitoring: ['observability.monitoring', 'observability.metrics']
+    };
+    for (const [category, factoryAlias] of Object.entries(defaults)) {
+        if (!factoryAlias)
+            continue;
+        const capabilities = categoryMappings[category] || [category];
+        for (const capability of capabilities) {
+            expanded.set(capability, factoryAlias);
+        }
+    }
+    return expanded;
+}
+/**
+ * Validate override references
+ *
+ * Checks that overrides reference declared factories.
+ *
+ * @param overrides - Override mappings to validate
+ * @param declaredFactories - Set of declared factory names
+ * @returns Validation errors (empty if valid)
+ */
+export function validateOverrides(overrides, declaredFactories) {
+    const errors = [];
+    for (const override of overrides) {
+        if (!declaredFactories.has(override.factory)) {
+            errors.push(`Override references undeclared factory: "${override.factory}" for target "${override.target}". ` +
+                `Add it to instanceFactories section.`);
+        }
+        // Warn if configuration is used with capability target
+        if (override.configuration && isCapabilityTarget(override.target)) {
+            errors.push(`Override for capability "${override.target}" has configuration, but capabilities don't support instance config. ` +
+                `Use an instance name as target instead.`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=unified-mappings.js.map

package/dist/types/unified-mappings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-mappings.js","sourceRoot":"","sources":["../../src/types/unified-mappings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+HH;;GAEG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,uEAAuE;IACvE,2DAA2D;IAC3D,OAAO,6BAA6B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAyB;IAC3D,MAAM,UAAU,GAAe,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC;QAChE,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,UAAU,CAAC;IAEf,OAAO;QACL,GAAG,QAAQ;QACX,UAAU;QACV,cAAc,EAAE,QAAQ,CAAC,MAAM;KAChC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAA2B;IACxD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3C,4CAA4C;IAC5C,MAAM,gBAAgB,GAA6B;QACjD,GAAG,EAAE,CAAC,kBAAkB,CAAC;QACzB,GAAG,EAAE,CAAC,UAAU,EAAE,eAAe,CAAC;QAClC,KAAK,EAAE,CAAC,eAAe,CAAC;QACxB,KAAK,EAAE,CAAC,iBAAiB,CAAC;QAC1B,IAAI,EAAE,CAAC,yBAAyB,EAAE,wBAAwB,CAAC;QAC3D,KAAK,EAAE,CAAC,qBAAqB,CAAC;QAC9B,OAAO,EAAE,CAAC,eAAe,EAAE,iBAAiB,CAAC;QAC7C,MAAM,EAAE,CAAC,gBAAgB,CAAC;QAC1B,OAAO,EAAE,CAAC,uBAAuB,CAAC;QAClC,UAAU,EAAE,CAAC,0BAA0B,EAAE,uBAAuB,CAAC;KAClE,CAAC;IAEF,KAAK,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,YAAY;YAAE,SAAS;QAE5B,MAAM,YAAY,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE9D,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;YACtC,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAA4B,EAC5B,iBAA8B;IAE9B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CACT,4CAA4C,QAAQ,CAAC,OAAO,iBAAiB,QAAQ,CAAC,MAAM,KAAK;gBACjG,sCAAsC,CACvC,CAAC;QACJ,CAAC;QAED,uDAAuD;QACvD,IAAI,QAAQ,CAAC,aAAa,IAAI,kBAAkB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAClE,MAAM,CAAC,IAAI,CACT,4BAA4B,QAAQ,CAAC,MAAM,uEAAuE;gBAClH,yCAAyC,CAC1C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/ai-spec-loader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * AI-Optimized Spec Loader Utility
+ *
+ * Loads SpecVerse YAML files and generates AIOptimizedSpec using:
+ * 1. UnifiedSpecVerseParser - Handles YAML parsing, imports, conventions
+ * 2. AIViewGenerator - Generates optimized spec with inference
+ *
+ * This utility eliminates duplicate parsing logic across all generators.
+ */
+export interface LoadOptions {
+    deployment?: string;
+    instance?: string;
+    manifest?: any;
+}
+export interface ComponentMetadata {
+    name: string;
+    version: string;
+    description?: string;
+    tags?: string[];
+    deployment?: string;
+    instance?: string;
+    manifest?: any;
+}
+export interface AIOptimizedSpec {
+    metadata: {
+        component: string;
+        version: string;
+        description?: string;
+        tags?: string[];
+        deployment?: string;
+        instance?: string;
+        manifest?: any;
+    };
+    models: any[];
+    controllers: any[];
+    services: any[];
+    events: any[];
+    views?: any[];
+    infrastructure?: any;
+}
+/**
+ * Load and generate AIOptimizedSpec from a SpecVerse YAML file
+ */
+export declare function loadAIOptimizedSpec(yamlFile: string, options?: LoadOptions): AIOptimizedSpec;
+/**
+ * Load AIOptimizedSpec with deployment filtering
+ */
+export declare function loadForDeployment(yamlFile: string, deploymentName: string, instanceName: string): AIOptimizedSpec;
+/**
+ * Load AIOptimizedSpec with manifest configuration
+ */
+export declare function loadWithManifest(yamlFile: string, manifestConfig: any): AIOptimizedSpec;
+/**
+ * Get component metadata from AIOptimizedSpec
+ */
+export declare function getComponentMetadata(spec: AIOptimizedSpec): ComponentMetadata;
+/**
+ * Get all models from AIOptimizedSpec
+ */
+export declare function getModels(spec: AIOptimizedSpec): any[];
+/**
+ * Get all controllers from AIOptimizedSpec
+ */
+export declare function getControllers(spec: AIOptimizedSpec): any[];
+/**
+ * Get all services from AIOptimizedSpec
+ */
+export declare function getServices(spec: AIOptimizedSpec): any[];
+/**
+ * Get all events from AIOptimizedSpec
+ */
+export declare function getEvents(spec: AIOptimizedSpec): any[];
+/**
+ * Get infrastructure requirements from AIOptimizedSpec
+ */
+export declare function getInfrastructure(spec: AIOptimizedSpec): any;
+//# sourceMappingURL=ai-spec-loader.d.ts.map

package/dist/utils/ai-spec-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-spec-loader.d.ts","sourceRoot":"","sources":["../../src/utils/ai-spec-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,GAAG,CAAC;KAChB,CAAC;IACF,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,WAAW,EAAE,GAAG,EAAE,CAAC;IACnB,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,MAAM,EAAE,GAAG,EAAE,CAAC;IACd,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IACd,cAAc,CAAC,EAAE,GAAG,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,eAAe,CAwChG;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,eAAe,CAKjB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,GAAG,eAAe,CAIvF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAU7E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,EAAE,CAE3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,GAAG,CAE5D"}

package/dist/utils/ai-spec-loader.js

@@ -0,0 +1,138 @@
+/**
+ * AI-Optimized Spec Loader Utility
+ *
+ * Loads SpecVerse YAML files and generates AIOptimizedSpec using:
+ * 1. UnifiedSpecVerseParser - Handles YAML parsing, imports, conventions
+ * 2. AIViewGenerator - Generates optimized spec with inference
+ *
+ * This utility eliminates duplicate parsing logic across all generators.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { UnifiedSpecVerseParser } from '@specverse/engine-parser';
+import { AIViewGenerator } from '@specverse/engine-generators';
+// ES module equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Load JSON schema
+const getSchemaPath = () => {
+    // Try multiple paths for schema location
+    const possiblePaths = [
+        resolve(process.cwd(), 'schema/SPECVERSE-SCHEMA.json'),
+        resolve(__dirname, '../../../schema/SPECVERSE-SCHEMA.json'),
+        resolve(__dirname, '../../schema/SPECVERSE-SCHEMA.json'),
+    ];
+    for (const path of possiblePaths) {
+        try {
+            if (existsSync(path)) {
+                return path;
+            }
+        }
+        catch (e) {
+            // Continue to next path
+        }
+    }
+    return possiblePaths[0]; // Fallback to cwd
+};
+const schemaPath = getSchemaPath();
+const schemaJson = JSON.parse(readFileSync(schemaPath, 'utf8'));
+/**
+ * Load and generate AIOptimizedSpec from a SpecVerse YAML file
+ */
+export function loadAIOptimizedSpec(yamlFile, options = {}) {
+    try {
+        // 1. Read YAML file
+        const yamlContent = readFileSync(yamlFile, 'utf8');
+        // 2. Parse with UnifiedSpecVerseParser (handles imports, conventions, validation)
+        const parser = new UnifiedSpecVerseParser(schemaJson);
+        const result = parser.parse(yamlContent, 'specly');
+        // Check for parse errors
+        if (result.errors && result.errors.length > 0) {
+            const errorMessages = result.errors
+                .map((err) => `  - ${err.message} (line ${err.line || '?'}, col ${err.column || '?'})`)
+                .join('\n');
+            throw new Error(`Parse errors in ${yamlFile}:\n${errorMessages}`);
+        }
+        // Check for warnings (non-fatal)
+        if (result.warnings && result.warnings.length > 0) {
+            console.warn(`⚠️  Warnings in ${yamlFile}:`);
+            result.warnings.forEach((warn) => {
+                console.warn(`  - ${warn.message}`);
+            });
+        }
+        // 3. Generate AIOptimizedSpec (runs inference, expands CURED, etc.)
+        const generator = new AIViewGenerator();
+        const optimized = generator.generate(result.ast, options);
+        return optimized;
+    }
+    catch (error) {
+        // Provide helpful error messages
+        if (error.code === 'ENOENT') {
+            throw new Error(`File not found: ${yamlFile}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Load AIOptimizedSpec with deployment filtering
+ */
+export function loadForDeployment(yamlFile, deploymentName, instanceName) {
+    return loadAIOptimizedSpec(yamlFile, {
+        deployment: deploymentName,
+        instance: instanceName
+    });
+}
+/**
+ * Load AIOptimizedSpec with manifest configuration
+ */
+export function loadWithManifest(yamlFile, manifestConfig) {
+    return loadAIOptimizedSpec(yamlFile, {
+        manifest: manifestConfig
+    });
+}
+/**
+ * Get component metadata from AIOptimizedSpec
+ */
+export function getComponentMetadata(spec) {
+    return {
+        name: spec.metadata.component,
+        version: spec.metadata.version,
+        description: spec.metadata.description,
+        tags: spec.metadata.tags,
+        deployment: spec.metadata.deployment,
+        instance: spec.metadata.instance,
+        manifest: spec.metadata.manifest
+    };
+}
+/**
+ * Get all models from AIOptimizedSpec
+ */
+export function getModels(spec) {
+    return spec.models || [];
+}
+/**
+ * Get all controllers from AIOptimizedSpec
+ */
+export function getControllers(spec) {
+    return spec.controllers || [];
+}
+/**
+ * Get all services from AIOptimizedSpec
+ */
+export function getServices(spec) {
+    return spec.services || [];
+}
+/**
+ * Get all events from AIOptimizedSpec
+ */
+export function getEvents(spec) {
+    return spec.events || [];
+}
+/**
+ * Get infrastructure requirements from AIOptimizedSpec
+ */
+export function getInfrastructure(spec) {
+    return spec.infrastructure || {};
+}
+//# sourceMappingURL=ai-spec-loader.js.map

package/dist/utils/ai-spec-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-spec-loader.js","sourceRoot":"","sources":["../../src/utils/ai-spec-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,oCAAoC;AACpC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,mBAAmB;AACnB,MAAM,aAAa,GAAG,GAAW,EAAE;IACjC,yCAAyC;IACzC,MAAM,aAAa,GAAG;QACpB,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,8BAA8B,CAAC;QACtD,OAAO,CAAC,SAAS,EAAE,uCAAuC,CAAC;QAC3D,OAAO,CAAC,SAAS,EAAE,oCAAoC,CAAC;KACzD,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,wBAAwB;QAC1B,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB;AAC7C,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;AACnC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAoChE;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,UAAuB,EAAE;IAC7E,IAAI,CAAC;QACH,oBAAoB;QACpB,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAEnD,kFAAkF;QAClF,MAAM,MAAM,GAAG,IAAI,sBAAsB,CAAC,UAAU,CAAC,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAEnD,yBAAyB;QACzB,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM;iBAChC,GAAG,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,OAAO,UAAU,GAAG,CAAC,IAAI,IAAI,GAAG,SAAS,GAAG,CAAC,MAAM,IAAI,GAAG,GAAG,CAAC;iBAC3F,IAAI,CAAC,IAAI,CAAC,CAAC;YAEd,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,MAAM,aAAa,EAAE,CAAC,CAAC;QACpE,CAAC;QAED,iCAAiC;QACjC,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,mBAAmB,QAAQ,GAAG,CAAC,CAAC;YAC7C,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAS,EAAE,EAAE;gBACpC,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;YACtC,CAAC,CAAC,CAAC;QACL,CAAC;QAED,oEAAoE;QACpE,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;QACxC,MAAM,SAAS,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAI,EAAE,OAAO,CAAC,CAAC;QAE3D,OAAO,SAA4B,CAAC;IAEtC,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,iCAAiC;QACjC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAgB,EAChB,cAAsB,EACtB,YAAoB;IAEpB,OAAO,mBAAmB,CAAC,QAAQ,EAAE;QACnC,UAAU,EAAE,cAAc;QAC1B,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,cAAmB;IACpE,OAAO,mBAAmB,CAAC,QAAQ,EAAE;QACnC,QAAQ,EAAE,cAAc;KACzB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAqB;IACxD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS;QAC7B,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO;QAC9B,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;QACtC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;QACxB,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU;QACpC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;QAChC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ;KACjC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAqB;IAC7C,OAAO,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,IAAqB;IAClD,OAAO,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAqB;IAC/C,OAAO,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAAqB;IAC7C,OAAO,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAqB;IACrD,OAAO,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Realize Utilities
+ *
+ * Shared utilities for code realization (code generation)
+ */
+export * from './ai-spec-loader.js';
+export * from './manifest-loader.js';
+export * from './mapping-migration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,9 @@
+/**
+ * Realize Utilities
+ *
+ * Shared utilities for code realization (code generation)
+ */
+export * from './ai-spec-loader.js';
+export * from './manifest-loader.js';
+export * from './mapping-migration.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC"}

package/dist/utils/manifest-loader.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Manifest Loader Utility
+ *
+ * Loads and validates SpecVerse manifest files.
+ * Provides default manifests for testing and development.
+ */
+import type { CapabilityMapping, InstanceMapping, DefaultMappings, DeploymentReference } from '../types/index.js';
+import type { DefaultMappingsV2, OverrideMapping } from '../types/unified-mappings.js';
+/**
+ * Instance Factory Declaration
+ *
+ * Declares an instance factory with its source metadata.
+ * Source structure matches registry FactorySource exactly.
+ */
+export interface InstanceFactoryDeclaration {
+    /** Factory name (must match registry) */
+    name: string;
+    /** Source metadata */
+    source: {
+        /** Source type */
+        type: 'npm' | 'git' | 'url';
+        /** NPM package name (for npm type) */
+        package?: string;
+        /** Version constraint (for npm type) */
+        version?: string;
+        /** Git repository URL (for git type) */
+        url?: string;
+        /** Entry point file path */
+        entrypoint?: string;
+    };
+}
+export interface ManifestConfig {
+    specVersion: string;
+    name: string;
+    description?: string;
+    version: string;
+    /** v3.3 Deployment Reference (REQUIRED) */
+    deployment: DeploymentReference;
+    /**
+     * Instance Factories (NEW - v3.6+)
+     *
+     * Explicit declarations of instance factories with source metadata.
+     * This allows validation without registry lookup.
+     */
+    instanceFactories?: InstanceFactoryDeclaration[];
+    /**
+     * Two-Level Mapping System (v3.6+) - RECOMMENDED
+     *
+     * Simplified mapping system with two clear levels:
+     * - defaults: Sugar syntax for common cases
+     * - overrides: Explicit control with optional configuration
+     */
+    defaults?: DefaultMappingsV2;
+    overrides?: OverrideMapping[];
+    /**
+     * Three-Level Mapping System (v3.3) - LEGACY
+     *
+     * Maintained for backward compatibility.
+     * Will be deprecated in future versions.
+     * Use two-level system (defaults + overrides) instead.
+     */
+    defaultMappings?: DefaultMappings;
+    capabilityMappings?: CapabilityMapping[];
+    instanceMappings?: InstanceMapping[];
+    /** Global configuration */
+    configuration?: Record<string, any>;
+    /** Manifest templates for common tech stacks */
+    manifestTemplates?: Array<{
+        template: string;
+        version?: string;
+    }>;
+    /** Internal metadata */
+    _manifestName?: string;
+    _manifestPath?: string;
+    _isDefault?: boolean;
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Load manifest from file
+ */
+export declare function loadManifest(manifestPath: string): ManifestConfig;
+/**
+ * Get manifest configuration value by path
+ */
+export declare function getManifestValue(manifest: ManifestConfig | null | undefined, path: string, defaultValue?: any): any;
+/**
+ * Validate manifest structure (v3.3 only - no backward compatibility)
+ */
+export declare function validateManifest(manifest: ManifestConfig | null | undefined): ManifestValidationResult;
+/**
+ * Merge manifests (v3.3 composition)
+ */
+export declare function mergeManifests(baseManifest: ManifestConfig | null | undefined, overrideManifest: ManifestConfig | null | undefined): ManifestConfig | null;
+/**
+ * Get manifest summary for debugging
+ */
+export declare function getManifestSummary(manifest: ManifestConfig): {
+    name: string;
+    version: string;
+    deployment: string;
+    mappingStrategies: string[];
+    instanceCount?: number;
+};
+//# sourceMappingURL=manifest-loader.d.ts.map

package/dist/utils/manifest-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-loader.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb,sBAAsB;IACtB,MAAM,EAAE;QACN,kBAAkB;QAClB,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;QAE5B,sCAAsC;QACtC,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,wCAAwC;QACxC,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB,wCAAwC;QACxC,GAAG,CAAC,EAAE,MAAM,CAAC;QAEb,4BAA4B;QAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAEhB,2CAA2C;IAC3C,UAAU,EAAE,mBAAmB,CAAC;IAEhC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAE9B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACzC,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IAErC,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IAEH,wBAAwB;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CA8CjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,GAAG,GACjB,GAAG,CAiBL;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,wBAAwB,CAgDtG;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,EAC/C,gBAAgB,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAClD,cAAc,GAAG,IAAI,CAyBvB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,cAAc,GAAG;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}