@jay-framework/stack-server-runtime 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -2,15 +2,36 @@ import { AnyJayStackComponentDefinition, PageProps, AnySlowlyRenderResult, UrlPa
 import { JayComponentCore } from '@jay-framework/component';
 import { ViteDevServer } from 'vite';
 import { JayRoute } from '@jay-framework/stack-route-scanner';
-import { WithValidations } from '@jay-framework/compiler-shared';
+import { WithValidations, JsonSchemaProperty, PluginManifest } from '@jay-framework/compiler-shared';
+export { JsonSchemaProperty } from '@jay-framework/compiler-shared';
+import { Contract, HeadlessContractInfo, ForEachHeadlessInstance, DiscoveredHeadlessInstance } from '@jay-framework/compiler-jay-html';
+export { ForEachHeadlessInstance } from '@jay-framework/compiler-jay-html';
 import { JayRollupConfig } from '@jay-framework/rollup-plugin';
 import { TrackByMap } from '@jay-framework/view-state-merge';
+import { Coordinate } from '@jay-framework/runtime';
 
 interface DevServerPagePart {
     compDefinition: AnyJayStackComponentDefinition;
     key?: string;
     clientImport: string;
     clientPart: string;
+    /** Contract metadata for dynamic contract components */
+    contractInfo?: {
+        contractName: string;
+        metadata?: Record<string, unknown>;
+    };
+}
+/**
+ * Instance-only headless component (no key attribute).
+ * Used for server-side phase orchestration of `<jay:xxx>` instances.
+ */
+interface HeadlessInstanceComponent {
+    /** Contract name from the script tag (e.g., "product-card") */
+    contractName: string;
+    /** Component definition for calling slowlyRender/fastRender */
+    compDefinition: AnyJayStackComponentDefinition;
+    /** Parsed contract (for phase detection in slow render Pass 2) */
+    contract: Contract;
 }
 interface LoadedPageParts {
     parts: DevServerPagePart[];
@@ -20,6 +41,10 @@ interface LoadedPageParts {
     clientTrackByMap?: Record<string, string>;
     /** NPM package names used on this page (for filtering plugin inits) */
     usedPackages: Set<string>;
+    /** Headless contracts for slow rendering (already loaded by parseJayFile) */
+    headlessContracts: HeadlessContractInfo[];
+    /** Instance-only headless components (no key) for server-side phase orchestration */
+    headlessInstanceComponents: HeadlessInstanceComponent[];
 }
 interface LoadPagePartsOptions {
     /**
@@ -44,6 +69,50 @@ declare function runSlowlyChangingRender<Refs extends object, SlowVS extends obj
 
 declare function renderFastChangingData(pageParams: object, pageProps: PageProps, carryForward: object, parts: Array<DevServerPagePart>): Promise<AnyFastRenderResult>;
 
+/**
+ * Action metadata loaded from .jay-action files.
+ *
+ * Uses the compiler's parseAction to parse .jay-action YAML into JayType,
+ * then converts JayType → JSON Schema for consumers (AI agent tool builders).
+ *
+ * Actions without .jay-action files are not exposed to AI agents.
+ */
+
+/**
+ * Input schema for an action (JSON Schema object type).
+ */
+interface ActionSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Metadata loaded from a .jay-action file.
+ */
+interface ActionMetadata {
+    /** Action name (must match the export name in plugin code) */
+    name: string;
+    /** Human-readable description of what the action does */
+    description: string;
+    /** JSON Schema for the action's input parameters */
+    inputSchema: ActionSchema;
+    /** JSON Schema for the action's output (optional) */
+    outputSchema?: JsonSchemaProperty;
+}
+/**
+ * Parses a .jay-action YAML string into ActionMetadata.
+ * Uses the compiler's parseAction to produce JayType, then converts to JSON Schema.
+ */
+declare function parseActionMetadata(yamlContent: string, fileName: string): ActionMetadata | null;
+/**
+ * Loads action metadata from a .jay-action file on disk.
+ */
+declare function loadActionMetadata(filePath: string): ActionMetadata | null;
+/**
+ * Resolves the absolute path of a .jay-action file relative to a plugin directory.
+ */
+declare function resolveActionMetadataPath(actionPath: string, pluginDir: string): string;
+
 /**
  * Action registry for Jay Stack server-side action handling.
  *
@@ -65,6 +134,9 @@ interface RegisteredAction {
     services: any[];
     /** The handler function */
     handler: (input: any, ...services: any[]) => Promise<any>;
+    /** Optional metadata from .jay-action file (description, input/output schemas).
+     *  Actions with metadata are exposed to AI agents; those without are not. */
+    metadata?: ActionMetadata;
 }
 /**
  * Result of executing an action.
@@ -130,6 +202,24 @@ declare class ActionRegistry {
      * @returns Array of registered action names
      */
     getNames(): string[];
+    /**
+     * Attaches metadata from a .jay-action file to a registered action.
+     * Called during action discovery when a plugin declares action metadata.
+     *
+     * @param actionName - The action name
+     * @param metadata - Parsed ActionMetadata from .jay-action file
+     */
+    setMetadata(actionName: string, metadata: ActionMetadata): void;
+    /**
+     * Gets all registered actions that have .jay-action metadata.
+     * These are the actions that should be exposed to AI agents.
+     *
+     * @returns Array of { actionName, metadata } for actions with metadata
+     */
+    getActionsWithMetadata(): Array<{
+        actionName: string;
+        metadata: ActionMetadata;
+    }>;
     /**
      * Clears all registered actions.
      */
@@ -191,33 +281,6 @@ declare function executeAction<T = any>(actionName: string, input: unknown): Pro
  * @deprecated Use actionRegistry.getCacheHeaders() instead
  */
 declare function getActionCacheHeaders(actionName: string): string | undefined;
-/**
- * Executes an action directly with proper service injection.
- * Use this when calling actions from backend code (e.g., render phases).
- *
- * Unlike calling the action directly (which bypasses service injection),
- * this function resolves services and calls the handler correctly.
- *
- * @param action - The JayAction to execute (with definition metadata)
- * @param input - The input data for the action
- * @returns The action result (throws on error)
- *
- * @example
- * ```typescript
- * // In a render phase
- * import { runAction } from '@jay-framework/stack-server-runtime';
- * import { searchProducts } from '../actions/stores-actions';
- *
- * async function renderFastChanging(props, slowCarryForward, wixStores) {
- *     // ✅ Correct - services are injected
- *     const result = await runAction(searchProducts, { query: '', pageSize: 12 });
- *
- *     // ❌ Wrong - services are NOT injected (passes empty array)
- *     // const result = await searchProducts({ query: '', pageSize: 12 });
- * }
- * ```
- */
-declare function runAction<I, O>(action: JayAction<I, O> & JayActionDefinition<I, O, any[]>, input: I): Promise<O>;
 
 /**
  * Action discovery and auto-registration for Jay Stack.
@@ -350,6 +413,8 @@ interface PluginWithInit {
     initExport: string;
     /** Dependencies from package.json (for ordering) */
     dependencies: string[];
+    /** When true, plugin is loaded on every page regardless of usage in jay-html */
+    global: boolean;
 }
 /**
  * Options for plugin init discovery.
@@ -387,7 +452,7 @@ declare function sortPluginsByDependencies(plugins: PluginWithInit[]): PluginWit
  * @param viteServer - Vite server for SSR module loading (optional)
  * @param verbose - Whether to log progress
  */
-declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<void>;
+declare function executePluginServerInits(plugins: PluginWithInit[], viteServer?: ViteSSRLoader, verbose?: boolean): Promise<Map<string, Error>>;
 /**
  * Information needed to generate client init script for a plugin.
  */
@@ -489,6 +554,11 @@ declare function hasService<ServiceType>(marker: ServiceMarker<ServiceType>): bo
  * Internal API used by dev-server during hot reload.
  */
 declare function clearServiceRegistry(): void;
+/**
+ * Returns the internal service registry map.
+ * Internal API used by contract materializer to pass services to dynamic generators.
+ */
+declare function getServiceRegistry(): Map<symbol, any>;
 /**
  * Resolves an array of service markers to their registered instances.
  * Used by the runtime to inject services into render functions.
@@ -598,6 +668,62 @@ declare function getClientInitDataForKey(key: string): Record<string, any>;
  */
 declare function clearClientInitData(): void;
 
+/**
+ * Server-side slow render orchestration for headless component instances.
+ *
+ * Given discovered instances (from discoverHeadlessInstances) and their
+ * component definitions, runs slowlyRender for each instance and collects
+ * the results for downstream consumers (pre-render pipeline, direct mode, fast phase).
+ */
+
+/**
+ * Data needed by the fast phase to render headless instances.
+ * Stored in carryForward.__instances so the fast phase can access it
+ * (both in pre-render and cached flows).
+ */
+interface InstancePhaseData {
+    /** Discovered instances with their props and coordinates */
+    discovered: Array<{
+        contractName: string;
+        props: Record<string, string>;
+        coordinate: Coordinate;
+    }>;
+    /** CarryForward per instance (keyed by coordinate path, e.g. "p1/product-card:0") */
+    carryForwards: Record<string, object>;
+    /** ForEach instances that need fast-phase per-item rendering */
+    forEachInstances?: ForEachHeadlessInstance[];
+}
+/**
+ * Result of running slowlyRender for all discovered headless instances.
+ */
+interface InstanceSlowRenderResult {
+    /** Resolved data for each instance (for resolveHeadlessInstances pass 2) */
+    resolvedData: Array<{
+        coordinate: Coordinate;
+        contract: Contract;
+        slowViewState: Record<string, unknown>;
+    }>;
+    /** Per-instance slow ViewState keyed by coordinate (for direct mode merge) */
+    slowViewStates: Record<string, object>;
+    /** Phase data for the fast render phase */
+    instancePhaseData: InstancePhaseData;
+}
+/**
+ * Run slowlyRender for each discovered headless instance.
+ *
+ * Shared between preRenderJayHtml (pre-render path) and handleDirectRequest (direct path).
+ */
+declare function slowRenderInstances(discovered: DiscoveredHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): Promise<InstanceSlowRenderResult | undefined>;
+/**
+ * Validate that forEach headless instances do not have a slow phase.
+ *
+ * Components with slowlyRender cannot be used inside forEach because
+ * forEach items are only known at request time, after slow rendering completes.
+ *
+ * @returns Array of validation error messages (empty if all valid)
+ */
+declare function validateForEachInstances(forEachInstances: ForEachHeadlessInstance[], headlessInstanceComponents: HeadlessInstanceComponent[]): string[];
+
 /**
  * Cache entry for pre-rendered jay-html
  */
@@ -677,4 +803,278 @@ declare class SlowRenderCache {
     getCachedPaths(): string[];
 }
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, ActionRegistry, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type LoadedPageParts, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginWithInit, type ProjectClientInitInfo, type RegisteredAction, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, executeAction, executePluginServerInits, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, hasAction, hasService, loadPageParts, onInit, onShutdown, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveServices, runAction, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, setClientInitData, sortPluginsByDependencies };
+/**
+ * Contract Materializer
+ *
+ * Materializes dynamic contracts to disk for agent discovery.
+ * Also creates an index file listing both static and dynamic contracts.
+ *
+ * @see Design Log #80 - Materializing Dynamic Contracts for Agentic Page Generation
+ */
+
+interface ContractIndexEntry {
+    plugin: string;
+    name: string;
+    type: 'static' | 'dynamic';
+    path: string;
+    metadata?: Record<string, unknown>;
+}
+interface ContractsIndex {
+    materialized_at: string;
+    jay_stack_version: string;
+    contracts: ContractIndexEntry[];
+}
+/** Action metadata entry in plugins-index.yaml */
+interface ActionIndexEntry {
+    name: string;
+    description: string;
+    /** Path to the .jay-action file (relative to project root) */
+    path: string;
+}
+/** Entry for plugins-index.yaml (Design Log #85) */
+interface PluginsIndexEntry {
+    name: string;
+    path: string;
+    contracts: Array<{
+        name: string;
+        type: 'static' | 'dynamic';
+        path: string;
+    }>;
+    /** Actions with .jay-action metadata (exposed to AI agents) */
+    actions?: ActionIndexEntry[];
+}
+interface PluginsIndex {
+    materialized_at: string;
+    jay_stack_version: string;
+    plugins: PluginsIndexEntry[];
+}
+interface MaterializeContractsOptions {
+    projectRoot: string;
+    outputDir?: string;
+    force?: boolean;
+    dynamicOnly?: boolean;
+    pluginFilter?: string;
+    verbose?: boolean;
+    /** Optional Vite server for TypeScript support */
+    viteServer?: ViteSSRLoader;
+}
+interface MaterializeResult {
+    index: ContractsIndex;
+    staticCount: number;
+    dynamicCount: number;
+    outputDir: string;
+}
+/**
+ * Materializes all contracts (static references + dynamic generated) to disk.
+ *
+ * @param options - Materialization options
+ * @param services - Map of service markers to service instances (from init.ts)
+ */
+declare function materializeContracts(options: MaterializeContractsOptions, services?: Map<symbol, unknown>): Promise<MaterializeResult>;
+/**
+ * Lists contracts without writing files (for --list mode)
+ */
+declare function listContracts(options: MaterializeContractsOptions): Promise<ContractsIndex>;
+
+/**
+ * Plugin Scanner
+ *
+ * Shared utility for scanning Jay plugins in a project.
+ * Used by both plugin-init-discovery and contract-materializer.
+ */
+
+/**
+ * Basic plugin information from scanning.
+ */
+interface ScannedPlugin {
+    /** Plugin name (from plugin.yaml or directory/package name) */
+    name: string;
+    /** Full path to plugin directory */
+    pluginPath: string;
+    /** Package name for NPM plugins, or directory name for local plugins */
+    packageName: string;
+    /** Whether this is a local plugin (src/plugins/) or NPM package */
+    isLocal: boolean;
+    /** Parsed plugin.yaml manifest */
+    manifest: PluginManifest;
+    /** Dependencies from package.json (for ordering) */
+    dependencies: string[];
+}
+/**
+ * Options for plugin scanning.
+ */
+interface PluginScanOptions {
+    /** Project root directory */
+    projectRoot: string;
+    /** Whether to log discovery progress */
+    verbose?: boolean;
+    /** Whether to include dev dependencies (default: false) */
+    includeDevDeps?: boolean;
+    /** Whether to discover transitive plugin dependencies (default: false) */
+    discoverTransitive?: boolean;
+}
+/**
+ * Scans for all Jay plugins in a project.
+ *
+ * Scans both local plugins (src/plugins/) and NPM plugins (node_modules/).
+ * Returns basic plugin information that can be used by different consumers
+ * (init discovery, contract materialization, etc.)
+ *
+ * @param options - Scanning options
+ * @returns Map of package/directory name to plugin info
+ */
+declare function scanPlugins(options: PluginScanOptions): Promise<Map<string, ScannedPlugin>>;
+
+/**
+ * Plugin Setup and References (Design Log #87)
+ *
+ * Two separate concerns:
+ *   - **Setup** (jay-stack setup): Config creation + credential/service validation
+ *   - **References** (jay-stack agent-kit): Generate discovery data using live services
+ *
+ * Setup flow:
+ *   1. Scan plugins for `setup.handler` in plugin.yaml
+ *   2. Run init for all plugins (dependency-ordered)
+ *   3. For each target plugin: load setup handler → call it → report result
+ *
+ * References flow (called by agent-kit after materializing contracts):
+ *   1. Scan plugins for `setup.references` in plugin.yaml
+ *   2. Services are already initialized (agent-kit does this for contract materialization)
+ *   3. For each plugin: load references handler → call it → report result
+ */
+
+/**
+ * Context passed to a plugin's setup handler.
+ * Setup handles config creation and service validation only.
+ */
+interface PluginSetupContext {
+    /** Plugin name (from plugin.yaml) */
+    pluginName: string;
+    /** Project root directory */
+    projectRoot: string;
+    /** Config directory path (from .jay configBase, defaults to ./config) */
+    configDir: string;
+    /** Registered services (may be empty if init failed) */
+    services: Map<symbol, unknown>;
+    /** Present if plugin init failed */
+    initError?: Error;
+    /** Whether --force flag was passed */
+    force: boolean;
+}
+/**
+ * Result returned by a plugin's setup handler.
+ */
+interface PluginSetupResult {
+    /** Overall status */
+    status: 'configured' | 'needs-config' | 'error';
+    /** Config files created (relative to project root) */
+    configCreated?: string[];
+    /** Human-readable status message */
+    message?: string;
+}
+/** A plugin's setup handler function signature. */
+type PluginSetupHandler = (context: PluginSetupContext) => Promise<PluginSetupResult>;
+/**
+ * Context passed to a plugin's references handler.
+ * Services may or may not be initialized — check initError if your handler needs them.
+ */
+interface PluginReferencesContext {
+    /** Plugin name (from plugin.yaml) */
+    pluginName: string;
+    /** Project root directory */
+    projectRoot: string;
+    /** Directory for this plugin's reference data (agent-kit/references/<plugin>/) */
+    referencesDir: string;
+    /** Registered services */
+    services: Map<symbol, unknown>;
+    /** Present if this plugin's server init failed */
+    initError?: Error;
+    /** Whether --force flag was passed */
+    force: boolean;
+}
+/**
+ * Result returned by a plugin's references handler.
+ */
+interface PluginReferencesResult {
+    /** Reference files created (relative to project root) */
+    referencesCreated: string[];
+    /** Human-readable status message */
+    message?: string;
+}
+/** A plugin's references handler function signature. */
+type PluginReferencesHandler = (context: PluginReferencesContext) => Promise<PluginReferencesResult>;
+/**
+ * Information about a discovered plugin with a setup handler.
+ */
+interface PluginWithSetup {
+    /** Plugin name from plugin.yaml */
+    name: string;
+    /** Plugin path (directory containing plugin.yaml) */
+    pluginPath: string;
+    /** Package name for NPM plugins, or path for local plugins */
+    packageName: string;
+    /** Whether this is a local plugin */
+    isLocal: boolean;
+    /** Setup handler export name or relative path */
+    setupHandler: string;
+    /** Setup description from plugin.yaml */
+    setupDescription?: string;
+    /** Dependencies from package.json (for ordering) */
+    dependencies: string[];
+}
+/**
+ * Information about a discovered plugin with a references handler.
+ */
+interface PluginWithReferences {
+    /** Plugin name from plugin.yaml */
+    name: string;
+    /** Plugin path (directory containing plugin.yaml) */
+    pluginPath: string;
+    /** Package name for NPM plugins, or path for local plugins */
+    packageName: string;
+    /** Whether this is a local plugin */
+    isLocal: boolean;
+    /** References handler export name */
+    referencesHandler: string;
+    /** Dependencies from package.json (for ordering) */
+    dependencies: string[];
+}
+/**
+ * Discovers all plugins that have a `setup.handler` in plugin.yaml.
+ */
+declare function discoverPluginsWithSetup(options: {
+    projectRoot: string;
+    verbose?: boolean;
+    pluginFilter?: string;
+}): Promise<PluginWithSetup[]>;
+/**
+ * Discovers all plugins that have a `setup.references` in plugin.yaml.
+ */
+declare function discoverPluginsWithReferences(options: {
+    projectRoot: string;
+    verbose?: boolean;
+    pluginFilter?: string;
+}): Promise<PluginWithReferences[]>;
+/**
+ * Loads and executes a plugin's setup handler.
+ */
+declare function executePluginSetup(plugin: PluginWithSetup, options: {
+    projectRoot: string;
+    configDir: string;
+    force: boolean;
+    initError?: Error;
+    viteServer?: ViteSSRLoader;
+    verbose?: boolean;
+}): Promise<PluginSetupResult>;
+/**
+ * Loads and executes a plugin's references handler.
+ */
+declare function executePluginReferences(plugin: PluginWithReferences, options: {
+    projectRoot: string;
+    force: boolean;
+    initError?: Error;
+    viteServer?: ViteSSRLoader;
+    verbose?: boolean;
+}): Promise<PluginReferencesResult>;
+
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, type ActionIndexEntry, type ActionMetadata, ActionRegistry, type ActionSchema, type ContractIndexEntry, type ContractsIndex, type DevServerPagePart, DevSlowlyChangingPhase, type GenerateClientScriptOptions, type HeadlessInstanceComponent, type InstancePhaseData, type InstanceSlowRenderResult, type LoadedPageParts, type MaterializeContractsOptions, type MaterializeResult, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginReferencesContext, type PluginReferencesHandler, type PluginReferencesResult, type PluginScanOptions, type PluginSetupContext, type PluginSetupHandler, type PluginSetupResult, type PluginWithInit, type PluginWithReferences, type PluginWithSetup, type PluginsIndex, type PluginsIndexEntry, type ProjectClientInitInfo, type RegisteredAction, type ScannedPlugin, SlowRenderCache, type SlowRenderCacheEntry, type SlowlyChangingPhase, type ViteSSRLoader, actionRegistry, clearActionRegistry, clearClientInitData, clearLifecycleCallbacks, clearServiceRegistry, discoverAllPluginActions, discoverAndRegisterActions, discoverPluginActions, discoverPluginsWithInit, discoverPluginsWithReferences, discoverPluginsWithSetup, executeAction, executePluginReferences, executePluginServerInits, executePluginSetup, generateClientScript, getActionCacheHeaders, getClientInitData, getClientInitDataForKey, getRegisteredAction, getRegisteredActionNames, getService, getServiceRegistry, hasAction, hasService, listContracts, loadActionMetadata, loadPageParts, materializeContracts, onInit, onShutdown, parseActionMetadata, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveActionMetadataPath, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies, validateForEachInstances };