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

package/dist/index.js

@@ -0,0 +1,1155 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_PREFIX: () => DEFAULT_PREFIX,
+  EngineError: () => EngineError,
+  EngineErrorCode: () => EngineErrorCode,
+  classifyFile: () => classifyFile,
+  createEngine: () => createEngine,
+  isTofuAvailable: () => isTofuAvailable,
+  parseHeader: () => parseHeader,
+  templateJsonSchema: () => templateJsonSchema,
+  validateJsonSchemaStructure: () => validateJsonSchemaStructure,
+  validateTemplateJson: () => validateTemplateJson
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var EngineErrorCode = /* @__PURE__ */ ((EngineErrorCode2) => {
+  EngineErrorCode2["TEMPLATE_NOT_FOUND"] = "TEMPLATE_NOT_FOUND";
+  EngineErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  EngineErrorCode2["GITHUB_NOT_FOUND"] = "GITHUB_NOT_FOUND";
+  EngineErrorCode2["GITHUB_RATE_LIMITED"] = "GITHUB_RATE_LIMITED";
+  EngineErrorCode2["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+  EngineErrorCode2["HTTPS_AUTH_FAILED"] = "HTTPS_AUTH_FAILED";
+  EngineErrorCode2["SCHEMA_INVALID"] = "SCHEMA_INVALID";
+  EngineErrorCode2["INPUT_VALIDATION_FAILED"] = "INPUT_VALIDATION_FAILED";
+  EngineErrorCode2["TEMPLATE_JSON_NOT_FOUND"] = "TEMPLATE_JSON_NOT_FOUND";
+  EngineErrorCode2["TEMPLATE_JSON_INVALID"] = "TEMPLATE_JSON_INVALID";
+  EngineErrorCode2["TEMPLATE_SYNTAX_ERROR"] = "TEMPLATE_SYNTAX_ERROR";
+  EngineErrorCode2["TOFU_NOT_FOUND"] = "TOFU_NOT_FOUND";
+  EngineErrorCode2["TOFU_FMT_FAILED"] = "TOFU_FMT_FAILED";
+  EngineErrorCode2["CACHE_ERROR"] = "CACHE_ERROR";
+  EngineErrorCode2["ENVELOPE_VALIDATION_FAILED"] = "ENVELOPE_VALIDATION_FAILED";
+  EngineErrorCode2["MANIFEST_PARSE_ERROR"] = "MANIFEST_PARSE_ERROR";
+  return EngineErrorCode2;
+})(EngineErrorCode || {});
+var EngineError = class _EngineError extends Error {
+  code;
+  details;
+  constructor(message, code, cause, details) {
+    super(message, { cause });
+    this.name = "EngineError";
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _EngineError);
+    }
+  }
+  /**
+   * Create a string representation including error code.
+   */
+  toString() {
+    return `[${this.code}] ${this.message}`;
+  }
+  /**
+   * Convert error to JSON-serializable object.
+   */
+  toJSON() {
+    const causeError = this.cause;
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      cause: causeError?.message
+    };
+  }
+};
+
+// src/schema/validator.ts
+var import_ajv = __toESM(require("ajv"));
+
+// src/schema/template-json-schema.ts
+var templateJsonSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  type: "object",
+  properties: {
+    template: {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1 },
+        description: { type: "string" },
+        version: { type: "string", pattern: "^\\d+\\.\\d+\\.\\d+$" }
+      },
+      required: ["name", "version"],
+      additionalProperties: false
+    },
+    schema: {
+      type: "object",
+      description: "JSON Schema Draft-07 defining template inputs",
+      properties: {
+        type: { type: "string", const: "object" },
+        properties: { type: "object" },
+        required: { type: "array", items: { type: "string" } }
+      },
+      required: ["type", "properties"]
+    }
+  },
+  required: ["template", "schema"]
+};
+
+// src/schema/validator.ts
+var ajv = new import_ajv.default({
+  allErrors: true,
+  strict: false,
+  validateSchema: false
+});
+var validate = ajv.compile(templateJsonSchema);
+function validateTemplateJson(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new EngineError(
+      "template.json must be a JSON object",
+      "TEMPLATE_JSON_INVALID" /* TEMPLATE_JSON_INVALID */
+    );
+  }
+  const valid = validate(data);
+  if (!valid) {
+    const message = formatAjvErrors(validate.errors ?? []);
+    throw new EngineError(message, "TEMPLATE_JSON_INVALID" /* TEMPLATE_JSON_INVALID */);
+  }
+  const record = data;
+  const templateBlock = record["template"];
+  const metadata = {
+    name: templateBlock["name"],
+    version: templateBlock["version"],
+    ...templateBlock["description"] !== void 0 ? { description: templateBlock["description"] } : {}
+  };
+  const jsonSchema = record["schema"];
+  return { metadata, jsonSchema };
+}
+function formatAjvErrors(errors) {
+  const first = errors[0];
+  if (!first) {
+    return "template.json validation failed";
+  }
+  const path = first.instancePath || "";
+  if (first.keyword === "required") {
+    const prop = first.params["missingProperty"];
+    return `template.json must have a "${prop}" key`;
+  }
+  if (first.keyword === "type") {
+    const expected = first.params["type"];
+    return `template.json${path ? ` "${dotPath(path)}"` : ""} must be ${expected}`;
+  }
+  if (first.keyword === "pattern" && path === "/template/version") {
+    return `template.json "template.version" must be semver format (x.y.z)`;
+  }
+  if (first.keyword === "minLength" && path === "/template/name") {
+    return `template.json "template.name" must be a non-empty string`;
+  }
+  if (first.keyword === "const") {
+    const expected = first.params["allowedValue"];
+    return `template.json "${dotPath(path)}" must be ${JSON.stringify(expected)}`;
+  }
+  return `template.json validation failed at ${path || "/"}: ${first.message ?? "unknown error"}`;
+}
+function dotPath(jsonPointer) {
+  return jsonPointer.replace(/^\//, "").replace(/\//g, ".");
+}
+
+// src/schema/input-validator.ts
+var import_ajv2 = __toESM(require("ajv"));
+var ajv2 = new import_ajv2.default({
+  useDefaults: true,
+  allErrors: true,
+  discriminator: true,
+  strict: false,
+  validateSchema: false
+});
+function createInputValidator(jsonSchema) {
+  try {
+    return ajv2.compile(jsonSchema);
+  } catch (error) {
+    throw new EngineError(
+      `Failed to compile JSON Schema: ${error.message}`,
+      "SCHEMA_INVALID" /* SCHEMA_INVALID */,
+      error
+    );
+  }
+}
+function validateAndApplyDefaults(validator, inputs) {
+  const valid = validator(inputs);
+  if (valid) {
+    return { valid: true };
+  }
+  const errors = (validator.errors ?? []).map(ajvErrorToValidationError);
+  return {
+    valid: false,
+    errors
+  };
+}
+function validateJsonSchemaStructure(schema) {
+  if (!schema || typeof schema !== "object") {
+    throw new EngineError(
+      "Schema must be a non-null object",
+      "SCHEMA_INVALID" /* SCHEMA_INVALID */,
+      void 0,
+      { received: typeof schema }
+    );
+  }
+  if (schema.type !== "object") {
+    throw new EngineError(
+      `Schema root must have "type": "object", got "${schema.type ?? "undefined"}"`,
+      "SCHEMA_INVALID" /* SCHEMA_INVALID */,
+      void 0,
+      { received: schema.type }
+    );
+  }
+  if (!schema.properties || typeof schema.properties !== "object") {
+    throw new EngineError(
+      'Schema root must have a "properties" key',
+      "SCHEMA_INVALID" /* SCHEMA_INVALID */,
+      void 0,
+      { hasProperties: !!schema.properties }
+    );
+  }
+}
+function ajvErrorToValidationError(error) {
+  return {
+    path: error.instancePath || "/",
+    message: error.message ?? "Validation failed",
+    expected: formatExpected(error),
+    received: void 0
+  };
+}
+function formatExpected(error) {
+  const params = error.params;
+  if (!params) return void 0;
+  if (error.keyword === "type") {
+    return String(params["type"]);
+  }
+  if (error.keyword === "required") {
+    return `required property '${String(params["missingProperty"])}'`;
+  }
+  if (error.keyword === "pattern") {
+    return `match pattern ${String(params["pattern"])}`;
+  }
+  if (error.keyword === "enum") {
+    return `one of ${JSON.stringify(params["allowedValues"])}`;
+  }
+  if (error.keyword === "const") {
+    return `value ${JSON.stringify(params["allowedValue"])}`;
+  }
+  return void 0;
+}
+
+// src/render/renderer.ts
+var import_handlebars2 = __toESM(require("handlebars"));
+
+// src/helpers/hcl.ts
+var import_handlebars = __toESM(require("handlebars"));
+function registerHclHelpers(handlebars) {
+  handlebars.registerHelper("toTerraformValue", function(value) {
+    return new import_handlebars.default.SafeString(formatValue(value));
+  });
+}
+function formatValue(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value === "string") {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+    return `"${escaped}"`;
+  }
+  if (typeof value === "boolean" || typeof value === "number") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const elements = value.map((item) => formatValue(item));
+    if (elements.length === 0) {
+      return "[]";
+    }
+    if (elements.some((e) => e.includes("\n") || e.length > 40)) {
+      return `[
+  ${elements.join(",\n  ")}
+]`;
+    }
+    return `[${elements.join(", ")}]`;
+  }
+  if (typeof value === "object") {
+    return formatObject(value);
+  }
+  return JSON.stringify(value);
+}
+function formatObject(obj) {
+  const entries = Object.entries(obj);
+  if (entries.length === 0) {
+    return "{}";
+  }
+  const formatted = entries.map(([key, val]) => {
+    const quotedKey = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(key) ? key : `"${key}"`;
+    return `${quotedKey} = ${formatValue(val)}`;
+  });
+  return `{
+  ${formatted.join("\n  ")}
+}`;
+}
+
+// src/helpers/logic.ts
+function registerLogicHelpers(handlebars) {
+  handlebars.registerHelper("eq", (a, b) => a === b);
+  handlebars.registerHelper("and", function(...args) {
+    const values = args.slice(0, -1);
+    return values.every(Boolean);
+  });
+  handlebars.registerHelper("or", function(...args) {
+    const values = args.slice(0, -1);
+    return values.some(Boolean);
+  });
+}
+
+// src/helpers/types.ts
+function registerTypeHelpers(handlebars) {
+  handlebars.registerHelper("isString", (value) => {
+    return typeof value === "string";
+  });
+  handlebars.registerHelper("isDefined", (value) => {
+    return value !== void 0 && value !== null;
+  });
+  handlebars.registerHelper("isNotEmpty", (value) => {
+    if (value === null || value === void 0) return false;
+    if (typeof value === "string") return value.length > 0;
+    if (Array.isArray(value)) return value.length > 0;
+    if (typeof value === "object") return Object.keys(value).length > 0;
+    return true;
+  });
+}
+
+// src/helpers/index.ts
+function registerAllHelpers(handlebars) {
+  registerHclHelpers(handlebars);
+  registerLogicHelpers(handlebars);
+  registerTypeHelpers(handlebars);
+}
+
+// src/render/renderer.ts
+var HBS_COMPILE_OPTIONS = {
+  noEscape: true,
+  strict: false
+};
+function createConfiguredHandlebars() {
+  const hbs = import_handlebars2.default.create();
+  registerAllHelpers(hbs);
+  return hbs;
+}
+function createRenderContext(inputs, template) {
+  return {
+    ...inputs,
+    _template: {
+      name: template.metadata.name,
+      version: template.metadata.version,
+      source: template.source
+    }
+  };
+}
+function renderTemplate(template, inputs) {
+  const hbs = createConfiguredHandlebars();
+  const context = createRenderContext(inputs, template);
+  const results = /* @__PURE__ */ new Map();
+  for (const [outputPath, hbsContent] of template.files) {
+    try {
+      const compiled = hbs.compile(hbsContent, HBS_COMPILE_OPTIONS);
+      const rendered = compiled(context);
+      results.set(outputPath, rendered);
+    } catch (error) {
+      throw new EngineError(
+        `Failed to render ${outputPath}: ${error.message}`,
+        "TEMPLATE_SYNTAX_ERROR" /* TEMPLATE_SYNTAX_ERROR */,
+        error,
+        { file: outputPath, template: template.source }
+      );
+    }
+  }
+  return results;
+}
+
+// src/render/formatter.ts
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var DEFAULT_FORMAT_OPTIONS = {
+  skip: false,
+  timeout: 1e4
+};
+function normalizeBlankLines(content) {
+  let result = content.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+  result = result.replace(/\n*$/, "\n");
+  return result;
+}
+var HCL_FORMATTABLE_SUFFIXES = [".tf", ".tfvars", ".tftest.hcl"];
+function isHclFormattable(filePath) {
+  return HCL_FORMATTABLE_SUFFIXES.some((suffix) => filePath.endsWith(suffix));
+}
+async function formatHCL(content, options) {
+  const opts = { ...DEFAULT_FORMAT_OPTIONS, ...options };
+  if (opts.skip) {
+    return normalizeBlankLines(content);
+  }
+  return new Promise((resolve, reject) => {
+    const child = (0, import_node_child_process.spawn)("tofu", ["fmt", "-"], {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill();
+    }, opts.timeout);
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      if (error.code === "ENOENT") {
+        reject(
+          new EngineError(
+            "tofu binary not found. Please install OpenTofu or use --skip-format option.",
+            "TOFU_NOT_FOUND" /* TOFU_NOT_FOUND */,
+            error,
+            { suggestion: "Install OpenTofu from https://opentofu.org/" }
+          )
+        );
+      } else {
+        reject(
+          new EngineError(
+            `tofu fmt failed: ${error.message}`,
+            "TOFU_FMT_FAILED" /* TOFU_FMT_FAILED */,
+            error,
+            { stderr }
+          )
+        );
+      }
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(
+          new EngineError(
+            `tofu fmt timed out after ${opts.timeout}ms`,
+            "TOFU_FMT_FAILED" /* TOFU_FMT_FAILED */,
+            void 0,
+            { timeout: opts.timeout }
+          )
+        );
+        return;
+      }
+      if (code !== 0) {
+        reject(
+          new EngineError(
+            `tofu fmt failed: ${stderr || "Unknown error"}`,
+            "TOFU_FMT_FAILED" /* TOFU_FMT_FAILED */,
+            void 0,
+            { stderr, exitCode: code }
+          )
+        );
+        return;
+      }
+      resolve(normalizeBlankLines(stdout));
+    });
+    child.stdin.write(content);
+    child.stdin.end();
+  });
+}
+async function formatFiles(files, options) {
+  const opts = { ...DEFAULT_FORMAT_OPTIONS, ...options };
+  if (opts.skip) {
+    return files;
+  }
+  const results = /* @__PURE__ */ new Map();
+  for (const [path, content] of files) {
+    if (isHclFormattable(path)) {
+      try {
+        const formatted = await formatHCL(content, options);
+        results.set(path, formatted);
+      } catch (error) {
+        if (error instanceof EngineError) {
+          throw new EngineError(error.message, error.code, error.cause, {
+            ...error.details,
+            file: path
+          });
+        }
+        throw error;
+      }
+    } else {
+      results.set(path, normalizeBlankLines(content));
+    }
+  }
+  return results;
+}
+async function isTofuAvailable() {
+  try {
+    await execFileAsync("tofu", ["version"], {
+      timeout: 5e3,
+      encoding: "utf-8"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/integrity/hasher.ts
+var import_node_crypto = require("crypto");
+
+// src/integrity/header.ts
+var HEADER_BEGIN = "# @tfy-status:begin";
+var HEADER_END = "# @tfy-status:end";
+function parseHeader(content) {
+  const lines = content.split("\n");
+  if (lines[0] !== HEADER_BEGIN) {
+    return void 0;
+  }
+  if (lines[2] !== HEADER_END) {
+    return void 0;
+  }
+  const jsonLine = lines[1];
+  if (!jsonLine || !jsonLine.startsWith("# ")) {
+    return void 0;
+  }
+  const jsonStr = jsonLine.substring(2);
+  try {
+    const parsed = JSON.parse(jsonStr);
+    return {
+      managed: parsed["managed"],
+      source: parsed["source"],
+      version: parsed["version"],
+      intentId: parsed["intent_id"],
+      contentHash: parsed["content_hash"]
+    };
+  } catch {
+    return void 0;
+  }
+}
+function stripHeader(content) {
+  if (!content.startsWith(HEADER_BEGIN + "\n")) {
+    return content;
+  }
+  const endMarker = HEADER_END + "\n";
+  const endIndex = content.indexOf(endMarker);
+  if (endIndex === -1) {
+    return content;
+  }
+  let stripped = content.substring(endIndex + endMarker.length);
+  if (stripped.startsWith("\n")) {
+    stripped = stripped.substring(1);
+  }
+  return stripped;
+}
+function injectHeader(content, header) {
+  const jsonPayload = JSON.stringify({
+    managed: header.managed,
+    source: header.source,
+    version: header.version,
+    intent_id: header.intentId,
+    content_hash: header.contentHash
+  });
+  return `${HEADER_BEGIN}
+# ${jsonPayload}
+${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/zones.ts
+var import_node_path = 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, "/"));
+  if (name === MANIFEST_FILENAME) {
+    return "platform";
+  }
+  if (name.startsWith(prefix)) {
+    return "platform";
+  }
+  return "user";
+}
+function countPlatformFiles(files) {
+  let count = 0;
+  for (const [, entry] of files) {
+    if (entry.zone === "platform") count++;
+  }
+  return count;
+}
+
+// src/integrity/hasher.ts
+function sha256(content) {
+  const hex = (0, import_node_crypto.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);
+}
+function computeAggregateHash(files) {
+  const entries = [];
+  for (const [path, entry] of files) {
+    if (entry.zone === "platform" && path !== MANIFEST_FILENAME) {
+      entries.push({
+        path,
+        hash: hashFileContent(entry.content)
+      });
+    }
+  }
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  const concatenated = entries.map((e) => `${e.path}:${e.hash}`).join("\n");
+  return sha256(concatenated);
+}
+
+// src/render/manifest.ts
+var ENGINE_VERSION = "0.0.0-canary.edab06d";
+function generateManifest(opts) {
+  const { files, template, inputs, formatted, intentId, platformPrefix = "tfy_" } = opts;
+  const manifestFiles = [];
+  for (const [path, entry] of files) {
+    if (path === MANIFEST_FILENAME) continue;
+    manifestFiles.push({
+      path,
+      hash: hashFileContent(entry.content),
+      size: Buffer.byteLength(entry.content, "utf-8"),
+      source: template.source,
+      version: template.metadata.version,
+      zone: entry.zone
+    });
+  }
+  manifestFiles.sort((a, b) => a.path.localeCompare(b.path));
+  const aggregateHash = computeAggregateHash(files);
+  return {
+    manifestVersion: "1.0",
+    intentId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    templateSource: template.source,
+    templateVersion: template.metadata.version,
+    aggregateHash,
+    engine: {
+      version: ENGINE_VERSION,
+      formatted
+    },
+    inputs,
+    platformPrefix,
+    files: manifestFiles
+  };
+}
+function serializeManifest(manifest) {
+  const ordered = {
+    manifestVersion: manifest.manifestVersion,
+    intentId: manifest.intentId,
+    generatedAt: manifest.generatedAt,
+    templateSource: manifest.templateSource,
+    templateVersion: manifest.templateVersion,
+    aggregateHash: manifest.aggregateHash,
+    engine: manifest.engine,
+    inputs: manifest.inputs,
+    platformPrefix: manifest.platformPrefix,
+    files: manifest.files
+  };
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+
+// src/integrity/drift.ts
+function buildDriftReport(currentFiles, manifest, prefix = DEFAULT_PREFIX, incomingSource) {
+  const entries = [];
+  const manifestPathSet = new Set(manifest.files.map((f) => f.path));
+  const checkedPaths = /* @__PURE__ */ new Set();
+  for (const manifestEntry of manifest.files) {
+    if (manifestEntry.zone !== "platform") continue;
+    checkedPaths.add(manifestEntry.path);
+    const currentEntry = currentFiles.get(manifestEntry.path);
+    if (!currentEntry) {
+      entries.push({
+        path: manifestEntry.path,
+        type: "missing_file",
+        details: "File listed in Manifest but not found in current file map"
+      });
+      continue;
+    }
+    const actualHash = hashFileContent(currentEntry.content);
+    if (actualHash !== manifestEntry.hash) {
+      entries.push({
+        path: manifestEntry.path,
+        type: "content_drift",
+        details: `Content hash mismatch: expected ${manifestEntry.hash}, actual ${actualHash}`
+      });
+    }
+    const header = currentEntry.header ?? parseHeader(currentEntry.content);
+    if (header) {
+      if (header.source !== manifestEntry.source) {
+        entries.push({
+          path: manifestEntry.path,
+          type: "metadata_inconsistency",
+          details: `Header source '${header.source}' does not match Manifest source '${manifestEntry.source}'`
+        });
+      }
+      if (header.version !== manifestEntry.version) {
+        entries.push({
+          path: manifestEntry.path,
+          type: "metadata_inconsistency",
+          details: `Header version '${header.version}' does not match Manifest version '${manifestEntry.version}'`
+        });
+      }
+      if (header.contentHash !== manifestEntry.hash) {
+        entries.push({
+          path: manifestEntry.path,
+          type: "metadata_inconsistency",
+          details: `Header content_hash '${header.contentHash}' does not match Manifest hash '${manifestEntry.hash}'`
+        });
+      }
+    }
+  }
+  for (const [path, entry] of currentFiles) {
+    if (entry.zone === "platform" || classifyFile(path, prefix) === "platform") {
+      if (!manifestPathSet.has(path) && path !== MANIFEST_FILENAME) {
+        entries.push({
+          path,
+          type: "unexpected_file",
+          details: "Platform-prefixed file found in current file map but not listed in Manifest"
+        });
+      }
+    }
+  }
+  if (incomingSource) {
+    for (const [path, entry] of currentFiles) {
+      if (entry.zone !== "platform") continue;
+      const header = entry.header ?? parseHeader(entry.content);
+      if (header && header.source !== incomingSource) {
+        entries.push({
+          path,
+          type: "source_mismatch",
+          details: `File source '${header.source}' does not match incoming source '${incomingSource}'`
+        });
+      }
+    }
+  }
+  const actualAggregateHash = computeAggregateHash(currentFiles);
+  const expectedAggregateHash = manifest.aggregateHash;
+  const summary = buildSummary(entries, manifest);
+  return {
+    valid: entries.length === 0,
+    aggregateHash: {
+      expected: expectedAggregateHash,
+      actual: actualAggregateHash
+    },
+    entries,
+    summary
+  };
+}
+function buildSummary(entries, manifest) {
+  const driftedPaths = /* @__PURE__ */ new Set();
+  const inconsistentPaths = /* @__PURE__ */ new Set();
+  let missingFiles = 0;
+  let unexpectedFiles = 0;
+  let sourceMismatches = 0;
+  for (const entry of entries) {
+    switch (entry.type) {
+      case "content_drift":
+        driftedPaths.add(entry.path);
+        break;
+      case "metadata_inconsistency":
+        inconsistentPaths.add(entry.path);
+        break;
+      case "missing_file":
+        missingFiles++;
+        break;
+      case "unexpected_file":
+        unexpectedFiles++;
+        break;
+      case "source_mismatch":
+        sourceMismatches++;
+        break;
+    }
+  }
+  return {
+    totalFiles: manifest.files.filter((f) => f.zone === "platform").length,
+    driftedFiles: driftedPaths.size,
+    inconsistentFiles: inconsistentPaths.size,
+    missingFiles,
+    unexpectedFiles,
+    sourceMismatches
+  };
+}
+
+// src/schema/envelope.ts
+function fail(message) {
+  throw new EngineError(message, "ENVELOPE_VALIDATION_FAILED" /* ENVELOPE_VALIDATION_FAILED */);
+}
+function validateEnvelope(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    fail("Envelope must be a non-null object");
+  }
+  const record = data;
+  const knownFields = /* @__PURE__ */ new Set(["template", "inputs", "options", "intentId", "platformPrefix"]);
+  for (const key of Object.keys(record)) {
+    if (!knownFields.has(key)) {
+      fail(`Unknown field "${key}" in envelope. Allowed: ${[...knownFields].join(", ")}`);
+    }
+  }
+  validateTemplateObject(record["template"]);
+  if (typeof record["intentId"] !== "string" || record["intentId"].length === 0) {
+    fail("intentId is required and must be non-empty");
+  }
+  const inputs = record["inputs"] !== void 0 ? record["inputs"] : {};
+  if (typeof inputs !== "object" || inputs === null || Array.isArray(inputs)) {
+    fail("inputs must be an object");
+  }
+  const platformPrefix = record["platformPrefix"] !== void 0 ? record["platformPrefix"] : "tfy_";
+  if (typeof platformPrefix !== "string") {
+    fail("platformPrefix must be a string");
+  }
+  let options;
+  if (record["options"] !== void 0) {
+    options = validateRenderOptions(record["options"]);
+  }
+  return {
+    template: record["template"],
+    inputs,
+    options,
+    intentId: record["intentId"],
+    platformPrefix
+  };
+}
+function parseRenderOptions(options) {
+  return {
+    skipFormat: options?.skipFormat ?? false
+  };
+}
+function validateTemplateObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fail("template must be a non-null object");
+  }
+  const template = value;
+  if (!template["metadata"] || typeof template["metadata"] !== "object") {
+    fail("template.metadata must be an object");
+  }
+  const metadata = template["metadata"];
+  if (typeof metadata["name"] !== "string" || metadata["name"].length === 0) {
+    fail("template.metadata.name must be a non-empty string");
+  }
+  if (typeof metadata["version"] !== "string" || !/^\d+\.\d+\.\d+$/.test(metadata["version"])) {
+    fail("template.metadata.version must be semver format (x.y.z)");
+  }
+  if (!template["jsonSchema"] || typeof template["jsonSchema"] !== "object") {
+    fail("template.jsonSchema must be an object");
+  }
+  const hasFiles = template["files"] instanceof Map && template["files"].size > 0 || template["staticFiles"] instanceof Map && template["staticFiles"].size > 0;
+  if (!hasFiles) {
+    fail("Template must have at least one file (in files or staticFiles)");
+  }
+  if (template["files"] !== void 0 && !(template["files"] instanceof Map)) {
+    fail("template.files must be a Map");
+  }
+  if (template["staticFiles"] !== void 0 && !(template["staticFiles"] instanceof Map)) {
+    fail("template.staticFiles must be a Map");
+  }
+  if (typeof template["source"] !== "string" || template["source"].length === 0) {
+    fail("Template source URI is required");
+  }
+  if (!template["version"] || typeof template["version"] !== "object") {
+    fail("Template version info is required");
+  }
+  const version = template["version"];
+  if (typeof version["semver"] !== "string" || !/^\d+\.\d+\.\d+$/.test(version["semver"])) {
+    fail("template.version.semver must be semver format (x.y.z)");
+  }
+  if (version["apiVersion"] !== void 0 && typeof version["apiVersion"] !== "string") {
+    fail("template.version.apiVersion must be a string if provided");
+  }
+}
+function validateRenderOptions(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    fail("options must be an object");
+  }
+  const opts = value;
+  const knownOptionFields = /* @__PURE__ */ new Set(["skipFormat"]);
+  for (const key of Object.keys(opts)) {
+    if (!knownOptionFields.has(key)) {
+      fail(`Unknown option field "${key}". Allowed: ${[...knownOptionFields].join(", ")}`);
+    }
+  }
+  if (opts["skipFormat"] !== void 0 && typeof opts["skipFormat"] !== "boolean") {
+    fail("options.skipFormat must be a boolean");
+  }
+  return {
+    skipFormat: opts["skipFormat"]
+  };
+}
+
+// src/engine.ts
+var HclEngineImpl = class {
+  /**
+   * Install: Generate all files for a new cluster.
+   *
+   * Pipeline: validate envelope → validate inputs (AJV) → render templates →
+   * format .tf files → classify by zone → hash + inject headers → generate manifest.
+   */
+  async install(envelope) {
+    const validatedEnvelope = this.validateEnvelopeOrThrow(envelope);
+    const options = parseRenderOptions(validatedEnvelope.options);
+    const prefix = validatedEnvelope.platformPrefix ?? DEFAULT_PREFIX;
+    const { renderedFiles, template, formatted, inputsWithDefaults } = await this.renderPipeline(
+      validatedEnvelope,
+      options
+    );
+    const { fileMap, manifest } = this.buildFilesAndManifest(
+      renderedFiles,
+      validatedEnvelope,
+      template,
+      inputsWithDefaults,
+      formatted,
+      prefix
+    );
+    return { files: fileMap, manifest };
+  }
+  /**
+   * Upgrade: Update an existing cluster to new templates.
+   *
+   * Pipeline: validate envelope → drift detection (FR-028) → if source mismatch,
+   * short-circuit → validate inputs → render → format → hash + manifest.
+   */
+  async upgrade(envelope, currentFiles, previousManifest) {
+    const validatedEnvelope = this.validateEnvelopeOrThrow(envelope);
+    const options = parseRenderOptions(validatedEnvelope.options);
+    const prefix = validatedEnvelope.platformPrefix ?? DEFAULT_PREFIX;
+    const incomingSource = validatedEnvelope.template.source;
+    const driftReport = buildDriftReport(currentFiles, previousManifest, prefix, incomingSource);
+    const sourceBlocked = driftReport.summary.sourceMismatches > 0;
+    if (sourceBlocked) {
+      return {
+        files: currentFiles,
+        manifest: previousManifest,
+        driftReport,
+        sourceBlocked: true
+      };
+    }
+    const { renderedFiles, template, formatted, inputsWithDefaults } = await this.renderPipeline(
+      validatedEnvelope,
+      options
+    );
+    const { fileMap, manifest } = this.buildFilesAndManifest(
+      renderedFiles,
+      validatedEnvelope,
+      template,
+      inputsWithDefaults,
+      formatted,
+      prefix
+    );
+    return { files: fileMap, manifest, driftReport, sourceBlocked: false };
+  }
+  /**
+   * Verify: Check integrity of existing files against a Manifest.
+   */
+  verify(currentFiles, previousManifest) {
+    if (!previousManifest || !previousManifest.manifestVersion || !previousManifest.files || !previousManifest.aggregateHash) {
+      throw new EngineError(
+        "Invalid manifest: missing required fields (manifestVersion, files, aggregateHash)",
+        "MANIFEST_PARSE_ERROR" /* MANIFEST_PARSE_ERROR */
+      );
+    }
+    const driftReport = buildDriftReport(currentFiles, previousManifest);
+    return Promise.resolve({ driftReport });
+  }
+  /**
+   * Hash-Only: Calculate expected aggregate hash without full file generation.
+   */
+  async hashOnly(envelope) {
+    const validatedEnvelope = this.validateEnvelopeOrThrow(envelope);
+    const options = parseRenderOptions(validatedEnvelope.options);
+    const prefix = validatedEnvelope.platformPrefix ?? DEFAULT_PREFIX;
+    const { renderedFiles, template, formatted, inputsWithDefaults } = await this.renderPipeline(
+      validatedEnvelope,
+      options
+    );
+    const { fileMap, manifest } = this.buildFilesAndManifest(
+      renderedFiles,
+      validatedEnvelope,
+      template,
+      inputsWithDefaults,
+      formatted,
+      prefix
+    );
+    return {
+      aggregateHash: manifest.aggregateHash,
+      templateSource: template.source,
+      templateVersion: template.metadata.version,
+      fileCount: countPlatformFiles(fileMap)
+    };
+  }
+  // =========================================================================
+  // Private helpers
+  // =========================================================================
+  /**
+   * Validate envelope or throw ENVELOPE_VALIDATION_FAILED.
+   */
+  validateEnvelopeOrThrow(envelope) {
+    try {
+      return validateEnvelope(envelope);
+    } catch (error) {
+      throw new EngineError(
+        `Envelope validation failed: ${error.message}`,
+        "ENVELOPE_VALIDATION_FAILED" /* ENVELOPE_VALIDATION_FAILED */,
+        error
+      );
+    }
+  }
+  /**
+   * Shared render pipeline: validate schema → validate inputs → render → format.
+   */
+  async renderPipeline(validatedEnvelope, options) {
+    const template = validatedEnvelope.template;
+    validateJsonSchemaStructure(template.jsonSchema);
+    const validator = createInputValidator(template.jsonSchema);
+    const inputsWithDefaults = structuredClone(validatedEnvelope.inputs);
+    const validation = validateAndApplyDefaults(validator, inputsWithDefaults);
+    if (!validation.valid) {
+      throw new EngineError(
+        `Input validation failed: ${validation.errors?.map((e) => `${e.path}: ${e.message}`).join(", ")}`,
+        "INPUT_VALIDATION_FAILED" /* INPUT_VALIDATION_FAILED */,
+        void 0,
+        { errors: validation.errors }
+      );
+    }
+    let renderedFiles = renderTemplate(template, inputsWithDefaults);
+    if (template.staticFiles) {
+      for (const [path, content] of template.staticFiles) {
+        renderedFiles.set(path, content);
+      }
+    }
+    const formatted = !options.skipFormat;
+    if (formatted) {
+      renderedFiles = await formatFiles(renderedFiles, {
+        skip: false,
+        timeout: 1e4
+      });
+    }
+    for (const [path, content] of renderedFiles) {
+      if (content.trim() === "") {
+        renderedFiles.delete(path);
+      }
+    }
+    return { renderedFiles, template, formatted, inputsWithDefaults };
+  }
+  /**
+   * Build a zone-tagged FileEntry map from raw rendered files.
+   */
+  buildFileMap(renderedFiles, prefix, meta) {
+    const fileMap = /* @__PURE__ */ new Map();
+    for (const [path, content] of renderedFiles) {
+      const zone = classifyFile(path, prefix);
+      if (zone === "platform") {
+        const contentHash = hashFileContent(content);
+        const header = {
+          managed: true,
+          source: meta.source,
+          version: meta.version,
+          intentId: meta.intentId,
+          contentHash
+        };
+        const contentWithHeader = injectHeader(content, header);
+        fileMap.set(path, {
+          content: contentWithHeader,
+          zone: "platform",
+          header
+        });
+      } else {
+        fileMap.set(path, {
+          content,
+          zone: "user"
+        });
+      }
+    }
+    return fileMap;
+  }
+  /**
+   * Build zone-tagged file map, generate manifest, and insert it into the map.
+   * Shared by install, upgrade, and hashOnly.
+   */
+  buildFilesAndManifest(renderedFiles, validatedEnvelope, template, inputsWithDefaults, formatted, prefix) {
+    const fileMap = this.buildFileMap(renderedFiles, prefix, {
+      source: template.source,
+      version: template.metadata.version,
+      intentId: validatedEnvelope.intentId
+    });
+    const manifest = generateManifest({
+      files: fileMap,
+      template,
+      inputs: inputsWithDefaults,
+      formatted,
+      intentId: validatedEnvelope.intentId,
+      platformPrefix: prefix
+    });
+    fileMap.set(MANIFEST_FILENAME, {
+      content: serializeManifest(manifest),
+      zone: "platform"
+    });
+    return { fileMap, manifest };
+  }
+};
+function createEngine() {
+  return new HclEngineImpl();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_PREFIX,
+  EngineError,
+  EngineErrorCode,
+  classifyFile,
+  createEngine,
+  isTofuAvailable,
+  parseHeader,
+  templateJsonSchema,
+  validateJsonSchemaStructure,
+  validateTemplateJson
+});
+//# sourceMappingURL=index.js.map