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

package/README.md

@@ -0,0 +1,287 @@
+# @truefoundry/tfy-infra-engine
+
+Config-driven HCL templating engine for infrastructure generation with integrity verification.
+
+## Installation
+
+```bash
+yarn add @truefoundry/tfy-infra-engine
+```
+
+## Quick Start
+
+```typescript
+import { createEngine } from '@truefoundry/tfy-infra-engine';
+import type { Template, Envelope } from '@truefoundry/tfy-infra-engine';
+
+const engine = createEngine();
+
+// The engine accepts pre-resolved Template objects.
+// The caller is responsible for fetching/resolving templates.
+const template: Template = {
+  metadata: { name: 'sample', version: '0.1.0' },
+  jsonSchema: {
+    type: 'object',
+    required: ['name'],
+    properties: {
+      name: { type: 'string' },
+      environment: { type: 'string', default: 'dev' },
+    },
+  },
+  files: new Map([['tfy_main.tf', '# HCL template content']]),
+  source: 'file:///path/to/template',
+  version: { major: 'v1', semver: '0.1.0', full: 'v1/0.1.0' },
+};
+
+const result = await engine.install({
+  template,
+  inputs: { name: 'my-cluster', environment: 'production' },
+  intentId: 'cluster-prod-001',
+});
+
+// result.files is a Map<string, FileEntry> (zone-tagged)
+for (const [path, entry] of result.files) {
+  console.log(`${path} [${entry.zone}]:\n${entry.content}`);
+}
+
+// result.manifest is a JSON Manifest v1.0
+console.log('Aggregate Hash:', result.manifest.aggregateHash);
+```
+
+## Features
+
+- **Pure transformer**: Accepts pre-resolved `Template` objects -- no I/O for fetching
+- **JSON Schema validation**: Validate inputs against JSON Schema Draft-07 using AJV with `useDefaults`, `allErrors`, and `discriminator` support
+- **Handlebars templating**: 7 built-in helpers for HCL generation
+- **HCL formatting**: Automatic formatting with `tofu fmt`
+- **Deterministic output**: Byte-identical output for identical inputs
+- **Integrity verification**: Zone-based file ownership, `@tfy-status` headers, JSON Manifest, and drift detection
+- **Four-operation API**: `install`, `verify`, `upgrade`, and `hashOnly`
+
+## API
+
+### `createEngine()`
+
+Create a new engine instance. Takes no parameters.
+
+```typescript
+const engine = createEngine();
+```
+
+### `engine.install(envelope)`
+
+Generate all files for a new cluster. Returns zone-tagged files with `@tfy-status` headers on platform files and a JSON Manifest.
+
+```typescript
+const result = await engine.install({
+  template,  // Pre-resolved Template object
+  inputs: { name: 'test' },
+  intentId: 'cluster-001',
+  options: { skipFormat: false },
+});
+
+// result.files: Map<string, FileEntry>
+// result.manifest: Manifest (JSON v1.0)
+```
+
+### `engine.verify(currentFiles, previousManifest)`
+
+Check integrity of existing files against a Manifest. Returns a structured drift report.
+
+```typescript
+const result = await engine.verify(currentFiles, previousManifest);
+if (!result.driftReport.valid) {
+  for (const entry of result.driftReport.entries) {
+    console.log(`${entry.path}: ${entry.type} -- ${entry.details}`);
+  }
+}
+```
+
+### `engine.upgrade(envelope, currentFiles, previousManifest)`
+
+Update platform files to new template versions. Performs pre-upgrade drift detection and source mismatch blocking.
+
+```typescript
+const result = await engine.upgrade(envelope, currentFiles, previousManifest);
+if (result.sourceBlocked) {
+  console.log('Upgrade blocked: template source mismatch');
+} else if (!result.driftReport.valid) {
+  console.log('Pre-upgrade drift detected');
+}
+```
+
+### `engine.hashOnly(envelope)`
+
+Calculate the expected Aggregate Platform Hash without generating files. Used by the Control Plane for fleet status comparison.
+
+```typescript
+const result = await engine.hashOnly(envelope);
+console.log('Expected hash:', result.aggregateHash);
+console.log('File count:', result.fileCount);
+```
+
+### Input Validation (AJV-based)
+
+Validate inputs against a template's JSON Schema. Exported as public utilities.
+
+```typescript
+import {
+  createInputValidator,
+  validateAndApplyDefaults,
+  validateJsonSchemaStructure,
+} from '@truefoundry/tfy-infra-engine';
+
+// Check schema is valid
+validateJsonSchemaStructure(template.jsonSchema); // Throws if not object with properties
+
+// Compile and validate (AJV resolves local $ref pointers natively)
+const validator = createInputValidator(template.jsonSchema);
+const inputs = { name: 'my-cluster' };
+const result = validateAndApplyDefaults(validator, inputs);
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+// inputs now has defaults applied in-place
+```
+
+### Template JSON Validation
+
+Validate the top-level structure of a `template.json` file:
+
+```typescript
+import { validateTemplateJson } from '@truefoundry/tfy-infra-engine';
+
+const parsed = JSON.parse(fs.readFileSync('template.json', 'utf-8'));
+const { metadata, jsonSchema } = validateTemplateJson(parsed);
+// metadata: { name, version, description? }
+// jsonSchema: the raw JSON Schema object
+```
+
+## Envelope Configuration
+
+The envelope is the engine's input configuration:
+
+```typescript
+{
+  template: templateObject,        // Pre-resolved Template object
+  inputs: { name: 'my-cluster' },  // Input values
+  intentId: 'cluster-prod-001',    // Cluster identity (required)
+  platformPrefix: 'tfy_',          // Platform Zone filename prefix (default: "tfy_")
+  options: {
+    skipFormat: false,              // Skip tofu fmt
+  },
+}
+```
+
+## Template Object
+
+The `Template` type represents a fully resolved template:
+
+```typescript
+interface Template {
+  metadata: TemplateMetadata;       // { name, version, description? }
+  jsonSchema: JSONSchema7;          // JSON Schema Draft-07 for input validation
+  files: Map<string, string>;      // HBS template files from src/ (rendered via Handlebars)
+  staticFiles: Map<string, string>; // Static files from src/ (copied verbatim)
+  source: string;                   // Source URI for tracking
+  version: VersionInfo;            // Version metadata
+}
+```
+
+## Integrity Engine
+
+### Zone Classification
+
+Files are classified into two zones based on filename prefix:
+
+- **Platform Zone** (`tfy_*` prefix, `manifest.json`): Engine-managed, includes `@tfy-status` headers
+- **User Zone** (no prefix): Customer-owned, excluded from integrity tracking
+
+### `@tfy-status` Header
+
+Platform Zone files include a structured metadata header:
+
+```hcl
+# @tfy-status:begin
+# {"managed":true,"source":"github://...","version":"v2.4.1","intent_id":"cluster-001","content_hash":"sha256:..."}
+# @tfy-status:end
+
+resource "aws_eks_cluster" "main" {
+  ...
+}
+```
+
+### JSON Manifest
+
+Each install/upgrade produces a `manifest.json` containing:
+
+- Cluster identity (`intentId`)
+- Template source and version
+- Aggregate Platform Hash
+- Per-file hashes, sources, versions, and zones
+
+### Drift Detection
+
+The `verify()` operation detects five types of drift:
+
+| Type | Description |
+|------|-------------|
+| `content_drift` | File content hash doesn't match Manifest |
+| `metadata_inconsistency` | Header fields don't match Manifest entry |
+| `source_mismatch` | File source differs from incoming source |
+| `missing_file` | File in Manifest but not on disk |
+| `unexpected_file` | Platform-prefixed file not in Manifest |
+
+## Handlebars Helpers
+
+The engine provides 7 focused helpers for HCL generation:
+
+### HCL Formatting
+- `toTerraformValue` - Convert any value to HCL syntax
+
+### Logic
+- `eq` - Strict equality comparison
+- `and` - Logical AND (all arguments truthy)
+- `or` - Logical OR (any argument truthy)
+
+### Type Checking
+- `isString` - Check if value is a string
+- `isDefined` - Check if value is defined (not null/undefined)
+- `isNotEmpty` - Check if value is not empty
+
+## Error Handling
+
+All errors are instances of `EngineError` with typed error codes:
+
+```typescript
+import { EngineError, EngineErrorCode } from '@truefoundry/tfy-infra-engine';
+
+try {
+  await engine.install(envelope);
+} catch (error) {
+  if (error instanceof EngineError) {
+    switch (error.code) {
+      case EngineErrorCode.ENVELOPE_VALIDATION_FAILED:
+        console.log('Invalid envelope:', error.message);
+        break;
+      case EngineErrorCode.INPUT_VALIDATION_FAILED:
+        console.log('Invalid inputs:', error.details);
+        break;
+      case EngineErrorCode.TEMPLATE_JSON_NOT_FOUND:
+        console.log('template.json not found in template directory');
+        break;
+      case EngineErrorCode.TEMPLATE_JSON_INVALID:
+        console.log('template.json has invalid structure:', error.message);
+        break;
+      case EngineErrorCode.TOFU_NOT_FOUND:
+        console.log('Install OpenTofu or use skipFormat option');
+        break;
+    }
+  }
+}
+```
+
+## License
+
+MIT