@dexto/image-bundler 1.5.8 → 1.6.1

package/src/generator.ts

@@ -1,53 +1,37 @@
 /**
- * Code generator for base images
+ * Code generator for images
  *
- * Transforms image definitions into importable packages with:
- * - Side-effect provider registration
- * - createAgent() factory
- * - Utility exports
- * - Metadata exports
+ * Transforms image definitions + convention folders into importable packages with:
+ * - A typed `DextoImage` default export (no side effects)
+ * - Optional utility re-exports
  */
 
-import type { ImageDefinition } from '@dexto/core';
+import type { ImageDefinition } from './image-definition/types.js';
 import type { GeneratedCode } from './types.js';
-import type { DiscoveredProviders } from './bundler.js';
+import type { DiscoveredFactories } from './bundler.js';
 
 /**
  * Generate JavaScript entry point for an image
  */
 export function generateEntryPoint(
     definition: ImageDefinition,
-    coreVersion: string,
-    discoveredProviders?: DiscoveredProviders
+    discoveredFactories: DiscoveredFactories
 ): GeneratedCode {
-    // Generate imports section
-    const imports = generateImports(definition, discoveredProviders);
-
-    // Generate provider registration section
-    const registrations = generateProviderRegistrations(definition, discoveredProviders);
-
-    // Generate factory function
-    const factory = generateFactory();
-
-    // Generate utility exports
+    const imports = generateImports(definition, discoveredFactories);
+    const helpers = definition.extends ? generateHelpers() : '';
+    const imageModule = generateImageModule(definition, discoveredFactories);
     const utilityExports = generateUtilityExports(definition);
 
-    // Generate metadata export
-    const metadata = generateMetadata(definition, coreVersion);
-
-    // Combine all sections
-    const js = `// AUTO-GENERATED by @dexto/bundler
+    const js = `// AUTO-GENERATED by @dexto/image-bundler
 // Do not edit this file directly. Edit dexto.image.ts instead.
 
 ${imports}
 
-${registrations}
+${helpers}
 
-${factory}
+${imageModule}
 
 ${utilityExports}
-
-${metadata}
 `;
 
     // Generate TypeScript definitions
@@ -56,159 +40,111 @@ ${metadata}
     return { js, dts };
 }
 
+function sanitizeIdentifier(value: string): string {
+    const sanitized = value.replace(/[^a-zA-Z0-9_$]/g, '_');
+    if (/^[a-zA-Z_$]/.test(sanitized)) {
+        return sanitized;
+    }
+    return `_${sanitized}`;
+}
+
+function toFactoryImportSymbol(prefix: string, type: string): string {
+    return sanitizeIdentifier(`${prefix}_${type}`);
+}
+
 function generateImports(
     definition: ImageDefinition,
-    discoveredProviders?: DiscoveredProviders
+    discoveredFactories: DiscoveredFactories
 ): string {
     const imports: string[] = [];
 
-    // Import base image first (if extending) - triggers side-effect provider registration
     if (definition.extends) {
-        imports.push(`// Import base image for provider registration (side effect)`);
-        imports.push(`import '${definition.extends}';`);
-        imports.push(``);
+        imports.push(`import baseImage from '${definition.extends}';`);
     }
 
-    // Core imports
-    imports.push(`import { DextoAgent } from '@dexto/core';`);
+    imports.push(`import { defaultLoggerFactory } from '@dexto/core';`);
 
