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

package/dist/index.d.ts

@@ -2,15 +2,34 @@ 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, PluginManifest } from '@jay-framework/compiler-shared';
+import { Contract, HeadlessContractInfo, DiscoveredHeadlessInstance } 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 +39,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 {
     /**
@@ -191,33 +214,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.
@@ -489,6 +485,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 +599,51 @@ 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>;
+}
+/**
+ * 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>;
+
 /**
  * Cache entry for pre-rendered jay-html
  */
@@ -677,4 +723,266 @@ 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[];
+}
+/** Entry for plugins-index.yaml (Design Log #85) */
+interface PluginsIndexEntry {
+    name: string;
+    path: string;
+    contracts: Array<{
+        name: string;
+        type: 'static' | 'dynamic';
+        path: string;
+    }>;
+}
+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 are guaranteed to be initialized (agent-kit already does this).
+ */
+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>;
+    /** 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;
+    viteServer?: ViteSSRLoader;
+    verbose?: boolean;
+}): Promise<PluginReferencesResult>;
+
+export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, ActionRegistry, 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, loadPageParts, materializeContracts, onInit, onShutdown, preparePluginClientInits, registerAction, registerService, renderFastChangingData, resolveServices, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, scanPlugins, setClientInitData, slowRenderInstances, sortPluginsByDependencies };