@stackwright-services/compiler 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,423 @@
+import { CapabilityRegistry } from '@stackwright-services/capabilities';
+import { DataSourceScanResult } from '@stackwright-services/runtime';
+import { FlowDefinition, WorkflowDefinition, RequiredPermission, Trigger } from '@stackwright-services/types';
+
+/**
+ * Validation result -- either success with parsed data, or failure with errors.
+ */
+interface ValidationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    path?: string;
+}
+interface ValidationWarning {
+    code: string;
+    message: string;
+    path?: string;
+}
+/**
+ * Options for validation — injectable for testing.
+ */
+interface ValidateOptions {
+    /**
+     * Injectable scanDataSources function — defaults to the real runtime scan.
+     * Pass a mock in tests to avoid depending on installed packages.
+     */
+    scanDataSources?: () => DataSourceScanResult;
+}
+/**
+ * Detect whether a parsed YAML object is a flow or workflow.
+ */
+declare function detectDefinitionType(obj: unknown): 'flow' | 'workflow' | 'unknown';
+/**
+ * Validate a YAML string as a flow or workflow definition.
+ *
+ * Pass 1: Schema validation (Zod parse)
+ * Pass 2: Semantic validation (capability refs, state graph, etc.)
+ *
+ * @param yamlContent - Raw YAML string
+ * @param registry - Capability registry for ref validation (optional)
+ */
+declare function validate(yamlContent: string, registry?: CapabilityRegistry, options?: ValidateOptions): ValidationResult;
+/**
+ * Validate a flow definition (two-pass).
+ */
+declare function validateFlow(parsed: unknown, registry?: CapabilityRegistry, options?: ValidateOptions): ValidationResult<FlowDefinition>;
+/**
+ * Validate a workflow definition (two-pass).
+ */
+declare function validateWorkflow(parsed: unknown, registry?: CapabilityRegistry): ValidationResult<WorkflowDefinition>;
+
+/**
+ * A derived permission set -- the minimal set of permissions a service needs.
+ * Computed by walking all capability invocations and collecting their requiredPermissions.
+ */
+interface DerivedPermissions {
+    /** All required permissions, deduplicated */
+    permissions: RequiredPermission[];
+    /** Which capabilities contributed each permission (for audit trail) */
+    sources: PermissionSource[];
+}
+interface PermissionSource {
+    /** The permission */
+    permission: RequiredPermission;
+    /** The capability that requires it */
+    capabilityName: string;
+    /** Where in the definition it's invoked */
+    location: string;
+}
+/**
+ * Derive the minimal permission set from a flow definition.
+ *
+ * Walks all steps, looks up each capability in the registry,
+ * collects requiredPermissions from Effect capabilities.
+ * Transform capabilities contribute no permissions (they're pure).
+ *
+ * Permission variables (e.g. `$url`) are resolved from step parameters
+ * at compile time for static permission derivation.
+ *
+ * @security-critical -- This is least-privilege derivation.
+ * The output of this function determines the IAM policy / RBAC manifest.
+ */
+declare function deriveFlowPermissions(flow: FlowDefinition, registry: CapabilityRegistry): DerivedPermissions;
+/**
+ * Derive the minimal permission set from a workflow definition.
+ *
+ * Walks all states' on_enter actions, collects requiredPermissions
+ * from Effect capabilities.
+ */
+declare function deriveWorkflowPermissions(workflow: WorkflowDefinition, registry: CapabilityRegistry): DerivedPermissions;
+/**
+ * Generate an AWS IAM policy document from derived permissions.
+ * Used by the Lambda compile target.
+ */
+declare function toIamPolicy(derived: DerivedPermissions): object;
+/**
+ * Generate an IAM policy for a Step Functions execution role.
+ *
+ * Includes:
+ * - Lambda invoke permissions for each state's on_enter handler
+ * - Capability-derived permissions (from deriveWorkflowPermissions)
+ * - EventBridge permissions if timeouts are configured
+ * - CloudWatch Logs for execution logging
+ *
+ * @security-critical
+ */
+declare function toStepFunctionsIamPolicy(workflow: WorkflowDefinition, derived: DerivedPermissions): object;
+/**
+ * Generate a Kubernetes RBAC rule set from derived permissions.
+ * Used by the Helm compile target.
+ */
+declare function toRbacRules(derived: DerivedPermissions): object[];
+
+/**
+ * The ObservabilityProvider interface -- what the generated code calls.
+ * This is defined here for code generation; the runtime package implements it.
+ */
+interface ObservabilityProvider {
+    /** Start a span for a capability invocation */
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanHandle;
+    /** Record a metric */
+    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
+}
+interface SpanHandle {
+    /** Set attributes on the span */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Mark the span as errored */
+    setError(error: Error): void;
+    /** End the span */
+    end(): void;
+}
+/**
+ * Instrumentation metadata for a single step.
+ */
+interface StepInstrumentation {
+    /** Step name (used as span name) */
+    stepName: string;
+    /** Capability name (span attribute) */
+    capabilityName: string;
+    /** Flow ID (span attribute) */
+    flowId: string;
+    /** Metric names */
+    metrics: {
+        latency: string;
+        invocations: string;
+        errors: string;
+    };
+}
+/**
+ * Generate instrumentation metadata for all steps in a flow.
+ */
+declare function generateFlowInstrumentation(flow: FlowDefinition): StepInstrumentation[];
+/**
+ * Sanitize a string to be a valid TypeScript identifier.
+ */
+declare function sanitizeIdentifier(name: string): string;
+/**
+ * Generate the TypeScript code for an instrumented step handler.
+ *
+ * This is what the compiler emits into the generated handler file.
+ * Each step becomes an async function wrapped with observability AND audit.
+ */
+declare function generateInstrumentedStepCode(instrumentation: StepInstrumentation): string;
+/**
+ * Generate the full instrumented handler code for a flow.
+ * Returns the complete TypeScript source for the compiled handler.
+ */
+declare function generateInstrumentedFlowCode(flow: FlowDefinition): string;
+
+/**
+ * Instrumentation metadata for a single workflow state handler.
+ * Mirrors StepInstrumentation but is scoped to state machine semantics:
+ * transitions, dwell time, timeout events.
+ */
+interface WorkflowStateInstrumentation {
+    /** State name */
+    stateName: string;
+    /** Capability invoked on entry (from on_enter.use) */
+    capabilityName: string;
+    /** Workflow ID */
+    workflowId: string;
+    /** Whether this is a terminal state */
+    isTerminal: boolean;
+    /** Metric name constants */
+    metrics: {
+        /** Counter — fires each time the state is entered */
+        invocations: string;
+        /** Counter — fires when the on_enter capability throws */
+        errors: string;
+        /** Histogram — on_enter handler execution time in ms */
+        latency: string;
+        /** Counter — per-signal transition counts into this state */
+        transitions: string;
+    };
+}
+/**
+ * Generate instrumentation metadata for all states that have an on_enter
+ * capability in the workflow.  States without on_enter have no Lambda handler
+ * and are therefore excluded.
+ */
+declare function generateWorkflowInstrumentation(workflow: WorkflowDefinition): WorkflowStateInstrumentation[];
+/**
+ * Generate a complete TypeScript Lambda handler file for an instrumented
+ * workflow state.
+ *
+ * The generated handler:
+ * - Opens a span per state execution (one span = one transition through the state)
+ * - Records a `workflow.state.transitions` counter tagged with the incoming signal
+ * - Records `workflow.state.invocations` / `workflow.state.errors` counters
+ * - Records `workflow.state.latency` histogram (on_enter execution time)
+ * - Emits an AuditProvider record on both success and error paths
+ *
+ * Providers default to noop — wire real implementations via your DI bootstrap.
+ */
+declare function generateInstrumentedStateHandlerCode(instrumentation: WorkflowStateInstrumentation, capabilityParams: Record<string, unknown>): string;
+
+/**
+ * Output files generated by the Lambda compile target.
+ */
+interface LambdaTarget {
+    /** Generated files, keyed by relative path */
+    files: Record<string, string>;
+}
+/**
+ * Compile a flow definition to Lambda target output.
+ *
+ * Generates:
+ * - handler.ts: Hono app entry point wired to the compiled flow
+ * - Dockerfile: AWS Lambda Web Adapter base image
+ * - iam-policy.json: Least-privilege IAM policy from derived permissions
+ * - package.json: Minimal package for the Lambda function
+ */
+declare function compileLambdaTarget(flow: FlowDefinition, permissions: DerivedPermissions, instrumentedCode: string): LambdaTarget;
+/**
+ * Return additional IAM policy statements required by the trigger type.
+ * These are merged with capability-derived permissions at compile time.
+ */
+declare function getTriggerPermissions(trigger: Trigger): object[];
+
+/**
+ * Output files generated by the Helm compile target.
+ */
+interface HelmTarget {
+    /** Generated files, keyed by relative path */
+    files: Record<string, string>;
+}
+/**
+ * Compile a flow definition to Helm chart output.
+ *
+ * Generates a complete Helm chart compatible with the Defense Unicorns ecosystem.
+ */
+declare function compileHelmTarget(flow: FlowDefinition, permissions: DerivedPermissions): HelmTarget;
+declare function sanitizeChartName(name: string): string;
+
+/**
+ * Output files generated by the Step Functions compile target.
+ */
+interface StepFunctionsTarget {
+    /** Generated files, keyed by relative path */
+    files: Record<string, string>;
+}
+/**
+ * Compile a workflow definition to AWS Step Functions target output.
+ *
+ * Generates:
+ * - asl-definition.json: Step Functions state machine definition in ASL
+ * - iam-execution-role.json: IAM policy for the execution role
+ * - handlers/<state>.ts: Lambda handler stubs for each state with on_enter
+ * - package.json: Minimal package for the handlers
+ */
+declare function compileStepFunctionsTarget(workflow: WorkflowDefinition, permissions: DerivedPermissions): StepFunctionsTarget;
+/**
+ * Convert an ISO 8601 duration string to seconds.
+ *
+ * Uses calendar approximations: 1 year = 365 days, 1 month = 30 days.
+ *
+ * @example
+ * iso8601ToSeconds('P3D')   // → 259200
+ * iso8601ToSeconds('PT1H')  // → 3600
+ * iso8601ToSeconds('PT30M') // → 1800
+ */
+declare function iso8601ToSeconds(duration: string): number;
+
+/**
+ * Output from the OpenAPI spec compile target.
+ */
+interface OpenApiTarget {
+    /** Generated files, keyed by relative path */
+    files: Record<string, string>;
+}
+/**
+ * Options for OpenAPI spec generation.
+ */
+interface OpenApiTargetOptions {
+    /** Optional build key to include as an apiKey security scheme */
+    buildKey?: string;
+    /** Optional server URL for the spec */
+    serverUrl?: string;
+    /** Optional version string (defaults to "0.0.1") */
+    version?: string;
+}
+/**
+ * Compile an HTTP-triggered flow definition to an OpenAPI 3.1 specification.
+ *
+ * This is the bridge between Services and Pro: the generated spec is consumed
+ * by Pro's existing OpenAPI parser to produce typed Pulse clients.
+ *
+ * For non-HTTP triggers, returns an empty target (no spec to generate).
+ * AsyncAPI for event-driven flows is future work.
+ *
+ * @returns OpenApiTarget with openapi.yaml content, or empty files for non-HTTP triggers
+ */
+declare function compileOpenApiTarget(flow: FlowDefinition, options?: OpenApiTargetOptions): OpenApiTarget;
+
+/**
+ * Auth requirements derived from a definition.
+ * The compiler emits these into target-specific auth configuration.
+ */
+interface DerivedAuthRequirements {
+    /** Whether any auth is required at all */
+    requiresAuth: boolean;
+    /** All roles referenced in guard_role transitions */
+    requiredRoles: string[];
+    /** Locations where auth is referenced (for audit trail) */
+    sources: AuthRequirementSource[];
+}
+interface AuthRequirementSource {
+    /** The role required */
+    role: string;
+    /** Where in the definition it's referenced */
+    location: string;
+}
+/**
+ * Derive auth requirements from a flow definition.
+ *
+ * For now, flows require auth if the HTTP trigger has auth config.
+ * (Future: auth field on trigger schema)
+ *
+ * @security-critical — Determines whether auth is wired into compiled output.
+ */
+declare function deriveFlowAuthRequirements(flow: FlowDefinition): DerivedAuthRequirements;
+/**
+ * Derive auth requirements from a workflow definition.
+ *
+ * Walks all states' transitions, collects guard_role references.
+ * If ANY transition has guard_role, the workflow requires auth.
+ *
+ * @security-critical — Determines auth wiring in compiled output.
+ */
+declare function deriveWorkflowAuthRequirements(workflow: WorkflowDefinition): DerivedAuthRequirements;
+/**
+ * Generate Lambda authorizer configuration from auth requirements.
+ * Used by the Lambda/Step Functions compile targets.
+ */
+declare function toLambdaAuthorizerConfig(auth: DerivedAuthRequirements): object | null;
+/**
+ * Generate Helm auth annotations from auth requirements.
+ * Used by the Helm compile target.
+ */
+declare function toHelmAuthAnnotations(auth: DerivedAuthRequirements): Record<string, string>;
+
+/**
+ * Build-coherence configuration derived from a definition.
+ *
+ * This is NOT authentication (that's AuthProvider). It's a deployment
+ * coherence mechanism that ensures frontend and backend were compiled
+ * from the same source at the same time.
+ *
+ * The key is:
+ * - Generated deterministically from flow content + build timestamp
+ * - Embedded in the compiled handler as middleware
+ * - Embedded in the OpenAPI spec as an apiKey security scheme
+ * - Short-lived: replaced every build
+ * - NOT a secret: visible in frontend bundle and spec file
+ *
+ * Works naturally with blue/green and canary deployments —
+ * matched frontend/backend pairs share the same key.
+ */
+interface BuildCoherenceConfig {
+    /** Whether build coherence is enabled */
+    enabled: boolean;
+    /** The build key (hex string) */
+    buildKey: string;
+    /** Hash of the flow content (for tracing which definition produced this key) */
+    contentHash: string;
+    /** Build timestamp (ISO 8601) */
+    buildTimestamp: string;
+}
+/**
+ * Derive build coherence config from a flow definition.
+ *
+ * The key is a SHA-256 hash of: flow content (serialized) + build timestamp.
+ * Same source + same moment = same key. Different build = different key.
+ *
+ * Follows the same pattern as deriveFlowAuthRequirements() and
+ * deriveFlowPermissions() — pure derivation, no side effects.
+ *
+ * @security-critical — The build key becomes a deployment coherence check.
+ */
+declare function deriveBuildCoherence(flow: FlowDefinition | WorkflowDefinition, options?: {
+    timestamp?: string;
+    enabled?: boolean;
+}): BuildCoherenceConfig;
+/**
+ * Generate Hono middleware code that validates the build-coherence key.
+ *
+ * Injected into the compiled handler.ts by the Lambda and Helm targets.
+ * The middleware runs before the flow handler and rejects requests
+ * with a mismatched or missing build key.
+ */
+declare function toBuildKeyMiddleware(config: BuildCoherenceConfig): string;
+/**
+ * Generate environment variables for the build key.
+ * Used by Helm values.yaml and Lambda environment config.
+ */
+declare function toBuildKeyEnv(config: BuildCoherenceConfig): Record<string, string>;
+
+export { type AuthRequirementSource, type BuildCoherenceConfig, type DerivedAuthRequirements, type DerivedPermissions, type HelmTarget, type LambdaTarget, type ObservabilityProvider, type OpenApiTarget, type OpenApiTargetOptions, type PermissionSource, type SpanHandle, type StepFunctionsTarget, type StepInstrumentation, type ValidationError, type ValidationResult, type ValidationWarning, type WorkflowStateInstrumentation, compileHelmTarget, compileLambdaTarget, compileOpenApiTarget, compileStepFunctionsTarget, deriveBuildCoherence, deriveFlowAuthRequirements, deriveFlowPermissions, deriveWorkflowAuthRequirements, deriveWorkflowPermissions, detectDefinitionType, generateFlowInstrumentation, generateInstrumentedFlowCode, generateInstrumentedStateHandlerCode, generateInstrumentedStepCode, generateWorkflowInstrumentation, getTriggerPermissions, iso8601ToSeconds, sanitizeChartName, sanitizeIdentifier, toBuildKeyEnv, toBuildKeyMiddleware, toHelmAuthAnnotations, toIamPolicy, toLambdaAuthorizerConfig, toRbacRules, toStepFunctionsIamPolicy, validate, validateFlow, validateWorkflow };