-    // Always import all registries since we re-export them in generateFactory()
-    // This ensures the re-exports don't reference unimported identifiers
-    imports.push(
-        `import { customToolRegistry, pluginRegistry, compactionRegistry, blobStoreRegistry } from '@dexto/core';`
+    const toolProviders = [...discoveredFactories.tools].sort((a, b) =>
+        a.type.localeCompare(b.type)
+    );
+    const hookProviders = [...discoveredFactories.hooks].sort((a, b) =>
+        a.type.localeCompare(b.type)
+    );
+    const compactionProviders = [...discoveredFactories.compaction].sort((a, b) =>
+        a.type.localeCompare(b.type)
+    );
+    const blobProviders = [...discoveredFactories.storage.blob].sort((a, b) =>
+        a.type.localeCompare(b.type)
+    );
+    const databaseProviders = [...discoveredFactories.storage.database].sort((a, b) =>
+        a.type.localeCompare(b.type)
+    );
+    const cacheProviders = [...discoveredFactories.storage.cache].sort((a, b) =>
+        a.type.localeCompare(b.type)
     );
 
-    // Import discovered providers
-    if (discoveredProviders) {
-        const categories = [
-            { key: 'blobStore', label: 'Blob Storage' },
-            { key: 'customTools', label: 'Custom Tools' },
-            { key: 'compaction', label: 'Compaction' },
-            { key: 'plugins', label: 'Plugins' },
-        ] as const;
-
-        for (const { key, label } of categories) {
-            const providers = discoveredProviders[key];
-            if (providers.length > 0) {
-                imports.push(``);
-                imports.push(`// ${label} providers (auto-discovered)`);
-                providers.forEach((path, index) => {
-                    const varName = `${key}Provider${index}`;
-                    imports.push(`import * as ${varName} from '${path}';`);
-                });
-            }
-        }
+    if (
+        toolProviders.length > 0 ||
+        hookProviders.length > 0 ||
+        compactionProviders.length > 0 ||
+        blobProviders.length > 0 ||
+        databaseProviders.length > 0 ||
+        cacheProviders.length > 0
+    ) {
+        imports.push('');
+        imports.push('// Factories (convention folders; each must `export const factory = ...`)');
     }
 
-    return imports.join('\n');
-}
-
-function generateProviderRegistrations(
-    definition: ImageDefinition,
-    discoveredProviders?: DiscoveredProviders
-): string {
-    const registrations: string[] = [];
-
-    if (definition.extends) {
-        registrations.push(
-            `// Base image providers already registered via import of '${definition.extends}'`
-        );
-        registrations.push('');
+    for (const entry of toolProviders) {
+        const symbol = toFactoryImportSymbol('tools', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
     }
-
-    registrations.push('// SIDE EFFECT: Register providers on import');
-    registrations.push('');
-
-    // Auto-register discovered providers
-    if (discoveredProviders) {
-        const categoryMap = [
-            { key: 'blobStore', registry: 'blobStoreRegistry', label: 'Blob Storage' },
-            { key: 'customTools', registry: 'customToolRegistry', label: 'Custom Tools' },
-            { key: 'compaction', registry: 'compactionRegistry', label: 'Compaction' },
-            { key: 'plugins', registry: 'pluginRegistry', label: 'Plugins' },
-        ] as const;
-
-        for (const { key, registry, label } of categoryMap) {
-            const providers = discoveredProviders[key];
-            if (providers.length === 0) continue;
-
-            registrations.push(`// Auto-register ${label} providers`);
-            providers.forEach((path, index) => {
-                const varName = `${key}Provider${index}`;
-                registrations.push(`// From ${path}`);
-                registrations.push(`for (const exported of Object.values(${varName})) {`);
-                registrations.push(
-                    `    if (exported && typeof exported === 'object' && 'type' in exported && 'create' in exported) {`
-                );
-                registrations.push(`        try {`);
-                registrations.push(`            ${registry}.register(exported);`);
-                registrations.push(
-                    `            console.log(\`✓ Registered ${key}: \${exported.type}\`);`
-                );
-                registrations.push(`        } catch (err) {`);
-                registrations.push(`            // Ignore duplicate registration errors`);
-                registrations.push(
-                    `            if (!err.message?.includes('already registered')) throw err;`
-                );
-                registrations.push(`        }`);
-                registrations.push(`    }`);
-                registrations.push(`}`);
-            });
-            registrations.push('');
-        }
+    for (const entry of hookProviders) {
+        const symbol = toFactoryImportSymbol('hooks', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
     }
-
-    // Handle manual registration functions (backwards compatibility)
-    for (const [category, config] of Object.entries(definition.providers)) {
-        if (!config) continue;
-
-        if (config.register) {
-            // Async registration function with duplicate prevention
-            registrations.push(`// Register ${category} via custom function (from dexto.image.ts)`);
-            registrations.push(`await (async () => {`);
-            registrations.push(`    try {`);
-            registrations.push(
-                `        ${config.register
-                    .toString()
-                    .replace(/^async\s*\(\)\s*=>\s*{/, '')
-                    .replace(/}$/, '')}`
-            );
-            registrations.push(`    } catch (err) {`);
-            registrations.push(`        // Ignore duplicate registration errors`);
-            registrations.push(`        if (!err.message?.includes('already registered')) {`);
-            registrations.push(`            throw err;`);
-            registrations.push(`        }`);
-            registrations.push(`    }`);
-            registrations.push(`})();`);
-            registrations.push('');
-        }
+    for (const entry of compactionProviders) {
+        const symbol = toFactoryImportSymbol('compaction', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
+    }
+    for (const entry of blobProviders) {
+        const symbol = toFactoryImportSymbol('storage_blob', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
+    }
+    for (const entry of databaseProviders) {
+        const symbol = toFactoryImportSymbol('storage_database', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
+    }
+    for (const entry of cacheProviders) {
+        const symbol = toFactoryImportSymbol('storage_cache', entry.type);
+        imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
     }
 
-    return registrations.join('\n');
+    return imports.join('\n');
 }
 
-function generateFactory(): string {
-    return `/**
- * Create a Dexto agent using this image's registered providers.
- *
- * @param config - Agent configuration
- * @param configPath - Optional path to config file
- * @returns DextoAgent instance with providers already registered
- */
-export function createAgent(config, configPath) {
-    return new DextoAgent(config, configPath);
+function generateHelpers(): string {
+    return `function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/**
- * Re-export registries for runtime customization.
- * This allows apps to add custom providers without depending on @dexto/core directly.
- */
-export {
-    customToolRegistry,
-    pluginRegistry,
-    compactionRegistry,
-    blobStoreRegistry,
-} from '@dexto/core';`;
+function mergeImageDefaults(baseDefaults, overrideDefaults) {
+    if (!baseDefaults) return overrideDefaults;
+    if (!overrideDefaults) return baseDefaults;
+
+    const merged = { ...baseDefaults, ...overrideDefaults };
+    for (const [key, baseValue] of Object.entries(baseDefaults)) {
+        const overrideValue = overrideDefaults[key];
+        if (!isPlainObject(baseValue) || !isPlainObject(overrideValue)) {
+            continue;
+        }
+        merged[key] = {
+            ...baseValue,
+            ...overrideValue,
+        };
+    }
+    return merged;
+}`;
 }
 
 function generateUtilityExports(definition: ImageDefinition): string {
@@ -250,32 +186,128 @@ function generateUtilityExports(definition: ImageDefinition): string {
     return sections.join('\n');
 }
 
-function generateMetadata(definition: ImageDefinition, coreVersion: string): string {
-    const metadata: Record<string, any> = {
-        name: definition.name,
-        version: definition.version,
-        description: definition.description,
-        target: definition.target || 'custom',
-        constraints: definition.constraints || [],
-        builtAt: new Date().toISOString(),
-        coreVersion: coreVersion,
-    };
-
-    // Include extends information if present
-    if (definition.extends) {
-        metadata.extends = definition.extends;
+function generateImageModule(
+    definition: ImageDefinition,
+    discoveredFactories: DiscoveredFactories
+): string {
+    const derivedDefaults =
+        definition.defaults !== undefined
+            ? JSON.stringify(definition.defaults, null, 4)
+            : 'undefined';
+
+    const toolsEntries = discoveredFactories.tools
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('tools', entry.type);
+            return `        ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const hookEntries = discoveredFactories.hooks
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('hooks', entry.type);
+            return `        ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const compactionEntries = discoveredFactories.compaction
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('compaction', entry.type);
+            return `        ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const blobEntries = discoveredFactories.storage.blob
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('storage_blob', entry.type);
+            return `            ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const databaseEntries = discoveredFactories.storage.database
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('storage_database', entry.type);
+            return `            ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const cacheEntries = discoveredFactories.storage.cache
+        .slice()
+        .sort((a, b) => a.type.localeCompare(b.type))
+        .map((entry) => {
+            const symbol = toFactoryImportSymbol('storage_cache', entry.type);
+            return `            ${JSON.stringify(entry.type)}: ${symbol},`;
+        });
+
+    const metadataLines: string[] = [];
+    metadataLines.push(`        name: ${JSON.stringify(definition.name)},`);
+    metadataLines.push(`        version: ${JSON.stringify(definition.version)},`);
+    metadataLines.push(`        description: ${JSON.stringify(definition.description)},`);
+
+    if (definition.target !== undefined) {
+        metadataLines.push(`        target: ${JSON.stringify(definition.target)},`);
+    } else if (definition.extends) {
+        metadataLines.push(`        target: baseImage.metadata.target,`);
     }
 
-    // Include bundled plugins if present
-    if (definition.bundledPlugins && definition.bundledPlugins.length > 0) {
-        metadata.bundledPlugins = definition.bundledPlugins;
+    if (definition.extends) {
+        const derivedConstraints = JSON.stringify(definition.constraints ?? []);
+        metadataLines.push(
+            `        constraints: Array.from(new Set([...(baseImage.metadata.constraints ?? []), ...${derivedConstraints}])),`
+        );
+    } else if (definition.constraints !== undefined) {
+        metadataLines.push(`        constraints: ${JSON.stringify(definition.constraints)},`);
     }
 
-    return `/**
- * Image metadata
- * Generated at build time
- */
-export const imageMetadata = ${JSON.stringify(metadata, null, 4)};`;
+    const defaultsExpression = definition.extends
+        ? `mergeImageDefaults(baseImage.defaults, ${derivedDefaults})`
+        : derivedDefaults;
+
+    const toolsSpread = definition.extends ? `        ...baseImage.tools,\n` : '';
+    const hooksSpread = definition.extends ? `        ...baseImage.hooks,\n` : '';
+    const compactionSpread = definition.extends ? `        ...baseImage.compaction,\n` : '';
+
+    const blobSpread = definition.extends ? `            ...baseImage.storage.blob,\n` : '';
+    const databaseSpread = definition.extends ? `            ...baseImage.storage.database,\n` : '';
+    const cacheSpread = definition.extends ? `            ...baseImage.storage.cache,\n` : '';
+
+    const loggerExpression = definition.extends
+        ? `baseImage.logger ?? defaultLoggerFactory`
+        : `defaultLoggerFactory`;
+
+    return `const image = {
+    metadata: {
+${metadataLines.join('\n')}
+    },
+    defaults: ${defaultsExpression},
+    tools: {
+${toolsSpread}${toolsEntries.join('\n')}
+    },
+    storage: {
+        blob: {
+${blobSpread}${blobEntries.join('\n')}
+        },
+        database: {
+${databaseSpread}${databaseEntries.join('\n')}
+        },
+        cache: {
+${cacheSpread}${cacheEntries.join('\n')}
+        },
+    },
+    hooks: {
+${hooksSpread}${hookEntries.join('\n')}
+    },
+    compaction: {
+${compactionSpread}${compactionEntries.join('\n')}
+    },
+    logger: ${loggerExpression},
+};
+
+export default image;`;
 }
 
 function generateTypeDefinitions(definition: ImageDefinition): string {
@@ -311,26 +343,13 @@ function generateTypeDefinitions(definition: ImageDefinition): string {
     return `// AUTO-GENERATED TypeScript definitions
 // Do not edit this file directly
 
-import type { DextoAgent, AgentConfig, ImageMetadata } from '@dexto/core';
-
-/**
- * Create a Dexto agent using this image's registered providers.
- */
-export declare function createAgent(config: AgentConfig, configPath?: string): DextoAgent;
-
-/**
- * Image metadata
- */
-export declare const imageMetadata: ImageMetadata;
+	import type { DextoImage } from '@dexto/agent-config';
 
-/**
- * Re-exported registries for runtime customization
- */
-export {
-    customToolRegistry,
-    pluginRegistry,
-    compactionRegistry,
-    blobStoreRegistry,
-} from '@dexto/core';${utilityExports}
-`;
+	/**
+	 * Typed image module (no side effects)
+	 */
+		declare const image: DextoImage;
+		export default image;
+${utilityExports}
+	`;
 }

package/src/image-definition/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Image Definition Types (bundler-only)
+ *
+ * The bundler consumes a `dexto.image.ts` file that declares metadata and defaults.
+ * Concrete tools/storage/hooks/compaction factories are discovered from convention folders
+ * and must `export const factory = ...` from their `index.ts`.
+ */
+
+import type { ImageDefaults } from '@dexto/agent-config';
+
+/**
+ * Image definition structure consumed by `@dexto/image-bundler`.
+ *
+ * Note: Provider factories are discovered from folders; this file is metadata + defaults only.
+ */
+export interface ImageDefinition {
+    /** Unique name for this image (e.g., 'image-local') */
+    name: string;
+    /** Semantic version of this image */
+    version: string;
+    /** Brief description of this image's purpose */
+    description: string;
+
+    /** Target deployment environment (for documentation and validation) */
+    target?: string;
+
+    /** Runtime constraints this image requires (for validation and error messages) */
+    constraints?: string[];
+
+    /** Parent image package name to extend (optional) */
+    extends?: string;
+
+    /**
+     * Default configuration values (merged into agent config; config wins).
+     *
+     * This must match the `AgentConfig` shape. Unknown fields will be rejected by schema validation.
+     */
+    defaults?: ImageDefaults;
+
+    /**
+     * Utility exports (optional).
+     * Maps export name to file path (relative to image root).
+     */
+    utils?: Record<string, string>;
+
+    /**
+     * Selective named exports from packages (optional).
+     */
+    exports?: Record<string, string[]>;
+}
+
+/**
+ * Metadata about a built image (generated by bundler).
+ */
+export interface ImageMetadata {
+    /** Image name */
+    name: string;
+    /** Image version */
+    version: string;
+    /** Description */
+    description: string;
+    /** Target environment */
+    target?: string;
+    /** Runtime constraints */
+    constraints: string[];
+    /** Build timestamp */
+    builtAt: string;
+    /** Core version this image was built for */
+    coreVersion: string;
+    /** Base image this extends (if any) */
+    extends?: string;
+}

package/src/image-definition/validate-image-definition.ts

@@ -0,0 +1,70 @@
+import type { ImageDefinition } from './types.js';
+
+/**
+ * Validate an image definition.
+ * Throws if the definition is invalid.
+ *
+ * Used by bundler to validate images before building.
+ */
+export function validateImageDefinition(definition: ImageDefinition): void {
+    // Basic validation
+    if (!definition.name || typeof definition.name !== 'string') {
+        throw new Error('Image name must be a non-empty string');
+    }
+
+    if (!definition.version || typeof definition.version !== 'string') {
+        throw new Error('Image version must be a non-empty string');
+    }
+
+    if (!definition.description || typeof definition.description !== 'string') {
+        throw new Error('Image description must be a non-empty string');
+    }
+
+    // Validate version format (basic semver check)
+    const versionRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?$/;
+    if (!versionRegex.test(definition.version)) {
+        throw new Error(
+            `Image version '${definition.version}' is not valid semver. Expected format: x.y.z`
+        );
+    }
+
+    // Validate target if provided
+    if (definition.target !== undefined) {
+        if (typeof definition.target !== 'string' || definition.target.trim().length === 0) {
+            throw new Error(`Image target must be a non-empty string when provided`);
+        }
+    }
+
+    if (definition.constraints) {
+        if (!Array.isArray(definition.constraints)) {
+            throw new Error('Image constraints must be an array');
+        }
+
+        for (const constraint of definition.constraints) {
+            if (typeof constraint !== 'string' || constraint.trim().length === 0) {
+                throw new Error(`Image constraint must be a non-empty string`);
+            }
+        }
+    }
+
+    // Validate utils if provided
+    if (definition.utils) {
+        for (const [name, path] of Object.entries(definition.utils)) {
+            if (typeof path !== 'string') {
+                throw new Error(`Utility '${name}' path must be a string`);
+            }
+            if (!path.startsWith('./')) {
+                throw new Error(
+                    `Utility '${name}' path must be relative (start with './'). Got: ${path}`
+                );
+            }
+        }
+    }
+
+    // Validate extends if provided
+    if (definition.extends) {
+        if (typeof definition.extends !== 'string') {
+            throw new Error('Image extends must be a string (parent image name)');
+        }
+    }
+}

package/src/index.ts

@@ -2,8 +2,9 @@
  * @dexto/bundler
  *
  * Bundles Dexto base images from dexto.image.ts definitions
- * into importable packages with side-effect provider registration.
+ * into importable packages exporting a typed `DextoImage` (no side effects).
  */
 
 export { bundle } from './bundler.js';
 export type { BundleOptions, BundleResult, GeneratedCode } from './types.js';
+export type { ImageDefinition, ImageMetadata } from './image-definition/types.js';

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ImageDefinition, ImageMetadata } from '@dexto/core';
+import type { ImageMetadata } from './image-definition/types.js';
 
 export interface BundleOptions {
     /** Path to dexto.image.ts file */