@jay-framework/stack-server-runtime 0.10.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,8 +39,20 @@ 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[];
 }
-declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig): Promise<WithValidations<LoadedPageParts>>;
+interface LoadPagePartsOptions {
+    /**
+     * Path to pre-rendered jay-html file to use instead of the original.
+     * When provided, this file (with slow-phase bindings resolved) is read.
+     * Import resolution still uses the original jay-html's directory.
+     */
+    preRenderedPath?: string;
+}
+declare function loadPageParts(vite: ViteDevServer, route: JayRoute, pagesBase: string, projectBase: string, jayRollupConfig: JayRollupConfig, options?: LoadPagePartsOptions): Promise<WithValidations<LoadedPageParts>>;
 
 interface SlowlyChangingPhase {
     runSlowlyForPage(pageParams: object, pageProps: PageProps, parts: Array<DevServerPagePart>): Promise<AnySlowlyRenderResult>;
@@ -332,6 +363,7 @@ interface PluginInitDiscoveryOptions {
  * in `plugin.yaml` via the `init` property.
  *
  * Scans both local plugins (src/plugins/) and NPM plugins (node_modules/).
+ * Also discovers transitive plugin dependencies (plugins that depend on other plugins).
  */
 declare function discoverPluginsWithInit(options: PluginInitDiscoveryOptions): Promise<PluginWithInit[]>;
 /**
@@ -383,7 +415,20 @@ interface ProjectClientInitInfo {
     /** Export name for the JayInit constant (default: 'init') */
     initExport?: string;
 }
-declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string, trackByMap?: TrackByMap, clientInitData?: Record<string, Record<string, any>>, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[]): string;
+/**
+ * Options for client script generation.
+ */
+interface GenerateClientScriptOptions {
+    /** Enable automation integration (default: true in dev mode) */
+    enableAutomation?: boolean;
+    /**
+     * Slow ViewState that was baked into the pre-rendered jay-html.
+     * When provided, this is merged with fastViewState for the automation API
+     * so that AI/automation tools can see the complete page state.
+     */
+    slowViewState?: object;
+}
+declare function generateClientScript(defaultViewState: object, fastCarryForward: object, parts: DevServerPagePart[], jayHtmlPath: string, trackByMap?: TrackByMap, clientInitData?: Record<string, Record<string, any>>, projectInit?: ProjectClientInitInfo, pluginInits?: PluginClientInitInfo[], options?: GenerateClientScriptOptions): string;
 
 /**
  * Service registry for Jay Stack server-side dependency injection.
@@ -440,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.
@@ -549,4 +599,390 @@ declare function getClientInitDataForKey(key: string): Record<string, any>;
  */
 declare function clearClientInitData(): void;
 
-export { type ActionDiscoveryOptions, type ActionDiscoveryResult, type ActionErrorResponse, type ActionExecutionResult, ActionRegistry, type DevServerPagePart, DevSlowlyChangingPhase, type LoadedPageParts, type PluginActionDiscoveryOptions, type PluginClientInitInfo, type PluginInitDiscoveryOptions, type PluginWithInit, type ProjectClientInitInfo, type RegisteredAction, 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, runInitCallbacks, runLoadParams, runShutdownCallbacks, runSlowlyChangingRender, setClientInitData, sortPluginsByDependencies };
+/**
+ * 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
+ */
+interface SlowRenderCacheEntry {
+    /** Path to the pre-rendered jay-html file on disk */
+    preRenderedPath: string;
+    /** Slow ViewState that was baked into the jay-html */
+    slowViewState: object;
+    /** CarryForward data from slow rendering (passed to fast phase) */
+    carryForward: object;
+    /** Timestamp when this entry was created */
+    createdAt: number;
+    /** Source jay-html path (for debugging) */
+    sourcePath: string;
+}
+/**
+ * Cache for pre-rendered jay-html files.
+ *
+ * This cache stores jay-html content that has been transformed with slow-phase
+ * data baked in. The key insight is that since slow ViewState is embedded directly
+ * into the jay-html, we don't need to pass it to the client - only fast and
+ * interactive ViewState is sent.
+ *
+ * Pre-rendered files are written to disk so Vite can pick them up and compile them.
+ */
+declare class SlowRenderCache {
+    private cache;
+    private pathToKeys;
+    private readonly cacheDir;
+    private readonly pagesRoot;
+    /**
+     * @param cacheDir - Directory where pre-rendered jay-html files are stored
+     * @param pagesRoot - Root directory of the pages (for relative path calculation)
+     */
+    constructor(cacheDir: string, pagesRoot: string);
+    /**
+     * Get a cached pre-rendered jay-html entry
+     */
+    get(jayHtmlPath: string, params: Record<string, string>): SlowRenderCacheEntry | undefined;
+    /**
+     * Store a pre-rendered jay-html entry in the cache.
+     * Writes the pre-rendered content to disk and stores metadata in memory.
+     */
+    set(jayHtmlPath: string, params: Record<string, string>, preRenderedJayHtml: string, slowViewState: object, carryForward: object): Promise<string>;
+    /**
+     * Check if a pre-rendered entry exists for the given path and params
+     */
+    has(jayHtmlPath: string, params: Record<string, string>): boolean;
+    /**
+     * Invalidate all cached entries for a given jay-html source path.
+     * This is called when the source file changes.
+     * Also deletes the cached files from disk.
+     */
+    invalidate(jayHtmlPath: string): Promise<void>;
+    /**
+     * Invalidate all entries that depend on a changed file.
+     * The changedPath could be:
+     * - A jay-html file itself
+     * - A component file (page.ts)
+     * - Any other dependency
+     *
+     * @param changedPath - Absolute path to the changed file
+     * @param resolveDependencies - Optional function to resolve which jay-html files depend on the changed file
+     */
+    invalidateByDependency(changedPath: string, resolveDependencies?: (changedPath: string) => string[]): Promise<void>;
+    /**
+     * Clear all cached entries and delete cached files from disk
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of cached entries
+     */
+    get size(): number;
+    /**
+     * Get all cached jay-html paths (for debugging/monitoring)
+     */
+    getCachedPaths(): string[];
+}
+
+/**
+ * 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 };