/**
 * Instance Factory Definitions
 *
 * TypeScript interfaces for SpecVerse Instance Factories.
 * These define reusable technology specifications for code generation.
 */
/**
 * Package dependency specification
 */
export interface Dependency {
    name: string;
    version: string;
    optional?: boolean;
}
/**
 * Code template specification
 */
export interface CodeTemplate {
    /** Template engine to use */
    engine: 'typescript' | 'handlebars' | 'ai';
    /** Template content or path (for handlebars) */
    template?: string;
    /** Path to generator function (for typescript) */
    generator?: string;
    /** Generation prompt (for AI) */
    prompt?: string;
    /** Output file path pattern with variables like {controller}, {model} */
    outputPattern: string;
    /** Paths to validation functions */
    validators?: string[];
    /** Paths to post-processing functions */
    postProcessors?: string[];
}
/**
 * Technology stack information
 */
export interface TechnologyStack {
    /**
     * Runtime environment identifier (kebab-case).
     * Standard: node, deno, bun, python, rust, go, browser
     * Custom values allowed (e.g., "zig", "dotnet")
     * Pattern: ^[a-z][a-z0-9-]+$
     */
    runtime: string;
    /**
     * Programming language identifier (kebab-case).
     * Standard: typescript, javascript, python, rust, go, java, csharp, php, ruby, kotlin, swift
     * Custom values allowed (e.g., "gleam", "elixir")
     * Pattern: ^[a-z][a-z0-9-]+$
     */
    language: string;
    /** Framework name (fastify, express, react, vue, etc.) */
    framework?: string;
    /** ORM/database library (prisma, typeorm, drizzle, etc.) */
    orm?: string;
    /** Validation library (zod, joi, class-validator, etc.) */
    validation?: string;
    /** Additional technology properties */
    [key: string]: string | undefined;
}
/**
 * Compatibility requirements
 */
export interface CompatibilityRequirements {
    /** SpecVerse version range (semver) */
    specverse: string;
    /** Node.js version requirement */
    node?: string;
    /** Additional compatibility requirements */
    [key: string]: string | undefined;
}
/**
 * Capability declaration
 */
export interface Capabilities {
    /** Capabilities this implementation provides */
    provides: string[];
    /** Capabilities this implementation requires */
    requires?: string[];
}
/**
 * Dependencies specification
 */
export interface Dependencies {
    /** Runtime dependencies */
    runtime?: Dependency[];
    /** Development dependencies */
    dev?: Dependency[];
    /** Peer dependencies */
    peer?: Dependency[];
}
/**
 * Instance factory metadata
 */
export interface InstanceFactoryMetadata {
    /** Author name or organization */
    author?: string;
    /** Repository URL */
    repository?: string;
    /** Homepage URL */
    homepage?: string;
    /** License identifier (MIT, Apache-2.0, etc.) */
    license?: string;
    /** Tags for categorization */
    tags?: string[];
    /** Keywords for search */
    keywords?: string[];
    /** Documentation URL */
    documentation?: string;
}
/**
 * V2 topology enum — how this factory deploys at runtime.
 * Drives the realize emitter family (Round 2 / Phase 3 work).
 * Distinct from `technology.runtime` (execution env: node | browser).
 */
export type FactoryTopology = 'library' | 'service' | 'managed' | 'executable' | 'messaging' | 'external';
/**
 * Deployment instance categories that a factory can target.
 * Maps 1-to-1 with the 8 deployment instance section names in specly.
 */
export type FactoryDeploymentCategory = 'controllers' | 'services' | 'views' | 'communications' | 'storage' | 'security' | 'infrastructure' | 'monitoring';
/**
 * Authentication scheme descriptor on a factory.
 * `kind` selects the scheme; provider-specific extras are free-form.
 */
