@truefoundry/tfy-infra-engine 0.1.0 → 0.1.2-canary.e8cd23d

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`

package/dist/index.d.mts

@@ -529,6 +529,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 +627,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 { 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, canonicalHash, classifyFile, createEngine, getCanonicalHashScriptPath, isTofuAvailable, parseHeader, templateJsonSchema, validateJsonSchemaStructure, validateTemplateJson };

package/dist/index.d.ts

@@ -529,6 +529,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 +627,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 { 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, canonicalHash, classifyFile, createEngine, getCanonicalHashScriptPath, isTofuAvailable, parseHeader, templateJsonSchema, validateJsonSchemaStructure, validateTemplateJson };

package/dist/index.js

@@ -33,8 +33,10 @@ __export(index_exports, {
   DEFAULT_PREFIX: () => DEFAULT_PREFIX,
   EngineError: () => EngineError,
   EngineErrorCode: () => EngineErrorCode,
+  canonicalHash: () => canonicalHash,
   classifyFile: () => classifyFile,
   createEngine: () => createEngine,
+  getCanonicalHashScriptPath: () => getCanonicalHashScriptPath,
   isTofuAvailable: () => isTofuAvailable,
   parseHeader: () => parseHeader,
   templateJsonSchema: () => templateJsonSchema,
@@ -533,6 +535,12 @@ async function isTofuAvailable() {
 }
 
 // src/integrity/hasher.ts
+var import_node_crypto2 = require("crypto");
+
+// src/integrity/canonical-hash.ts
+var import_node_child_process2 = require("child_process");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
 var import_node_crypto = require("crypto");
 
 // src/integrity/header.ts
@@ -594,20 +602,65 @@ ${HEADER_END}
 ${content}`;
 }
 
-// src/integrity/normalizer.ts
-function normalizeForHashing(content) {
-  let normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-  normalized = normalized.split("\n").map((line) => line.replace(/[\t ]+$/, "")).join("\n");
-  normalized = normalized.replace(/\n*$/, "\n");
-  return normalized;
+// src/integrity/canonical-hash.ts
+var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+var DEFAULT_TIMEOUT_MS = 3e3;
+var _cachedScriptPath;
+function findPackageRoot(startDir) {
+  let dir = startDir;
+  for (; ; ) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(dir, "package.json"))) return dir;
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(`Cannot find package root (no package.json found above ${startDir})`);
+}
+function getCanonicalHashScriptPath() {
+  if (_cachedScriptPath !== void 0) return _cachedScriptPath;
+  const pkgRoot = findPackageRoot(__dirname);
+  _cachedScriptPath = (0, import_node_path.join)(pkgRoot, "scripts", "canonical_hash.sh");
+  return _cachedScriptPath;
+}
+function canonicalHash(content, options) {
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT_MS;
+  try {
+    const scriptPath = getCanonicalHashScriptPath();
+    const result = (0, import_node_child_process2.spawnSync)("sh", [scriptPath], {
+      input: content,
+      encoding: "utf-8",
+      timeout,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    if (result.error) {
+      throw result.error;
+    }
+    if (result.status !== 0) {
+      throw new Error(`canonical_hash.sh exited with code ${result.status}: ${result.stderr}`);
+    }
+    const hash = result.stdout.trim();
+    if (!HASH_PATTERN.test(hash)) {
+      throw new Error(`canonical_hash.sh returned malformed output: ${hash}`);
+    }
+    return hash;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `[tfy-infra-engine] canonical hash failed, using raw hash fallback: ${message}
+`
+    );
+    const stripped = stripHeader(content);
+    const hex = (0, import_node_crypto.createHash)("sha256").update(stripped, "utf-8").digest("hex");
+    return `sha256:${hex}`;
+  }
 }
 
 // src/integrity/zones.ts
-var import_node_path = require("path");
+var import_node_path2 = require("path");
 var DEFAULT_PREFIX = "tfy_";
 var MANIFEST_FILENAME = "manifest.json";
 function classifyFile(filePath, prefix = DEFAULT_PREFIX) {
-  const name = (0, import_node_path.basename)(filePath.replace(/\\/g, "/"));
+  const name = (0, import_node_path2.basename)(filePath.replace(/\\/g, "/"));
   if (name === MANIFEST_FILENAME) {
     return "platform";
   }
@@ -626,13 +679,11 @@ function countPlatformFiles(files) {
 
 // src/integrity/hasher.ts
 function sha256(content) {
-  const hex = (0, import_node_crypto.createHash)("sha256").update(content, "utf-8").digest("hex");
+  const hex = (0, import_node_crypto2.createHash)("sha256").update(content, "utf-8").digest("hex");
   return `sha256:${hex}`;
 }
 function hashFileContent(content) {
-  const stripped = stripHeader(content);
-  const normalized = normalizeForHashing(stripped);
-  return sha256(normalized);
+  return canonicalHash(content);
 }
 function computeAggregateHash(files) {
   const entries = [];
@@ -650,7 +701,7 @@ function computeAggregateHash(files) {
 }
 
 // src/render/manifest.ts
-var ENGINE_VERSION = "0.1.0";
+var ENGINE_VERSION = "0.1.2-canary.e8cd23d";
 function generateManifest(opts) {
   const { files, template, inputs, formatted, intentId, platformPrefix = "tfy_" } = opts;
   const manifestFiles = [];
@@ -1144,8 +1195,10 @@ function createEngine() {
   DEFAULT_PREFIX,
   EngineError,
   EngineErrorCode,
+  canonicalHash,
   classifyFile,
   createEngine,
+  getCanonicalHashScriptPath,
   isTofuAvailable,
   parseHeader,
   templateJsonSchema,