@jay-framework/jay-stack-cli 0.10.0 → 0.12.0

package/dist/index.js

@@ -1,17 +1,21 @@
 #!/usr/bin/env node
 import express from "express";
-import { mkDevServer } from "@jay-framework/dev-server";
+import { mkDevServer, createViteForCli } from "@jay-framework/dev-server";
 import { createEditorServer } from "@jay-framework/editor-server";
 import getPort from "get-port";
 import path from "path";
-import fs from "fs";
+import fs, { promises } from "fs";
 import YAML from "yaml";
+import { getLogger, createDevLogger, setDevLogger } from "@jay-framework/logger";
 import { parse } from "node-html-parser";
 import { createRequire } from "module";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseContract, ContractTagType } from "@jay-framework/compiler-jay-html";
-import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, JayAtomicType, JayEnumType, loadPluginManifest } from "@jay-framework/compiler-shared";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, parseContract, ContractTagType, generateElementFile } from "@jay-framework/compiler-jay-html";
+import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, JayAtomicType, JayEnumType, loadPluginManifest, RuntimeMode, GenerateTarget } from "@jay-framework/compiler-shared";
+import { listContracts, materializeContracts } from "@jay-framework/stack-server-runtime";
+import { listContracts as listContracts2, materializeContracts as materializeContracts2 } from "@jay-framework/stack-server-runtime";
 import { Command } from "commander";
 import chalk from "chalk";
+import { glob } from "glob";
 const DEFAULT_CONFIG = {
   devServer: {
     portRange: [3e3, 3100],
@@ -43,7 +47,7 @@ function loadConfig() {
       }
     };
   } catch (error) {
-    console.warn("Failed to parse .jay YAML config file, using defaults:", error);
+    getLogger().warn(`Failed to parse .jay YAML config file, using defaults: ${error}`);
     return DEFAULT_CONFIG;
   }
 }
@@ -81,7 +85,7 @@ function updateConfig(updates) {
     const yamlContent = YAML.stringify(updatedConfig, { indent: 2 });
     fs.writeFileSync(configPath, yamlContent);
   } catch (error) {
-    console.warn("Failed to update .jay config file:", error);
+    getLogger().warn(`Failed to update .jay config file: ${error}`);
   }
 }
 const PAGE_FILENAME = `page${JAY_EXTENSION}`;
@@ -157,7 +161,7 @@ async function scanPageDirectories(pagesBasePath, onPageFound) {
         }
       }
     } catch (error) {
-      console.warn(`Failed to scan directory ${dirPath}:`, error);
+      getLogger().warn(`Failed to scan directory ${dirPath}: ${error}`);
     }
   }
   await scanDirectory(pagesBasePath);
@@ -167,9 +171,8 @@ async function parseContractFile(contractFilePath) {
     const contractYaml = await fs.promises.readFile(contractFilePath, "utf-8");
     const parsedContract = parseContract(contractYaml, contractFilePath);
     if (parsedContract.validations.length > 0) {
-      console.warn(
-        `Contract validation errors in ${contractFilePath}:`,
-        parsedContract.validations
+      getLogger().warn(
+        `Contract validation errors in ${contractFilePath}: ${parsedContract.validations.join(", ")}`
       );
     }
     if (parsedContract.val) {
@@ -183,7 +186,7 @@ async function parseContractFile(contractFilePath) {
       };
     }
   } catch (error) {
-    console.warn(`Failed to parse contract file ${contractFilePath}:`, error);
+    getLogger().warn(`Failed to parse contract file ${contractFilePath}: ${error}`);
   }
   return null;
 }
@@ -209,11 +212,11 @@ async function resolveLinkedTags(tags, baseDir) {
           }
           resolvedTags.push(resolvedTag);
         } else {
-          console.warn(`Failed to load linked contract: ${tag.link} from ${baseDir}`);
+          getLogger().warn(`Failed to load linked contract: ${tag.link} from ${baseDir}`);
           resolvedTags.push(convertContractTagToProtocol(tag));
         }
       } catch (error) {
-        console.warn(`Error resolving linked contract ${tag.link}:`, error);
+        getLogger().warn(`Error resolving linked contract ${tag.link}: ${error}`);
         resolvedTags.push(convertContractTagToProtocol(tag));
       }
     } else if (tag.tags) {
@@ -234,9 +237,8 @@ function resolveAppContractPath(appModule, contractFileName, projectRootPath) {
     const resolvedPath = require2.resolve(modulePath);
     return resolvedPath;
   } catch (error) {
-    console.warn(
-      `Failed to resolve contract: ${appModule}/${contractFileName}`,
-      error instanceof Error ? error.message : error
+    getLogger().warn(
+      `Failed to resolve contract: ${appModule}/${contractFileName} - ${error instanceof Error ? error.message : error}`
     );
     return null;
   }
@@ -315,12 +317,12 @@ async function scanInstalledAppContracts(configBasePath, projectRootPath) {
             installedAppContracts[appName] = appContracts;
           }
         } catch (error) {
-          console.warn(`Failed to parse app config ${appConfigPath}:`, error);
+          getLogger().warn(`Failed to parse app config ${appConfigPath}: ${error}`);
         }
       }
     }
   } catch (error) {
-    console.warn(`Failed to scan installed apps directory ${installedAppsPath}:`, error);
+    getLogger().warn(`Failed to scan installed apps directory ${installedAppsPath}: ${error}`);
   }
   return installedAppContracts;
 }
@@ -419,7 +421,7 @@ async function scanProjectComponents(componentsBasePath) {
       }
     }
   } catch (error) {
-    console.warn(`Failed to scan components directory ${componentsBasePath}:`, error);
+    getLogger().warn(`Failed to scan components directory ${componentsBasePath}: ${error}`);
   }
   return components;
 }
@@ -447,12 +449,12 @@ async function scanInstalledApps(configBasePath) {
             });
           }
         } catch (error) {
-          console.warn(`Failed to parse app config ${appConfigPath}:`, error);
+          getLogger().warn(`Failed to parse app config ${appConfigPath}: ${error}`);
         }
       }
     }
   } catch (error) {
-    console.warn(`Failed to scan installed apps directory ${installedAppsPath}:`, error);
+    getLogger().warn(`Failed to scan installed apps directory ${installedAppsPath}: ${error}`);
   }
   return installedApps;
 }
@@ -465,7 +467,7 @@ async function getProjectName(configBasePath) {
       return projectConfig.name || "Unnamed Project";
     }
   } catch (error) {
-    console.warn(`Failed to read project config ${projectConfigPath}:`, error);
+    getLogger().warn(`Failed to read project config ${projectConfigPath}: ${error}`);
   }
   return "Unnamed Project";
 }