export interface FactoryAuthentication {
    /** Authentication scheme kind */
    kind: 'api-key' | 'bearer' | 'oauth2' | 'mtls' | 'none';
    /** Free-form provider-specific extras (e.g. scopes, flow, tokenUrl) */
    [key: string]: unknown;
}
/**
 * V2 factory metadata — the HOW layer for realize emitter dispatch.
 *
 * These fields are intentionally absent from the component spec (WHAT layer)
 * and from the deployment instance (already serves its role via `advertises:` /
 * `uses:` / `config:`). They live here, on the factory definition, because
 * technology choice belongs in the manifest layer.
 *
 * All fields are optional — existing factories without a `v2metadata:` block
 * continue to load. Defaults are applied by the loader (see loader.ts).
 */
export interface FactoryV2Metadata {
    /**
     * Deployment topology — which realize emitter family handles this factory.
     * Default: derived from the factory's `category` field by the loader.
     *   controller → service, service → service, storage → library,
     *   infrastructure → managed, communication → messaging,
     *   view → library, security → library, scaffolding/application/cli/tools → library.
     */
    topology?: FactoryTopology;
    /**
     * Transport protocol for non-library topologies.
     * Free string (not enum-bound) to allow ecosystem extensibility:
     * rest, grpc, mcp, cli, mqtt, amqp, ai-completion, graphql, websocket, …
     */
    protocol?: string;
    /**
     * npm package name of the SDK to install at the consumer (when topology = managed).
     * Example: "@stripe/stripe-js"
     */
    sdk?: string;
    /**
     * Authentication scheme descriptor.
     * Tells the realize emitter which auth wiring to inject at the call site.
     */
    authentication?: FactoryAuthentication;
    /**
     * Which topologies this factory can satisfy when selected by capabilityMappings.
     * Default: [topology] (the factory supports exactly its own topology).
     * Multi-topology factories (e.g. a proxy that wraps both service and managed) list all.
     */
    supportedTopologies?: FactoryTopology[];
    /**
     * Path (relative to `codeTemplates` dir) to the Handlebars/TS client template,
     * or null when the factory has no client wrapper to generate (e.g. library topology).
     * The realize emitter uses this to generate the typed client wrapper that consumers import.
     */
    clientTemplate?: string | null;
    /**
     * Path to the server-side bind template, or null when the factory has no server component.
     * null is the correct value for managed / external / library topologies.
     */
    serverTemplate?: string | null;
    /**
     * Whether the realize emitter should emit a deployment instance entry for this factory.
     * Default: true for non-library topologies; false for topology = library.
     */
    emitsDeploymentInstance?: boolean;
    /**
     * Which of the 8 deployment instance categories this factory's instance lands in.
     * Default: derived from `topology` by the loader when not explicit.
     *   service → services, managed → infrastructure, executable → infrastructure,
     *   messaging → communications, external → infrastructure. library → (no instance).
     */
    deploymentCategory?: FactoryDeploymentCategory;
}
/**
 * Complete Instance Factory definition
 *
 * An instance factory defines a specific technology stack and
 * how to generate code for that stack from SpecVerse specifications.
 */
export interface InstanceFactory {
    /** Unique name for this instance factory */
    name: string;
    /** Semantic version */
    version: string;
    /** Category for deployment instances */
    category: 'controller' | 'service' | 'view' | 'storage' | 'security' | 'infrastructure' | 'monitoring' | 'communication';
    /** Human-readable description */
    description?: string;
    /** Version compatibility requirements */
    compatibility?: CompatibilityRequirements;
    /** What this implementation provides and requires */
    capabilities: Capabilities;
    /** Technology stack information */
    technology: TechnologyStack;
    /** Package dependencies */
    dependencies?: Dependencies;
    /** Code generation templates */
    codeTemplates: Record<string, CodeTemplate>;
    /** Default configuration */
    configuration?: Record<string, any>;
    /** Parent implementation type to extend from */
    extends?: string;
    /** Additional metadata */
    metadata?: InstanceFactoryMetadata;
    /**
     * V2 factory metadata — topology, protocol, sdk, authentication, templates,
     * emitter flags. Consumed by per-runtime realize emitters (Round 2 work).
     * Optional: defaults are applied by the loader for backwards-compatibility.
     */
    v2metadata?: FactoryV2Metadata;
}
/**
 * Reference to an instance factory in a manifest
 */
