@jay-framework/compiler-shared 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -69,6 +69,8 @@ declare const Import: {
     mimicJayElement: ImportName;
     jayContract: ImportName;
     injectHeadLinks: ImportName;
+    makeJayComponent: ImportName;
+    makeHeadlessInstanceComponent: ImportName;
 };
 declare class Imports {
     private readonly imports;
@@ -93,6 +95,7 @@ declare const JAY_SECURE = "@jay-framework/secure";
 declare const JAY_RUNTIME = "@jay-framework/runtime";
 declare const JAY_4_REACT = "@jay-framework/4-react";
 declare const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
+declare const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
 declare const REACT = "react";
 declare const MAKE_JAY_COMPONENT = "makeJayComponent";
 declare const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -386,6 +389,20 @@ declare class WithValidations<Value> {
     flatMap<R>(func: (v: Value) => WithValidations<R>): WithValidations<R>;
     flatMapAsync<R>(func: (v: Value) => Promise<WithValidations<R>>): Promise<WithValidations<R>>;
     merge(other: WithValidations<Value>, merge: (t1: Value, t2: Value) => Value): WithValidations<Value>;
+    /**
+     * Append validations from another WithValidations without changing the value.
+     * Useful for collecting validations from side-effect operations.
+     */
+    withValidationsFrom<T>(other: WithValidations<T>): WithValidations<Value>;
+    /**
+     * Merge an array of WithValidations into a single WithValidations containing an array of values.
+     * All validations are collected.
+     */
+    static all<T>(items: WithValidations<T>[]): WithValidations<T[]>;
+    /**
+     * Create a WithValidations with no validations (pure value).
+     */
+    static pure<T>(value: T): WithValidations<T>;
 }
 declare function checkValidationErrors<T>(withValidations: WithValidations<T>): T;
 
@@ -475,6 +492,17 @@ declare function removeComments(code: string): string;
  * ```
  */
 type PluginInitConfig = string;
+/**
+ * Dynamic contract generator configuration.
+ */
+interface DynamicContractConfig {
+    /** Path to the generator module (relative to plugin root) */
+    generator: string;
+    /** Path to the headless component (relative to plugin root) */
+    component: string;
+    /** Prefix for generated contract names (e.g., "cms" -> "cms/blog-posts") */
+    prefix: string;
+}
 /**
  * Plugin manifest structure from plugin.yaml
  */
@@ -488,15 +516,20 @@ interface PluginManifest {
         component: string;
         description?: string;
     }>;
-    dynamic_contracts?: {
-        generator: string;
-        component: string;
-        prefix: string;
-    };
+    dynamic_contracts?: DynamicContractConfig | DynamicContractConfig[];
     /** Named exports from plugin backend bundle that are JayAction instances */
     actions?: string[];
     /** Plugin initialization configuration */
     init?: PluginInitConfig;
+    /** Plugin setup configuration (Design Log #87) */
+    setup?: {
+        /** Export name (NPM) or relative path (local) to setup handler function */
+        handler: string;
+        /** Export name for reference data generation (called by jay-stack agent-kit) */
+        references?: string;
+        /** Human-readable description of what setup does */
+        description?: string;
+    };
 }
 /**
  * Result of resolving a plugin component
@@ -548,4 +581,4 @@ declare function resolveNpmPlugin(projectRoot: string, pluginName: string, contr
  */
 declare function resolvePluginComponent(projectRoot: string, pluginName: string, contractName: string): WithValidations<PluginComponentResolution>;
 
-export { CSS_EXTENSION, type CompilerSourceFile, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, equalJayTypes, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isPromiseType, isRecursiveType, isTypeAliasType, isUnionType, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolveLocalPlugin, resolveNpmPlugin, resolvePluginComponent, resolvePrimitiveType, withOriginalTrace, withoutExtension };
+export { CSS_EXTENSION, type CompilerSourceFile, type DynamicContractConfig, GenerateTarget, type GenericTypescriptSourceFile, Import, type ImportName, type ImportedRefsTree, Imports, ImportsFor, JAY_4_REACT, JAY_COMPONENT, JAY_CONTRACT_DTS_EXTENSION, JAY_CONTRACT_EXTENSION, JAY_DTS_EXTENSION, JAY_EXTENSION, JAY_FULLSTACK_COMPONENTS, JAY_QUERY_CLIENT, JAY_QUERY_MAIN_SANDBOX, JAY_QUERY_MAIN_SANDBOX_TS, JAY_QUERY_PREFIX, JAY_QUERY_SERVER, JAY_QUERY_WORKER_SANDBOX, JAY_QUERY_WORKER_SANDBOX_TS, JAY_QUERY_WORKER_TRUSTED, JAY_QUERY_WORKER_TRUSTED_TS, JAY_RUNTIME, JAY_SECURE, JAY_STACK_CLIENT_RUNTIME, JAY_TS_EXTENSION, JayArrayType, JayAtomicType, JayBoolean, JayBuildEnvironment, JayComponentApiMember, JayComponentType, JayDate, JayElementConstructorType, JayElementType, JayEnumType, type JayEnvironment, JayErrorType, JayHTMLType, type JayImportLink, type JayImportName, JayImportedType, JayNumber, JayObjectType, JayPromiseType, JayRecursiveType, JayString, type JayType, JayTypeAlias, JayTypeKind, JayUnionType, JayUnknown, type JayValidations, MAKE_JAY_4_REACT_COMPONENT, MAKE_JAY_COMPONENT, MAKE_JAY_TSX_COMPONENT, type MainRuntimeModes, type ParsedJayModuleSpecifier, type PluginComponentResolution, type PluginInitConfig, type PluginManifest, REACT, type RecursiveRegion, type Ref, type RefsTree, RenderFragment, RuntimeMode, SourceFileFormat, TSX_EXTENSION, TS_EXTENSION, WithValidations, addBuildEnvironment, checkValidationErrors, equalJayTypes, getBasePath, getBuildEnvironment, getJayTsFileSourcePath, getMode, getModeFileExtension, getModeFromExtension, hasBuildEnvironment, hasExtension, hasJayExtension, hasJayModeExtension, hasRefs, isArrayType, isAtomicType, isComponentType, isCurrencyType, isDateWithTimezoneType, isElementConstructorType, isElementType, isEnumType, isHTMLType, isImportedType, isLocalModule, isObjectType, isPromiseType, isRecursiveType, isTypeAliasType, isUnionType, loadPluginManifest, mergeRefsTrees, mkRef, mkRefsTree, nestRefs, parseJayModuleSpecifier, prettify, prettifyHtml, removeComments, resolveLocalPlugin, resolveNpmPlugin, resolvePluginComponent, resolvePrimitiveType, withOriginalTrace, withoutExtension };

package/dist/index.js

@@ -21,6 +21,7 @@ const JAY_SECURE = "@jay-framework/secure";
 const JAY_RUNTIME = "@jay-framework/runtime";
 const JAY_4_REACT = "@jay-framework/4-react";
 const JAY_FULLSTACK_COMPONENTS = "@jay-framework/fullstack-component";
+const JAY_STACK_CLIENT_RUNTIME = "@jay-framework/stack-client-runtime";
 const REACT = "react";
 const MAKE_JAY_COMPONENT = "makeJayComponent";
 const MAKE_JAY_TSX_COMPONENT = "makeJayTsxComponent";
@@ -400,6 +401,18 @@ const Import = {
     "injectHeadLinks",
     1
     /* implementation */
+  ),
+  makeJayComponent: importStatementFragment(
+    JAY_COMPONENT,
+    "makeJayComponent",
+    1
+    /* implementation */
+  ),
+  makeHeadlessInstanceComponent: importStatementFragment(
+    JAY_STACK_CLIENT_RUNTIME,
+    "makeHeadlessInstanceComponent",
+    1
+    /* implementation */
   )
 };
 class Imports {
@@ -928,6 +941,28 @@ class WithValidations {
       ...other.validations
     ]);
   }
+  /**
+   * Append validations from another WithValidations without changing the value.
+   * Useful for collecting validations from side-effect operations.
+   */
+  withValidationsFrom(other) {
+    return new WithValidations(this.val, [...this.validations, ...other.validations]);
+  }
+  /**
+   * Merge an array of WithValidations into a single WithValidations containing an array of values.
+   * All validations are collected.
+   */
+  static all(items) {
+    const values = items.map((item) => item.val).filter((v) => v !== void 0);
+    const validations = items.flatMap((item) => item.validations);
+    return new WithValidations(values, validations);
+  }
+  /**
+   * Create a WithValidations with no validations (pure value).
+   */
+  static pure(value) {
+    return new WithValidations(value, []);
+  }
 }
 function checkValidationErrors(withValidations) {
   const { validations } = withValidations;
@@ -1102,6 +1137,18 @@ function loadPluginManifest(pluginDir) {
     return null;
   }
 }
+function findDynamicContract(manifest, contractName) {
+  if (!manifest.dynamic_contracts) {
+    return null;
+  }
+  const slashIndex = contractName.indexOf("/");
+  if (slashIndex === -1) {
+    return null;
+  }
+  const prefix = contractName.substring(0, slashIndex);
+  const dynamicConfigs = Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts];
+  return dynamicConfigs.find((config) => config.prefix === prefix) || null;
+}
 function resolveLocalPlugin(projectRoot, pluginName, contractName) {
   const localPluginPath = path.join(projectRoot, "src/plugins", pluginName);
   const pluginYamlPath = path.join(localPluginPath, "plugin.yaml");
@@ -1119,30 +1166,46 @@ function resolveLocalPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for local plugin "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
-  if (!manifest.contracts || manifest.contracts.length === 0) {
-    return new WithValidations(null, [
-      `Local plugin "${pluginName}" has no contracts defined in plugin.yaml`
-    ]);
+  const componentModule = manifest.module || "index.js";
+  const componentPath = path.join(localPluginPath, componentModule);
+  if (manifest.contracts && manifest.contracts.length > 0) {
+    const contract = manifest.contracts.find((c2) => c2.name === contractName);
+    if (contract) {
+      return new WithValidations(
+        {
+          contractPath: path.join(localPluginPath, contract.contract),
+          componentPath,
+          componentName: contract.component,
+          isNpmPackage: false
+        },
+        []
+      );
+    }
   }
-  const contract = manifest.contracts.find((c2) => c2.name === contractName);
-  if (!contract) {
-    const availableContracts = manifest.contracts.map((c2) => c2.name).join(", ");
+  const dynamicConfig = findDynamicContract(manifest, contractName);
+  if (dynamicConfig) {
+    return new WithValidations(
+      {
+        contractPath: "",
+        // Dynamic contracts don't have a static path
+        componentPath,
+        componentName: dynamicConfig.component,
+        isNpmPackage: false
+      },
+      []
+    );
+  }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
     return new WithValidations(null, [
-      `Contract "${contractName}" not found in local plugin "${pluginName}". Available contracts: ${availableContracts}`
+      `Local plugin "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
     ]);
   }
