@crossdelta/platform-sdk 0.19.0 → 0.19.3

package/dist/facade.d.mts

@@ -0,0 +1,840 @@
+import { FlowContext, FlowRunOptions, FlowResult } from '@crossdelta/flowcore';
+export { FlowContext, FlowResult, FlowRunOptions } from '@crossdelta/flowcore';
+import { P as PfWorkspaceContext, g as PfEffect, a as PfPluginContext, L as LoadedPlugin, b as PfPlugin } from './plugin-types-DQOv97Zh.mjs';
+export { E as ElicitInputEffect, h as ElicitInputField, i as EnvAddEffect, F as FileWriteEffect, I as InfraAddEffect, c as PfCommand, d as PfCommandArg, e as PfCommandOption, j as PfCommandResult, k as isElicitInputEffect } from './plugin-types-DQOv97Zh.mjs';
+export { deriveEventNames } from '@crossdelta/cloudevents';
+import { z } from 'zod';
+
+/**
+ * Capability Configuration
+ *
+ * Manages capability/provider configuration from workspace package.json.
+ * Single Source of Truth: workspaceConfig.pf.capabilities
+ *
+ * NO BUILT-IN DEFAULTS:
+ * - Provider metadata (deps/envVars/adapterFile) comes ONLY from workspace config
+ * - Unknown providers trigger elicitation (interactive) or error (strict)
+ * - This enables teams to define their own providers without hardcoded assumptions
+ */
+
+declare const ProviderMetaSchema: z.ZodObject<{
+    dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    envVars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    adapterFile: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ProviderMeta = z.infer<typeof ProviderMetaSchema>;
+declare const CapabilitiesConfigSchema: z.ZodObject<{
+    notifier: z.ZodOptional<z.ZodObject<{
+        defaults: z.ZodOptional<z.ZodObject<{
+            push: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            slack: z.ZodOptional<z.ZodString>;
+            sms: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        providers: z.ZodOptional<z.ZodObject<{
+            push: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                envVars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    description: z.ZodString;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>>;
+                adapterFile: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            email: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                envVars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    description: z.ZodString;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>>;
+                adapterFile: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            slack: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                envVars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    description: z.ZodString;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>>;
+                adapterFile: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            sms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                dependencies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                envVars: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    key: z.ZodString;
+                    description: z.ZodString;
+                    required: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strip>>>;
+                adapterFile: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type CapabilitiesConfig = z.infer<typeof CapabilitiesConfigSchema>;
+type NotifierChannel = 'push' | 'email' | 'slack' | 'sms';
+/**
+ * Get registered providers from workspace config.
+ * Returns empty arrays if no config - NO BUILT-IN FALLBACKS.
+ * Pure function.
+ */
+declare const getRegisteredProviders: (workspaceConfig?: CapabilitiesConfig) => Record<NotifierChannel, string[]>;
+interface ProviderLookupResult {
+    found: true;
+    provider: string;
+    meta: ProviderMeta;
+    source: 'workspace' | 'inferred';
+}
+interface ProviderNotFoundResult {
+    found: false;
+    channel: NotifierChannel;
+    provider: string;
+    availableProviders: string[];
+    configSnippet: string;
+}
+type ProviderLookup = ProviderLookupResult | ProviderNotFoundResult;
+declare const lookupProvider: (channel: NotifierChannel, provider: string, workspaceConfig?: CapabilitiesConfig) => ProviderLookup;
+interface ApplyDefaultResult {
+    provider: string;
+    source: 'explicit' | 'default';
+}
+interface NeedElicitationResult {
+    needsElicitation: true;
+    channel: NotifierChannel;
+    availableProviders: string[];
+}
+type ResolveProviderResult = ({
+    resolved: true;
+} & ApplyDefaultResult) | ({
+    resolved: false;
+} & NeedElicitationResult);
+/**
+ * Resolve provider - use explicit if provided, else check defaults, else elicit.
+ * Pure function.
+ */
+declare const resolveProvider: (channel: NotifierChannel, explicitProvider: string | undefined, workspaceConfig?: CapabilitiesConfig) => ResolveProviderResult;
+/**
+ * Load capabilities config from workspace package.json.
+ * Returns undefined if no config or parsing fails.
+ *
+ * NOTE: This is the ONLY place that reads from workspace config.
+ * CLI and MCP both use this function via the capabilities module.
+ */
+declare const loadCapabilitiesConfig: (workspacePkg: Record<string, unknown> | null) => CapabilitiesConfig | undefined;
+/**
+ * Load capabilities config from workspace root.
+ * Convenience wrapper that integrates with packages/config.ts.
+ *
+ * Usage (CLI/MCP):
+ * ```ts
+ * import { loadCapabilitiesConfigFromWorkspace } from './capabilities/config'
+ * const config = loadCapabilitiesConfigFromWorkspace()
+ * const registry = createDefaultRegistry(config)
+ * ```
+ */
+declare const loadCapabilitiesConfigFromWorkspace: (getWorkspacePackageJson: () => Record<string, unknown> | null) => CapabilitiesConfig | undefined;
+
+/**
+ * Capability Types
+ *
+ * Core types for the deterministic planning system.
+ * AI generates content ONLY - paths/structure come from policy.
+ *
+ * Pipeline:
+ * 1. Parser: NL prompt -> ServiceSpec (with explicit provider if mentioned)
+ * 2. Lowering: ServiceSpec -> CapabilityInvocation[] (pure, deterministic)
+ * 3. Planning: Invocations -> GenerationPlan (deterministic, policy-based paths)
+ * 4. Content Generation: Plan.files -> AI fills content (constrained)
+ * 5. Validation: Check generated files against policy + patterns
+ */
+
+declare const ServiceSpecSchema: z.ZodObject<{
+    serviceName: z.ZodString;
+    framework: z.ZodDefault<z.ZodEnum<{
+        hono: "hono";
+        nest: "nest";
+    }>>;
+    triggers: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"event">;
+        eventType: z.ZodString;
+        stream: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"http">;
+        method: z.ZodOptional<z.ZodEnum<{
+            POST: "POST";
+            GET: "GET";
+            PUT: "PUT";
+            DELETE: "DELETE";
+            PATCH: "PATCH";
+        }>>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+    actions: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"emit.event">;
+        eventType: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"notify">;
+        channel: z.ZodEnum<{
+            push: "push";
+            email: "email";
+            slack: "slack";
+            sms: "sms";
+        }>;
+        provider: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"call.http">;
+        name: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"persist">;
+        store: z.ZodEnum<{
+            db: "db";
+            kv: "kv";
+            cache: "cache";
+        }>;
+        entity: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+type ServiceSpec = z.infer<typeof ServiceSpecSchema>;
+interface ElicitField {
+    path: string;
+    prompt: string;
+    type: 'string' | 'enum';
+    options?: string[];
+    required: boolean;
+}
+type ParseResult = {
+    complete: true;
+    spec: ServiceSpec;
+} | {
+    complete: false;
+    fields: ElicitField[];
+    partialSpec: Partial<ServiceSpec>;
+};
+
+/**
+ * Capability Lowering
+ *
+ * Converts ServiceSpec to metadata (files, deps, env vars, postCommands).
+ * Pure, deterministic - no side effects, no defaults, no guessing.
+ */
+
+interface ServiceMetadata {
+    files: {
+        path: string;
+        intent: string;
+        inputs?: Record<string, unknown>;
+        layer?: 'handler' | 'useCase' | 'adapter' | 'service';
+        kind?: 'event-consumer' | 'notifier' | 'http-client' | 'persistence';
+    }[];
+    dependencies: Record<string, string>;
+    envVars: {
+        key: string;
+        description: string;
+        required: boolean;
+    }[];
+    postCommands: string[];
+}
+/**
+ * Lower ServiceSpec to ServiceMetadata (files, deps, env vars, postCommands).
+ * AI generates file content based on intents.
+ */
+declare const lowerSpecToCapabilities: (spec: ServiceSpec, serviceDir: string) => ServiceMetadata;
+
+/**
+ * ServiceSpec Parser
+ *
+ * Converts natural language prompts to validated ServiceSpec.
+ * CRITICAL: Explicit provider mentions MUST land in spec - NO defaults.
+ * Missing required info triggers elicitation.
+ *
+ * Provider detection uses keyword matching + workspace config validation.
+ * Pure functions - no side effects, AI abstracted behind interface.
+ */
+
+interface RawServiceSpec {
+    serviceName?: string;
+    framework?: string;
+    triggers?: Array<Record<string, unknown>>;
+    actions?: Array<Record<string, unknown>>;
+}
+interface PromptInterpreter {
+    extract(prompt: string): Promise<RawServiceSpec>;
+}
+interface ParseOptions {
+    interpreter?: PromptInterpreter;
+    workspaceConfig?: CapabilitiesConfig;
+}
+/**
+ * Parse natural language prompt to ServiceSpec.
+ * Uses interpreter for extraction, with pattern matching fallback.
+ * Supports workspace config for defaults and provider detection.
+ */
+declare const parseServicePrompt: (prompt: string, options?: ParseOptions | PromptInterpreter) => Promise<ParseResult>;
+
+/**
+ * Effect Handlers
+ *
+ * pf applies domain effects returned by plugin commands.
+ * Handlers are keyed by effect kind - clean data-driven dispatch.
+ */
+
+/**
+ * Runtime context for effect handlers
+ */
+interface EffectRuntimeContext {
+    workspace: PfWorkspaceContext;
+    logger: {
+        debug: (message: string) => void;
+        info: (message: string) => void;
+        warn: (message: string) => void;
+        error: (message: string) => void;
+    };
+}
+/**
+ * Represents a planned change (for dry-run mode)
+ */
+interface Change {
+    type: 'create' | 'update' | 'delete';
+    path: string;
+    description: string;
+    preview?: string;
+}
+/**
+ * Result of applying an effect
+ */
+interface EffectResult {
+    success: boolean;
+    message?: string;
+    changes?: Change[];
+}
+/**
+ * Options for effect handlers
+ */
+interface EffectHandlerOptions {
+    dryRun?: boolean;
+}
+/**
+ * Apply a list of effects
+ *
+ * Iterates through effects and dispatches to registered handlers.
+ * Unknown effects are logged and skipped (not fatal).
+ *
+ * @param effects - List of effects to apply
+ * @param context - Runtime context with workspace and logger
+ * @param options - Optional settings (e.g., dryRun for plan mode)
+ * @returns Array of effect results
+ */
+declare const applyEffects: (effects: PfEffect[], context: EffectRuntimeContext, options?: EffectHandlerOptions) => EffectResult[];
+
+/**
+ * Change Aggregation Utilities
+ *
+ * For plan mode (dry-run) - aggregate and format change previews.
+ *
+ * Code organization: types → pure functions → higher-order functions
+ */
+
+/**
+ * Aggregate all changes from effect results
+ *
+ * Filters successful results and flattens their changes arrays.
+ */
+declare const aggregateChanges: (results: EffectResult[]) => Change[];
+/**
+ * Format change summary for display
+ *
+ * Groups by type and shows counts + file list.
+ */
+declare const formatChangeSummary: (changes: Change[]) => string;
+/**
+ * Format detailed change preview (with code snippets)
+ */
+declare const formatChangeDetails: (changes: Change[]) => string;
+
+/**
+ * Operation Result Types
+ *
+ * Standard result shape for all pf operations.
+ * Enables consistent MCP tool responses and plan/apply workflows.
+ */
+
+/**
+ * Artifact generated by an operation
+ */
+interface Artifact {
+    /** Artifact type (file, config, env, etc.) */
+    type: 'file' | 'config' | 'env' | 'stream' | 'service';
+    /** Path or identifier */
+    path: string;
+    /** Human-readable description */
+    description: string;
+}
+/**
+ * Diagnostic message from an operation
+ */
+interface Diagnostic {
+    /** Severity level */
+    level: 'info' | 'warning' | 'error';
+    /** Diagnostic message */
+    message: string;
+    /** Optional: Location (file path, line number) */
+    location?: string;
+}
+/**
+ * Suggested next action after operation
+ */
+interface NextAction {
+    /** Command to run */
+    command: string;
+    /** Description of what the command does */
+    description: string;
+}
+/**
+ * Standard operation result
+ *
+ * All pf operations return this shape for consistency.
+ * Supports both plan mode (effects only) and apply mode (execution).
+ */
+interface OperationResult<T = unknown> {
+    /** Operation succeeded */
+    ok: boolean;
+    /** Operation identifier (e.g., 'service.generate', 'event.add') */
+    operation: string;
+    /** Human-readable summary */
+    summary: string;
+    /** Generated artifacts */
+    artifacts: Artifact[];
+    /** Structured changes (effects) for plan/apply */
+    changes: PfEffect[];
+    /** Non-blocking diagnostics */
+    diagnostics: Diagnostic[];
+    /** Optional: Suggested next actions */
+    next?: NextAction[];
+    /** Optional: Operation-specific data */
+    data?: T;
+}
+/**
+ * Create a successful operation result
+ */
+declare const ok: <T>(operation: string, summary: string, options?: {
+    artifacts?: Artifact[];
+    changes?: PfEffect[];
+    diagnostics?: Diagnostic[];
+    next?: NextAction[];
+    data?: T;
+}) => OperationResult<T>;
+/**
+ * Create a failed operation result
+ */
+declare const err: (operation: string, error: string, options?: {
+    diagnostics?: Diagnostic[];
+    data?: unknown;
+}) => OperationResult;
+
+/**
+ * Template Engine Types
+ *
+ * Type-safe service generation templates.
+ * Templates define the structure (files, dependencies, config).
+ */
+/**
+ * Environment variable definition for service config
+ */
+interface EnvVarDef {
+    key: string;
+    description?: string;
+    required?: boolean;
+}
+/**
+ * Variables passed to template functions
+ */
+interface TemplateVars {
+    /** Service name (kebab-case) */
+    serviceName: string;
+    /** Package name with scope (@org/service-name) */
+    packageName: string;
+    /** Service path relative to workspace root */
+    servicePath: string;
+    /** Assigned port for the service */
+    port: number;
+    /** Environment variable name for port (SCREAMING_SNAKE_CASE) */
+    envVarName: string;
+    /** Whether service has event consumers */
+    hasEvents: boolean;
+    /** NATS stream names if hasEvents is true */
+    streams: string[];
+    /** Event types to consume (e.g., ['order.created']) */
+    events: string[];
+    /** Workspace scope (@org) */
+    workspaceScope: string;
+    /** Additional features */
+    features?: string[];
+    /** Environment variables from capability plan (Pusher, etc.) */
+    envVars?: EnvVarDef[];
+}
+
+/**
+ * Template System
+ *
+ * Includes:
+ * - Handlebars renderer (existing)
+ * - String helpers (existing)
+ * - Service templates (new)
+ */
+
+/**
+ * Template type for selection
+ */
+type TemplateType = 'hono-bun' | 'hono-micro' | 'nest' | 'nest-micro';
+
+/**
+ * Service Generation Flow
+ *
+ * Deterministic flow for generating microservices from templates.
+ * Supports plan/apply separation for MCP integration.
+ */
+
+/**
+ * Service generation inputs
+ */
+interface ServiceGenerationInputs {
+    /** Template type (hono-bun, hono-micro, nest, nest-micro) */
+    type: TemplateType;
+    /** Service name (kebab-case) */
+    name: string;
+    /** Optional: Custom service path (default: services/<name>) */
+    path?: string;
+    /** Optional: Enable event consumers (auto-set if events provided) */
+    hasEvents?: boolean;
+    /** Optional: NATS streams to consume from (auto-derived if events provided) */
+    streams?: string[];
+    /** Optional: Event types to consume (e.g., ['order.created']) */
+    events?: string[];
+    /** Optional: Workspace root (auto-detected if not provided) */
+    workspaceRoot?: string;
+    /** Optional: Explicit port (for deterministic generation) */
+    port?: number;
+    /** Optional: Environment variables from capability plan (for env.ts) */
+    envVars?: EnvVarDef[];
+}
+/**
+ * Service metadata
+ */
+interface ServiceMeta {
+    serviceName: string;
+    servicePath: string;
+    port: number;
+    vars: TemplateVars;
+}
+/**
+ * Plan service generation (returns OperationResult)
+ *
+ * This is the MCP-ready interface that returns a structured result
+ * with effects that can be inspected before execution.
+ */
+declare const planServiceGeneration: (inputs: ServiceGenerationInputs) => OperationResult<ServiceMeta>;
+
+/**
+ * Find the workspace root by looking for workspace indicators
+ * Throws if not in a workspace
+ */
+declare const findWorkspaceRoot: () => string;
+
+/**
+ * Service Layout Policy (v1)
+ *
+ * Machine-readable policy for service file layouts and coding constraints.
+ * Enforces consistent structure across generators (CLI + MCP).
+ *
+ * - Hono: Use-cases for business logic (src/use-cases/*.use-case.ts)
+ * - NestJS: Services following NestJS conventions
+ *
+ * Features:
+ * - PathGuards: Forbidden directories per framework
+ * - CodingConstraints: Forbidden patterns in domain/use-case code
+ */
+/** Policy version for backward compatibility */
+declare const SERVICE_LAYOUT_POLICY_VERSION = 1;
+/**
+ * Supported service frameworks
+ */
+type ServiceFramework = 'hono' | 'nestjs';
+/**
+ * Forbidden pattern for coding constraints
+ */
+interface ForbiddenPattern {
+    /** Pattern to match (string or regex source) */
+    pattern: string;
+    /** Human-readable description */
+    description: string;
+    /** Error code for structured reporting */
+    code: string;
+}
+/**
+ * Coding constraints for business logic code
+ */
+interface CodingConstraints {
+    /** Directories where constraints apply (relative to service root) */
+    appliesTo: readonly string[];
+    /** Forbidden patterns in code */
+    forbiddenPatterns: readonly ForbiddenPattern[];
+}
+/**
+ * Path guards for framework
+ */
+interface PathGuards {
+    /** Directories that must not be used for business logic */
+    forbidDirs: readonly string[];
+}
+/**
+ * Framework-specific layout configuration
+ */
+interface FrameworkLayout {
+    /** Directory for business logic (relative to src/) */
+    businessLogicDir: string;
+    /** Directory for event handlers (relative to src/) */
+    eventsDir: string;
+    /** File naming pattern. Placeholders: {name} */
+    filePattern: string;
+    /** File suffix (e.g., 'use-case', 'service') */
+    suffix: string;
+    /** Whether event handlers should delegate to business logic */
+    handlerDelegatesToBusinessLogic: boolean;
+    /** Path guards for this framework */
+    pathGuards: PathGuards;
+    /** Coding constraints for business logic */
+    codingConstraints: CodingConstraints;
+}
+/**
+ * Service layout policy
+ *
+ * Defines where business logic files should be placed for each framework.
+ * This is the single source of truth for service structure.
+ */
+declare const serviceLayoutPolicy: Record<ServiceFramework, FrameworkLayout>;
+/**
+ * Policy violation details
+ */
+interface PolicyViolation {
+    /** Error code for structured handling */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** File path that caused the violation */
+    path: string;
+    /** Line number (if applicable) */
+    line?: number;
+}
+/**
+ * Validation result for generated files
+ */
+interface PolicyValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** List of violations (empty if valid) */
+    violations: PolicyViolation[];
+}
+/**
+ * Planned file for validation
+ */
+interface PlannedFile {
+    /** Relative path within service (e.g., 'src/services/foo.ts') */
+    path: string;
+    /** File content */
+    content: string;
+}
+/**
+ * Validate generated files against service policy
+ *
+ * Call this before applying effects to ensure compliance.
+ * Returns violations that MUST block generation.
+ *
+ * @param framework - Target framework
+ * @param files - Planned files to validate
+ * @returns Validation result with any violations
+ *
+ * @example
+ * const result = validateGeneratedFiles('hono', [
+ *   { path: 'src/services/foo.ts', content: '...' }
+ * ])
+ * if (!result.valid) {
+ *   throw new PolicyViolationError(result.violations)
+ * }
+ */
+declare const validateGeneratedFiles: (framework: ServiceFramework, files: readonly PlannedFile[]) => PolicyValidationResult;
+/**
+ * Get policy for a specific framework
+ *
+ * Useful for MCP/CLI to pass policy data to templates.
+ */
+declare const getFrameworkPolicy: (framework: ServiceFramework) => FrameworkLayout;
+
+/**
+ * Context Factory
+ *
+ * Functions for creating plugin contexts from workspace configuration.
+ */
+
+/**
+ * Create plugin context by auto-discovering workspace configuration
+ *
+ * Reads workspace config from package.json (pf.* fields) and discovers
+ * contracts path, services, etc. This is the recommended way to create context.
+ *
+ * @param workspaceRoot - Optional workspace root (defaults to auto-discovery from cwd)
+ * @param logger - Optional logger (defaults to console)
+ * @returns Plugin context ready for use
+ *
+ * @example
+ * // Auto-discover workspace from current directory
+ * const context = await createContextFromWorkspace()
+ *
+ * @example
+ * // Specify workspace root explicitly
+ * const context = await createContextFromWorkspace('/path/to/workspace')
+ */
+declare const createContextFromWorkspace: (workspaceRoot?: string, logger?: PfPluginContext["logger"]) => Promise<PfPluginContext>;
+/**
+ * Create a plugin context from workspace information (manual)
+ *
+ * Use this when you need full control over workspace configuration.
+ * For most cases, prefer `createContextFromWorkspace()` which auto-discovers config.
+ *
+ * @param workspace - Workspace context with paths and configuration
+ * @param logger - Optional logger (defaults to console)
+ * @returns Plugin context ready for use
+ *
+ * @example
+ * const context = createContext({
+ *   workspaceRoot: '/path/to/workspace',
+ *   contracts: {
+ *     path: '/path/to/contracts',
+ *     packageName: '@my-org/contracts'
+ *   },
+ *   availableServices: ['orders', 'notifications']
+ * })
+ */
+declare const createContext: (workspace: PfWorkspaceContext, logger?: PfPluginContext["logger"]) => PfPluginContext;
+
+/**
+ * Facade Types
+ *
+ * Public type definitions for external integrations.
+ */
+
+/**
+ * Tool specification for external integrations (MCP, VS Code, etc.)
+ */
+interface ToolSpec {
+    /** Tool name (e.g., 'event.add', 'service.create') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Input schema (JSON Schema format) */
+    inputSchema: ToolInputSchema;
+}
+interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, ToolPropertySchema>;
+    required?: string[];
+}
+interface ToolPropertySchema {
+    type: string;
+    description: string;
+    default?: unknown;
+}
+/**
+ * Result from a legacy command execution (plan-like wrapper)
+ */
+interface CommandLikeResult {
+    ok: boolean;
+    operation: string;
+    summary: string;
+    effects: PfEffect[];
+    output?: string | string[];
+}
+/**
+ * Executable tool specification
+ *
+ * Extends ToolSpec with an execute function for direct dispatch.
+ * Returns OperationResult for consistency with plan/apply workflows.
+ */
+interface ExecutableToolSpec extends ToolSpec {
+    /** Execute the tool with given args (returns OperationResult or CommandLikeResult) */
+    execute: (args: Record<string, unknown>) => Promise<OperationResult | CommandLikeResult>;
+}
+
+/**
+ * Tool Collection
+ *
+ * Functions for transforming plugin commands into tool specifications.
+ * Shared schema building logic to avoid duplication.
+ */
+
+/**
+ * Collect tool specifications from loaded plugins
+ *
+ * Transforms plugin commands into a unified tool specification format.
+ * This abstraction allows different consumers (MCP, VS Code) to use the same data.
+ *
+ * @param plugins - Array of loaded plugins
+ * @returns Array of tool specifications with schema information
+ *
+ * @example
+ * const tools = collectToolSpecs(plugins)
+ * // Returns: [{ name: 'event.add', description: '...', inputSchema: {...} }]
+ */
+declare const collectToolSpecs: (plugins: LoadedPlugin[]) => ToolSpec[];
+/**
+ * Collect executable tool specifications from loaded plugins
+ *
+ * Transforms plugin commands into executable tool specs with dispatch functions.
+ * Each tool's execute() returns a plan-like result without applying effects.
+ *
+ * @param plugins - Array of loaded plugins
+ * @param context - Plugin context for command execution
+ * @returns Array of executable tool specifications
+ *
+ * @example
+ * const tools = collectExecutableToolSpecs(plugins, context)
+ * const result = await tools[0].execute({ eventType: 'order.created' })
+ */
+declare const collectExecutableToolSpecs: (plugins: LoadedPlugin[], _context: PfPluginContext) => ExecutableToolSpec[];
+
+/**
+ * Platform SDK Facade
+ *
+ * Stable API surface for external integrations (MCP adapters, extensions, etc.)
+ * This facade isolates internal implementation details and provides version stability.
+ *
+ * Design Philosophy:
+ * - Minimal surface area: Only expose what's needed for tool/flow execution
+ * - Semantic versioning: Breaking changes bump major version
+ * - Internal freedom: Implementation can change without affecting consumers
+ *
+ * Consumers:
+ * - @crossdelta/pf-mcp (MCP server adapter)
+ * - Future extensions (VS Code, etc.)
+ */
+
+declare const loadPlugins: (moduleNames: string[], context: PfPluginContext) => Promise<LoadedPlugin[]>;
+declare const runFlow: <TContext extends FlowContext = FlowContext>(plugin: PfPlugin, flowName: string, options: FlowRunOptions<TContext>) => Promise<FlowResult<TContext>>;
+/**
+ * Get the absolute path to the generator docs directory
+ *
+ * @returns Absolute path to packages/platform-sdk/bin/docs/generators (built artifacts)
+ */
+declare const getGeneratorDocsDir: () => string;
+/**
+ * List all available generator documentation files
+ *
+ * @returns Array of doc filenames (without .md extension)
+ */
+declare const listGeneratorDocs: () => Promise<string[]>;
+
+export { type Artifact, type CapabilitiesConfig, type Change, type CodingConstraints, type CommandLikeResult, type Diagnostic, type EffectHandlerOptions, type EffectResult, type EffectRuntimeContext, type ExecutableToolSpec, type ForbiddenPattern, type FrameworkLayout, LoadedPlugin, type NextAction, type OperationResult, type ParseResult, type PathGuards, PfEffect, PfPlugin, PfPluginContext, PfWorkspaceContext, type PlannedFile, type PolicyValidationResult, type PolicyViolation, type ProviderLookup, SERVICE_LAYOUT_POLICY_VERSION, type ServiceFramework, type ServiceGenerationInputs, type ServiceMeta, type ServiceMetadata, type ServiceSpec, type ToolInputSchema, type ToolPropertySchema, type ToolSpec, aggregateChanges, applyEffects, collectExecutableToolSpecs, collectToolSpecs, createContext, createContextFromWorkspace, err as createErrResult, ok as createOkResult, findWorkspaceRoot, formatChangeDetails, formatChangeSummary, getFrameworkPolicy, getGeneratorDocsDir, getRegisteredProviders, listGeneratorDocs, loadCapabilitiesConfig, loadCapabilitiesConfigFromWorkspace, loadPlugins, lookupProvider, lowerSpecToCapabilities, parseServicePrompt, planServiceGeneration, resolveProvider, runFlow, serviceLayoutPolicy, validateGeneratedFiles };