export interface InstanceFactoryReference {
    /** Reference path: "backend/fastify-prisma" or "@org/impl-types/name" */
    ref: string;
    /** Semantic version range */
    version?: string;
    /** Short alias for referencing in mappings */
    alias?: string;
    /** Configuration overrides */
    configuration?: Record<string, any>;
    /** Template overrides */
    templates?: Record<string, string>;
}
/**
 * Capability mapping in a manifest (v3.3 with instanceFactory)
 */
export interface CapabilityMapping {
    /** Capability pattern (e.g., "api.rest" or "storage.database.*") */
    capability: string;
    /** Instance factory reference (alias or full ref) */
    instanceFactory: string;
    /** Version constraint for instance factory */
    version?: string;
    /** Configuration overrides for this mapping */
    configuration?: Record<string, any>;
    /** Namespace for grouping */
    namespace?: string;
}
/**
 * Instance mapping in a manifest (v3.3 - highest priority)
 */
export interface InstanceMapping {
    /** Specific instance name from deployment */
    instanceName: string;
    /** Instance factory reference */
    instanceFactory: string;
    /** Version constraint for instance factory */
    version?: string;
    /** Configuration overrides for this mapping */
    configuration?: Record<string, any>;
}
/**
 * Default mappings by category (v3.3 - lowest priority)
 */
export interface DefaultMappings {
    controller?: string;
    service?: string;
    view?: string;
    storage?: string;
    security?: string;
    infrastructure?: string;
    monitoring?: string;
    communication?: string;
}
/**
 * Deployment reference in manifest (v3.3)
 */
export interface DeploymentReference {
    /** Path to .specly file containing deployment */
    deploymentSource: string;
    /** Name of deployment in the spec */
    deploymentName: string;
    /** Version constraint for deployment */
    deploymentVersion?: string;
}
/**
 * Resolved implementation with context
 */
export interface ResolvedImplementation {
    /** The capability being resolved */
    capability: string;
    /** The resolved instance factory (with overrides applied) */
    instanceFactory: InstanceFactory;
    /** The deployment instance this is for */
    instance?: any;
    /** Resolved configuration (defaults + manifest overrides + mapping overrides) */
    configuration: Record<string, any>;
    /** Base path for resolving template files (directory containing the instance factory file) */
    basePath?: string;
}
/**
 * Factory validation result
 */
export interface FactoryValidationResult {
    /** Whether validation passed */
    valid: boolean;
    /** Error messages if validation failed */
    errors?: string[];
    /** Warning messages */
    warnings?: string[];
    /** Suggested fixes */
    suggestions?: string[];
}
/**
 * Template context for code generation
 */
export interface TemplateContext {
    /** AI-optimized specification */
    spec: any;
    /** Resolved instance factory */
    factory: InstanceFactory;
    /** Current model (if generating for a specific model) */
    model?: any;
    /** Current controller (if generating for a specific controller) */
    controller?: any;
    /** Current service (if generating for a specific service) */
    service?: any;
    /** Deployment instance (if generating for a specific instance) */
    instance?: any;
    /** Additional context properties */
    [key: string]: any;
}
/**
 * Template engine interface
 */
export interface TemplateEngine {
    /**
     * Render a template with the given context
     */
    render(template: CodeTemplate, context: TemplateContext): Promise<string>;
}
/**
 * Library source configuration
 */
export interface LibrarySource {
    /** Source type */
    type: 'local' | 'npm' | 'remote';
    /** Source path or URL */
    path: string;
    /** Priority (higher = checked first) */
    priority?: number;
}
/**
 * Implementation type library configuration
 */
export interface LibraryConfig {
    /** Library sources to search */
    sources: LibrarySource[];
    /** Cache configuration */
    cache?: {
        enabled: boolean;
        ttl?: number;
    };
}
//# sourceMappingURL=instance-factory.d.ts.map