@dexto/image-bundler 1.5.7 → 1.6.0

package/dist/cli.js

@@ -5,153 +5,168 @@ import { Command } from "commander";
 
 // src/bundler.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from "fs";
+import { mkdtemp, rm } from "fs/promises";
+import { createRequire } from "module";
 import { dirname, join, resolve, extname } from "path";
 import { pathToFileURL } from "url";
-import { validateImageDefinition } from "@dexto/core";
+
+// src/image-definition/validate-image-definition.ts
+function validateImageDefinition(definition) {
+  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");
+  }
+  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`
+    );
+  }
+  if (definition.target !== void 0) {
+    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`);
+      }
+    }
+  }
+  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}`
+        );
+      }
+    }
+  }
+  if (definition.extends) {
+    if (typeof definition.extends !== "string") {
+      throw new Error("Image extends must be a string (parent image name)");
+    }
+  }
+}
 
 // src/generator.ts
-function generateEntryPoint(definition, coreVersion, discoveredProviders) {
-  const imports = generateImports(definition, discoveredProviders);
-  const registrations = generateProviderRegistrations(definition, discoveredProviders);
-  const factory = generateFactory();
+function generateEntryPoint(definition, discoveredFactories) {
+  const imports = generateImports(definition, discoveredFactories);
+  const helpers = definition.extends ? generateHelpers() : "";
+  const imageModule = generateImageModule(definition, discoveredFactories);
   const utilityExports = generateUtilityExports(definition);
-  const metadata = generateMetadata(definition, coreVersion);
-  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}
 `;
   const dts = generateTypeDefinitions(definition);
   return { js, dts };
 }
-function generateImports(definition, discoveredProviders) {
+function sanitizeIdentifier(value) {
+  const sanitized = value.replace(/[^a-zA-Z0-9_$]/g, "_");
+  if (/^[a-zA-Z_$]/.test(sanitized)) {
+    return sanitized;
+  }
+  return `_${sanitized}`;
+}
+function toFactoryImportSymbol(prefix, type) {
+  return sanitizeIdentifier(`${prefix}_${type}`);
+}
+function generateImports(definition, discoveredFactories) {
   const imports = [];
   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}';`);
   }
-  imports.push(`import { DextoAgent } from '@dexto/core';`);
-  imports.push(
-    `import { customToolRegistry, pluginRegistry, compactionRegistry, blobStoreRegistry } from '@dexto/core';`
+  imports.push(`import { defaultLoggerFactory } from '@dexto/core';`);
+  const toolProviders = [...discoveredFactories.tools].sort(
+    (a, b) => a.type.localeCompare(b.type)
   );
-  if (discoveredProviders) {
-    const categories = [
-      { key: "blobStore", label: "Blob Storage" },
-      { key: "customTools", label: "Custom Tools" },
-      { key: "compaction", label: "Compaction" },
-      { key: "plugins", label: "Plugins" }
-    ];
-    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}';`);
-        });
-      }
-    }
+  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)
+  );
+  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, discoveredProviders) {
-  const registrations = [];
-  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("");
-  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" }
-    ];
-    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(\`\u2713 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 toolProviders) {
+    const symbol = toFactoryImportSymbol("tools", entry.type);
+    imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
   }
-  for (const [category, config] of Object.entries(definition.providers)) {
-    if (!config) continue;
-    if (config.register) {
-      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 hookProviders) {
+    const symbol = toFactoryImportSymbol("hooks", entry.type);
+    imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
+  }
+  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}';`);
   }
-  return registrations.join("\n");
+  for (const entry of cacheProviders) {
+    const symbol = toFactoryImportSymbol("storage_cache", entry.type);
+    imports.push(`import { factory as ${symbol} } from '${entry.importPath}';`);
+  }
+  return imports.join("\n");
 }