@@ -492,12 +494,14 @@ async function scanPlugins(projectRootPath) {
               }
             });
           } catch (error) {
-            console.warn(`Failed to parse plugin.yaml for ${dir.name}:`, error);
+            getLogger().warn(`Failed to parse plugin.yaml for ${dir.name}: ${error}`);
           }
         }
       }
     } catch (error) {
-      console.warn(`Failed to scan local plugins directory ${localPluginsPath}:`, error);
+      getLogger().warn(
+        `Failed to scan local plugins directory ${localPluginsPath}: ${error}`
+      );
     }
   }
   const nodeModulesPath = path.join(projectRootPath, "node_modules");
@@ -548,16 +552,15 @@ async function scanPlugins(projectRootPath) {
                 }
               });
             } catch (error) {
-              console.warn(
-                `Failed to parse plugin.yaml for package ${pkgPath}:`,
-                error
+              getLogger().warn(
+                `Failed to parse plugin.yaml for package ${pkgPath}: ${error}`
               );
             }
           }
         }
       }
     } catch (error) {
-      console.warn(`Failed to scan node_modules for plugins:`, error);
+      getLogger().warn(`Failed to scan node_modules for plugins: ${error}`);
     }
   }
   return plugins;
@@ -585,7 +588,7 @@ async function scanProjectInfo(pagesBasePath, componentsBasePath, configBasePath
           contractSchema = parsedContract;
         }
       } catch (error) {
-        console.warn(`Failed to parse contract file ${contractPath}:`, error);
+        getLogger().warn(`Failed to parse contract file ${contractPath}: ${error}`);
       }
     }
     if (hasPageHtml) {
@@ -597,7 +600,7 @@ async function scanProjectInfo(pagesBasePath, componentsBasePath, configBasePath
           installedAppContracts
         );
       } catch (error) {
-        console.warn(`Failed to read page file ${pageFilePath}:`, error);
+        getLogger().warn(`Failed to read page file ${pageFilePath}: ${error}`);
       }
     } else if (hasPageConfig) {
       try {
@@ -698,7 +701,7 @@ async function scanProjectInfo(pagesBasePath, componentsBasePath, configBasePath
           }
         }
       } catch (error) {
-        console.warn(`Failed to parse page config ${pageConfigPath}:`, error);
+        getLogger().warn(`Failed to parse page config ${pageConfigPath}: ${error}`);
       }
     }
     pages.push({
@@ -731,7 +734,7 @@ async function handlePagePublish(resolvedConfig, page) {
     if (page.contract) {
       contractPath = path.join(dirname, `page${JAY_CONTRACT_EXTENSION}`);
       await fs.promises.writeFile(contractPath, page.contract, "utf-8");
-      console.log(`📄 Published page contract: ${contractPath}`);
+      getLogger().info(`📄 Published page contract: ${contractPath}`);
     }
     const createdJayHtml = {
       jayHtml: page.jayHtml,
@@ -739,7 +742,7 @@ async function handlePagePublish(resolvedConfig, page) {
       dirname,
       fullPath
     };
-    console.log(`📝 Published page: ${fullPath}`);
+    getLogger().info(`📝 Published page: ${fullPath}`);
     return [
       {
         success: true,
@@ -749,7 +752,7 @@ async function handlePagePublish(resolvedConfig, page) {
       createdJayHtml
     ];
   } catch (error) {
-    console.error(`Failed to publish page ${page.route}:`, error);
+    getLogger().error(`Failed to publish page ${page.route}: ${error}`);
     return [
       {
         success: false,
@@ -777,7 +780,7 @@ async function handleComponentPublish(resolvedConfig, component) {
       dirname,
       fullPath
     };
-    console.log(`🧩 Published component: ${fullPath}`);
+    getLogger().info(`🧩 Published component: ${fullPath}`);
     return [
       {
         success: true,
@@ -787,7 +790,7 @@ async function handleComponentPublish(resolvedConfig, component) {
       createdJayHtml
     ];
   } catch (error) {
-    console.error(`Failed to publish component ${component.name}:`, error);
+    getLogger().error(`Failed to publish component ${component.name}: ${error}`);
     return [
       {
         success: false,
@@ -831,7 +834,7 @@ function createEditorHandlers(config, tsConfigPath, projectRoot) {
       );
       const definitionFile = generateElementDefinitionFile(parsedJayHtml);
       if (definitionFile.validations.length > 0)
-        console.log(
+        getLogger().warn(
           `failed to generate .d.ts for ${fullPath} with validation errors: ${definitionFile.validations.join("\n")}`
         );
       else
@@ -850,14 +853,14 @@ function createEditorHandlers(config, tsConfigPath, projectRoot) {
       const filename = `${params.imageId}.png`;
       const imagePath = path.join(imagesDir, filename);
       await fs.promises.writeFile(imagePath, Buffer.from(params.imageData, "base64"));
-      console.log(`🖼️  Saved image: ${imagePath}`);
+      getLogger().info(`🖼️  Saved image: ${imagePath}`);
       return {
         type: "saveImage",
         success: true,
         imageUrl: `/images/${filename}`
       };
     } catch (error) {
-      console.error("Failed to save image:", error);
+      getLogger().error(`Failed to save image: ${error}`);
       return {
         type: "saveImage",
         success: false,
@@ -881,7 +884,7 @@ function createEditorHandlers(config, tsConfigPath, projectRoot) {
         imageUrl: exists ? `/images/${filename}` : void 0
       };
     } catch (error) {
-      console.error("Failed to check image:", error);
+      getLogger().error(`Failed to check image: ${error}`);
       return {
         type: "hasImage",
         success: false,
@@ -902,18 +905,18 @@ function createEditorHandlers(config, tsConfigPath, projectRoot) {
         configBasePath,
         projectRootPath
       );
-      console.log(`📋 Retrieved project info: ${info.name}`);
-      console.log(`   Pages: ${info.pages.length}`);
-      console.log(`   Components: ${info.components.length}`);
-      console.log(`   Installed Apps: ${info.installedApps.length}`);
-      console.log(`   App Contracts: ${Object.keys(info.installedAppContracts).length}`);
+      getLogger().info(`📋 Retrieved project info: ${info.name}`);
+      getLogger().info(`   Pages: ${info.pages.length}`);
+      getLogger().info(`   Components: ${info.components.length}`);
+      getLogger().info(`   Installed Apps: ${info.installedApps.length}`);
+      getLogger().info(`   App Contracts: ${Object.keys(info.installedAppContracts).length}`);
       return {
         type: "getProjectInfo",
         success: true,
         info
       };
     } catch (error) {
-      console.error("Failed to get project info:", error);
+      getLogger().error(`Failed to get project info: ${error}`);
       return {
         type: "getProjectInfo",
         success: false,
@@ -968,16 +971,16 @@ async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
       );
       const definitionFile = generateElementDefinitionFile(parsedJayHtml);
       if (definitionFile.validations.length > 0) {
-        console.log(
+        getLogger().warn(
           `failed to generate .d.ts for ${jayHtmlPath} with validation errors: ${definitionFile.validations.join("\n")}`
         );
       } else {
         const definitionFilePath2 = jayHtmlPath + ".d.ts";
         await fs.promises.writeFile(definitionFilePath2, definitionFile.val, "utf-8");
-        console.log(`📦 Generated definition file: ${definitionFilePath2}`);
+        getLogger().info(`📦 Generated definition file: ${definitionFilePath2}`);
       }
     } catch (error) {
-      console.error(`Failed to generate definition file for ${jayHtmlPath}:`, error);
+      getLogger().error(`Failed to generate definition file for ${jayHtmlPath}: ${error}`);
     }
   }
 }
@@ -994,11 +997,12 @@ async function startDevServer(options = {}) {
   };
   const app = express();
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
+  const log = getLogger();
   const editorServer = createEditorServer({
     portRange: resolvedConfig.editorServer.portRange,
     editorId: resolvedConfig.editorServer.editorId,
     onEditorId: (editorId2) => {
-      console.log(`Editor connected with ID: ${editorId2}`);
+      log.info(`Editor connected with ID: ${editorId2}`);
       updateConfig({
         editorServer: {
           editorId: editorId2
@@ -1021,35 +1025,69 @@ async function startDevServer(options = {}) {
     projectRootFolder: process.cwd(),
     publicBaseUrlPath: "/",
     dontCacheSlowly: false,
-    jayRollupConfig: jayOptions
+    jayRollupConfig: jayOptions,
+    logLevel: options.logLevel
   });
   app.use(server);
   const publicPath = path.resolve(resolvedConfig.devServer.publicFolder);
   if (fs.existsSync(publicPath)) {
     app.use(express.static(publicPath));
   } else {
-    console.log(`⚠️  Public folder not found: ${resolvedConfig.devServer.publicFolder}`);
+    log.important(`⚠️  Public folder not found: ${resolvedConfig.devServer.publicFolder}`);
   }
   routes.forEach((route) => {
     app.get(route.path, route.handler);
   });
   generatePageDefinitionFiles(routes, jayOptions.tsConfigFilePath, process.cwd());
   const expressServer = app.listen(devServerPort, () => {
-    console.log(`🚀 Jay Stack dev server started successfully!`);
-    console.log(`📱 Dev Server: http://localhost:${devServerPort}`);
-    console.log(`🎨 Editor Server: http://localhost:${editorPort} (ID: ${editorId})`);
-    console.log(`📁 Pages directory: ${resolvedConfig.devServer.pagesBase}`);
+    log.important(`🚀 Jay Stack dev server started successfully!`);
+    log.important(`📱 Dev Server: http://localhost:${devServerPort}`);
+    log.important(`🎨 Editor Server: http://localhost:${editorPort} (ID: ${editorId})`);
+    log.important(`📁 Pages directory: ${resolvedConfig.devServer.pagesBase}`);
     if (fs.existsSync(publicPath)) {
-      console.log(`📁 Public folder: ${resolvedConfig.devServer.publicFolder}`);
+      log.important(`📁 Public folder: ${resolvedConfig.devServer.publicFolder}`);
+    }
+    if (options.testMode) {
+      log.important(`🧪 Test Mode: enabled`);
+      log.important(`   Health: http://localhost:${devServerPort}/_jay/health`);
+      log.important(
+        `   Shutdown: curl -X POST http://localhost:${devServerPort}/_jay/shutdown`
+      );
+      if (options.timeout) {
+        log.important(`   Timeout: ${options.timeout}s`);
+      }
     }
   });
   const shutdown = async () => {
-    console.log("\n🛑 Shutting down servers...");
+    log.important("\n🛑 Shutting down servers...");
     await editorServer.stop();
     expressServer.closeAllConnections();
     await new Promise((resolve) => expressServer.close(resolve));
     process.exit(0);
   };
+  if (options.testMode) {
+    app.get("/_jay/health", (_req, res) => {
+      res.json({
+        status: "ready",
+        port: devServerPort,
+        editorPort,
+        uptime: process.uptime()
+      });
+    });
+    app.post("/_jay/shutdown", async (_req, res) => {
+      res.json({ status: "shutting_down" });
+      setTimeout(async () => {
+        await shutdown();
+      }, 100);
+    });
+    if (options.timeout) {
+      setTimeout(async () => {
+        log.important(`
+⏰ Timeout (${options.timeout}s) reached, shutting down...`);
+        await shutdown();
+      }, options.timeout * 1e3);
+    }
+  }
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
@@ -1207,29 +1245,33 @@ async function validateSchema(context, result) {
     }
   }
   if (manifest.dynamic_contracts) {
-    if (!manifest.dynamic_contracts.component) {
-      result.errors.push({
-        type: "schema",
-        message: 'dynamic_contracts is missing "component" field',
-        location: "plugin.yaml",
-        suggestion: "Specify path to shared component for dynamic contracts"
-      });
-    }
-    if (!manifest.dynamic_contracts.generator) {
-      result.errors.push({
-        type: "schema",
-        message: 'dynamic_contracts is missing "generator" field',
-        location: "plugin.yaml",
-        suggestion: "Specify path to generator file"
-      });
-    }
-    if (!manifest.dynamic_contracts.prefix) {
-      result.errors.push({
-        type: "schema",
-        message: 'dynamic_contracts is missing "prefix" field',
-        location: "plugin.yaml",
-        suggestion: 'Specify prefix for dynamic contract names (e.g., "cms")'
-      });
+    const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+    for (const config of dynamicConfigs) {
+      const prefix = config.prefix || "(unknown)";
+      if (!config.component) {
+        result.errors.push({
+          type: "schema",
+          message: `dynamic_contracts[${prefix}] is missing "component" field`,
+          location: "plugin.yaml",
+          suggestion: "Specify path to shared component for dynamic contracts"
+        });
+      }
+      if (!config.generator) {
+        result.errors.push({
+          type: "schema",
+          message: `dynamic_contracts[${prefix}] is missing "generator" field`,
+          location: "plugin.yaml",
+          suggestion: "Specify path to generator file or export name"
+        });
+      }
+      if (!config.prefix) {
+        result.errors.push({
+          type: "schema",
+          message: 'dynamic_contracts entry is missing "prefix" field',
+          location: "plugin.yaml",
+          suggestion: 'Specify prefix for dynamic contract names (e.g., "cms")'
+        });
+      }
     }
   }
   if (!manifest.contracts && !manifest.dynamic_contracts) {
@@ -1420,54 +1462,549 @@ async function validateDynamicContracts(context, result) {
   const { dynamic_contracts } = context.manifest;
   if (!dynamic_contracts)
     return;
-  if (dynamic_contracts.generator) {
-    const generatorPath = path.join(context.pluginPath, dynamic_contracts.generator);
-    const possibleExtensions = [".ts", ".js", "/index.ts", "/index.js"];
-    let found = false;
-    for (const ext of possibleExtensions) {
-      if (fs.existsSync(generatorPath + ext)) {
-        found = true;
-        break;
+  const dynamicConfigs = Array.isArray(dynamic_contracts) ? dynamic_contracts : [dynamic_contracts];
+  for (const config of dynamicConfigs) {
+    const prefix = config.prefix || "(unknown)";
+    if (config.generator) {
+      const isFilePath = config.generator.startsWith("./") || config.generator.startsWith("/") || config.generator.includes(".ts") || config.generator.includes(".js");
+      if (isFilePath) {
+        const generatorPath = path.join(context.pluginPath, config.generator);
+        const possibleExtensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
+        let found = false;
+        for (const ext of possibleExtensions) {
+          if (fs.existsSync(generatorPath + ext)) {
+            found = true;
+            break;
+          }
+        }
+        if (!found && !context.isNpmPackage) {
+          result.errors.push({
+            type: "file-missing",
+            message: `Generator file not found for ${prefix}: ${config.generator}`,
+            location: "plugin.yaml dynamic_contracts",
+            suggestion: `Create generator file at ${generatorPath}.ts`
+          });
+        }
       }
     }
-    if (!found && !context.isNpmPackage) {
-      result.errors.push({
-        type: "file-missing",
-        message: `Generator file not found: ${dynamic_contracts.generator}`,
-        location: "plugin.yaml dynamic_contracts",
-        suggestion: `Create generator file at ${generatorPath}.ts`
-      });
+    if (config.component) {
+      const isFilePath = config.component.startsWith("./") || config.component.startsWith("/") || config.component.includes(".ts") || config.component.includes(".js");
+      if (isFilePath) {
+        const componentPath = path.join(context.pluginPath, config.component);
+        const possibleExtensions = ["", ".ts", ".js", "/index.ts", "/index.js"];
+        let found = false;
+        for (const ext of possibleExtensions) {
+          if (fs.existsSync(componentPath + ext)) {
+            found = true;
+            break;
+          }
+        }
+        if (!found && !context.isNpmPackage) {
+          result.errors.push({
+            type: "file-missing",
+            message: `Dynamic contracts component not found for ${prefix}: ${config.component}`,
+            location: "plugin.yaml dynamic_contracts",
+            suggestion: `Create component file at ${componentPath}.ts`
+          });
+        }
+      }
     }
   }
-  if (dynamic_contracts.component) {
-    const componentPath = path.join(context.pluginPath, dynamic_contracts.component);
-    const possibleExtensions = [".ts", ".js", "/index.ts", "/index.js"];
-    let found = false;
-    for (const ext of possibleExtensions) {
-      if (fs.existsSync(componentPath + ext)) {
-        found = true;
-        break;
+}
+async function findJayFiles(dir) {
+  return await glob(`${dir}/**/*${JAY_EXTENSION}`);
+}
+async function findContractFiles(dir) {
+  return await glob(`${dir}/**/*${JAY_CONTRACT_EXTENSION}`);
+}
+async function validateJayFiles(options = {}) {
+  const config = loadConfig();
+  const resolvedConfig = getConfigWithDefaults(config);
+  const projectRoot = process.cwd();
+  const scanDir = options.path ? path.resolve(options.path) : path.resolve(resolvedConfig.devServer.pagesBase);
+  const errors = [];
+  const warnings = [];
+  const jayHtmlFiles = await findJayFiles(scanDir);
+  const contractFiles = await findContractFiles(scanDir);
+  if (options.verbose) {
+    getLogger().info(chalk.gray(`Scanning directory: ${scanDir}`));
+    getLogger().info(chalk.gray(`Found ${jayHtmlFiles.length} .jay-html files`));
+    getLogger().info(chalk.gray(`Found ${contractFiles.length} .jay-contract files
+`));
+  }
+  for (const contractFile of contractFiles) {
+    const relativePath = path.relative(projectRoot, contractFile);
+    try {
+      const content = await promises.readFile(contractFile, "utf-8");
+      const result = parseContract(content, path.basename(contractFile));
+      if (result.validations.length > 0) {
+        for (const validation of result.validations) {
+          errors.push({
+            file: relativePath,
+            message: validation,
+            stage: "parse"
+          });
+        }
+        if (options.verbose) {
+          getLogger().info(chalk.red(`❌ ${relativePath}`));
+        }
+      } else if (options.verbose) {
+        getLogger().info(chalk.green(`✓ ${relativePath}`));
+      }
+    } catch (error) {
+      errors.push({
+        file: relativePath,
+        message: error.message,
+        stage: "parse"
+      });
+      if (options.verbose) {
+        getLogger().info(chalk.red(`❌ ${relativePath}`));
       }
     }
-    if (!found && !context.isNpmPackage) {
-      result.errors.push({
-        type: "file-missing",
-        message: `Dynamic contracts component not found: ${dynamic_contracts.component}`,
-        location: "plugin.yaml dynamic_contracts",
-        suggestion: `Create component file at ${componentPath}.ts`
+  }
+  for (const jayFile of jayHtmlFiles) {
+    const relativePath = path.relative(projectRoot, jayFile);
+    const filename = path.basename(jayFile.replace(JAY_EXTENSION, ""));
+    const dirname = path.dirname(jayFile);
+    try {
+      const content = await promises.readFile(jayFile, "utf-8");
+      const parsedFile = await parseJayFile(
+        content,
+        filename,
+        dirname,
+        {},
+        JAY_IMPORT_RESOLVER,
+        projectRoot
+      );
+      if (parsedFile.validations.length > 0) {
+        for (const validation of parsedFile.validations) {
+          errors.push({
+            file: relativePath,
+            message: validation,
+            stage: "parse"
+          });
+        }
+        if (options.verbose) {
+          getLogger().info(chalk.red(`❌ ${relativePath}`));
+        }
+        continue;
+      }
+      const generatedFile = generateElementFile(
+        parsedFile.val,
+        RuntimeMode.MainTrusted,
+        GenerateTarget.jay
+      );
+      if (generatedFile.validations.length > 0) {
+        for (const validation of generatedFile.validations) {
+          errors.push({
+            file: relativePath,
+            message: validation,
+            stage: "generate"
+          });
+        }
+        if (options.verbose) {
+          getLogger().info(chalk.red(`❌ ${relativePath}`));
+        }
+      } else if (options.verbose) {
+        getLogger().info(chalk.green(`✓ ${relativePath}`));
+      }
+    } catch (error) {
+      errors.push({
+        file: relativePath,
+        message: error.message,
+        stage: "parse"
       });
+      if (options.verbose) {
+        getLogger().info(chalk.red(`❌ ${relativePath}`));
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    jayHtmlFilesScanned: jayHtmlFiles.length,
+    contractFilesScanned: contractFiles.length,
+    errors,
+    warnings
+  };
+}
+function printJayValidationResult(result, options) {
+  const logger = getLogger();
+  if (options.json) {
+    logger.important(JSON.stringify(result, null, 2));
+    return;
+  }
+  logger.important("");
+  if (result.valid) {
+    logger.important(chalk.green("✅ Jay Stack validation successful!\n"));
+    logger.important(
+      `Scanned ${result.jayHtmlFilesScanned} .jay-html files, ${result.contractFilesScanned} .jay-contract files`
+    );
+    logger.important("No errors found.");
+  } else {
+    logger.important(chalk.red("❌ Jay Stack validation failed\n"));
+    logger.important("Errors:");
+    for (const error of result.errors) {
+      logger.important(chalk.red(`  ❌ ${error.file}`));
+      logger.important(chalk.gray(`     ${error.message}`));
+      logger.important("");
+    }
+    const validFiles = result.jayHtmlFilesScanned + result.contractFilesScanned - result.errors.length;
+    logger.important(
+      chalk.red(`${result.errors.length} error(s) found, ${validFiles} file(s) valid.`)
+    );
+  }
+}
+async function initializeServicesForCli(projectRoot, viteServer) {
+  const path2 = await import("node:path");
+  const fs2 = await import("node:fs");
+  const {
+    runInitCallbacks,
+    getServiceRegistry,
+    discoverPluginsWithInit,
+    sortPluginsByDependencies,
+    executePluginServerInits
+  } = await import("@jay-framework/stack-server-runtime");
+  try {
+    const discoveredPlugins = await discoverPluginsWithInit({
+      projectRoot,
+      verbose: false
+    });
+    const pluginsWithInit = sortPluginsByDependencies(discoveredPlugins);
+    try {
+      await executePluginServerInits(pluginsWithInit, viteServer, false);
+    } catch (error) {
+      getLogger().warn(chalk.yellow(`⚠️  Plugin initialization skipped: ${error.message}`));
+    }
+    const initPathTs = path2.join(projectRoot, "src", "init.ts");
+    const initPathJs = path2.join(projectRoot, "src", "init.js");
+    let initModule;
+    if (fs2.existsSync(initPathTs) && viteServer) {
+      initModule = await viteServer.ssrLoadModule(initPathTs);
+    } else if (fs2.existsSync(initPathJs)) {
+      initModule = await import(initPathJs);
+    }
+    if (initModule?.init?._serverInit) {
+      await initModule.init._serverInit();
+    }
+    await runInitCallbacks();
+  } catch (error) {
+    getLogger().warn(chalk.yellow(`⚠️  Service initialization failed: ${error.message}`));
+    getLogger().warn(chalk.gray("   Static contracts will still be listed."));
+  }
+  return getServiceRegistry();
+}
+async function runAction(actionRef, options, projectRoot, initializeServices) {
+  let viteServer;
+  try {
+    const slashIndex = actionRef.indexOf("/");
+    if (slashIndex === -1) {
+      getLogger().error(
+        chalk.red("❌ Invalid action reference. Use format: <plugin>/<action>")
+      );
+      process.exit(1);
+    }
+    const actionExport = actionRef.substring(slashIndex + 1);
+    const input = options.input ? JSON.parse(options.input) : {};
+    if (options.verbose) {
+      getLogger().info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    await initializeServices(projectRoot, viteServer);
+    const { discoverAndRegisterActions, discoverAllPluginActions, ActionRegistry } = await import("@jay-framework/stack-server-runtime");
+    const registry = new ActionRegistry();
+    await discoverAndRegisterActions({
+      projectRoot,
+      registry,
+      verbose: options.verbose,
+      viteServer
+    });
+    await discoverAllPluginActions({
+      projectRoot,
+      registry,
+      verbose: options.verbose,
+      viteServer
+    });
+    const allNames = registry.getNames();
+    const matchedName = allNames.find((name) => name === actionExport) || allNames.find((name) => name.endsWith("." + actionExport)) || allNames.find((name) => name === actionRef);
+    if (!matchedName) {
+      getLogger().error(chalk.red(`❌ Action "${actionExport}" not found.`));
+      if (allNames.length > 0) {
+        getLogger().error(`   Available actions: ${allNames.join(", ")}`);
+      } else {
+        getLogger().error("   No actions registered. Does the plugin have actions?");
+      }
+      process.exit(1);
+    }
+    if (options.verbose) {
+      getLogger().info(`Executing action: ${matchedName}`);
+      getLogger().info(`Input: ${JSON.stringify(input)}`);
+    }
+    const result = await registry.execute(matchedName, input);
+    if (result.success) {
+      if (options.yaml) {
+        getLogger().important(YAML.stringify(result.data));
+      } else {
+        getLogger().important(JSON.stringify(result.data, null, 2));
+      }
+    } else {
+      getLogger().error(
+        chalk.red(`❌ Action failed: [${result.error.code}] ${result.error.message}`)
+      );
+      process.exit(1);
+    }
+  } catch (error) {
+    getLogger().error(chalk.red("❌ Failed to run action:") + " " + error.message);
+    if (options.verbose) {
+      getLogger().error(error.stack);
+    }
+    process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
+    }
+  }
+}
+async function runParams(contractRef, options, projectRoot, initializeServices) {
+  let viteServer;
+  try {
+    const slashIndex = contractRef.indexOf("/");
+    if (slashIndex === -1) {
+      getLogger().error(
+        chalk.red("❌ Invalid contract reference. Use format: <plugin>/<contract>")
+      );
+      process.exit(1);
+    }
+    const pluginName = contractRef.substring(0, slashIndex);
+    const contractName = contractRef.substring(slashIndex + 1);
+    if (options.verbose) {
+      getLogger().info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    await initializeServices(projectRoot, viteServer);
+    const { resolvePluginComponent } = await import("@jay-framework/compiler-shared");
+    const resolution = resolvePluginComponent(projectRoot, pluginName, contractName);
+    if (resolution.validations.length > 0 || !resolution.val) {
+      getLogger().error(
+        chalk.red(`❌ Could not resolve plugin "${pluginName}" contract "${contractName}"`)
+      );
+      for (const msg of resolution.validations) {
+        getLogger().error(`   ${msg}`);
+      }
+      process.exit(1);
+    }
+    const componentPath = resolution.val.componentPath;
+    const componentName = resolution.val.componentName;
+    if (options.verbose) {
+      getLogger().info(`Loading component "${componentName}" from ${componentPath}`);
+    }
+    const module = await viteServer.ssrLoadModule(componentPath);
+    const component = module[componentName];
+    if (!component || !component.loadParams) {
+      getLogger().error(
+        chalk.red(`❌ Component "${componentName}" does not have loadParams.`)
+      );
+      getLogger().error(
+        "   Only components with withLoadParams() expose discoverable URL params."
+      );
+      process.exit(1);
+    }
+    const { resolveServices } = await import("@jay-framework/stack-server-runtime");
+    const resolvedServices = resolveServices(component.services || []);
+    const allParams = [];
+    const paramsGenerator = component.loadParams(resolvedServices);
+    for await (const batch of paramsGenerator) {
+      allParams.push(...batch);
+    }
+    if (options.yaml) {
+      getLogger().important(YAML.stringify(allParams));
+    } else {
+      getLogger().important(JSON.stringify(allParams, null, 2));
+    }
+    if (!options.yaml) {
+      getLogger().important(
+        chalk.green(`
+✅ Found ${allParams.length} param combination(s)`)
+      );
+    }
+  } catch (error) {
+    getLogger().error(chalk.red("❌ Failed to discover params:") + " " + error.message);
+    if (options.verbose) {
+      getLogger().error(error.stack);
+    }
+    process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
+    }
+  }
+}
+async function runSetup(pluginFilter, options, projectRoot, initializeServices) {
+  let viteServer;
+  try {
+    const logger = getLogger();
+    const path2 = await import("node:path");
+    const jayConfig = loadConfig();
+    const configDir = path2.resolve(projectRoot, jayConfig.devServer?.configBase || "./config");
+    logger.important(chalk.bold("\n🔧 Setting up plugins...\n"));
+    if (options.verbose) {
+      logger.info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    const { discoverPluginsWithSetup, executePluginSetup } = await import("@jay-framework/stack-server-runtime");
+    const pluginsWithSetup = await discoverPluginsWithSetup({
+      projectRoot,
+      verbose: options.verbose,
+      pluginFilter
+    });
+    if (pluginsWithSetup.length === 0) {
+      if (pluginFilter) {
+        logger.important(
+          chalk.yellow(
+            `⚠️  Plugin "${pluginFilter}" not found or has no setup handler.`
+          )
+        );
+      } else {
+        logger.important(chalk.gray("No plugins with setup handlers found."));
+      }
+      return;
+    }
+    if (options.verbose) {
+      logger.info(
+        `Found ${pluginsWithSetup.length} plugin(s) with setup: ${pluginsWithSetup.map((p) => p.name).join(", ")}`
+      );
+    }
+    let initError;
+    try {
+      await initializeServices(projectRoot, viteServer);
+    } catch (error) {
+      initError = error;
+      if (options.verbose) {
+        logger.info(chalk.yellow(`⚠️  Service init error: ${error.message}`));
+      }
+    }
+    let configured = 0;
+    let needsConfig = 0;
+    let errors = 0;
+    for (const plugin of pluginsWithSetup) {
+      logger.important(chalk.bold(`📦 ${plugin.name}`));
+      if (plugin.setupDescription && options.verbose) {
+        logger.important(chalk.gray(`   ${plugin.setupDescription}`));
+      }
+      try {
+        const result = await executePluginSetup(plugin, {
+          projectRoot,
+          configDir,
+          force: options.force ?? false,
+          initError,
+          viteServer,
+          verbose: options.verbose
+        });
+        switch (result.status) {
+          case "configured":
+            configured++;
+            logger.important(chalk.green("   ✅ Services verified"));
+            if (result.configCreated?.length) {
+              for (const cfg of result.configCreated) {
+                logger.important(chalk.green(`   ✅ Created ${cfg}`));
+              }
+            }
+            if (result.message) {
+              logger.important(chalk.gray(`   ${result.message}`));
+            }
+            break;
+          case "needs-config":
+            needsConfig++;
+            if (result.configCreated?.length) {
+              for (const cfg of result.configCreated) {
+                logger.important(chalk.yellow(`   ⚠️  Config template created: ${cfg}`));
+              }
+            }
+            if (result.message) {
+              logger.important(chalk.yellow(`   → ${result.message}`));
+            } else {
+              logger.important(
+                chalk.yellow(
+                  `   → Fill in credentials and re-run: jay-stack setup ${plugin.name}`
+                )
+              );
+            }
+            break;
+          case "error":
+            errors++;
+            logger.important(
+              chalk.red(`   ❌ ${result.message || "Setup failed"}`)
+            );
+            break;
+        }
+      } catch (error) {
+        errors++;
+        logger.important(chalk.red(`   ❌ Setup failed: ${error.message}`));
+        if (options.verbose) {
+          logger.error(error.stack);
+        }
+      }
+      logger.important("");
+    }
+    const parts = [];
+    if (configured > 0)
+      parts.push(`${configured} configured`);
+    if (needsConfig > 0)
+      parts.push(`${needsConfig} needs config`);
+    if (errors > 0)
+      parts.push(`${errors} error(s)`);
+    logger.important(`Setup complete: ${parts.join(", ")}`);
+    if (errors > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    getLogger().error(chalk.red("❌ Setup failed:") + " " + error.message);
+    if (options.verbose) {
+      getLogger().error(error.stack);
+    }
+    process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
     }
   }
 }
 const program = new Command();
 program.name("jay-stack").description("Jay Stack CLI - Development server and plugin validation").version("0.9.0");
-program.command("dev [path]").description("Start the Jay Stack development server").action(async (path2, options) => {
+program.command("dev [path]").description("Start the Jay Stack development server").option("-v, --verbose", "Enable verbose logging output").option("-q, --quiet", "Suppress all non-error output").option("--test-mode", "Enable test endpoints (/_jay/health, /_jay/shutdown)").option("--timeout <seconds>", "Auto-shutdown after N seconds (implies --test-mode)", parseInt).action(async (path2, options) => {
   try {
+    const logLevel = options.quiet ? "silent" : options.verbose ? "verbose" : "info";
+    setDevLogger(createDevLogger(logLevel));
+    const testMode = options.testMode || options.timeout !== void 0;
     await startDevServer({
-      projectPath: path2 || process.cwd()
+      projectPath: path2 || process.cwd(),
+      testMode,
+      timeout: options.timeout,
+      logLevel
     });
   } catch (error) {
-    console.error(chalk.red("Error starting dev server:"), error.message);
+    getLogger().error(chalk.red("Error starting dev server:") + " " + error.message);
+    process.exit(1);
+  }
+});
+program.command("validate [path]").description("Validate all .jay-html and .jay-contract files in the project").option("-v, --verbose", "Show per-file validation status").option("--json", "Output results as JSON").action(async (scanPath, options) => {
+  try {
+    const result = await validateJayFiles({
+      path: scanPath,
+      verbose: options.verbose,
+      json: options.json
+    });
+    printJayValidationResult(result, options);
+    if (!result.valid) {
+      process.exit(1);
+    }
+  } catch (error) {
+    if (options.json) {
+      getLogger().important(
+        JSON.stringify({ valid: false, error: error.message }, null, 2)
+      );
+    } else {
+      getLogger().error(chalk.red("Validation error:") + " " + error.message);
+    }
     process.exit(1);
   }
 });
@@ -1485,64 +2022,238 @@ program.command("validate-plugin [path]").description("Validate a Jay Stack plug
       process.exit(1);
     }
   } catch (error) {
-    console.error(chalk.red("Validation error:"), error.message);
+    getLogger().error(chalk.red("Validation error:") + " " + error.message);
     process.exit(1);
   }
 });
+async function ensureAgentKitDocs(projectRoot, force) {
+  const path2 = await import("node:path");
+  const fs2 = await import("node:fs/promises");
+  const { fileURLToPath } = await import("node:url");
+  const agentKitDir = path2.join(projectRoot, "agent-kit");
+  await fs2.mkdir(agentKitDir, { recursive: true });
+  const thisDir = path2.dirname(fileURLToPath(import.meta.url));
+  const templateDir = path2.resolve(thisDir, "..", "agent-kit-template");
+  let files;
+  try {
+    files = (await fs2.readdir(templateDir)).filter((f) => f.endsWith(".md"));
+  } catch {
+    getLogger().warn(
+      chalk.yellow("   Agent-kit template folder not found: " + templateDir)
+    );
+    return;
+  }
+  for (const filename of files) {
+    const destPath = path2.join(agentKitDir, filename);
+    if (!force) {
+      try {
+        await fs2.access(destPath);
+        continue;
+      } catch {
+      }
+    }
+    await fs2.copyFile(path2.join(templateDir, filename), destPath);
+    getLogger().info(chalk.gray(`   Created agent-kit/${filename}`));
+  }
+}
+async function generatePluginReferences(projectRoot, options) {
+  const { discoverPluginsWithReferences, executePluginReferences } = await import("@jay-framework/stack-server-runtime");
+  const plugins = await discoverPluginsWithReferences({
+    projectRoot,
+    verbose: options.verbose,
+    pluginFilter: options.plugin
+  });
+  if (plugins.length === 0)
+    return;
+  const logger = getLogger();
+  logger.important("");
+  logger.important(chalk.bold("📚 Generating plugin references..."));
+  for (const plugin of plugins) {
+    try {
+      const result = await executePluginReferences(plugin, {
+        projectRoot,
+        force: options.force ?? false,
+        verbose: options.verbose
+      });
+      if (result.referencesCreated.length > 0) {
+        logger.important(chalk.green(`   ✅ ${plugin.name}:`));
+        for (const ref of result.referencesCreated) {
+          logger.important(chalk.gray(`      ${ref}`));
+        }
+        if (result.message) {
+          logger.important(chalk.gray(`      ${result.message}`));
+        }
+      }
+    } catch (error) {
+      logger.warn(
+        chalk.yellow(`   ⚠️  ${plugin.name}: references skipped — ${error.message}`)
+      );
+    }
+  }
+}
+async function runMaterialize(projectRoot, options, defaultOutputRelative) {
+  const path2 = await import("node:path");
+  const outputDir = options.output ?? path2.join(projectRoot, defaultOutputRelative);
+  let viteServer;
+  try {
+    if (options.list) {
+      const index = await listContracts({
+        projectRoot,
+        dynamicOnly: options.dynamicOnly,
+        pluginFilter: options.plugin
+      });
+      if (options.yaml) {
+        getLogger().important(YAML.stringify(index));
+      } else {
+        printContractList(index);
+      }
+      return;
+    }
+    if (options.verbose) {
+      getLogger().info("Starting Vite for TypeScript support...");
+    }
+    viteServer = await createViteForCli({ projectRoot });
+    const services = await initializeServicesForCli(projectRoot, viteServer);
+    const result = await materializeContracts(
+      {
+        projectRoot,
+        outputDir,
+        force: options.force,
+        dynamicOnly: options.dynamicOnly,
+        pluginFilter: options.plugin,
+        verbose: options.verbose,
+        viteServer
+      },
+      services
+    );
+    if (options.yaml) {
+      getLogger().important(YAML.stringify(result.index));
+    } else {
+      getLogger().important(
+        chalk.green(`
+✅ Materialized ${result.index.contracts.length} contracts`)
+      );
+      getLogger().important(`   Static: ${result.staticCount}`);
+      getLogger().important(`   Dynamic: ${result.dynamicCount}`);
+      getLogger().important(`   Output: ${result.outputDir}`);
+    }
+  } catch (error) {
+    getLogger().error(chalk.red("❌ Failed to materialize contracts:") + " " + error.message);
+    if (options.verbose) {
+      getLogger().error(error.stack);
+    }
+    process.exit(1);
+  } finally {
+    if (viteServer) {
+      await viteServer.close();
+    }
+  }
+}
+program.command("setup [plugin]").description(
+  "Run plugin setup: create config templates, validate credentials, generate reference data"
+).option("--force", "Force re-run (overwrite config templates and regenerate references)").option("-v, --verbose", "Show detailed output").action(async (plugin, options) => {
+  await runSetup(plugin, options, process.cwd(), initializeServicesForCli);
+});
+program.command("agent-kit").description(
+  "Prepare the agent kit: materialize contracts, generate references, and write docs to agent-kit/"
+).option("-o, --output <dir>", "Output directory (default: agent-kit/materialized-contracts)").option("--yaml", "Output contract index as YAML to stdout").option("--list", "List contracts without writing files").option("--plugin <name>", "Filter to specific plugin").option("--dynamic-only", "Only process dynamic contracts").option("--force", "Force re-materialization").option("--no-references", "Skip reference data generation").option("-v, --verbose", "Show detailed output").action(async (options) => {
+  const projectRoot = process.cwd();
+  await runMaterialize(projectRoot, options, "agent-kit/materialized-contracts");
+  if (!options.list) {
+    await ensureAgentKitDocs(projectRoot, options.force);
+    if (options.references !== false) {
+      await generatePluginReferences(projectRoot, options);
+    }
+  }
+});
+program.command("action <plugin/action>").description(
+  `Run a plugin action (e.g., jay-stack action wix-stores/searchProducts --input '{"query":""}')`
+).option("--input <json>", "JSON input for the action (default: {})").option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (actionRef, options) => {
+  await runAction(actionRef, options, process.cwd(), initializeServicesForCli);
+});
+program.command("params <plugin/contract>").description(
+  "Discover load param values for a contract (e.g., jay-stack params wix-stores/product-page)"
+).option("--yaml", "Output result as YAML instead of JSON").option("-v, --verbose", "Show detailed output").action(async (contractRef, options) => {
+  await runParams(contractRef, options, process.cwd(), initializeServicesForCli);
+});
 program.parse(process.argv);
 if (!process.argv.slice(2).length) {
   program.outputHelp();
 }
 function printValidationResult(result, verbose) {
+  const logger = getLogger();
   if (result.valid && result.warnings.length === 0) {
-    console.log(chalk.green("✅ Plugin validation successful!\n"));
+    logger.important(chalk.green("✅ Plugin validation successful!\n"));
     if (verbose) {
-      console.log("Plugin:", result.pluginName);
-      console.log("  ✅ plugin.yaml valid");
-      console.log(`  ✅ ${result.contractsChecked} contracts validated`);
+      logger.important("Plugin: " + result.pluginName);
+      logger.important("  ✅ plugin.yaml valid");
+      logger.important(`  ✅ ${result.contractsChecked} contracts validated`);
       if (result.typesGenerated) {
-        console.log(`  ✅ ${result.typesGenerated} type definitions generated`);
+        logger.important(`  ✅ ${result.typesGenerated} type definitions generated`);
       }
-      console.log(`  ✅ ${result.componentsChecked} components validated`);
+      logger.important(`  ✅ ${result.componentsChecked} components validated`);
       if (result.packageJsonChecked) {
-        console.log("  ✅ package.json valid");
+        logger.important("  ✅ package.json valid");
       }
-      console.log("\nNo errors found.");
+      logger.important("\nNo errors found.");
     }
   } else if (result.valid && result.warnings.length > 0) {
-    console.log(chalk.yellow("⚠️  Plugin validation passed with warnings\n"));
-    console.log("Warnings:");
+    logger.important(chalk.yellow("⚠️  Plugin validation passed with warnings\n"));
+    logger.important("Warnings:");
     result.warnings.forEach((warning) => {
-      console.log(chalk.yellow(`  ⚠️  ${warning.message}`));
+      logger.important(chalk.yellow(`  ⚠️  ${warning.message}`));
       if (warning.location) {
-        console.log(chalk.gray(`      Location: ${warning.location}`));
+        logger.important(chalk.gray(`      Location: ${warning.location}`));
       }
       if (warning.suggestion) {
-        console.log(chalk.gray(`      → ${warning.suggestion}`));
+        logger.important(chalk.gray(`      → ${warning.suggestion}`));
       }
-      console.log();
+      logger.important("");
     });
-    console.log(chalk.gray("Use --strict to treat warnings as errors."));
+    logger.important(chalk.gray("Use --strict to treat warnings as errors."));
   } else {
-    console.log(chalk.red("❌ Plugin validation failed\n"));
-    console.log("Errors:");
+    logger.important(chalk.red("❌ Plugin validation failed\n"));
+    logger.important("Errors:");
     result.errors.forEach((error) => {
-      console.log(chalk.red(`  ❌ ${error.message}`));
+      logger.important(chalk.red(`  ❌ ${error.message}`));
       if (error.location) {
-        console.log(chalk.gray(`      Location: ${error.location}`));
+        logger.important(chalk.gray(`      Location: ${error.location}`));
       }
       if (error.suggestion) {
-        console.log(chalk.gray(`      → ${error.suggestion}`));
+        logger.important(chalk.gray(`      → ${error.suggestion}`));
       }
-      console.log();
+      logger.important("");
     });
-    console.log(chalk.red(`${result.errors.length} errors found.`));
+    logger.important(chalk.red(`${result.errors.length} errors found.`));
+  }
+}
+function printContractList(index) {
+  const logger = getLogger();
+  logger.important("\nAvailable Contracts:\n");
+  const byPlugin = /* @__PURE__ */ new Map();
+  for (const contract of index.contracts) {
+    const existing = byPlugin.get(contract.plugin) || [];
+    existing.push(contract);
+    byPlugin.set(contract.plugin, existing);
+  }
+  for (const [plugin, contracts] of byPlugin) {
+    logger.important(chalk.bold(`📦 ${plugin}`));
+    for (const contract of contracts) {
+      const typeIcon = contract.type === "static" ? "📄" : "⚡";
+      logger.important(`   ${typeIcon} ${contract.name}`);
+    }
+    logger.important("");
+  }
+  if (index.contracts.length === 0) {
+    logger.important(chalk.gray("No contracts found."));
   }
 }
 export {
   createEditorHandlers,
   getConfigWithDefaults,
+  listContracts2 as listContracts,
   loadConfig,
+  materializeContracts2 as materializeContracts,
   startDevServer,
   updateConfig
 };