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

package/dist/index.js

@@ -6,14 +6,19 @@ import getPort from "get-port";
 import path from "path";
 import fs from "fs";
 import YAML from "yaml";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile } from "@jay-framework/compiler-jay-html";
-import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION } from "@jay-framework/compiler-shared";
+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 { Command } from "commander";
+import chalk from "chalk";
 const DEFAULT_CONFIG = {
   devServer: {
     portRange: [3e3, 3100],
     pagesBase: "./src/pages",
     componentsBase: "./src/components",
-    publicFolder: "./public"
+    publicFolder: "./public",
+    configBase: "./config"
   },
   editorServer: {
     portRange: [3101, 3200]
@@ -42,17 +47,18 @@ function loadConfig() {
     return DEFAULT_CONFIG;
   }
 }
-function getConfigWithDefaults(config2) {
+function getConfigWithDefaults(config) {
   return {
     devServer: {
-      portRange: config2.devServer?.portRange || DEFAULT_CONFIG.devServer.portRange,
-      pagesBase: config2.devServer?.pagesBase || DEFAULT_CONFIG.devServer.pagesBase,
-      componentsBase: config2.devServer?.componentsBase || DEFAULT_CONFIG.devServer.componentsBase,
-      publicFolder: config2.devServer?.publicFolder || DEFAULT_CONFIG.devServer.publicFolder
+      portRange: config.devServer?.portRange || DEFAULT_CONFIG.devServer.portRange,
+      pagesBase: config.devServer?.pagesBase || DEFAULT_CONFIG.devServer.pagesBase,
+      componentsBase: config.devServer?.componentsBase || DEFAULT_CONFIG.devServer.componentsBase,
+      publicFolder: config.devServer?.publicFolder || DEFAULT_CONFIG.devServer.publicFolder,
+      configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase
     },
     editorServer: {
-      portRange: config2.editorServer?.portRange || DEFAULT_CONFIG.editorServer.portRange,
-      editorId: config2.editorServer?.editorId
+      portRange: config.editorServer?.portRange || DEFAULT_CONFIG.editorServer.portRange,
+      editorId: config.editorServer?.editorId
     }
   };
 }
@@ -79,9 +85,643 @@ function updateConfig(updates) {
   }
 }
 const PAGE_FILENAME = `page${JAY_EXTENSION}`;
-async function handlePagePublish(resolvedConfig2, page) {
+const PAGE_CONTRACT_FILENAME = `page${JAY_CONTRACT_EXTENSION}`;
+const PAGE_CONFIG_FILENAME = "page.conf.yaml";
+function jayTypeToString(jayType) {
+  if (!jayType)
+    return void 0;
+  if (jayType instanceof JayAtomicType) {
+    return jayType.name;
+  } else if (jayType instanceof JayEnumType) {
+    return `enum (${jayType.values.join(" | ")})`;
+  } else {
+    return jayType.name || "unknown";
+  }
+}
+function convertContractTagToProtocol(tag) {
+  const protocolTag = {
+    tag: tag.tag,
+    type: tag.type.length === 1 ? ContractTagType[tag.type[0]] : tag.type.map((t) => ContractTagType[t])
+  };
+  if (tag.dataType) {
+    protocolTag.dataType = jayTypeToString(tag.dataType);
+  }
+  if (tag.elementType) {
+    protocolTag.elementType = tag.elementType.join(" | ");
+  }
+  if (tag.required !== void 0) {
+    protocolTag.required = tag.required;
+  }
+  if (tag.repeated !== void 0) {
+    protocolTag.repeated = tag.repeated;
+  }
+  if (tag.link) {
+    protocolTag.link = tag.link;
+  }
+  if (tag.tags) {
+    protocolTag.tags = tag.tags.map(convertContractTagToProtocol);
+  }
+  return protocolTag;
+}
+function isPageDirectory(entries) {
+  const hasPageHtml = entries.some((e) => e.name === PAGE_FILENAME);
+  const hasPageContract = entries.some((e) => e.name === PAGE_CONTRACT_FILENAME);
+  const hasPageConfig = entries.some((e) => e.name === PAGE_CONFIG_FILENAME);
+  const isPage = hasPageHtml || hasPageContract || hasPageConfig;
+  return { isPage, hasPageHtml, hasPageContract, hasPageConfig };
+}
+async function scanPageDirectories(pagesBasePath, onPageFound) {
+  async function scanDirectory(dirPath, urlPath = "") {
+    try {
+      const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+      const { isPage, hasPageHtml, hasPageContract, hasPageConfig } = isPageDirectory(entries);
+      if (isPage) {
+        const pageUrl = urlPath || "/";
+        const pageName = dirPath === pagesBasePath ? "Home" : path.basename(dirPath);
+        await onPageFound({
+          dirPath,
+          pageUrl,
+          pageName,
+          hasPageHtml,
+          hasPageContract,
+          hasPageConfig
+        });
+      }
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+          const isParam = entry.name.startsWith("[") && entry.name.endsWith("]");
+          const segmentUrl = isParam ? `:${entry.name.slice(1, -1)}` : entry.name;
+          const newUrlPath = urlPath + "/" + segmentUrl;
+          await scanDirectory(fullPath, newUrlPath);
+        }
+      }
+    } catch (error) {
+      console.warn(`Failed to scan directory ${dirPath}:`, error);
+    }
+  }
+  await scanDirectory(pagesBasePath);
+}
+async function parseContractFile(contractFilePath) {
+  try {
+    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
+      );
+    }
+    if (parsedContract.val) {
+      const resolvedTags = await resolveLinkedTags(
+        parsedContract.val.tags,
+        path.dirname(contractFilePath)
+      );
+      return {
+        name: parsedContract.val.name,
+        tags: resolvedTags
+      };
+    }
+  } catch (error) {
+    console.warn(`Failed to parse contract file ${contractFilePath}:`, error);
+  }
+  return null;
+}
+async function resolveLinkedTags(tags, baseDir) {
+  const resolvedTags = [];
+  for (const tag of tags) {
+    if (tag.link) {
+      try {
+        const linkedPath = path.resolve(baseDir, tag.link);
+        const linkedContract = await parseContractFile(linkedPath);
+        if (linkedContract) {
+          const resolvedTag = {
+            tag: tag.tag,
+            type: tag.type.length === 1 ? ContractTagType[tag.type[0]] : tag.type.map((t) => ContractTagType[t]),
+            tags: linkedContract.tags
+            // Use tags from linked contract
+          };
+          if (tag.required !== void 0) {
+            resolvedTag.required = tag.required;
+          }
+          if (tag.repeated !== void 0) {
+            resolvedTag.repeated = tag.repeated;
+          }
+          resolvedTags.push(resolvedTag);
+        } else {
+          console.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);
+        resolvedTags.push(convertContractTagToProtocol(tag));
+      }
+    } else if (tag.tags) {
+      const resolvedSubTags = await resolveLinkedTags(tag.tags, baseDir);
+      const protocolTag = convertContractTagToProtocol(tag);
+      protocolTag.tags = resolvedSubTags;
+      resolvedTags.push(protocolTag);
+    } else {
+      resolvedTags.push(convertContractTagToProtocol(tag));
+    }
+  }
+  return resolvedTags;
+}
+function resolveAppContractPath(appModule, contractFileName, projectRootPath) {
+  try {
+    const require2 = createRequire(path.join(projectRootPath, "package.json"));
+    const modulePath = `${appModule}/${contractFileName}`;
+    const resolvedPath = require2.resolve(modulePath);
+    return resolvedPath;
+  } catch (error) {
+    console.warn(
+      `Failed to resolve contract: ${appModule}/${contractFileName}`,
+      error instanceof Error ? error.message : error
+    );
+    return null;
+  }
+}
+async function scanInstalledAppContracts(configBasePath, projectRootPath) {
+  const installedAppContracts = {};
+  const installedAppsPath = path.join(configBasePath, "installedApps");
+  try {
+    if (!fs.existsSync(installedAppsPath)) {
+      return installedAppContracts;
+    }
+    const appDirs = await fs.promises.readdir(installedAppsPath, { withFileTypes: true });
+    for (const appDir of appDirs) {
+      if (appDir.isDirectory()) {
+        const appConfigPath = path.join(installedAppsPath, appDir.name, "app.conf.yaml");
+        try {
+          if (fs.existsSync(appConfigPath)) {
+            const configContent = await fs.promises.readFile(appConfigPath, "utf-8");
+            const appConfig = YAML.parse(configContent);
+            const appName = appConfig.name || appDir.name;
+            const appModule = appConfig.module || appDir.name;
+            const appContracts = {
+              appName,
+              module: appModule,
+              pages: [],
+              components: []
+            };
+            if (appConfig.pages && Array.isArray(appConfig.pages)) {
+              for (const page of appConfig.pages) {
+                if (page.headless_components && Array.isArray(page.headless_components)) {
+                  for (const component of page.headless_components) {
+                    if (component.contract) {
+                      const contractPath = resolveAppContractPath(
+                        appModule,
+                        component.contract,
+                        projectRootPath
+                      );
+                      if (contractPath) {
+                        const contractSchema = await parseContractFile(contractPath);
+                        if (contractSchema) {
+                          appContracts.pages.push({
+                            pageName: page.name,
+                            contractSchema
+                          });
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            if (appConfig.components && Array.isArray(appConfig.components)) {
+              for (const component of appConfig.components) {
+                if (component.headless_components && Array.isArray(component.headless_components)) {
+                  for (const headlessComp of component.headless_components) {
+                    if (headlessComp.contract) {
+                      const contractPath = resolveAppContractPath(
+                        appModule,
+                        headlessComp.contract,
+                        projectRootPath
+                      );
+                      if (contractPath) {
+                        const contractSchema = await parseContractFile(contractPath);
+                        if (contractSchema) {
+                          appContracts.components.push({
+                            componentName: component.name,
+                            contractSchema
+                          });
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+            installedAppContracts[appName] = appContracts;
+          }
+        } catch (error) {
+          console.warn(`Failed to parse app config ${appConfigPath}:`, error);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn(`Failed to scan installed apps directory ${installedAppsPath}:`, error);
+  }
+  return installedAppContracts;
+}
+function extractHeadlessComponents(jayHtmlContent, installedApps, installedAppContracts) {
+  const root = parse(jayHtmlContent);
+  const headlessScripts = root.querySelectorAll('script[type="application/jay-headless"]');
+  const resolvedComponents = [];
+  for (const script of headlessScripts) {
+    const src = script.getAttribute("src") || "";
+    const name = script.getAttribute("name") || "";
+    const key = script.getAttribute("key") || "";
+    let resolved = false;
+    for (const app of installedApps) {
+      if (app.module !== src && app.name !== src) {
+        continue;
+      }
+      for (const appPage of app.pages) {
+        for (const headlessComp of appPage.headless_components) {
+          if (headlessComp.name === name && headlessComp.key === key) {
+            const appContracts = installedAppContracts[app.name];
+            if (appContracts) {
+              const matchingPageContract = appContracts.pages.find(
+                (pc) => pc.pageName === appPage.name
+              );
+              if (matchingPageContract) {
+                resolvedComponents.push({
+                  appName: app.name,
+                  componentName: appPage.name,
+                  key
+                });
+                resolved = true;
+                break;
+              }
+            }
+          }
+        }
+        if (resolved)
+          break;
+      }
+      if (resolved)
+        break;
+      for (const appComponent of app.components) {
+        for (const headlessComp of appComponent.headless_components) {
+          if (headlessComp.name === name && headlessComp.key === key) {
+            const appContracts = installedAppContracts[app.name];
+            if (appContracts) {
+              const matchingComponentContract = appContracts.components.find(
+                (cc) => cc.componentName === appComponent.name
+              );
+              if (matchingComponentContract) {
+                resolvedComponents.push({
+                  appName: app.name,
+                  componentName: appComponent.name,
+                  key
+                });
+                resolved = true;
+                break;
+              }
+            }
+          }
+        }
+        if (resolved)
+          break;
+      }
+      if (resolved)
+        break;
+    }
+    if (!resolved) {
+      resolvedComponents.push({
+        appName: src,
+        componentName: name,
+        key
+      });
+    }
+  }
+  return resolvedComponents;
+}
+async function scanProjectComponents(componentsBasePath) {
+  const components = [];
   try {
-    const pagesBasePath = path.resolve(resolvedConfig2.devServer.pagesBase);
+    const entries = await fs.promises.readdir(componentsBasePath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(JAY_EXTENSION)) {
+        const componentName = path.basename(entry.name, JAY_EXTENSION);
+        const componentPath = path.join(componentsBasePath, entry.name);
+        const contractPath = path.join(
+          componentsBasePath,
+          `${componentName}${JAY_CONTRACT_EXTENSION}`
+        );
+        const hasContract = fs.existsSync(contractPath);
+        components.push({
+          name: componentName,
+          filePath: componentPath,
+          contractPath: hasContract ? contractPath : void 0
+        });
+      }
+    }
+  } catch (error) {
+    console.warn(`Failed to scan components directory ${componentsBasePath}:`, error);
+  }
+  return components;
+}
+async function scanInstalledApps(configBasePath) {
+  const installedApps = [];
+  const installedAppsPath = path.join(configBasePath, "installedApps");
+  try {
+    if (!fs.existsSync(installedAppsPath)) {
+      return installedApps;
+    }
+    const appDirs = await fs.promises.readdir(installedAppsPath, { withFileTypes: true });
+    for (const appDir of appDirs) {
+      if (appDir.isDirectory()) {
+        const appConfigPath = path.join(installedAppsPath, appDir.name, "app.conf.yaml");
+        try {
+          if (fs.existsSync(appConfigPath)) {
+            const configContent = await fs.promises.readFile(appConfigPath, "utf-8");
+            const appConfig = YAML.parse(configContent);
+            installedApps.push({
+              name: appConfig.name || appDir.name,
+              module: appConfig.module || appDir.name,
+              pages: appConfig.pages || [],
+              components: appConfig.components || [],
+              config_map: appConfig.config_map || []
+            });
+          }
+        } catch (error) {
+          console.warn(`Failed to parse app config ${appConfigPath}:`, error);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn(`Failed to scan installed apps directory ${installedAppsPath}:`, error);
+  }
+  return installedApps;
+}
+async function getProjectName(configBasePath) {
+  const projectConfigPath = path.join(configBasePath, "project.conf.yaml");
+  try {
+    if (fs.existsSync(projectConfigPath)) {
+      const configContent = await fs.promises.readFile(projectConfigPath, "utf-8");
+      const projectConfig = YAML.parse(configContent);
+      return projectConfig.name || "Unnamed Project";
+    }
+  } catch (error) {
+    console.warn(`Failed to read project config ${projectConfigPath}:`, error);
+  }
+  return "Unnamed Project";
+}
+async function scanPlugins(projectRootPath) {
+  const plugins = [];
+  const localPluginsPath = path.join(projectRootPath, "src/plugins");
+  if (fs.existsSync(localPluginsPath)) {
+    try {
+      const pluginDirs = await fs.promises.readdir(localPluginsPath, { withFileTypes: true });
+      for (const dir of pluginDirs) {
+        if (!dir.isDirectory())
+          continue;
+        const pluginPath = path.join(localPluginsPath, dir.name);
+        const pluginYamlPath = path.join(pluginPath, "plugin.yaml");
+        if (fs.existsSync(pluginYamlPath)) {
+          try {
+            const yamlContent = await fs.promises.readFile(pluginYamlPath, "utf-8");
+            const manifest = YAML.parse(yamlContent);
+            plugins.push({
+              manifest,
+              location: {
+                type: "local",
+                path: pluginPath
+              }
+            });
+          } catch (error) {
+            console.warn(`Failed to parse plugin.yaml for ${dir.name}:`, error);
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(`Failed to scan local plugins directory ${localPluginsPath}:`, error);
+    }
+  }
+  const nodeModulesPath = path.join(projectRootPath, "node_modules");
+  if (fs.existsSync(nodeModulesPath)) {
+    try {
+      const topLevelDirs = await fs.promises.readdir(nodeModulesPath, {
+        withFileTypes: true
+      });
+      for (const entry of topLevelDirs) {
+        if (!entry.isDirectory())
+          continue;
+        const packageDirs = [];
+        if (entry.name.startsWith("@")) {
+          const scopePath = path.join(nodeModulesPath, entry.name);
+          const scopedPackages = await fs.promises.readdir(scopePath, {
+            withFileTypes: true
+          });
+          for (const scopedPkg of scopedPackages) {
+            if (scopedPkg.isDirectory()) {
+              packageDirs.push(path.join(scopePath, scopedPkg.name));
+            }
+          }
+        } else {
+          packageDirs.push(path.join(nodeModulesPath, entry.name));
+        }
+        for (const pkgPath of packageDirs) {
+          const pluginYamlPath = path.join(pkgPath, "plugin.yaml");
+          if (fs.existsSync(pluginYamlPath)) {
+            try {
+              const yamlContent = await fs.promises.readFile(pluginYamlPath, "utf-8");
+              const manifest = YAML.parse(yamlContent);
+              const packageJsonPath = path.join(pkgPath, "package.json");
+              let moduleName = manifest.module;
+              if (fs.existsSync(packageJsonPath)) {
+                const packageJson = JSON.parse(
+                  await fs.promises.readFile(packageJsonPath, "utf-8")
+                );
+                moduleName = packageJson.name;
+              }
+              plugins.push({
+                manifest: {
+                  ...manifest,
+                  module: moduleName
+                },
+                location: {
+                  type: "npm",
+                  module: moduleName || manifest.name
+                }
+              });
+            } catch (error) {
+              console.warn(
+                `Failed to parse plugin.yaml for package ${pkgPath}:`,
+                error
+              );
+            }
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(`Failed to scan node_modules for plugins:`, error);
+    }
+  }
+  return plugins;
+}
+async function scanProjectInfo(pagesBasePath, componentsBasePath, configBasePath, projectRootPath) {
+  const [projectName, components, installedApps, plugins] = await Promise.all([
+    getProjectName(configBasePath),
+    scanProjectComponents(componentsBasePath),
+    scanInstalledApps(configBasePath),
+    scanPlugins(projectRootPath)
+  ]);
+  const installedAppContracts = await scanInstalledAppContracts(configBasePath, projectRootPath);
+  const pages = [];
+  await scanPageDirectories(pagesBasePath, async (context) => {
+    const { dirPath, pageUrl, pageName, hasPageHtml, hasPageContract, hasPageConfig } = context;
+    const pageFilePath = path.join(dirPath, PAGE_FILENAME);
+    const pageConfigPath = path.join(dirPath, PAGE_CONFIG_FILENAME);
+    const contractPath = path.join(dirPath, PAGE_CONTRACT_FILENAME);
+    let usedComponents = [];
+    let contractSchema;
+    if (hasPageContract) {
+      try {
+        const parsedContract = await parseContractFile(contractPath);
+        if (parsedContract) {
+          contractSchema = parsedContract;
+        }
+      } catch (error) {
+        console.warn(`Failed to parse contract file ${contractPath}:`, error);
+      }
+    }
+    if (hasPageHtml) {
+      try {
+        const jayHtmlContent = await fs.promises.readFile(pageFilePath, "utf-8");
+        usedComponents = extractHeadlessComponents(
+          jayHtmlContent,
+          installedApps,
+          installedAppContracts
+        );
+      } catch (error) {
+        console.warn(`Failed to read page file ${pageFilePath}:`, error);
+      }
+    } else if (hasPageConfig) {
+      try {
+        const configContent = await fs.promises.readFile(pageConfigPath, "utf-8");
+        const pageConfig = YAML.parse(configContent);
+        if (pageConfig.used_components && Array.isArray(pageConfig.used_components)) {
+          for (const comp of pageConfig.used_components) {
+            const key = comp.key || "";
+            let src = "";
+            let name = "";
+            if (comp.plugin && comp.contract) {
+              const plugin = plugins.find((p) => p.manifest.name === comp.plugin);
+              if (plugin && plugin.manifest.contracts) {
+                const contract = plugin.manifest.contracts.find(
+                  (c) => c.name === comp.contract
+                );
+                if (contract) {
+                  usedComponents.push({
+                    appName: comp.plugin,
+                    componentName: comp.contract,
+                    key
+                  });
+                  continue;
+                }
+              }
+              usedComponents.push({
+                appName: comp.plugin,
+                componentName: comp.contract,
+                key
+              });
+              continue;
+            }
+            src = comp.src || "";
+            name = comp.name || "";
+            let resolved = false;
+            for (const app of installedApps) {
+              if (app.module !== src && app.name !== src) {
+                continue;
+              }
+              for (const appPage of app.pages) {
+                for (const headlessComp of appPage.headless_components) {
+                  if (headlessComp.name === name && headlessComp.key === key) {
+                    const appContracts = installedAppContracts[app.name];
+                    if (appContracts) {
+                      const matchingPageContract = appContracts.pages.find(
+                        (pc) => pc.pageName === appPage.name
+                      );
+                      if (matchingPageContract) {
+                        usedComponents.push({
+                          appName: app.name,
+                          componentName: appPage.name,
+                          key
+                        });
+                        resolved = true;
+                        break;
+                      }
+                    }
+                  }
+                }
+                if (resolved)
+                  break;
+              }
+              if (resolved)
+                break;
+              for (const appComponent of app.components) {
+                for (const headlessComp of appComponent.headless_components) {
+                  if (headlessComp.name === name && headlessComp.key === key) {
+                    const appContracts = installedAppContracts[app.name];
+                    if (appContracts) {
+                      const matchingComponentContract = appContracts.components.find(
+                        (cc) => cc.componentName === appComponent.name
+                      );
+                      if (matchingComponentContract) {
+                        usedComponents.push({
+                          appName: app.name,
+                          componentName: appComponent.name,
+                          key
+                        });
+                        resolved = true;
+                        break;
+                      }
+                    }
+                  }
+                }
+                if (resolved)
+                  break;
+              }
+              if (resolved)
+                break;
+            }
+            if (!resolved) {
+              usedComponents.push({
+                appName: src,
+                componentName: name,
+                key
+              });
+            }
+          }
+        }
+      } catch (error) {
+        console.warn(`Failed to parse page config ${pageConfigPath}:`, error);
+      }
+    }
+    pages.push({
+      name: pageName,
+      url: pageUrl,
+      filePath: pageFilePath,
+      contractSchema,
+      usedComponents
+    });
+  });
+  return {
+    name: projectName,
+    localPath: projectRootPath,
+    pages,
+    components,
+    installedApps,
+    installedAppContracts,
+    plugins
+  };
+}
+async function handlePagePublish(resolvedConfig, page) {
+  try {
+    const pagesBasePath = path.resolve(resolvedConfig.devServer.pagesBase);
     const routePath = page.route === "/" ? "" : page.route;
     const dirname = path.join(pagesBasePath, routePath);
     const fullPath = path.join(dirname, PAGE_FILENAME);
@@ -119,9 +759,9 @@ async function handlePagePublish(resolvedConfig2, page) {
     ];
   }
 }
-async function handleComponentPublish(resolvedConfig2, component) {
+async function handleComponentPublish(resolvedConfig, component) {
   try {
-    const dirname = path.resolve(resolvedConfig2.devServer.componentsBase);
+    const dirname = path.resolve(resolvedConfig.devServer.componentsBase);
     const filename = `${component.name}${JAY_EXTENSION}`;
     const fullPath = path.join(dirname, filename);
     await fs.promises.mkdir(dirname, { recursive: true });
@@ -157,13 +797,13 @@ async function handleComponentPublish(resolvedConfig2, component) {
     ];
   }
 }
-function createEditorHandlers(config2, tsConfigPath) {
+function createEditorHandlers(config, tsConfigPath, projectRoot) {
   const onPublish = async (params) => {
     const status = [];
     const createdJayHtmls = [];
     if (params.pages) {
       for (const page of params.pages) {
-        const [pageStatus, createdJayHtml] = await handlePagePublish(config2, page);
+        const [pageStatus, createdJayHtml] = await handlePagePublish(config, page);
         status.push(pageStatus);
         if (pageStatus.success)
           createdJayHtmls.push(createdJayHtml);
@@ -172,7 +812,7 @@ function createEditorHandlers(config2, tsConfigPath) {
     if (params.components) {
       for (const component of params.components) {
         const [compStatus, createdJayHtml] = await handleComponentPublish(
-          config2,
+          config,
           component
         );
         status.push(compStatus);
@@ -186,7 +826,8 @@ function createEditorHandlers(config2, tsConfigPath) {
         filename,
         dirname,
         { relativePath: tsConfigPath },
-        JAY_IMPORT_RESOLVER
+        JAY_IMPORT_RESOLVER,
+        projectRoot
       );
       const definitionFile = generateElementDefinitionFile(parsedJayHtml);
       if (definitionFile.validations.length > 0)
@@ -204,7 +845,7 @@ function createEditorHandlers(config2, tsConfigPath) {
   };
   const onSaveImage = async (params) => {
     try {
-      const imagesDir = path.join(path.resolve(config2.devServer.publicFolder), "images");
+      const imagesDir = path.join(path.resolve(config.devServer.publicFolder), "images");
       await fs.promises.mkdir(imagesDir, { recursive: true });
       const filename = `${params.imageId}.png`;
       const imagePath = path.join(imagesDir, filename);
@@ -228,7 +869,7 @@ function createEditorHandlers(config2, tsConfigPath) {
     try {
       const filename = `${params.imageId}.png`;
       const imagePath = path.join(
-        path.resolve(config2.devServer.publicFolder),
+        path.resolve(config.devServer.publicFolder),
         "images",
         filename
       );
@@ -249,13 +890,54 @@ function createEditorHandlers(config2, tsConfigPath) {
       };
     }
   };
+  const onGetProjectInfo = async (params) => {
+    try {
+      const pagesBasePath = path.resolve(config.devServer.pagesBase);
+      const componentsBasePath = path.resolve(config.devServer.componentsBase);
+      const configBasePath = path.resolve(config.devServer.configBase);
+      const projectRootPath = process.cwd();
+      const info = await scanProjectInfo(
+        pagesBasePath,
+        componentsBasePath,
+        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}`);
+      return {
+        type: "getProjectInfo",
+        success: true,
+        info
+      };
+    } catch (error) {
+      console.error("Failed to get project info:", error);
+      return {
+        type: "getProjectInfo",
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error",
+        info: {
+          name: "Error",
+          localPath: process.cwd(),
+          pages: [],
+          components: [],
+          installedApps: [],
+          installedAppContracts: {},
+          plugins: []
+        }
+      };
+    }
+  };
   return {
     onPublish,
     onSaveImage,
-    onHasImage
+    onHasImage,
+    onGetProjectInfo
   };
 }
-async function generatePageDefinitionFiles(routes, tsConfigPath) {
+async function generatePageDefinitionFiles(routes, tsConfigPath, projectRoot) {
   for (const route of routes) {
     const jayHtmlPath = route.fsRoute.jayHtmlPath;
     if (!fs.existsSync(jayHtmlPath)) {
@@ -281,7 +963,8 @@ async function generatePageDefinitionFiles(routes, tsConfigPath) {
         filename,
         dirname,
         { relativePath: tsConfigPath },
-        JAY_IMPORT_RESOLVER
+        JAY_IMPORT_RESOLVER,
+        projectRoot
       );
       const definitionFile = generateElementDefinitionFile(parsedJayHtml);
       if (definitionFile.validations.length > 0) {
@@ -298,14 +981,18 @@ async function generatePageDefinitionFiles(routes, tsConfigPath) {
     }
   }
 }
-const config = loadConfig();
-const resolvedConfig = getConfigWithDefaults(config);
-const jayOptions = {
-  tsConfigFilePath: "./tsconfig.json",
-  outputDir: "build/jay-runtime"
-};
-const app = express();
-async function initApp() {
+async function startDevServer(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  if (projectPath !== process.cwd()) {
+    process.chdir(projectPath);
+  }
+  const config = loadConfig();
+  const resolvedConfig = getConfigWithDefaults(config);
+  const jayOptions = {
+    tsConfigFilePath: "./tsconfig.json",
+    outputDir: "build/jay-runtime"
+  };
+  const app = express();
   const devServerPort = await getPort({ port: resolvedConfig.devServer.portRange });
   const editorServer = createEditorServer({
     portRange: resolvedConfig.editorServer.portRange,
@@ -320,10 +1007,15 @@ async function initApp() {
     }
   });
   const { port: editorPort, editorId } = await editorServer.start();
-  const handlers = createEditorHandlers(resolvedConfig, jayOptions.tsConfigFilePath);
+  const handlers = createEditorHandlers(
+    resolvedConfig,
+    jayOptions.tsConfigFilePath,
+    process.cwd()
+  );
   editorServer.onPublish(handlers.onPublish);
   editorServer.onSaveImage(handlers.onSaveImage);
   editorServer.onHasImage(handlers.onHasImage);
+  editorServer.onGetProjectInfo(handlers.onGetProjectInfo);
   const { server, viteServer, routes } = await mkDevServer({
     pagesRootFolder: path.resolve(resolvedConfig.devServer.pagesBase),
     projectRootFolder: process.cwd(),
@@ -341,7 +1033,7 @@ async function initApp() {
   routes.forEach((route) => {
     app.get(route.path, route.handler);
   });
-  generatePageDefinitionFiles(routes, jayOptions.tsConfigFilePath);
+  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}`);
@@ -361,13 +1053,496 @@ async function initApp() {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
-initApp().catch((error) => {
-  console.error("Failed to start servers:", error);
-  process.exit(1);
+async function validatePlugin(options = {}) {
+  const pluginPath = options.pluginPath || process.cwd();
+  if (options.local) {
+    return validateLocalPlugins(pluginPath, options);
+  } else {
+    return validatePluginPackage(pluginPath, options);
+  }
+}
+async function validatePluginPackage(pluginPath, options) {
+  const result = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    contractsChecked: 0,
+    componentsChecked: 0
+  };
+  const pluginYamlPath = path.join(pluginPath, "plugin.yaml");
+  const pluginManifest = loadPluginManifest(pluginPath);
+  if (!pluginManifest) {
+    if (!fs.existsSync(pluginYamlPath)) {
+      result.errors.push({
+        type: "file-missing",
+        message: "plugin.yaml not found",
+        location: pluginPath,
+        suggestion: "Create a plugin.yaml file in the plugin root directory"
+      });
+    } else {
+      result.errors.push({
+        type: "schema",
+        message: "Invalid YAML syntax or format",
+        location: pluginYamlPath
+      });
+    }
+    result.valid = false;
+    return result;
+  }
+  result.pluginName = pluginManifest.name;
+  const context = {
+    manifest: pluginManifest,
+    pluginPath,
+    isNpmPackage: fs.existsSync(path.join(pluginPath, "package.json"))
+  };
+  await validateSchema(context, result);
+  if (pluginManifest.contracts) {
+    for (let i = 0; i < pluginManifest.contracts.length; i++) {
+      await validateContract(
+        pluginManifest.contracts[i],
+        i,
+        context,
+        options.generateTypes || false,
+        result
+      );
+    }
+  }
+  if (pluginManifest.contracts) {
+    for (let i = 0; i < pluginManifest.contracts.length; i++) {
+      await validateComponent(pluginManifest.contracts[i], i, context, result);
+    }
+  }
+  if (context.isNpmPackage) {
+    await validatePackageJson(context, result);
+    result.packageJsonChecked = true;
+  }
+  if (pluginManifest.dynamic_contracts) {
+    await validateDynamicContracts(context, result);
+  }
+  result.valid = result.errors.length === 0;
+  return result;
+}
+async function validateLocalPlugins(projectPath, options) {
+  const pluginsPath = path.join(projectPath, "src/plugins");
+  if (!fs.existsSync(pluginsPath)) {
+    return {
+      valid: false,
+      errors: [
+        {
+          type: "file-missing",
+          message: "src/plugins/ directory not found",
+          location: projectPath,
+          suggestion: "Create src/plugins/ directory for local plugins"
+        }
+      ],
+      warnings: []
+    };
+  }
+  const pluginDirs = fs.readdirSync(pluginsPath, { withFileTypes: true }).filter((d) => d.isDirectory());
+  const allResults = [];
+  for (const pluginDir of pluginDirs) {
+    const pluginPath = path.join(pluginsPath, pluginDir.name);
+    const result = await validatePluginPackage(pluginPath, options);
+    allResults.push(result);
+  }
+  return {
+    valid: allResults.every((r) => r.valid),
+    errors: allResults.flatMap((r) => r.errors),
+    warnings: allResults.flatMap((r) => r.warnings),
+    contractsChecked: allResults.reduce((sum, r) => sum + (r.contractsChecked || 0), 0),
+    componentsChecked: allResults.reduce((sum, r) => sum + (r.componentsChecked || 0), 0),
+    typesGenerated: allResults.reduce((sum, r) => sum + (r.typesGenerated || 0), 0)
+  };
+}
+async function validateSchema(context, result) {
+  const { manifest } = context;
+  if (!manifest.name) {
+    result.errors.push({
+      type: "schema",
+      message: "Missing required field: name",
+      location: "plugin.yaml",
+      suggestion: 'Add a "name" field with a kebab-case plugin name'
+    });
+  } else if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(manifest.name)) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid plugin name: "${manifest.name}". Must be kebab-case.`,
+      location: "plugin.yaml",
+      suggestion: 'Use lowercase letters, numbers, and hyphens only (e.g., "my-plugin")'
+    });
+  }
+  if (manifest.contracts) {
+    if (!Array.isArray(manifest.contracts)) {
+      result.errors.push({
+        type: "schema",
+        message: 'Field "contracts" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.contracts.forEach((contract, index) => {
+        if (!contract.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!contract.contract) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract "${contract.name || index}" is missing "contract" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify path to .jay-contract file"
+          });
+        }
+        if (!contract.component) {
+          result.errors.push({
+            type: "schema",
+            message: `Contract "${contract.name || index}" is missing "component" field`,
+            location: "plugin.yaml",
+            suggestion: 'Specify the exported member name from the module (e.g., "moodTracker")'
+          });
+        }
+      });
+    }
+  }
+  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")'
+      });
+    }
+  }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
+    result.warnings.push({
+      type: "schema",
+      message: "Plugin has no contracts or dynamic_contracts defined",
+      location: "plugin.yaml",
+      suggestion: 'Add either "contracts" or "dynamic_contracts" to expose functionality'
+    });
+  }
+}
+async function validateContract(contract, index, context, generateTypes, result) {
+  result.contractsChecked = (result.contractsChecked || 0) + 1;
+  let contractPath;
+  if (context.isNpmPackage) {
+    const contractSpec = contract.contract;
+    const possiblePaths = [
+      path.join(context.pluginPath, "dist", contractSpec),
+      path.join(context.pluginPath, "lib", contractSpec),
+      path.join(context.pluginPath, contractSpec)
+    ];
+    let found = false;
+    for (const possiblePath of possiblePaths) {
+      if (fs.existsSync(possiblePath)) {
+        contractPath = possiblePath;
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Contract file not found: ${contractSpec}`,
+        location: `plugin.yaml contracts[${index}]`,
+        suggestion: `Ensure the contract file exists (looked in dist/, lib/, and root)`
+      });
+      return;
+    }
+  } else {
+    contractPath = path.join(context.pluginPath, contract.contract);
+    if (!fs.existsSync(contractPath)) {
+      result.errors.push({
+        type: "file-missing",
+        message: `Contract file not found: ${contract.contract}`,
+        location: `plugin.yaml contracts[${index}]`,
+        suggestion: `Create the contract file at ${contractPath}`
+      });
+      return;
+    }
+  }
+  try {
+    const contractContent = await fs.promises.readFile(contractPath, "utf-8");
+    const parsedContract = YAML.parse(contractContent);
+    if (!parsedContract.name) {
+      result.errors.push({
+        type: "contract-invalid",
+        message: `Contract file ${contract.contract} is missing "name" field`,
+        location: contractPath
+      });
+    }
+    if (!parsedContract.tags || !Array.isArray(parsedContract.tags)) {
+      result.errors.push({
+        type: "contract-invalid",
+        message: `Contract file ${contract.contract} is missing "tags" array`,
+        location: contractPath
+      });
+    }
+  } catch (error) {
+    result.errors.push({
+      type: "contract-invalid",
+      message: `Invalid contract YAML: ${error.message}`,
+      location: contractPath,
+      suggestion: "Check YAML syntax and ensure it follows Jay contract format"
+    });
+    return;
+  }
+  if (generateTypes) {
+    try {
+      const { compileContractFile } = await import("@jay-framework/compiler-jay-html");
+      const dtsPath = contractPath + ".d.ts";
+      await compileContractFile(contractPath, dtsPath);
+      result.typesGenerated = (result.typesGenerated || 0) + 1;
+    } catch (error) {
+      result.errors.push({
+        type: "type-generation-failed",
+        message: `Failed to generate types for ${contract.contract}: ${error.message}`,
+        location: contractPath
+      });
+    }
+  }
+}
+async function validateComponent(contract, index, context, result) {
+  result.componentsChecked = (result.componentsChecked || 0) + 1;
+  if (typeof contract.component !== "string" || contract.component.length === 0) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid component name: ${contract.component}`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: 'Component should be the exported member name (e.g., "moodTracker")'
+    });
+  }
+  if (contract.component.includes("/") || contract.component.includes(".")) {
+    result.warnings.push({
+      type: "schema",
+      message: `Component "${contract.component}" looks like a path. Should it be an export name?`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: 'Component should be the exported member name (e.g., "moodTracker"), not a file path'
+    });
+  }
+}
+async function validatePackageJson(context, result) {
+  const packageJsonPath = path.join(context.pluginPath, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    result.warnings.push({
+      type: "file-missing",
+      message: "package.json not found",
+      location: context.pluginPath,
+      suggestion: "Create a package.json file for NPM package distribution"
+    });
+    return;
+  }
+  try {
+    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf-8"));
+    if (!packageJson.exports) {
+      result.warnings.push({
+        type: "export-mismatch",
+        message: 'package.json missing "exports" field',
+        location: packageJsonPath,
+        suggestion: "Add exports field to define entry points for server/client builds"
+      });
+    } else {
+      if (!packageJson.exports["."]) {
+        result.warnings.push({
+          type: "export-mismatch",
+          message: 'package.json exports missing "." entry point',
+          location: packageJsonPath,
+          suggestion: 'Add "." export for the main module entry'
+        });
+      }
+      if (context.manifest.contracts) {
+        for (const contract of context.manifest.contracts) {
+          const contractExport = "./" + contract.contract;
+          if (!packageJson.exports[contractExport]) {
+            result.errors.push({
+              type: "export-mismatch",
+              message: `Contract "${contract.name}" not exported in package.json`,
+              location: packageJsonPath,
+              suggestion: `Add "${contractExport}": "./dist/${contract.contract}" to exports field`
+            });
+          }
+        }
+      }
+      if (!packageJson.exports["."]) {
+        result.errors.push({
+          type: "export-mismatch",
+          message: 'NPM package missing "." export in package.json',
+          location: packageJsonPath,
+          suggestion: 'Add ".": "./dist/index.js" (or your main file) to exports field'
+        });
+      }
+      if (context.manifest.module) {
+        const moduleName = context.manifest.module;
+        result.warnings.push({
+          type: "schema",
+          message: 'NPM packages should omit the "module" field - the package main export will be used',
+          location: "plugin.yaml",
+          suggestion: 'Remove the "module" field from plugin.yaml'
+        });
+      }
+    }
+    if (!packageJson.exports || !packageJson.exports["./plugin.yaml"]) {
+      result.errors.push({
+        type: "export-mismatch",
+        message: "plugin.yaml not exported in package.json (required for plugin resolution)",
+        location: packageJsonPath,
+        suggestion: 'Add "./plugin.yaml": "./plugin.yaml" to exports field'
+      });
+    }
+  } catch (error) {
+    result.errors.push({
+      type: "schema",
+      message: `Invalid package.json: ${error.message}`,
+      location: packageJsonPath
+    });
+  }
+}
+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;
+      }
+    }
+    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 (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;
+      }
+    }
+    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`
+      });
+    }
+  }
+}
+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) => {
+  try {
+    await startDevServer({
+      projectPath: path2 || process.cwd()
+    });
+  } catch (error) {
+    console.error(chalk.red("Error starting dev server:"), error.message);
+    process.exit(1);
+  }
+});
+program.command("validate-plugin [path]").description("Validate a Jay Stack plugin package").option("--local", "Validate local plugins in src/plugins/").option("-v, --verbose", "Show detailed validation output").option("--strict", "Treat warnings as errors (for CI)").option("--generate-types", "Generate .d.ts files for contracts").action(async (pluginPath, options) => {
+  try {
+    const result = await validatePlugin({
+      pluginPath: pluginPath || process.cwd(),
+      local: options.local,
+      verbose: options.verbose,
+      strict: options.strict,
+      generateTypes: options.generateTypes
+    });
+    printValidationResult(result, options.verbose);
+    if (!result.valid || options.strict && result.warnings.length > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(chalk.red("Validation error:"), error.message);
+    process.exit(1);
+  }
 });
+program.parse(process.argv);
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}
+function printValidationResult(result, verbose) {
+  if (result.valid && result.warnings.length === 0) {
+    console.log(chalk.green("✅ Plugin validation successful!\n"));
+    if (verbose) {
+      console.log("Plugin:", result.pluginName);
+      console.log("  ✅ plugin.yaml valid");
+      console.log(`  ✅ ${result.contractsChecked} contracts validated`);
+      if (result.typesGenerated) {
+        console.log(`  ✅ ${result.typesGenerated} type definitions generated`);
+      }
+      console.log(`  ✅ ${result.componentsChecked} components validated`);
+      if (result.packageJsonChecked) {
+        console.log("  ✅ package.json valid");
+      }
+      console.log("\nNo errors found.");
+    }
+  } else if (result.valid && result.warnings.length > 0) {
+    console.log(chalk.yellow("⚠️  Plugin validation passed with warnings\n"));
+    console.log("Warnings:");
+    result.warnings.forEach((warning) => {
+      console.log(chalk.yellow(`  ⚠️  ${warning.message}`));
+      if (warning.location) {
+        console.log(chalk.gray(`      Location: ${warning.location}`));
+      }
+      if (warning.suggestion) {
+        console.log(chalk.gray(`      → ${warning.suggestion}`));
+      }
+      console.log();
+    });
+    console.log(chalk.gray("Use --strict to treat warnings as errors."));
+  } else {
+    console.log(chalk.red("❌ Plugin validation failed\n"));
+    console.log("Errors:");
+    result.errors.forEach((error) => {
+      console.log(chalk.red(`  ❌ ${error.message}`));
+      if (error.location) {
+        console.log(chalk.gray(`      Location: ${error.location}`));
+      }
+      if (error.suggestion) {
+        console.log(chalk.gray(`      → ${error.suggestion}`));
+      }
+      console.log();
+    });
+    console.log(chalk.red(`${result.errors.length} errors found.`));
+  }
+}
 export {
   createEditorHandlers,
   getConfigWithDefaults,
   loadConfig,
+  startDevServer,
   updateConfig
 };