-function generateFactory() {
-  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() {
+  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) {
   const sections = [];
@@ -182,27 +197,92 @@ function generateUtilityExports(definition) {
   }
   return sections.join("\n");
 }
-function generateMetadata(definition, coreVersion) {
-  const metadata = {
-    name: definition.name,
-    version: definition.version,
-    description: definition.description,
-    target: definition.target || "custom",
-    constraints: definition.constraints || [],
-    builtAt: (/* @__PURE__ */ new Date()).toISOString(),
-    coreVersion
-  };
-  if (definition.extends) {
-    metadata.extends = definition.extends;
+function generateImageModule(definition, discoveredFactories) {
+  const derivedDefaults = definition.defaults !== void 0 ? 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 = [];
+  metadataLines.push(`        name: ${JSON.stringify(definition.name)},`);
+  metadataLines.push(`        version: ${JSON.stringify(definition.version)},`);
+  metadataLines.push(`        description: ${JSON.stringify(definition.description)},`);
+  if (definition.target !== void 0) {
+    metadataLines.push(`        target: ${JSON.stringify(definition.target)},`);
+  } else if (definition.extends) {
+    metadataLines.push(`        target: baseImage.metadata.target,`);
   }
-  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 !== void 0) {
+    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,
+` : "";
+  const hooksSpread = definition.extends ? `        ...baseImage.hooks,
+` : "";
+  const compactionSpread = definition.extends ? `        ...baseImage.compaction,
+` : "";
+  const blobSpread = definition.extends ? `            ...baseImage.storage.blob,
+` : "";
+  const databaseSpread = definition.extends ? `            ...baseImage.storage.database,
+` : "";
+  const cacheSpread = definition.extends ? `            ...baseImage.storage.cache,
+` : "";
+  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) {
   const sections = [];
@@ -229,31 +309,19 @@ function generateTypeDefinitions(definition) {
   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}
+	`;
 }
 
 // src/bundler.ts
+import { build } from "esbuild";
 import ts from "typescript";
 async function bundle(options) {
   const warnings = [];
@@ -268,31 +336,55 @@ async function bundle(options) {
     throw new Error(`Image validation failed: ${error}`);
   }
   const coreVersion = getCoreVersion();
-  console.log(`\u{1F50D} Discovering providers from folders...`);
+  console.log(`\u{1F50D} Discovering factories from folders...`);
   const imageDir = dirname(options.imagePath);
-  const discoveredProviders = discoverProviders(imageDir);
-  console.log(`\u2705 Discovered ${discoveredProviders.totalCount} provider(s)`);
+  const discoveredFactories = discoverFactories(imageDir, warnings);
+  console.log(`\u2705 Discovered ${discoveredFactories.totalCount} factory(ies)`);
   console.log(`\u{1F528} Generating entry point...`);
-  const generated = generateEntryPoint(definition, coreVersion, discoveredProviders);
+  const generated = generateEntryPoint(definition, discoveredFactories);
   const outDir = resolve(options.outDir);
   if (!existsSync(outDir)) {
     mkdirSync(outDir, { recursive: true });
   }
-  console.log(`\u{1F528} Compiling provider source files...`);
-  const categories = ["blob-store", "tools", "compaction", "plugins"];
+  console.log(`\u{1F528} Compiling factory source files...`);
   let compiledCount = 0;
-  for (const category of categories) {
-    const categoryDir = join(imageDir, category);
-    if (existsSync(categoryDir)) {
-      compileSourceFiles(categoryDir, join(outDir, category));
-      compiledCount++;
-    }
+  const toolsDir = join(imageDir, "tools");
+  if (existsSync(toolsDir)) {
+    compileSourceFiles(toolsDir, join(outDir, "tools"));
+    compiledCount++;
+  }
+  const hooksDir = join(imageDir, "hooks");
+  if (existsSync(hooksDir)) {
+    compileSourceFiles(hooksDir, join(outDir, "hooks"));
+    compiledCount++;
+  }
+  const compactionDir = join(imageDir, "compaction");
+  if (existsSync(compactionDir)) {
+    compileSourceFiles(compactionDir, join(outDir, "compaction"));
+    compiledCount++;
+  }
+  const storageBlobDir = join(imageDir, "storage", "blob");
+  if (existsSync(storageBlobDir)) {
+    compileSourceFiles(storageBlobDir, join(outDir, "storage", "blob"));
+    compiledCount++;
+  }
+  const storageDatabaseDir = join(imageDir, "storage", "database");
+  if (existsSync(storageDatabaseDir)) {
+    compileSourceFiles(storageDatabaseDir, join(outDir, "storage", "database"));
+    compiledCount++;
+  }
+  const storageCacheDir = join(imageDir, "storage", "cache");
+  if (existsSync(storageCacheDir)) {
+    compileSourceFiles(storageCacheDir, join(outDir, "storage", "cache"));
+    compiledCount++;
   }
   if (compiledCount > 0) {
     console.log(
-      `\u2705 Compiled ${compiledCount} provider categor${compiledCount === 1 ? "y" : "ies"}`
+      `\u2705 Compiled ${compiledCount} factory categor${compiledCount === 1 ? "y" : "ies"}`
     );
   }
+  console.log(`\u{1F50D} Validating factory exports...`);
+  await validateDiscoveredFactories(outDir, discoveredFactories);
   const entryFile = join(outDir, "index.js");
   const typesFile = join(outDir, "index.d.ts");
   console.log(`\u{1F4DD} Writing ${entryFile}...`);
@@ -325,13 +417,29 @@ async function loadImageDefinition(imagePath) {
     throw new Error(`Image file not found: ${absolutePath}`);
   }
   try {
-    const fileUrl = pathToFileURL(absolutePath).href;
-    const module = await import(fileUrl);
-    const definition = module.default;
-    if (!definition) {
-      throw new Error("Image file must have a default export");
+    const imageDir = dirname(absolutePath);
+    const tempDir = await mkdtemp(join(imageDir, ".dexto-image-definition-"));
+    const compiledPath = join(tempDir, "dexto.image.mjs");
+    try {
+      await build({
+        entryPoints: [absolutePath],
+        outfile: compiledPath,
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        target: "node20",
+        packages: "external",
+        logLevel: "silent"
+      });
+      const module = await import(pathToFileURL(compiledPath).href);
+      const definition = module.default;
+      if (!definition) {
+        throw new Error("Image file must have a default export");
+      }
+      return definition;
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
     }
-    return definition;
   } catch (error) {
     if (error instanceof Error) {
       throw new Error(`Failed to load image definition: ${error.message}`);
@@ -341,12 +449,9 @@ async function loadImageDefinition(imagePath) {
 }
 function getCoreVersion() {
   try {
-    const corePackageJson = join(process.cwd(), "node_modules/@dexto/core/package.json");
-    if (existsSync(corePackageJson)) {
-      const pkg = JSON.parse(readFileSync(corePackageJson, "utf-8"));
-      return pkg.version;
-    }
-    return "1.0.0";
+    const require2 = createRequire(import.meta.url);
+    const pkg = require2("@dexto/core/package.json");
+    return typeof pkg.version === "string" ? pkg.version : "1.0.0";
   } catch {
     return "1.0.0";
   }
@@ -435,58 +540,144 @@ function findTypeScriptFiles(dir) {
   walk(dir);
   return files;
 }
-function discoverProviders(imageDir) {
+function discoverFactories(imageDir, warnings) {
   const result = {
-    blobStore: [],
-    customTools: [],
+    tools: [],
+    storage: {
+      blob: [],
+      database: [],
+      cache: []
+    },
+    hooks: [],
     compaction: [],
-    plugins: [],
     totalCount: 0
   };
-  const categories = {
-    "blob-store": "blobStore",
-    tools: "customTools",
-    compaction: "compaction",
-    plugins: "plugins"
-  };
-  for (const [folderName, propName] of Object.entries(categories)) {
-    const categoryDir = join(imageDir, folderName);
-    if (!existsSync(categoryDir)) {
-      continue;
+  const discoverFolder = (options) => {
+    const { srcDir, importBase, label } = options;
+    if (!existsSync(srcDir)) {
+      return [];
     }
-    const providerFolders = readdirSync(categoryDir).filter((entry) => {
-      const entryPath = join(categoryDir, entry);
+    const factoryFolders = readdirSync(srcDir).filter((entry) => {
+      const entryPath = join(srcDir, entry);
       const stat = statSync(entryPath);
       if (!stat.isDirectory()) {
         return false;
       }
       const indexPath = join(entryPath, "index.ts");
       return existsSync(indexPath);
-    }).map((folder) => {
-      return `./${folderName}/${folder}/index.js`;
     });
-    if (providerFolders.length > 0) {
-      result[propName].push(
-        ...providerFolders
-      );
-      result.totalCount += providerFolders.length;
-      console.log(`   Found ${providerFolders.length} provider(s) in ${folderName}/`);
+    if (factoryFolders.length > 0) {
+      console.log(`   Found ${factoryFolders.length} factory(ies) in ${label}`);
     }
+    return factoryFolders.map((type) => ({
+      type,
+      importPath: `./${importBase}/${type}/index.js`
+    }));
+  };
+  result.tools = discoverFolder({
+    srcDir: join(imageDir, "tools"),
+    importBase: "tools",
+    label: "tools/"
+  });
+  result.hooks = discoverFolder({
+    srcDir: join(imageDir, "hooks"),
+    importBase: "hooks",
+    label: "hooks/"
+  });
+  result.compaction = discoverFolder({
+    srcDir: join(imageDir, "compaction"),
+    importBase: "compaction",
+    label: "compaction/"
+  });
+  result.storage.blob = discoverFolder({
+    srcDir: join(imageDir, "storage", "blob"),
+    importBase: "storage/blob",
+    label: "storage/blob/"
+  });
+  result.storage.database = discoverFolder({
+    srcDir: join(imageDir, "storage", "database"),
+    importBase: "storage/database",
+    label: "storage/database/"
+  });
+  result.storage.cache = discoverFolder({
+    srcDir: join(imageDir, "storage", "cache"),
+    importBase: "storage/cache",
+    label: "storage/cache/"
+  });
+  result.totalCount = result.tools.length + result.hooks.length + result.compaction.length + result.storage.blob.length + result.storage.database.length + result.storage.cache.length;
+  if (result.totalCount === 0) {
+    warnings.push(
+      "No factories discovered from convention folders. This image will not be able to resolve tools/storage unless it extends a base image."
+    );
   }
   return result;
 }
+async function validateFactoryExport(options) {
+  const { outDir, kind, entry } = options;
+  const absolutePath = resolve(outDir, entry.importPath);
+  const fileUrl = pathToFileURL(absolutePath).href;
+  let module;
+  try {
+    module = await import(fileUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to import ${kind} factory '${entry.type}' (${entry.importPath}): ${message}`
+    );
+  }
+  if (!module || typeof module !== "object") {
+    throw new Error(
+      `Invalid ${kind} factory '${entry.type}' (${entry.importPath}): expected an object module export`
+    );
+  }
+  const factory = module.factory;
+  if (!factory || typeof factory !== "object") {
+    throw new Error(
+      `Invalid ${kind} factory '${entry.type}' (${entry.importPath}): missing 'factory' export`
+    );
+  }
+  const configSchema = factory.configSchema;
+  const create = factory.create;
+  const parse = configSchema?.parse;
+  if (!configSchema || typeof configSchema !== "object" || typeof parse !== "function") {
+    throw new Error(
+      `Invalid ${kind} factory '${entry.type}' (${entry.importPath}): factory.configSchema must be a Zod schema`
+    );
+  }
+  if (typeof create !== "function") {
+    throw new Error(
+      `Invalid ${kind} factory '${entry.type}' (${entry.importPath}): factory.create must be a function`
+    );
+  }
+}
+async function validateDiscoveredFactories(outDir, discovered) {
+  const validations = [];
+  for (const entry of discovered.tools) {
+    validations.push(validateFactoryExport({ outDir, kind: "tool", entry }));
+  }
+  for (const entry of discovered.hooks) {
+    validations.push(validateFactoryExport({ outDir, kind: "hook", entry }));
+  }
+  for (const entry of discovered.compaction) {
+    validations.push(validateFactoryExport({ outDir, kind: "compaction", entry }));
+  }
+  for (const entry of discovered.storage.blob) {
+    validations.push(validateFactoryExport({ outDir, kind: "storage.blob", entry }));
+  }
+  for (const entry of discovered.storage.database) {
+    validations.push(validateFactoryExport({ outDir, kind: "storage.database", entry }));
+  }
+  for (const entry of discovered.storage.cache) {
+    validations.push(validateFactoryExport({ outDir, kind: "storage.cache", entry }));
+  }
+  await Promise.all(validations);
+}
 
 // src/cli.ts
 import { readFileSync as readFileSync2 } from "fs";
 import { join as join2, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 import pc from "picocolors";
-process.removeAllListeners("warning");
-process.on("warning", (warning) => {
-  if (warning.name !== "ExperimentalWarning") {
-    console.warn(warning);
-  }
-});
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname2(__filename2);
 var packageJson = JSON.parse(readFileSync2(join2(__dirname2, "../package.json"), "utf-8"));
@@ -525,15 +716,14 @@ program.command("build").description("Build a base image from dexto.image.ts").o
     } catch {
     }
     console.log(pc.green("\n\u2705 Image is ready to use!"));
-    console.log("   To use this image in an app:");
+    console.log("   Install into the Dexto CLI:");
+    console.log(pc.dim("   1. Install:    dexto image install ."));
     console.log(
       pc.dim(
-        `   1. Install it: pnpm add ${packageName}@file:../${packageName.split("/").pop()}`
+        `   2. Use it:     set \`image: "${packageName}"\` in your agent config (or pass --image in the CLI)`
       )
     );
-    console.log(pc.dim(`   2. Import it:  import { createAgent } from '${packageName}';`));
-    console.log(pc.dim(`
-   Or publish to npm and install normally.`));
+    console.log(pc.dim("\n   Or publish to npm and install by package name."));
   } catch (error) {
     console.error(pc.red("\n\u274C Build failed:"), error);
     process.exit(1);