@dexto/image-bundler 1.5.0

package/src/generator.ts

@@ -0,0 +1,331 @@
+/**
+ * Code generator for base images
+ *
+ * Transforms image definitions into importable packages with:
+ * - Side-effect provider registration
+ * - createAgent() factory
+ * - Utility exports
+ * - Metadata exports
+ */
+
+import type { ImageDefinition } from '@dexto/core';
+import type { GeneratedCode } from './types.js';
+import type { DiscoveredProviders } from './bundler.js';
+
+/**
+ * Generate JavaScript entry point for an image
+ */
+export function generateEntryPoint(
+    definition: ImageDefinition,
+    coreVersion: string,
+    discoveredProviders?: DiscoveredProviders
+): 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 utilityExports = generateUtilityExports(definition);
+
+    // Generate metadata export
+    const metadata = generateMetadata(definition, coreVersion);
+
+    // Combine all sections
+    const js = `// AUTO-GENERATED by @dexto/bundler
+// Do not edit this file directly. Edit dexto.image.ts instead.
+
+${imports}
+
+${registrations}
+
+${factory}
+
+${utilityExports}
+
+${metadata}
+`;
+
+    // Generate TypeScript definitions
+    const dts = generateTypeDefinitions(definition);
+
+    return { js, dts };
+}
+
+function generateImports(
+    definition: ImageDefinition,
+    discoveredProviders?: DiscoveredProviders
+): 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(``);
+    }
+
+    // Core imports
+    imports.push(`import { DextoAgent } 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';`
+    );
+
+    // 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}';`);
+                });
+            }
+        }
+    }
+
+    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('');
+    }
+
+    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('');
+        }
+    }
+
+    // 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('');
+        }
+    }
+
+    return registrations.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);
+}
+
+/**
+ * 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 generateUtilityExports(definition: ImageDefinition): string {
+    const sections: string[] = [];
+
+    // Generate wildcard utility exports
+    if (definition.utils && Object.keys(definition.utils).length > 0) {
+        sections.push('// Utility exports');
+        for (const [name, path] of Object.entries(definition.utils)) {
+            sections.push(`export * from '${path}';`);
+        }
+    }
+
+    // Generate selective named exports (filter out type-only exports for runtime JS)
+    if (definition.exports && Object.keys(definition.exports).length > 0) {
+        if (sections.length > 0) sections.push('');
+        sections.push('// Selective package re-exports');
+        for (const [packageName, exports] of Object.entries(definition.exports)) {
+            // Check for wildcard re-export
+            if (exports.length === 1 && exports[0] === '*') {
+                sections.push(`export * from '${packageName}';`);
+                continue;
+            }
+
+            // Filter out type-only exports (those starting with 'type ')
+            const runtimeExports = exports.filter((exp) => !exp.startsWith('type '));
+            if (runtimeExports.length > 0) {
+                sections.push(`export {`);
+                sections.push(`    ${runtimeExports.join(',\n    ')}`);
+                sections.push(`} from '${packageName}';`);
+            }
+        }
+    }
+
+    if (sections.length === 0) {
+        return '// No utilities or exports defined for this image';
+    }
+
+    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;
+    }
+
+    return `/**
+ * Image metadata
+ * Generated at build time
+ */
+export const imageMetadata = ${JSON.stringify(metadata, null, 4)};`;
+}
+
+function generateTypeDefinitions(definition: ImageDefinition): string {
+    const sections: string[] = [];
+
+    // Wildcard utility exports
+    if (definition.utils && Object.keys(definition.utils).length > 0) {
+        sections.push('// Utility re-exports');
+        for (const path of Object.values(definition.utils)) {
+            sections.push(`export * from '${path}';`);
+        }
+    }
+
+    // Selective named exports
+    if (definition.exports && Object.keys(definition.exports).length > 0) {
+        if (sections.length > 0) sections.push('');
+        sections.push('// Selective package re-exports');
+        for (const [packageName, exports] of Object.entries(definition.exports)) {
+            // Check for wildcard re-export
+            if (exports.length === 1 && exports[0] === '*') {
+                sections.push(`export * from '${packageName}';`);
+                continue;
+            }
+
+            sections.push(`export {`);
+            sections.push(`    ${exports.join(',\n    ')}`);
+            sections.push(`} from '${packageName}';`);
+        }
+    }
+
+    const utilityExports = sections.length > 0 ? '\n\n' + sections.join('\n') : '';
+
+    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;
+
+/**
+ * Re-exported registries for runtime customization
+ */
+export {
+    customToolRegistry,
+    pluginRegistry,
+    compactionRegistry,
+    blobStoreRegistry,
+} from '@dexto/core';${utilityExports}
+`;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @dexto/bundler
+ *
+ * Bundles Dexto base images from dexto.image.ts definitions
+ * into importable packages with side-effect provider registration.
+ */
+
+export { bundle } from './bundler.js';
+export type { BundleOptions, BundleResult, GeneratedCode } from './types.js';

package/src/types.ts

@@ -0,0 +1,30 @@
+import type { ImageDefinition, ImageMetadata } from '@dexto/core';
+
+export interface BundleOptions {
+    /** Path to dexto.image.ts file */
+    imagePath: string;
+    /** Output directory for built image */
+    outDir: string;
+    /** Whether to generate source maps */
+    sourcemap?: boolean;
+    /** Whether to minify output */
+    minify?: boolean;
+}
+
+export interface BundleResult {
+    /** Path to generated entry file */
+    entryFile: string;
+    /** Path to generated types file */
+    typesFile: string;
+    /** Image metadata */
+    metadata: ImageMetadata;
+    /** Warnings encountered during build */
+    warnings: string[];
+}
+
+export interface GeneratedCode {
+    /** Generated JavaScript code */
+    js: string;
+    /** Generated TypeScript definitions */
+    dts: string;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts', 'src/cli.ts'],
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    sourcemap: true,
+    splitting: false,
+    shims: true,
+    external: ['typescript', '@dexto/core', 'picocolors', 'commander'],
+    noExternal: [],
+});