@jay-framework/jay-stack-cli 0.15.4 → 0.15.6

package/dist/index.js

@@ -8,12 +8,13 @@ import path from "path";
 import fs, { promises } from "fs";
 import YAML from "yaml";
 import { getLogger, createDevLogger, setDevLogger } from "@jay-framework/logger";
-import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile } from "@jay-framework/compiler-jay-html";
+import { parseJayFile, JAY_IMPORT_RESOLVER, generateElementDefinitionFile, ContractTagType, parseContract, generateElementFile, htmlElementTagNameMap } from "@jay-framework/compiler-jay-html";
 import { JAY_CONTRACT_EXTENSION, JAY_EXTENSION, resolvePluginManifest, LOCAL_PLUGIN_PATH, 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 { createRequire } from "module";
 import { glob } from "glob";
 import { parse } from "node-html-parser";
 const DEFAULT_CONFIG = {
@@ -244,7 +245,7 @@ function getCommonStyles(node) {
     transformStyles.push(`rotate(${node.rotation}deg)`);
   }
   if (node.effects && Array.isArray(node.effects) && node.effects.length > 0) {
-    const visibleEffects = node.effects.filter((e) => e.visible !== false).reverse();
+    const visibleEffects = node.effects.filter((e2) => e2.visible !== false).reverse();
     const filterFunctions = [];
     const boxShadows = [];
     for (const effect of visibleEffects) {
@@ -410,7 +411,7 @@ function getStrokeStyles(node) {
   if (!node.strokes || node.strokes.length === 0) {
     return "";
   }
-  const visibleStrokes = node.strokes.filter((s) => s.visible !== false);
+  const visibleStrokes = node.strokes.filter((s2) => s2.visible !== false);
   if (visibleStrokes.length === 0) {
     return "";
   }
@@ -1588,9 +1589,9 @@ function convertContractToProtocol(contract) {
 }
 async function isPageDirectory(dirPath) {
   const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
-  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 hasPageHtml = entries.some((e2) => e2.name === PAGE_FILENAME);
+  const hasPageContract = entries.some((e2) => e2.name === PAGE_CONTRACT_FILENAME);
+  const hasPageConfig = entries.some((e2) => e2.name === PAGE_CONFIG_FILENAME);
   const isPage = hasPageHtml || hasPageContract || hasPageConfig;
   return { isPage, hasPageHtml, hasPageContract, hasPageConfig };
 }
@@ -2155,7 +2156,7 @@ function createEditorHandlers(config, tsConfigPath, projectRoot) {
     }
     return {
       type: "publish",
-      success: status.every((s) => s.success),
+      success: status.every((s2) => s2.success),
       status
     };
   };
@@ -2511,6 +2512,280 @@ async function startDevServer(options = {}) {
   process.on("SIGTERM", shutdown);
   process.on("SIGINT", shutdown);
 }
+const s = createRequire(import.meta.url), e = s("typescript"), u = e;
+new Proxy(e, {
+  get(t, r) {
+    return t[r];
+  }
+});
+const FRAMEWORK_PROP_TYPES = /* @__PURE__ */ new Set(["PageProps", "RequestQuery"]);
+function checkComponentPropsAndParams(sourceCode, contract, contractName, contractPath, sourcePath) {
+  const errors = [];
+  const warnings = [];
+  const sourceFile = u.createSourceFile(
+    sourcePath,
+    sourceCode,
+    u.ScriptTarget.Latest,
+    true,
+    u.ScriptKind.TS
+  );
+  const localInterfaces = collectLocalInterfaces(sourceFile);
+  const contractImportedTypes = collectContractImportedTypes(sourceFile);
+  const builderInfo = analyzeBuilderChains(sourceFile);
+  for (const propsTypeName of builderInfo.propsTypeNames) {
+    checkPropsConsistency(
+      propsTypeName,
+      localInterfaces,
+      contractImportedTypes,
+      contract,
+      contractName,
+      contractPath,
+      sourcePath,
+      errors,
+      warnings
+    );
+  }
+  if (builderInfo.hasLoadParams) {
+    checkParamsConsistency(
+      builderInfo.paramsTypeNames,
+      localInterfaces,
+      contractImportedTypes,
+      contract,
+      contractName,
+      contractPath,
+      sourcePath,
+      errors,
+      warnings
+    );
+  }
+  return { errors, warnings };
+}
+function collectLocalInterfaces(sourceFile) {
+  const interfaces = /* @__PURE__ */ new Map();
+  for (const statement of sourceFile.statements) {
+    if (u.isInterfaceDeclaration(statement)) {
+      const name = statement.name.text;
+      const properties = [];
+      for (const member of statement.members) {
+        if (u.isPropertySignature(member) && member.name) {
+          if (u.isIdentifier(member.name)) {
+            properties.push(member.name.text);
+          } else if (u.isStringLiteral(member.name)) {
+            properties.push(member.name.text);
+          }
+        }
+      }
+      const extendsTypes = [];
+      if (statement.heritageClauses) {
+        for (const clause of statement.heritageClauses) {
+          for (const type of clause.types) {
+            if (u.isIdentifier(type.expression)) {
+              extendsTypes.push(type.expression.text);
+            }
+          }
+        }
+      }
+      interfaces.set(name, { name, properties, extendsTypes });
+    }
+    if (u.isTypeAliasDeclaration(statement)) {
+      const name = statement.name.text;
+      if (u.isTypeLiteralNode(statement.type)) {
+        const properties = [];
+        for (const member of statement.type.members) {
+          if (u.isPropertySignature(member) && member.name) {
+            if (u.isIdentifier(member.name)) {
+              properties.push(member.name.text);
+            }
+          }
+        }
+        interfaces.set(name, { name, properties, extendsTypes: [] });
+      }
+    }
+  }
+  return interfaces;
+}
+function collectContractImportedTypes(sourceFile) {
+  const contractTypes = /* @__PURE__ */ new Set();
+  for (const statement of sourceFile.statements) {
+    if (!u.isImportDeclaration(statement))
+      continue;
+    const moduleSpecifier = statement.moduleSpecifier;
+    if (!u.isStringLiteral(moduleSpecifier))
+      continue;
+    const modulePath = moduleSpecifier.text;
+    if (!modulePath.includes(".jay-contract"))
+      continue;
+    const importClause = statement.importClause;
+    if (!importClause)
+      continue;
+    const namedBindings = importClause.namedBindings;
+    if (namedBindings && u.isNamedImports(namedBindings)) {
+      for (const element of namedBindings.elements) {
+        contractTypes.add(element.name.text);
+      }
+    }
+  }
+  return contractTypes;
+}
+function analyzeBuilderChains(sourceFile) {
+  const result = {
+    propsTypeNames: [],
+    hasLoadParams: false,
+    paramsTypeNames: []
+  };
+  visitNode(sourceFile, result);
+  return result;
+}
+function visitNode(node, result) {
+  if (u.isCallExpression(node)) {
+    const expr = node.expression;
+    if (u.isPropertyAccessExpression(expr) && expr.name.text === "withProps") {
+      if (node.typeArguments && node.typeArguments.length > 0) {
+        const typeNames = extractTypeNames(node.typeArguments[0]);
+        result.propsTypeNames.push(...typeNames);
+      }
+    }
+    if (u.isPropertyAccessExpression(expr) && expr.name.text === "withLoadParams") {
+      result.hasLoadParams = true;
+      if (node.typeArguments && node.typeArguments.length > 0) {
+        const typeNames = extractTypeNames(node.typeArguments[0]);
+        result.paramsTypeNames.push(...typeNames);
+      }
+      if (node.arguments.length > 0) {
+        const arg = node.arguments[0];
+        if (u.isIdentifier(arg))
+          ;
+      }
+    }
+  }
+  u.forEachChild(node, (child) => visitNode(child, result));
+}
+function extractTypeNames(typeNode) {
+  if (u.isTypeReferenceNode(typeNode)) {
+    if (u.isIdentifier(typeNode.typeName)) {
+      return [typeNode.typeName.text];
+    }
+  }
+  if (u.isIntersectionTypeNode(typeNode)) {
+    const names = [];
+    for (const member of typeNode.types) {
+      names.push(...extractTypeNames(member));
+    }
+    return names;
+  }
+  return [];
+}
+function checkPropsConsistency(propsTypeName, localInterfaces, contractImportedTypes, contract, contractName, contractPath, sourcePath, errors, warnings) {
+  if (FRAMEWORK_PROP_TYPES.has(propsTypeName))
+    return;
+  if (contractImportedTypes.has(propsTypeName))
+    return;
+  const prefix = `[${contractName}]`;
+  const iface = localInterfaces.get(propsTypeName);
+  if (!iface) {
+    if (!contract.props || contract.props.length === 0) {
+      errors.push({
+        type: "contract-invalid",
+        message: `${prefix} component uses .withProps<${propsTypeName}>() but the contract does not declare any props`,
+        location: contractPath,
+        suggestion: `Add a props section to the contract`
+      });
+    }
+    return;
+  }
+  const ownProperties = iface.properties;
+  if (ownProperties.length === 0)
+    return;
+  if (!contract.props || contract.props.length === 0) {
+    errors.push({
+      type: "contract-invalid",
+      message: `${prefix} component uses .withProps<${propsTypeName}>() with properties [${ownProperties.join(", ")}] but the contract does not declare any props`,
+      location: contractPath,
+      suggestion: `Add to contract: props:
+` + ownProperties.map((p) => `  - name: ${p}
+    type: string`).join("\n")
+    });
+    return;
+  }
+  const contractPropNames = new Set(contract.props.map((p) => p.name));
+  for (const prop of ownProperties) {
+    if (!contractPropNames.has(prop)) {
+      errors.push({
+        type: "contract-invalid",
+        message: `${prefix} component prop "${prop}" (from ${propsTypeName}) is not declared in the contract`,
+        location: contractPath,
+        suggestion: `Add to contract props: - name: ${prop}`
+      });
+    }
+  }
+  for (const contractProp of contract.props) {
+    if (!ownProperties.includes(contractProp.name)) {
+      warnings.push({
+        type: "contract-invalid",
+        message: `${prefix} contract declares prop "${contractProp.name}" but the component's ${propsTypeName} interface does not include it`,
+        location: sourcePath,
+        suggestion: `Add "${contractProp.name}" to the ${propsTypeName} interface, or remove it from the contract`
+      });
+    }
+  }
+}
+function checkParamsConsistency(paramsTypeNames, localInterfaces, contractImportedTypes, contract, contractName, contractPath, sourcePath, errors, warnings) {
+  const prefix = `[${contractName}]`;
+  if (!contract.params || contract.params.length === 0) {
+    errors.push({
+      type: "contract-invalid",
+      message: `${prefix} component uses .withLoadParams() but the contract does not declare any params`,
+      location: contractPath,
+      suggestion: `Add a params section to the contract (e.g., params: { slug: string })`
+    });
+    for (const typeName of paramsTypeNames) {
+      if (FRAMEWORK_PROP_TYPES.has(typeName))
+        continue;
+      if (contractImportedTypes.has(typeName))
+        continue;
+      const iface = localInterfaces.get(typeName);
+      if (iface) {
+        const ownProps = iface.properties;
+        if (ownProps.length > 0) {
+          errors[errors.length - 1].suggestion = `Add to contract: params:
+` + ownProps.map((p) => `  ${p}: string`).join("\n");
+        }
+      }
+    }
+    return;
+  }
+  for (const typeName of paramsTypeNames) {
+    if (FRAMEWORK_PROP_TYPES.has(typeName))
+      continue;
+    if (contractImportedTypes.has(typeName))
+      continue;
+    const iface = localInterfaces.get(typeName);
+    if (!iface)
+      continue;
+    const ownProperties = iface.properties;
+    const contractParamNames = new Set(contract.params.map((p) => p.name));
+    for (const prop of ownProperties) {
+      if (!contractParamNames.has(prop)) {
+        errors.push({
+          type: "contract-invalid",
+          message: `${prefix} component param "${prop}" (from ${typeName}) is not declared in the contract`,
+          location: contractPath,
+          suggestion: `Add to contract params: ${prop}: string`
+        });
+      }
+    }
+    for (const contractParam of contract.params) {
+      if (!ownProperties.includes(contractParam.name)) {
+        warnings.push({
+          type: "contract-invalid",
+          message: `${prefix} contract declares param "${contractParam.name}" but the component's ${typeName} interface does not include it`,
+          location: sourcePath,
+          suggestion: `Add "${contractParam.name}" to the ${typeName} interface, or remove it from the contract`
+        });
+      }
+    }
+  }
+}
 async function validatePlugin(options = {}) {
   const pluginPath = options.pluginPath || process.cwd();
   if (options.local) {
@@ -2612,6 +2887,36 @@ async function validateLocalPlugins(projectPath, options) {
     typesGenerated: allResults.reduce((sum, r) => sum + (r.typesGenerated || 0), 0)
   };
 }
+function validateDocFile(docPath, label, context, result) {
+  const resolvedPath = path.join(context.pluginPath, docPath);
+  if (!fs.existsSync(resolvedPath)) {
+    result.errors.push({
+      type: "file-missing",
+      message: `Doc file for ${label} not found: ${docPath}`,
+      location: "plugin.yaml",
+      suggestion: `Create the documentation file at ${resolvedPath}`
+    });
+    return;
+  }
+  if (context.isNpmPackage) {
+    const packageJsonPath = path.join(context.pluginPath, "package.json");
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+      if (packageJson.exports) {
+        const exportKey = "./" + docPath.replace(/^\.\//, "");
+        if (!packageJson.exports[exportKey]) {
+          result.errors.push({
+            type: "export-mismatch",
+            message: `Doc file for ${label} is not exported in package.json: ${docPath}`,
+            location: packageJsonPath,
+            suggestion: `Add "${exportKey}": "${docPath}" to the exports field`
+          });
+        }
+      }
+    } catch {
+    }
+  }
+}
 async function validateSchema(context, result) {
   const { manifest } = context;
   if (!manifest.name) {
@@ -2702,45 +3007,110 @@ async function validateSchema(context, result) {
       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) {
+  if (manifest.services) {
+    if (!Array.isArray(manifest.services)) {
       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)`
+        type: "schema",
+        message: 'Field "services" must be an array',
+        location: "plugin.yaml"
+      });
+    } else {
+      manifest.services.forEach((service, index) => {
+        if (!service.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Service at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!service.marker) {
+          result.errors.push({
+            type: "schema",
+            message: `Service "${service.name || index}" is missing "marker" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the exported service marker constant name"
+          });
+        }
+        if (service.doc) {
+          validateDocFile(service.doc, `service "${service.name}"`, context, result);
+        }
       });
-      return;
     }
-  } else {
-    contractPath = path.join(context.pluginPath, contract.contract);
-    if (!fs.existsSync(contractPath)) {
+  }
+  if (manifest.contexts) {
+    if (!Array.isArray(manifest.contexts)) {
       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}`
+        type: "schema",
+        message: 'Field "contexts" must be an array',
+        location: "plugin.yaml"
       });
-      return;
+    } else {
+      manifest.contexts.forEach((ctx, index) => {
+        if (!ctx.name) {
+          result.errors.push({
+            type: "schema",
+            message: `Context at index ${index} is missing "name" field`,
+            location: "plugin.yaml"
+          });
+        }
+        if (!ctx.marker) {
+          result.errors.push({
+            type: "schema",
+            message: `Context "${ctx.name || index}" is missing "marker" field`,
+            location: "plugin.yaml",
+            suggestion: "Specify the exported context marker constant name"
+          });
+        }
+        if (ctx.doc) {
+          validateDocFile(ctx.doc, `context "${ctx.name}"`, context, result);
+        }
+      });
+    }
+  }
+}
+function resolveContractFile(contractSpec, context) {
+  if (context.isNpmPackage) {
+    const packageJsonPath = path.join(context.pluginPath, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        if (packageJson.exports) {
+          const exportKey = "./" + contractSpec;
+          const exportValue = packageJson.exports[exportKey];
+          if (exportValue) {
+            const resolvedPath = typeof exportValue === "string" ? exportValue : exportValue.default || exportValue.import || exportValue.require;
+            if (resolvedPath) {
+              const fullPath = path.join(context.pluginPath, resolvedPath);
+              if (fs.existsSync(fullPath))
+                return fullPath;
+            }
+          }
+        }
+      } catch {
+      }
     }
+    for (const dir of ["dist", "lib", ""]) {
+      const candidate = path.join(context.pluginPath, dir, contractSpec);
+      if (fs.existsSync(candidate))
+        return candidate;
+    }
+    return void 0;
+  } else {
+    const candidate = path.join(context.pluginPath, contractSpec);
+    return fs.existsSync(candidate) ? candidate : void 0;
+  }
+}
+async function validateContract(contract, index, context, generateTypes, result) {
+  result.contractsChecked = (result.contractsChecked || 0) + 1;
+  const contractPath = resolveContractFile(contract.contract, context);
+  if (!contractPath) {
+    result.errors.push({
+      type: "file-missing",
+      message: `Contract file not found: ${contract.contract}`,
+      location: `plugin.yaml contracts[${index}]`,
+      suggestion: context.isNpmPackage ? `Ensure the contract is exported in package.json and the file exists` : `Create the contract file at ${path.join(context.pluginPath, contract.contract)}`
+    });
+    return;
   }
   try {
     const contractContent = await fs.promises.readFile(contractPath, "utf-8");
@@ -2792,6 +3162,7 @@ async function validateComponent(contract, index, context, result) {
       location: `plugin.yaml contracts[${index}]`,
       suggestion: 'Component should be the exported member name (e.g., "moodTracker")'
     });
+    return;
   }
   if (contract.component.includes("/") || contract.component.includes(".")) {
     result.warnings.push({
@@ -2801,6 +3172,143 @@ async function validateComponent(contract, index, context, result) {
       suggestion: 'Component should be the exported member name (e.g., "moodTracker"), not a file path'
     });
   }
+  await checkComponentContractConsistency(contract, context, result);
+}
+function hasExportModifier(node) {
+  return node.modifiers?.some((m) => m.kind === u.SyntaxKind.ExportKeyword) ?? false;
+}
+function resolveModulePath(basePath) {
+  for (const ext of ["", ".ts", ".js", "/index.ts", "/index.js"]) {
+    const candidate = basePath + ext;
+    if (fs.existsSync(candidate))
+      return candidate;
+  }
+  return void 0;
+}
+function resolveComponentSourcePath(componentName, context) {
+  const modulePath = context.manifest.module || "index";
+  const entryBase = path.join(context.pluginPath, modulePath);
+  const entryFile = resolveModulePath(entryBase);
+  const libEntryFile = !entryFile ? resolveModulePath(path.join(context.pluginPath, "lib", modulePath)) : void 0;
+  const sourceEntry = entryFile || libEntryFile;
+  if (!sourceEntry)
+    return void 0;
+  if (!sourceEntry.endsWith(".ts"))
+    return void 0;
+  let sourceCode;
+  try {
+    sourceCode = fs.readFileSync(sourceEntry, "utf-8");
+  } catch {
+    return void 0;
+  }
+  const sourceFile = u.createSourceFile(
+    sourceEntry,
+    sourceCode,
+    u.ScriptTarget.Latest,
+    true,
+    u.ScriptKind.TS
+  );
+  const starReexportModules = [];
+  for (const statement of sourceFile.statements) {
+    if (!u.isExportDeclaration(statement))
+      continue;
+    if (!statement.moduleSpecifier)
+      continue;
+    if (!u.isStringLiteral(statement.moduleSpecifier))
+      continue;
+    const moduleSpec = statement.moduleSpecifier.text;
+    const exportClause = statement.exportClause;
+    if (!exportClause) {
+      starReexportModules.push(moduleSpec);
+      continue;
+    }
+    if (u.isNamedExports(exportClause)) {
+      for (const element of exportClause.elements) {
+        const exportedName = element.name.text;
+        if (exportedName === componentName) {
+          const resolvedBase = path.resolve(path.dirname(sourceEntry), moduleSpec);
+          return resolveModulePath(resolvedBase);
+        }
+      }
+    }
+  }
+  for (const moduleSpec of starReexportModules) {
+    if (!moduleSpec.startsWith("."))
+      continue;
+    const resolvedBase = path.resolve(path.dirname(sourceEntry), moduleSpec);
+    const resolvedPath = resolveModulePath(resolvedBase);
+    if (!resolvedPath || !resolvedPath.endsWith(".ts"))
+      continue;
+    try {
+      const modSource = fs.readFileSync(resolvedPath, "utf-8");
+      const modFile = u.createSourceFile(
+        resolvedPath,
+        modSource,
+        u.ScriptTarget.Latest,
+        true,
+        u.ScriptKind.TS
+      );
+      for (const stmt of modFile.statements) {
+        if (u.isVariableStatement(stmt) && hasExportModifier(stmt)) {
+          for (const decl of stmt.declarationList.declarations) {
+            if (u.isIdentifier(decl.name) && decl.name.text === componentName) {
+              return resolvedPath;
+            }
+          }
+        }
+        if (u.isFunctionDeclaration(stmt) && hasExportModifier(stmt) && stmt.name?.text === componentName) {
+          return resolvedPath;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return sourceEntry;
+}
+function resolveContractPath(contract, context) {
+  return resolveContractFile(contract.contract, context);
+}
+async function checkComponentContractConsistency(contract, context, result) {
+  const componentName = contract.component;
+  if (!componentName)
+    return;
+  const sourcePath = resolveComponentSourcePath(componentName, context);
+  if (!sourcePath)
+    return;
+  if (!sourcePath.endsWith(".ts"))
+    return;
+  const contractPath = resolveContractPath(contract, context);
+  if (!contractPath)
+    return;
+  let contractContent;
+  try {
+    contractContent = await fs.promises.readFile(contractPath, "utf-8");
+  } catch {
+    return;
+  }
+  const parsed = parseContract(contractContent, path.basename(contractPath));
+  if (parsed.validations.length > 0)
+    return;
+  let sourceCode;
+  try {
+    sourceCode = await fs.promises.readFile(sourcePath, "utf-8");
+  } catch {
+    return;
+  }
+  const contractName = contract.contract.replace(/\.jay-contract$/, "");
+  const checkResult = checkComponentPropsAndParams(
+    sourceCode,
+    {
+      props: parsed.val?.props,
+      params: parsed.val?.params
+    },
+    contractName,
+    contractPath,
+    sourcePath
+  );
+  result.errors.push(...checkResult.errors);
+  result.warnings.push(...checkResult.warnings);
 }
 async function validatePackageJson(context, result) {
   const packageJsonPath = path.join(context.pluginPath, "package.json");
@@ -3129,6 +3637,128 @@ function analyzeTagCoverage(jayHtml, file) {
   }
   return { file, contracts };
 }
+const htmlTagNameMap = htmlElementTagNameMap;
+function resolveContractTag(contract, tagPath) {
+  const segments = tagPath.split(".");
+  let tags = contract.tags;
+  for (let i = 0; i < segments.length; i++) {
+    const tag = tags.find((t) => t.tag === segments[i]);
+    if (!tag)
+      return void 0;
+    if (i === segments.length - 1)
+      return tag;
+    if (!tag.tags)
+      return void 0;
+    tags = tag.tags;
+  }
+  return void 0;
+}
+function checkRefElementTypes(jayHtml, file) {
+  const imports = jayHtml.headlessImports;
+  const keyMap = /* @__PURE__ */ new Map();
+  for (let i = 0; i < imports.length; i++) {
+    if (imports[i].key) {
+      keyMap.set(imports[i].key, i);
+    }
+  }
+  const warnings = [];
+  function checkRef(ref, scopes) {
+    const refPath = ref.refPath;
+    const dot = refPath.indexOf(".");
+    let importIndex;
+    let tagPath;
+    if (dot !== -1) {
+      const key = refPath.substring(0, dot);
+      const idx = keyMap.get(key);
+      if (idx !== void 0) {
+        importIndex = idx;
+        tagPath = refPath.substring(dot + 1);
+      }
+    }
+    if (importIndex === void 0 && scopes.length > 0) {
+      const scope = scopes[scopes.length - 1];
+      importIndex = scope.importIndex;
+      tagPath = scope.prefix ? `${scope.prefix}.${refPath}` : refPath;
+    }
+    if (importIndex === void 0)
+      return;
+    const imp = imports[importIndex];
+    if (!imp.contract)
+      return;
+    const contractTag = resolveContractTag(imp.contract, tagPath);
+    if (!contractTag || !contractTag.elementType)
+      return;
+    const contractTypes = contractTag.elementType;
+    if (contractTypes.includes("HTMLElement"))
+      return;
+    if (!contractTypes.includes(ref.actualType)) {
+      const label = imp.key ? `${imp.key}.${tagPath}` : tagPath;
+      warnings.push(
+        `Ref "${label}" is on a <${ref.htmlTag}> (${ref.actualType}) but the contract declares ${contractTypes.join(" | ")}`
+      );
+    }
+  }
+  function walkElement(element, scopes) {
+    const tagName = element.rawTagName?.toLowerCase();
+    let childScopes = scopes;
+    if (tagName?.startsWith("jay:")) {
+      const contractName = tagName.substring(4);
+      const idx = imports.findIndex(
+        (imp) => imp.contractName === contractName && imp.contract
+      );
+      if (idx !== -1) {
+        childScopes = [...scopes, { importIndex: idx, prefix: "" }];
+      }
+    }
+    const forEachVal = element.getAttribute?.("forEach");
+    if (forEachVal) {
+      const fePath = extractTagPath(forEachVal);
+      if (fePath) {
+        const dot = fePath.indexOf(".");
+        if (dot !== -1) {
+          const key = fePath.substring(0, dot);
+          const idx = keyMap.get(key);
+          if (idx !== void 0) {
+            childScopes = [
+              ...childScopes,
+              { importIndex: idx, prefix: fePath.substring(dot + 1) }
+            ];
+          }
+        } else if (childScopes.length > 0) {
+          const scope = childScopes[childScopes.length - 1];
+          const newPrefix = scope.prefix ? `${scope.prefix}.${fePath}` : fePath;
+          childScopes = [
+            ...childScopes,
+            { importIndex: scope.importIndex, prefix: newPrefix }
+          ];
+        }
+      }
+    }
+    if (tagName === "with-data") {
+      const accessor = element.getAttribute?.("accessor");
+      if (accessor && accessor !== "." && childScopes.length > 0) {
+        const scope = childScopes[childScopes.length - 1];
+        const newPrefix = scope.prefix ? `${scope.prefix}.${accessor}` : accessor;
+        childScopes = [
+          ...childScopes,
+          { importIndex: scope.importIndex, prefix: newPrefix }
+        ];
+      }
+    }
+    const refVal = element.getAttribute?.("ref");
+    if (refVal && tagName) {
+      const actualType = htmlTagNameMap[tagName] ?? "HTMLElement";
+      checkRef({ refPath: refVal, htmlTag: tagName, actualType }, childScopes);
+    }
+    for (const child of element.childNodes ?? []) {
+      if (child.nodeType === 1) {
+        walkElement(child, childScopes);
+      }
+    }
+  }
+  walkElement(jayHtml.body, []);
+  return warnings;
+}
 const PARSE_PARAM = /^\[(\[)?(\.\.\.)?([^\]]+)\]?\]$/;
 function extractRouteParams(filePath, pagesBase) {
   const relative = path.relative(pagesBase, filePath);
@@ -3205,6 +3835,101 @@ function checkRouteParams(parsedFile, filePath, pagesBase, jayHtmlContent) {
   }
   return warnings;
 }
+function checkRouteToContractParams(parsedFile, filePath, pagesBase) {
+  const routeParams = extractRouteParams(filePath, pagesBase);
+  if (routeParams.size === 0)
+    return [];
+  const hasAnyContract = !!parsedFile.contract || parsedFile.headlessImports.some((imp) => !!imp.contract);
+  if (!hasAnyContract)
+    return [];
+  const declaredParams = /* @__PURE__ */ new Set();
+  if (parsedFile.contract?.params) {
+    for (const p of parsedFile.contract.params) {
+      declaredParams.add(p.name);
+    }
+  }
+  for (const imp of parsedFile.headlessImports) {
+    if (imp.contract?.params) {
+      for (const p of imp.contract.params) {
+        declaredParams.add(p.name);
+      }
+    }
+  }
+  const warnings = [];
+  for (const routeParam of routeParams) {
+    if (!declaredParams.has(routeParam)) {
+      warnings.push(
+        `Route provides param "${routeParam}" but no contract on this page declares it. Add params: { ${routeParam}: string } to the appropriate contract.`
+      );
+    }
+  }
+  return warnings;
+}
+const HEADLESS_SKIP_ATTRS = /* @__PURE__ */ new Set([
+  "foreach",
+  "if",
+  "ref",
+  "trackby",
+  "slowforeach",
+  "jayindex",
+  "jaytrackby",
+  "when-resolved",
+  "when-loading",
+  "when-rejected",
+  "accessor",
+  "props",
+  "key",
+  "jay-coordinate-base",
+  "jay-scope"
+]);
+function checkHeadlessInstanceProps(jayHtml, file) {
+  const imports = jayHtml.headlessImports;
+  const warnings = [];
+  function walkElement(element) {
+    const tagName = element.rawTagName?.toLowerCase();
+    if (tagName?.startsWith("jay:")) {
+      const contractName = tagName.substring(4);
+      const imp = imports.find((i) => i.contractName === contractName && i.contract);
+      if (imp?.contract) {
+        const contract = imp.contract;
+        const attrs = element.attributes ?? {};
+        const passedProps = /* @__PURE__ */ new Set();
+        for (const attrName of Object.keys(attrs)) {
+          if (!HEADLESS_SKIP_ATTRS.has(attrName.toLowerCase())) {
+            passedProps.add(attrName);
+          }
+        }
+        if (passedProps.size > 0) {
+          const contractPropNames = new Set((contract.props || []).map((p) => p.name));
+          for (const prop of passedProps) {
+            if (!contractPropNames.has(prop)) {
+              imp.key ? `${imp.key} (${contractName})` : contractName;
+              warnings.push(
+                `<jay:${contractName}> passes attribute "${prop}" but the "${contract.name}" contract does not declare it as a prop. Add to ${contractName}.jay-contract: props: [{ name: ${prop}, type: string }]`
+              );
+            }
+          }
+        }
+        if (contract.props) {
+          for (const contractProp of contract.props) {
+            if (contractProp.required && !passedProps.has(contractProp.name)) {
+              warnings.push(
+                `<jay:${contractName}> is missing required prop "${contractProp.name}" declared in the "${contract.name}" contract.`
+              );
+            }
+          }
+        }
+      }
+    }
+    for (const child of element.childNodes ?? []) {
+      if (child.nodeType === 1) {
+        walkElement(child);
+      }
+    }
+  }
+  walkElement(jayHtml.body);
+  return warnings;
+}
 async function validateJayFiles(options = {}) {
   const config = loadConfig();
   const resolvedConfig = getConfigWithDefaults(config);
@@ -3282,6 +4007,22 @@ async function validateJayFiles(options = {}) {
       for (const msg of routeParamWarnings) {
         warnings.push({ file: relativePath, message: msg });
       }
+      const routeToContractWarnings = checkRouteToContractParams(
+        parsedFile.val,
+        jayFile,
+        scanDir
+      );
+      for (const msg of routeToContractWarnings) {
+        warnings.push({ file: relativePath, message: msg });
+      }
+      const refTypeErrors = checkRefElementTypes(parsedFile.val, relativePath);
+      for (const msg of refTypeErrors) {
+        errors.push({ file: relativePath, message: msg, stage: "generate" });
+      }
+      const headlessPropWarnings = checkHeadlessInstanceProps(parsedFile.val, relativePath);
+      for (const msg of headlessPropWarnings) {
+        warnings.push({ file: relativePath, message: msg });
+      }
       const fileCoverage = analyzeTagCoverage(parsedFile.val, relativePath);
       if (fileCoverage) {
         coverage.push(fileCoverage);
@@ -3752,32 +4493,32 @@ program.command("validate-plugin [path]").description("Validate a Jay Stack plug
     process.exit(1);
   }
 });
-async function ensureAgentKitDocs(projectRoot, force) {
+const ALL_ROLES = ["designer", "developer", "plugin"];
+async function ensureAgentKitDocs(projectRoot, _force, mode) {
   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 {
-      }
+  const roles = mode && ALL_ROLES.includes(mode) ? [mode] : ALL_ROLES;
+  for (const role of roles) {
+    const roleTemplateDir = path2.join(templateDir, role);
+    const roleOutputDir = path2.join(agentKitDir, role);
+    let files;
+    try {
+      files = (await fs2.readdir(roleTemplateDir)).filter((f) => f.endsWith(".md"));
+    } catch {
+      continue;
+    }
+    await fs2.mkdir(roleOutputDir, { recursive: true });
+    for (const filename of files) {
+      await fs2.copyFile(
+        path2.join(roleTemplateDir, filename),
+        path2.join(roleOutputDir, filename)
+      );
+      getLogger().info(chalk.gray(`   Created agent-kit/${role}/${filename}`));
     }
-    await fs2.copyFile(path2.join(templateDir, filename), destPath);
-    getLogger().info(chalk.gray(`   Created agent-kit/${filename}`));
   }
 }
 async function generatePluginReferences(projectRoot, options, initErrors, viteServer) {
@@ -3899,7 +4640,10 @@ program.command("setup [plugin]").description(
 });
 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) => {
+).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(
+  "-m, --mode <role>",
+  "Generate guides for a specific role: designer, developer, or plugin (default: all)"
+).option("-v, --verbose", "Show detailed output").action(async (options) => {
   const projectRoot = process.cwd();
   const { initErrors, viteServer } = await runMaterialize(
     projectRoot,
@@ -3910,7 +4654,7 @@ program.command("agent-kit").description(
   );
   try {
     if (!options.list) {
-      await ensureAgentKitDocs(projectRoot, options.force);
+      await ensureAgentKitDocs(projectRoot, options.force, options.mode);
       if (options.references !== false) {
         await generatePluginReferences(projectRoot, options, initErrors, viteServer);
       }