@truefoundry/tfy-infra-engine 0.1.2 → 0.1.3-canary.4058145

package/README.md

@@ -53,7 +53,8 @@ console.log('Aggregate Hash:', result.manifest.aggregateHash);
 - **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`
+- **HCL formatting**: Optional formatting with `tofu fmt` for output readability
+- **Format-independent canonical hashing**: Deterministic SHA-256 hashes via `canonical_hash.sh` regardless of formatting, comments, or whitespace. The script is available for external callers (e.g., bash scripts using Terraform directly)
 - **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`
@@ -99,15 +100,21 @@ if (!result.driftReport.valid) {
 
 ### `engine.upgrade(envelope, currentFiles, previousManifest)`
 
-Update platform files to new template versions. Performs pre-upgrade drift detection and source mismatch blocking.
+Update platform files to new template versions. Always renders new files and returns a pre-upgrade drift report. The `sourceBlocked` flag indicates a template source mismatch -- callers enforce blocking policy (FR-029).
 
 ```typescript
 const result = await engine.upgrade(envelope, currentFiles, previousManifest);
+
 if (result.sourceBlocked) {
-  console.log('Upgrade blocked: template source mismatch');
-} else if (!result.driftReport.valid) {
+  // Template source changed -- caller decides whether to proceed
+  console.log('Source mismatch detected');
+}
+if (!result.driftReport.valid) {
+  // Managed files were modified since last render
   console.log('Pre-upgrade drift detected');
 }
+
+// result.files always contains newly rendered files, even when sourceBlocked
 ```
 
 ### `engine.hashOnly(envelope)`
@@ -145,15 +152,15 @@ if (!result.valid) {
 // inputs now has defaults applied in-place
 ```
 
-### Template JSON Validation
+### Bundle Validation
 
-Validate the top-level structure of a `template.json` file:
+Validate the top-level structure of a `bundle.json` file:
 
 ```typescript
-import { validateTemplateJson } from '@truefoundry/tfy-infra-engine';
+import { validateBundle } from '@truefoundry/tfy-infra-engine';
 
-const parsed = JSON.parse(fs.readFileSync('template.json', 'utf-8'));
-const { metadata, jsonSchema } = validateTemplateJson(parsed);
+const parsed = JSON.parse(fs.readFileSync('bundle.json', 'utf-8'));
+const { metadata, jsonSchema } = validateBundle(parsed);
 // metadata: { name, version, description? }
 // jsonSchema: the raw JSON Schema object
 ```
@@ -268,11 +275,11 @@ try {
       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');
+      case EngineErrorCode.BUNDLE_NOT_FOUND:
+        console.log('bundle.json not found in template directory');
         break;
-      case EngineErrorCode.TEMPLATE_JSON_INVALID:
-        console.log('template.json has invalid structure:', error.message);
+      case EngineErrorCode.BUNDLE_INVALID:
+        console.log('bundle.json has invalid structure:', error.message);
         break;
       case EngineErrorCode.TOFU_NOT_FOUND:
         console.log('Install OpenTofu or use skipFormat option');

package/dist/index.d.mts

@@ -4,14 +4,12 @@
 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",
+    BUNDLE_NOT_FOUND = "BUNDLE_NOT_FOUND",
+    BUNDLE_INVALID = "BUNDLE_INVALID",
     TEMPLATE_SYNTAX_ERROR = "TEMPLATE_SYNTAX_ERROR",
     TOFU_NOT_FOUND = "TOFU_NOT_FOUND",
     TOFU_FMT_FAILED = "TOFU_FMT_FAILED",
@@ -42,7 +40,7 @@ declare class EngineError extends Error {
  *
  * 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.
+ * Templates provide JSON Schema directly via bundle.json.
  */
 /**
  * JSON Schema Draft-07 type.
@@ -174,7 +172,7 @@ interface RenderOptions {
     skipFormat?: boolean;
 }
 /**
- * Metadata about a template, sourced from the "template" key in template.json.
+ * Metadata about a template, sourced from the "metadata" key in bundle.json.
  */
 interface TemplateMetadata {
     /** Template name */
@@ -188,12 +186,12 @@ interface TemplateMetadata {
  * 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.
+ * Metadata comes from bundle.json "metadata" key; schema from "jsonSchema" key.
  */
 interface Template {
-    /** Template metadata from template.json → "template" key */
+    /** Template metadata from bundle.json → "metadata" key */
     metadata: TemplateMetadata;
-    /** JSON Schema Draft-07 from template.json → "schema" key */
+    /** JSON Schema Draft-07 from bundle.json → "jsonSchema" key */
     jsonSchema: JSONSchema7;
     /** Map of output paths to HBS content (rendered via Handlebars) */
     files: Map<string, string>;
@@ -423,36 +421,36 @@ interface HclEngine {
 }
 
 /**
- * Template JSON structure validation using AJV.
+ * Bundle 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.
+ * Validates the top-level structure of a bundle against the
+ * bundleSchema (JSON Schema Draft-07) defined in bundle-schema.ts.
  *
  * Reference: R-006, data-model.md validator.ts
  */
 
 /**
- * Result of validating a template.json file.
+ * Result of validating a bundle.
  */
-interface TemplateJsonResult {
+interface BundleValidationResult {
     metadata: TemplateMetadata;
     jsonSchema: JSONSchema7;
 }
 /**
- * Validate the structure of a parsed template.json file.
+ * Validate the structure of a parsed bundle.
  *
  * 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
+ *   - Data is an object with "metadata" and "jsonSchema" keys
+ *   - metadata.name is a non-empty string
+ *   - metadata.version is a semver string (x.y.z)
+ *   - metadata.description is an optional string
+ *   - jsonSchema is a non-null object with type: "object" and properties
  *
- * @param data - Parsed JSON content from template.json
+ * @param data - Parsed JSON content from a bundle
  * @returns Validated metadata and JSON Schema
- * @throws EngineError with TEMPLATE_JSON_INVALID on failure
+ * @throws EngineError with BUNDLE_INVALID on failure
  */
-declare function validateTemplateJson(data: unknown): TemplateJsonResult;
+declare function validateBundle(data: unknown): BundleValidationResult;
 
 /**
  * AJV-based JSON Schema input validation.
@@ -480,20 +478,20 @@ declare function validateTemplateJson(data: unknown): TemplateJsonResult;
 declare function validateJsonSchemaStructure(schema: JSONSchema7): void;
 
 /**
- * JSON Schema (Draft-07) for template.json files.
+ * JSON Schema (Draft-07) for bundle.json files.
  *
- * This is the source of truth for template.json validation.
+ * This is the source of truth for bundle structure 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
+ *   - "metadata" key: name (required, non-empty), version (semver, required), description (optional string)
+ *   - "jsonSchema" 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.
+ * Note: No additionalProperties: false at root level -- extra top-level keys are allowed
+ * for forward compatibility (e.g., uiSchema, files, staticFiles, version).
  */
 
-declare const templateJsonSchema: JSONSchema7;
+declare const bundleSchema: JSONSchema7;
 
 /**
  * Check if tofu is available in the system.
@@ -529,6 +527,47 @@ declare const DEFAULT_PREFIX = "tfy_";
  */
 declare function classifyFile(filePath: string, prefix?: string): Zone;
 
+/**
+ * Format-independent canonical hashing via external shell script.
+ *
+ * Delegates to `scripts/canonical_hash.sh` which canonicalizes HCL content
+ * (stripping headers, comments, whitespace, and normalizing trailing commas)
+ * then computes a SHA-256 hash. Uses spawnSync to keep the entire call graph
+ * synchronous.
+ *
+ * Reference: R-003, R-010
+ */
+/**
+ * Get the absolute path to the canonical_hash.sh script.
+ *
+ * Resolves by walking up from the current module's directory to find the
+ * package root, then appending `scripts/canonical_hash.sh`. The result is
+ * cached after first resolution.
+ *
+ * Works in all environments:
+ *   - Dev/test: __dirname = src/integrity -> walk up 2 levels
+ *   - tsup CJS: __dirname = dist -> walk up 1 level
+ *   - tsup ESM: __dirname shimmed by esbuild -> walk up 1 level
+ */
+declare function getCanonicalHashScriptPath(): string;
+/**
+ * Compute a format-independent canonical hash of HCL content.
+ *
+ * The shell script handles the full pipeline: strip @tfy-status header,
+ * strip carriage returns, canonicalize via AWK 4-state machine, then SHA-256.
+ *
+ * If the script fails for any reason (not found, timeout, bad exit code,
+ * malformed output), falls back to a raw SHA-256 of the header-stripped
+ * content and logs a warning.
+ *
+ * @param content - Raw file content (may include @tfy-status header)
+ * @param options - Optional timeout in milliseconds (default: 10000)
+ * @returns Hash string in format "sha256:<64-hex-chars>"
+ */
+declare function canonicalHash(content: string, options?: {
+    timeout?: number;
+}): string;
+
 /**
  * @tfy-status header processing: parse, strip, inject.
  *
@@ -586,4 +625,4 @@ declare function parseHeader(content: string): TfyStatusHeader | undefined;
  */
 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 };
+export { type BundleValidationResult, 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 TemplateMetadata, type UpgradeResult, type VerifyResult, type VersionInfo, bundleSchema, canonicalHash, classifyFile, createEngine, getCanonicalHashScriptPath, isTofuAvailable, parseHeader, validateBundle, validateJsonSchemaStructure };

package/dist/index.d.ts

@@ -4,14 +4,12 @@
 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",
+    BUNDLE_NOT_FOUND = "BUNDLE_NOT_FOUND",
+    BUNDLE_INVALID = "BUNDLE_INVALID",
     TEMPLATE_SYNTAX_ERROR = "TEMPLATE_SYNTAX_ERROR",
     TOFU_NOT_FOUND = "TOFU_NOT_FOUND",
     TOFU_FMT_FAILED = "TOFU_FMT_FAILED",
@@ -42,7 +40,7 @@ declare class EngineError extends Error {
  *
  * 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.
+ * Templates provide JSON Schema directly via bundle.json.
  */
 /**
  * JSON Schema Draft-07 type.
@@ -174,7 +172,7 @@ interface RenderOptions {
     skipFormat?: boolean;
 }
 /**
- * Metadata about a template, sourced from the "template" key in template.json.
+ * Metadata about a template, sourced from the "metadata" key in bundle.json.
  */
 interface TemplateMetadata {
     /** Template name */
@@ -188,12 +186,12 @@ interface TemplateMetadata {
  * 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.
+ * Metadata comes from bundle.json "metadata" key; schema from "jsonSchema" key.
  */
 interface Template {
-    /** Template metadata from template.json → "template" key */
+    /** Template metadata from bundle.json → "metadata" key */
     metadata: TemplateMetadata;
-    /** JSON Schema Draft-07 from template.json → "schema" key */
+    /** JSON Schema Draft-07 from bundle.json → "jsonSchema" key */
     jsonSchema: JSONSchema7;
     /** Map of output paths to HBS content (rendered via Handlebars) */
     files: Map<string, string>;
@@ -423,36 +421,36 @@ interface HclEngine {
 }
 
 /**
- * Template JSON structure validation using AJV.
+ * Bundle 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.
+ * Validates the top-level structure of a bundle against the
+ * bundleSchema (JSON Schema Draft-07) defined in bundle-schema.ts.
  *
  * Reference: R-006, data-model.md validator.ts
  */
 
 /**
- * Result of validating a template.json file.
+ * Result of validating a bundle.
  */
-interface TemplateJsonResult {
+interface BundleValidationResult {
     metadata: TemplateMetadata;
     jsonSchema: JSONSchema7;
 }
 /**
- * Validate the structure of a parsed template.json file.
+ * Validate the structure of a parsed bundle.
  *
  * 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
+ *   - Data is an object with "metadata" and "jsonSchema" keys
+ *   - metadata.name is a non-empty string
+ *   - metadata.version is a semver string (x.y.z)
+ *   - metadata.description is an optional string
+ *   - jsonSchema is a non-null object with type: "object" and properties
  *
- * @param data - Parsed JSON content from template.json
+ * @param data - Parsed JSON content from a bundle
  * @returns Validated metadata and JSON Schema
- * @throws EngineError with TEMPLATE_JSON_INVALID on failure
+ * @throws EngineError with BUNDLE_INVALID on failure
  */
-declare function validateTemplateJson(data: unknown): TemplateJsonResult;
+declare function validateBundle(data: unknown): BundleValidationResult;
 
 /**
  * AJV-based JSON Schema input validation.
@@ -480,20 +478,20 @@ declare function validateTemplateJson(data: unknown): TemplateJsonResult;
 declare function validateJsonSchemaStructure(schema: JSONSchema7): void;
 
 /**
- * JSON Schema (Draft-07) for template.json files.
+ * JSON Schema (Draft-07) for bundle.json files.
  *
- * This is the source of truth for template.json validation.
+ * This is the source of truth for bundle structure 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
+ *   - "metadata" key: name (required, non-empty), version (semver, required), description (optional string)
+ *   - "jsonSchema" 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.
+ * Note: No additionalProperties: false at root level -- extra top-level keys are allowed
+ * for forward compatibility (e.g., uiSchema, files, staticFiles, version).
  */
 
-declare const templateJsonSchema: JSONSchema7;
+declare const bundleSchema: JSONSchema7;
 
 /**
  * Check if tofu is available in the system.
@@ -529,6 +527,47 @@ declare const DEFAULT_PREFIX = "tfy_";
  */
 declare function classifyFile(filePath: string, prefix?: string): Zone;
 
+/**
+ * Format-independent canonical hashing via external shell script.
+ *
+ * Delegates to `scripts/canonical_hash.sh` which canonicalizes HCL content
+ * (stripping headers, comments, whitespace, and normalizing trailing commas)
+ * then computes a SHA-256 hash. Uses spawnSync to keep the entire call graph
+ * synchronous.
+ *
+ * Reference: R-003, R-010
+ */
+/**
+ * Get the absolute path to the canonical_hash.sh script.
+ *
+ * Resolves by walking up from the current module's directory to find the
+ * package root, then appending `scripts/canonical_hash.sh`. The result is
+ * cached after first resolution.
+ *
+ * Works in all environments:
+ *   - Dev/test: __dirname = src/integrity -> walk up 2 levels
+ *   - tsup CJS: __dirname = dist -> walk up 1 level
+ *   - tsup ESM: __dirname shimmed by esbuild -> walk up 1 level
+ */
+declare function getCanonicalHashScriptPath(): string;
+/**
+ * Compute a format-independent canonical hash of HCL content.
+ *
+ * The shell script handles the full pipeline: strip @tfy-status header,
+ * strip carriage returns, canonicalize via AWK 4-state machine, then SHA-256.
+ *
+ * If the script fails for any reason (not found, timeout, bad exit code,
+ * malformed output), falls back to a raw SHA-256 of the header-stripped
+ * content and logs a warning.
+ *
+ * @param content - Raw file content (may include @tfy-status header)
+ * @param options - Optional timeout in milliseconds (default: 10000)
+ * @returns Hash string in format "sha256:<64-hex-chars>"
+ */
+declare function canonicalHash(content: string, options?: {
+    timeout?: number;
+}): string;
+
 /**
  * @tfy-status header processing: parse, strip, inject.
  *
@@ -586,4 +625,4 @@ declare function parseHeader(content: string): TfyStatusHeader | undefined;
  */
 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 };
+export { type BundleValidationResult, 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 TemplateMetadata, type UpgradeResult, type VerifyResult, type VersionInfo, bundleSchema, canonicalHash, classifyFile, createEngine, getCanonicalHashScriptPath, isTofuAvailable, parseHeader, validateBundle, validateJsonSchemaStructure };