@truefoundry/tfy-infra-engine 0.0.0-canary.6233945

package/dist/index.d.mts

@@ -0,0 +1,589 @@
+/**
+ * Engine error codes for programmatic error handling.
+ */
+declare enum EngineErrorCode {
+    TEMPLATE_NOT_FOUND = "TEMPLATE_NOT_FOUND",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    GITHUB_NOT_FOUND = "GITHUB_NOT_FOUND",
+    GITHUB_RATE_LIMITED = "GITHUB_RATE_LIMITED",
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    HTTPS_AUTH_FAILED = "HTTPS_AUTH_FAILED",
+    SCHEMA_INVALID = "SCHEMA_INVALID",
+    INPUT_VALIDATION_FAILED = "INPUT_VALIDATION_FAILED",
+    TEMPLATE_JSON_NOT_FOUND = "TEMPLATE_JSON_NOT_FOUND",
+    TEMPLATE_JSON_INVALID = "TEMPLATE_JSON_INVALID",
+    TEMPLATE_SYNTAX_ERROR = "TEMPLATE_SYNTAX_ERROR",
+    TOFU_NOT_FOUND = "TOFU_NOT_FOUND",
+    TOFU_FMT_FAILED = "TOFU_FMT_FAILED",
+    CACHE_ERROR = "CACHE_ERROR",
+    ENVELOPE_VALIDATION_FAILED = "ENVELOPE_VALIDATION_FAILED",
+    MANIFEST_PARSE_ERROR = "MANIFEST_PARSE_ERROR"
+}
+/**
+ * Custom error class for engine errors.
+ * Provides structured error information including error code, cause, and details.
+ */
+declare class EngineError extends Error {
+    readonly code: EngineErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: EngineErrorCode, cause?: Error, details?: Record<string, unknown>);
+    /**
+     * Create a string representation including error code.
+     */
+    toString(): string;
+    /**
+     * Convert error to JSON-serializable object.
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * JSON Schema type definitions.
+ *
+ * CHANGE (008): All Zod-based converter functions and zod-to-json-schema
+ * import removed. Only the JSONSchema7 type interface remains.
+ * Templates provide JSON Schema directly via template.json.
+ */
+/**
+ * JSON Schema Draft-07 type.
+ */
+interface JSONSchema7 {
+    $schema?: string;
+    $ref?: string;
+    type?: string;
+    properties?: Record<string, JSONSchema7>;
+    required?: string[];
+    default?: unknown;
+    description?: string;
+    items?: JSONSchema7;
+    additionalProperties?: boolean | JSONSchema7;
+    oneOf?: JSONSchema7[];
+    anyOf?: JSONSchema7[];
+    allOf?: JSONSchema7[];
+    enum?: unknown[];
+    const?: unknown;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    discriminator?: {
+        propertyName: string;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Core type definitions for the HCL templating engine.
+ *
+ * These interfaces define the data model for templates, schemas, rendering,
+ * and the integrity engine (zone classification, file headers, manifests,
+ * drift reports, and the four-operation API).
+ *
+ * CHANGE (008): TemplateSchema, InputDefinition, OutputDefinition removed.
+ * Replaced by TemplateMetadata + JSONSchema7. sideOutputs removed from results.
+ *
+ * References:
+ *   - specs/004-infra-integrity-engine/contracts/engine-api.ts
+ *   - specs/004-infra-integrity-engine/data-model.md
+ *   - specs/008-json-schema-engine/data-model.md
+ */
+
+/**
+ * File ownership zone classification.
+ * (FR-001, FR-002)
+ */
+type Zone = 'platform' | 'user';
+/**
+ * Drift finding classification.
+ * (FR-015, FR-028, FR-042)
+ */
+type DriftType = 'content_drift' | 'metadata_inconsistency' | 'source_mismatch' | 'missing_file' | 'unexpected_file';
+/**
+ * Structured metadata embedded in every Platform Zone file as HCL comments.
+ * (FR-025)
+ *
+ * Serialized format (R-001):
+ * ```hcl
+ * # @tfy-status:begin
+ * # {"managed":true,"source":"...","version":"...","intent_id":"...","content_hash":"sha256:..."}
+ * # @tfy-status:end
+ * ```
+ *
+ * Note: JSON field names use snake_case (intent_id, content_hash) for HCL
+ * convention consistency. TypeScript interface uses camelCase.
+ */
+interface TfyStatusHeader {
+    /** Always true for Platform Zone files */
+    managed: boolean;
+    /** Template origin URI (e.g., "tfy-registry/aws/eks-core") */
+    source: string;
+    /** Template semver tag (e.g., "v2.4.1") */
+    version: string;
+    /** Cluster identity — same value for all files in a cluster */
+    intentId: string;
+    /** SHA-256 of file content excluding the header ("sha256:<hex>") */
+    contentHash: string;
+}
+/**
+ * A single entry in the engine's output file map.
+ * (FR-039, FR-040)
+ */
+interface FileEntry {
+    /** Full file content (includes @tfy-status header for platform files) */
+    content: string;
+    /** File ownership zone */
+    zone: Zone;
+    /** Parsed header metadata (present only for platform zone files) */
+    header?: TfyStatusHeader;
+}
+/**
+ * Zone-tagged file map — the engine's standard output format.
+ * Keys are relative file paths.
+ * (FR-021, FR-039)
+ */
+type FileMap = Map<string, FileEntry>;
+/**
+ * The engine's input configuration.
+ *
+ * CHANGE (006): `template` field accepts a resolved `Template` object
+ * instead of a URI string. The caller is responsible for fetching
+ * and constructing the Template before calling the engine.
+ * (FR-031, FR-032)
+ */
+interface Envelope {
+    /** Resolved template (caller fetches, engine consumes) */
+    template: Template;
+    /** Input values to pass to template */
+    inputs: Record<string, unknown>;
+    /** Optional rendering options */
+    options?: RenderOptions;
+    /** Cluster identity — propagated to file headers and Manifest (FR-031) */
+    intentId: string;
+    /** Filename prefix for Platform Zone files (default: "tfy_") */
+    platformPrefix?: string;
+}
+/**
+ * Options for rendering operations.
+ *
+ * CHANGE (006): Removed `noCache`, `cacheDir`, `timeout` — these were
+ * resolver options that no longer apply to the pure engine.
+ */
+interface RenderOptions {
+    /** Skip tofu fmt formatting (default: false) */
+    skipFormat?: boolean;
+}
+/**
+ * Metadata about a template, sourced from the "template" key in template.json.
+ */
+interface TemplateMetadata {
+    /** Template name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Template version (semver) */
+    version: string;
+}
+/**
+ * A remote template package containing source files and schema.
+ *
+ * CHANGE (008): Replaced `schema: TemplateSchema` with `metadata` + `jsonSchema`.
+ * Metadata comes from template.json "template" key; schema from "schema" key.
+ */
+interface Template {
+    /** Template metadata from template.json → "template" key */
+    metadata: TemplateMetadata;
+    /** JSON Schema Draft-07 from template.json → "schema" key */
+    jsonSchema: JSONSchema7;
+    /** Map of output paths to HBS content (rendered via Handlebars) */
+    files: Map<string, string>;
+    /** Map of output paths to static content (copied verbatim, no rendering) */
+    staticFiles: Map<string, string>;
+    /** Template source URI */
+    source: string;
+    /** Resolved version info */
+    version: VersionInfo;
+}
+/**
+ * Version information for a template.
+ */
+interface VersionInfo {
+    /** Semantic version (e.g., "0.1.0") */
+    semver: string;
+    /** API version directory from the URI path (e.g., "v1"), for display/logging */
+    apiVersion?: string;
+}
+
+/**
+ * Per-file entry in the Manifest.
+ * (FR-035)
+ */
+interface ManifestFileEntry {
+    /** Relative file path */
+    path: string;
+    /** SHA-256 content hash, header-agnostic ("sha256:<hex>") */
+    hash: string;
+    /** File size in bytes */
+    size: number;
+    /** Template origin for this file */
+    source: string;
+    /** Template semver for this file */
+    version: string;
+    /** File ownership zone */
+    zone: Zone;
+}
+/**
+ * Manifest (State Passport) — JSON format.
+ * (FR-007, FR-033, FR-034, FR-036)
+ */
+interface Manifest {
+    /** Format version discriminator */
+    manifestVersion: '1.0';
+    /** Cluster identity (matches envelope.intentId) */
+    intentId: string;
+    /** ISO-8601 generation timestamp */
+    generatedAt: string;
+    /** Primary template origin URI */
+    templateSource: string;
+    /** Primary template semver */
+    templateVersion: string;
+    /** Aggregate Platform Hash ("sha256:<hex>") */
+    aggregateHash: string;
+    /** Engine metadata */
+    engine: {
+        version: string;
+        formatted: boolean;
+    };
+    /** Resolved input values used during generation (005) */
+    inputs: Record<string, unknown>;
+    /** Filename prefix for Platform Zone files (005) */
+    platformPrefix: string;
+    /** Per-file entries, sorted lexicographically by path */
+    files: ManifestFileEntry[];
+}
+/**
+ * A single drift finding.
+ * (FR-042)
+ */
+interface DriftEntry {
+    /** File path (relative) */
+    path: string;
+    /** Classification of the finding */
+    type: DriftType;
+    /** Human-readable description of the mismatch */
+    details: string;
+}
+/**
+ * Quick counts for CLI display and telemetry.
+ */
+interface DriftSummary {
+    /** Total Platform Zone files checked */
+    totalFiles: number;
+    /** Files with content_drift */
+    driftedFiles: number;
+    /** Files with metadata_inconsistency */
+    inconsistentFiles: number;
+    /** Files in Manifest but not found */
+    missingFiles: number;
+    /** Platform-prefixed files not in Manifest */
+    unexpectedFiles: number;
+    /** Files with source_mismatch */
+    sourceMismatches: number;
+}
+/**
+ * Structured drift report from Verify and Upgrade operations.
+ * (FR-041, FR-043)
+ */
+interface DriftReport {
+    /** True if no drift entries (all files match) */
+    valid: boolean;
+    /** Aggregate hash comparison */
+    aggregateHash: {
+        expected: string;
+        actual: string;
+    };
+    /** Per-file findings (a file may appear multiple times with different types) */
+    entries: DriftEntry[];
+    /** Quick counts for display/telemetry */
+    summary: DriftSummary;
+}
+/**
+ * Result of the Install operation.
+ * (FR-012)
+ *
+ * CHANGE (008): sideOutputs removed — templates own all Terraform output via .hbs files.
+ */
+interface InstallResult {
+    /** Zone-tagged file map (platform + user boilerplate files) */
+    files: FileMap;
+    /** Initial Manifest */
+    manifest: Manifest;
+}
+/**
+ * Result of the Upgrade operation.
+ * (FR-014, FR-015, FR-016)
+ *
+ * CHANGE (008): sideOutputs removed — templates own all Terraform output via .hbs files.
+ */
+interface UpgradeResult {
+    /** New zone-tagged file map */
+    files: FileMap;
+    /** Updated Manifest */
+    manifest: Manifest;
+    /** Pre-upgrade drift analysis */
+    driftReport: DriftReport;
+    /**
+     * True if the upgrade was blocked due to source mismatch (FR-028).
+     * When true, `files` and `manifest` reflect the CURRENT state (not upgraded).
+     */
+    sourceBlocked: boolean;
+}
+/**
+ * Result of the Verify operation.
+ * (FR-015, FR-041)
+ */
+interface VerifyResult {
+    /** Full drift analysis */
+    driftReport: DriftReport;
+}
+/**
+ * Result of the Hash-Only operation.
+ * (FR-022, FR-023)
+ */
+interface HashOnlyResult {
+    /** Aggregate Platform Hash ("sha256:<hex>") */
+    aggregateHash: string;
+    /** Template source used */
+    templateSource: string;
+    /** Template version used */
+    templateVersion: string;
+    /** Number of Platform Zone files that would be generated */
+    fileCount: number;
+}
+/**
+ * Options for resolver operations.
+ */
+interface ResolverOptions {
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Number of retries */
+    retries?: number;
+    /** Skip cache lookup */
+    noCache?: boolean;
+}
+/**
+ * Interface for fetching templates from different sources.
+ */
+interface Resolver {
+    /** Check if resolver handles this URI scheme */
+    canResolve(uri: string): boolean;
+    /** Fetch template from source */
+    resolve(uri: string, options?: ResolverOptions): Promise<Template>;
+}
+/**
+ * The HCL Engine public API.
+ *
+ * CHANGE (006): Narrowed to four core operations. Removed:
+ *   - getSchema(uri) — caller reads template.schema directly
+ *   - validate(uri, inputs) — caller uses exported validateInputs()
+ *   - clearCache(uri?) — caching is caller's concern
+ *   - EngineConfig — deleted entirely (all fields were resolver-related)
+ *
+ * (FR-037, FR-038, FR-024)
+ */
+interface HclEngine {
+    /**
+     * Install: Generate all files for a new cluster.
+     * Input: Envelope with intentId, resolved Template, and inputs.
+     * Output: Zone-tagged file map + initial Manifest.
+     * (FR-012, FR-025, FR-039)
+     */
+    install(envelope: Envelope): Promise<InstallResult>;
+    /**
+     * Upgrade: Update an existing cluster to new templates.
+     * Input: Envelope + current file map (from disk) + previous Manifest.
+     * Output: New file map + new Manifest + drift report.
+     * (FR-014, FR-015, FR-016, FR-027, FR-028, FR-047)
+     */
+    upgrade(envelope: Envelope, currentFiles: FileMap, previousManifest: Manifest): Promise<UpgradeResult>;
+    /**
+     * Verify: Check integrity of existing files against a Manifest.
+     * Input: Current file map (from disk) + previous Manifest.
+     * Output: Drift report only (no file generation).
+     * (FR-015, FR-041, FR-047)
+     */
+    verify(currentFiles: FileMap, previousManifest: Manifest): Promise<VerifyResult>;
+    /**
+     * Hash-Only: Calculate expected aggregate hash without full generation.
+     * Input: Envelope (same as install).
+     * Output: Aggregate Platform Hash + metadata.
+     * (FR-022, FR-023)
+     */
+    hashOnly(envelope: Envelope): Promise<HashOnlyResult>;
+}
+
+/**
+ * Template JSON structure validation using AJV.
+ *
+ * Validates the top-level structure of template.json against the
+ * templateJsonSchema (JSON Schema Draft-07) defined in template-json-schema.ts.
+ *
+ * Reference: R-006, data-model.md validator.ts
+ */
+
+/**
+ * Result of validating a template.json file.
+ */
+interface TemplateJsonResult {
+    metadata: TemplateMetadata;
+    jsonSchema: JSONSchema7;
+}
+/**
+ * Validate the structure of a parsed template.json file.
+ *
+ * Checks:
+ *   - Data is an object with "template" and "schema" keys
+ *   - template.name is a non-empty string
+ *   - template.version is a semver string (x.y.z)
+ *   - template.description is an optional string
+ *   - schema is a non-null object with type: "object" and properties
+ *
+ * @param data - Parsed JSON content from template.json
+ * @returns Validated metadata and JSON Schema
+ * @throws EngineError with TEMPLATE_JSON_INVALID on failure
+ */
+declare function validateTemplateJson(data: unknown): TemplateJsonResult;
+
+/**
+ * AJV-based JSON Schema input validation.
+ *
+ * Provides:
+ *   - createInputValidator(): Compiles a JSON Schema into an AJV validator
+ *   - validateAndApplyDefaults(): Validates inputs + applies defaults in one pass
+ *   - validateJsonSchemaStructure(): Asserts root type: "object" + properties key
+ *
+ * Local $ref pointers (e.g., "#/components/schemas/...") are supported natively
+ * by AJV and resolved automatically during schema compilation.
+ *
+ * CHANGE (008): New module replacing hand-rolled validateInputs() and applyDefaults().
+ *
+ * Reference: R-001, R-007, R-010
+ */
+
+/**
+ * Validate that a JSON Schema has the required structure for template inputs.
+ * Must be an object with type: "object" and a properties key.
+ *
+ * @param schema - Schema to validate
+ * @throws EngineError if structure is invalid
+ */
+declare function validateJsonSchemaStructure(schema: JSONSchema7): void;
+
+/**
+ * JSON Schema (Draft-07) for template.json files.
+ *
+ * This is the source of truth for template.json validation.
+ * Used by validator.ts via AJV for runtime validation.
+ *
+ * Validates:
+ *   - "template" key: name (required, non-empty), version (semver, required), description (optional string)
+ *   - "schema" key: must be a JSON Schema object with type: "object" and a properties key
+ *
+ * Note: No additionalProperties: false at root level — extra top-level keys are allowed
+ * for forward compatibility.
+ */
+
+declare const templateJsonSchema: JSONSchema7;
+
+/**
+ * Check if tofu is available in the system.
+ *
+ * @returns true if tofu is available
+ */
+declare function isTofuAvailable(): Promise<boolean>;
+
+/**
+ * Zone classification for file ownership.
+ *
+ * Classifies files as Platform Zone or User Zone based on filename prefix.
+ * Reference: R-007, FR-001, FR-002
+ */
+
+/**
+ * Default platform filename prefix.
+ */
+declare const DEFAULT_PREFIX = "tfy_";
+/**
+ * Classify a file as Platform Zone or User Zone based on its filename.
+ *
+ * Rules (R-007):
+ * 1. Only the basename matters (not the directory path).
+ * 2. The prefix check is case-sensitive.
+ * 3. The Manifest file itself (manifest.json) is classified as Platform Zone.
+ * 4. Files without .tf extension that have the prefix are still Platform Zone.
+ * 5. The prefix is configurable per envelope/configuration.
+ *
+ * @param filePath - Relative or absolute file path
+ * @param prefix - Platform Zone filename prefix (default: "tfy_")
+ * @returns Zone classification ("platform" or "user")
+ */
+declare function classifyFile(filePath: string, prefix?: string): Zone;
+
+/**
+ * @tfy-status header processing: parse, strip, inject.
+ *
+ * The header is a structured metadata block embedded as Terraform comment lines
+ * at the top of every Platform Zone file.
+ *
+ * Format (R-001):
+ * ```hcl
+ * # @tfy-status:begin
+ * # {"managed":true,"source":"...","version":"...","intent_id":"...","content_hash":"sha256:..."}
+ * # @tfy-status:end
+ * ```
+ *
+ * Reference: R-001, R-002, R-010, FR-044 through FR-046
+ */
+
+/**
+ * Parse a @tfy-status header from file content.
+ * Returns undefined if no valid header is found.
+ * (FR-044)
+ *
+ * @param content - File content possibly containing a header
+ * @returns Parsed header or undefined
+ */
+declare function parseHeader(content: string): TfyStatusHeader | undefined;
+
+/**
+ * HCL Engine implementation — four-operation integrity API.
+ *
+ * Operations:
+ *   - install(envelope): Generate all files for a new cluster
+ *   - upgrade(envelope, currentFiles, previousManifest): Update to new templates
+ *   - verify(currentFiles, previousManifest): Check integrity
+ *   - hashOnly(envelope): Calculate expected aggregate hash
+ *
+ * Reference: R-006, FR-037, FR-038, plan.md Operation Pipelines
+ */
+
+/**
+ * Create a new HCL engine instance.
+ *
+ * @returns Engine instance
+ *
+ * @example
+ * ```typescript
+ * import { createEngine } from '@truefoundry/tfy-infra-engine';
+ *
+ * const engine = createEngine();
+ * const result = await engine.install({
+ *   template,  // pre-resolved Template object
+ *   inputs: { cluster_name: 'prod' },
+ *   intentId: 'cluster-prod-001',
+ * });
+ * ```
+ */
+declare function createEngine(): HclEngine;
+
+export { DEFAULT_PREFIX, type DriftReport, type DriftType, EngineError, EngineErrorCode, type Envelope, type FileEntry, type FileMap, type HashOnlyResult, type InstallResult, type JSONSchema7, type Manifest, type Resolver, type ResolverOptions, type Template, type UpgradeResult, type VerifyResult, type VersionInfo, classifyFile, createEngine, isTofuAvailable, parseHeader, templateJsonSchema, validateJsonSchemaStructure, validateTemplateJson };