-  const componentModule = manifest.module || "index.js";
-  const componentPath = path.join(localPluginPath, componentModule);
-  return new WithValidations(
-    {
-      contractPath: path.join(localPluginPath, contract.contract),
-      componentPath,
-      componentName: contract.component,
-      // This is the exported member name
-      isNpmPackage: false
-    },
-    []
-  );
+  const availableContracts = manifest.contracts?.map((c2) => c2.name) || [];
+  const dynamicPrefixes = manifest.dynamic_contracts ? (Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts]).map((c2) => `${c2.prefix}/*`) : [];
+  const allAvailable = [...availableContracts, ...dynamicPrefixes].join(", ");
+  return new WithValidations(null, [
+    `Contract "${contractName}" not found in local plugin "${pluginName}". Available: ${allAvailable}`
+  ]);
 }
 function resolveNpmPlugin(projectRoot, pluginName, contractName) {
   let pluginYamlPath;
@@ -1167,65 +1230,88 @@ function resolveNpmPlugin(projectRoot, pluginName, contractName) {
       `Failed to parse plugin.yaml for NPM package "${pluginName}" at ${pluginYamlPath}`
     ]);
   }
-  if (!manifest.contracts || manifest.contracts.length === 0) {
-    return new WithValidations(null, [
-      `NPM package "${pluginName}" has no contracts defined in plugin.yaml`
-    ]);
-  }
-  const contract = manifest.contracts.find((c2) => c2.name === contractName);
-  if (!contract) {
-    const availableContracts = manifest.contracts.map((c2) => c2.name).join(", ");
-    return new WithValidations(null, [
-      `Contract "${contractName}" not found in NPM package "${pluginName}". Available contracts: ${availableContracts}`
-    ]);
-  }
   const packageJsonPath = path.join(npmPluginPath, "package.json");
-  let componentPath;
-  let contractPath;
-  if (fs.existsSync(packageJsonPath)) {
-    try {
-      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-      const packageName = packageJson.name;
-      const moduleName = manifest.module || packageName;
-      if ((moduleName === packageName || !manifest.module) && packageJson.exports && packageJson.exports["."]) {
-        const mainExport = packageJson.exports["."];
-        const mainPath = typeof mainExport === "string" ? mainExport : mainExport.default || mainExport.import;
-        componentPath = path.join(npmPluginPath, mainPath);
-      } else {
-        componentPath = path.join(npmPluginPath, "dist/index.js");
+  const getComponentPath = () => {
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+        const packageName = packageJson.name;
+        const moduleName = manifest.module || packageName;
+        if ((moduleName === packageName || !manifest.module) && packageJson.exports && packageJson.exports["."]) {
+          const mainExport = packageJson.exports["."];
+          const mainPath = typeof mainExport === "string" ? mainExport : mainExport.default || mainExport.import;
+          return path.join(npmPluginPath, mainPath);
+        }
+      } catch {
       }
-      const contractSpec = contract.contract;
-      const contractExportKey = "./" + contractSpec;
-      if (packageJson.exports && packageJson.exports[contractExportKey]) {
-        const exportPath = packageJson.exports[contractExportKey];
-        contractPath = path.join(npmPluginPath, exportPath);
+    }
+    return path.join(npmPluginPath, "dist/index.js");
+  };
+  if (manifest.contracts && manifest.contracts.length > 0) {
+    const contract = manifest.contracts.find((c2) => c2.name === contractName);
+    if (contract) {
+      const componentPath = getComponentPath();
+      let contractPath;
+      if (fs.existsSync(packageJsonPath)) {
+        try {
+          const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+          const contractSpec = contract.contract;
+          const contractExportKey = "./" + contractSpec;
+          if (packageJson.exports && packageJson.exports[contractExportKey]) {
+            const exportPath = packageJson.exports[contractExportKey];
+            contractPath = path.join(npmPluginPath, exportPath);
+          } else {
+            const possiblePaths = [
+              path.join(npmPluginPath, "dist", contractSpec),
+              path.join(npmPluginPath, "lib", contractSpec),
+              path.join(npmPluginPath, contractSpec)
+            ];
+            contractPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+          }
+        } catch {
+          contractPath = path.join(npmPluginPath, "dist", contract.contract);
+        }
       } else {
-        const possiblePaths = [
-          path.join(npmPluginPath, "dist", contractSpec),
-          path.join(npmPluginPath, "lib", contractSpec),
-          path.join(npmPluginPath, contractSpec)
-        ];
-        contractPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+        contractPath = path.join(npmPluginPath, "dist", contract.contract);
       }
-    } catch (error) {
-      componentPath = path.join(npmPluginPath, "dist/index.js");
-      contractPath = path.join(npmPluginPath, "dist", contract.contract);
+      return new WithValidations(
+        {
+          contractPath,
+          componentPath,
+          componentName: contract.component,
+          isNpmPackage: true,
+          packageName: pluginName
+        },
+        []
+      );
     }
-  } else {
-    componentPath = path.join(npmPluginPath, "dist/index.js");
-    contractPath = path.join(npmPluginPath, "dist", contract.contract);
   }
-  return new WithValidations(
-    {
-      contractPath,
-      componentPath,
-      componentName: contract.component,
-      // This is the exported member name
-      isNpmPackage: true,
-      packageName: pluginName
-    },
-    []
-  );
+  const dynamicConfig = findDynamicContract(manifest, contractName);
+  if (dynamicConfig) {
+    const componentPath = getComponentPath();
+    return new WithValidations(
+      {
+        contractPath: "",
+        // Dynamic contracts don't have a static path
+        componentPath,
+        componentName: dynamicConfig.component,
+        isNpmPackage: true,
+        packageName: pluginName
+      },
+      []
+    );
+  }
+  if (!manifest.contracts && !manifest.dynamic_contracts) {
+    return new WithValidations(null, [
+      `NPM package "${pluginName}" has no contracts or dynamic_contracts defined in plugin.yaml`
+    ]);
+  }
+  const availableContracts = manifest.contracts?.map((c2) => c2.name) || [];
+  const dynamicPrefixes = manifest.dynamic_contracts ? (Array.isArray(manifest.dynamic_contracts) ? manifest.dynamic_contracts : [manifest.dynamic_contracts]).map((c2) => `${c2.prefix}/*`) : [];
+  const allAvailable = [...availableContracts, ...dynamicPrefixes].join(", ");
+  return new WithValidations(null, [
+    `Contract "${contractName}" not found in NPM package "${pluginName}". Available: ${allAvailable}`
+  ]);
 }
 function resolvePluginComponent(projectRoot, pluginName, contractName) {
   const localResult = resolveLocalPlugin(projectRoot, pluginName, contractName);
@@ -1272,6 +1358,7 @@ export {
   JAY_QUERY_WORKER_TRUSTED_TS,
   JAY_RUNTIME,
   JAY_SECURE,
+  JAY_STACK_CLIENT_RUNTIME,
   JAY_TS_EXTENSION,
   JayArrayType,
   JayAtomicType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/compiler-shared",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "",
   "license": "Apache-2.0",
@@ -25,10 +25,10 @@
   },
   "author": "",
   "dependencies": {
-    "@jay-framework/component": "^0.11.0",
-    "@jay-framework/runtime": "^0.11.0",
-    "@jay-framework/secure": "^0.11.0",
-    "@jay-framework/typescript-bridge": "^0.6.0",
+    "@jay-framework/component": "^0.12.0",
+    "@jay-framework/runtime": "^0.12.0",
+    "@jay-framework/secure": "^0.12.0",
+    "@jay-framework/typescript-bridge": "^0.7.0",
     "@types/js-yaml": "^4.0.9",
     "change-case": "^4.1.2",
     "js-beautify": "^1.14.11",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@caiogondim/strip-margin": "^1.0.0",
-    "@jay-framework/dev-environment": "^0.11.0",
+    "@jay-framework/dev-environment": "^0.12.0",
     "@testing-library/jest-dom": "^6.2.0",
     "@types/js-beautify": "^1",
     "@types/node": "^20.11.5",