@kungfu-tech/buildchain 2.3.1 → 2.4.0-alpha.0

package/packages/core/buildchain-config.js

@@ -9,7 +9,7 @@ const RESERVED_LIFECYCLE_KEYS = new Set(["env", "shell"]);
 const SUPPORTED_VERSION_FILE_TYPES = new Set(["json", "toml", "regex"]);
 const SUPPORTED_VERSION_STRATEGIES = new Set(["semver", "anchored"]);
 const SUPPORTED_VERSION_NEXT = new Set(["auto", "manual"]);
-const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface"]);
+const SUPPORTED_PROJECT_TYPES = new Set(["package", "web-surface", "infra-contract"]);
 const SUPPORTED_PUBLISH_MODES = new Set(["publish-final-version", "promote-existing-version"]);
 const SUPPORTED_PUBLISH_AUTH = new Set(["trusted-publishing", "npm-token"]);
 const SUPPORTED_PACKAGE_SET_ORDER = new Set(["as-provided", "platforms-first-main-last"]);
@@ -23,6 +23,25 @@ const SUPPORTED_DEPLOY_ADAPTERS = new Set([
   "aws-elastic-beanstalk",
   "aws-ecs-service",
 ]);
+const SUPPORTED_INFRA_ADAPTERS = new Set([
+  "manual-observed",
+  "aws-cloudformation",
+  "terraform",
+  "opentofu",
+  "pulumi",
+  "aws-cdk",
+  "aws-cli",
+  "custom-command",
+]);
+const SUPPORTED_INFRA_ADOPTION_MODES = new Set([
+  "validate-only",
+  "plan-only",
+  "observe-only",
+  "manual-observed",
+  "import-planned",
+  "managed-apply",
+]);
+const SUPPORTED_INFRA_APPLY_MODES = new Set(["disabled", "manual-approval", "environment-approval"]);
 
 function posixPath(value) {
   return String(value || "").split(path.sep).join("/");
@@ -117,6 +136,12 @@ export function normalizeBuildchainConfig(config) {
   if (normalized.deploy !== undefined) {
     normalized.deploy = normalizeDeploySection(normalized.deploy, normalized.project);
   }
+  if (normalized.infra !== undefined) {
+    normalized.infra = normalizeInfraSection(normalized.infra);
+  }
+  if (normalized.consumers !== undefined) {
+    normalized.consumers = normalizeConsumersSection(normalized.consumers);
+  }
   if (normalized.surfaces !== undefined) {
     normalized.surfaces = normalizeSurfacesSection(normalized.surfaces);
   }
@@ -130,6 +155,7 @@ export function normalizeBuildchainConfig(config) {
     normalized.diagnostics = normalizeDiagnosticsSection(normalized.diagnostics);
   }
   validateWebSurfaceConfig(normalized);
+  validateInfraContractConfig(normalized);
   return normalized;
 }
 
@@ -211,7 +237,7 @@ function normalizeProjectSection(project) {
   assertPlainObject(project, "project");
   const type = assertString(project.type, "project.type");
   if (!SUPPORTED_PROJECT_TYPES.has(type)) {
-    throw new Error("project.type must be one of package or web-surface");
+    throw new Error("project.type must be one of package, web-surface, or infra-contract");
   }
   const normalized = { type };
   for (const key of ["name", "site"]) {
@@ -222,6 +248,73 @@ function normalizeProjectSection(project) {
   return normalized;
 }
 
+function normalizeInfraSection(infra) {
+  assertPlainObject(infra, "infra");
+  const adapter = assertString(infra.adapter, "infra.adapter");
+  if (!SUPPORTED_INFRA_ADAPTERS.has(adapter)) {
+    throw new Error(
+      "infra.adapter must be one of manual-observed, aws-cloudformation, terraform, opentofu, pulumi, aws-cdk, aws-cli, or custom-command",
+    );
+  }
+  const adoptionMode = infra.adoption_mode === undefined
+    ? (adapter === "manual-observed" ? "manual-observed" : "validate-only")
+    : assertString(infra.adoption_mode, "infra.adoption_mode");
+  if (!SUPPORTED_INFRA_ADOPTION_MODES.has(adoptionMode)) {
+    throw new Error(
+      "infra.adoption_mode must be one of validate-only, plan-only, observe-only, manual-observed, import-planned, or managed-apply",
+    );
+  }
+  const applyMode = infra.apply === undefined
+    ? "disabled"
+    : assertString(infra.apply, "infra.apply");
+  if (!SUPPORTED_INFRA_APPLY_MODES.has(applyMode)) {
+    throw new Error("infra.apply must be one of disabled, manual-approval, or environment-approval");
+  }
+  const normalized = {
+    adapter,
+    adoptionMode,
+    applyMode,
+    environment: infra.environment === undefined ? "" : assertString(infra.environment, "infra.environment"),
+    identityRef: infra.identity_ref === undefined ? "" : assertString(infra.identity_ref, "infra.identity_ref"),
+    desired: normalizeStringArray(infra.desired, "infra.desired").map(posixPath),
+    contract: normalizeStringArray(infra.contract, "infra.contract").map(posixPath),
+    secretRefs: normalizeStringArray(infra.secret_refs, "infra.secret_refs"),
+  };
+  if (infra.commands !== undefined) {
+    normalized.commands = normalizeInfraCommands(infra.commands);
+  }
+  assertNoInlineSecretValues(infra, "infra", new Set(["secret_refs", "commands"]));
+  return normalized;
+}
+
+function normalizeInfraCommands(commands) {
+  assertPlainObject(commands, "infra.commands");
+  const normalized = {};
+  for (const stage of ["validate", "plan", "apply", "observe"]) {
+    if (commands[stage] !== undefined) {
+      normalized[stage] = assertString(commands[stage], `infra.commands.${stage}`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeConsumersSection(consumers) {
+  if (!Array.isArray(consumers)) {
+    throw new Error("consumers must be an array of tables");
+  }
+  return consumers.map((consumer, index) => normalizeConsumerConfig(consumer, index));
+}
+
+function normalizeConsumerConfig(consumer, index) {
+  assertPlainObject(consumer, `consumers[${index}]`);
+  return {
+    repo: assertString(consumer.repo, `consumers[${index}].repo`),
+    path: posixPath(assertString(consumer.path, `consumers[${index}].path`)),
+    source: posixPath(assertString(consumer.source, `consumers[${index}].source`)),
+    branch: consumer.branch === undefined ? "" : assertString(consumer.branch, `consumers[${index}].branch`),
+  };
+}
+
 function normalizeChannelsSection(channels) {
   assertPlainObject(channels, "channels");
   return Object.fromEntries(
@@ -531,6 +624,36 @@ function validateWebSurfaceConfig(config) {
   validateWebSurfaceSurfaces(config);
 }
 
+function validateInfraContractConfig(config) {
+  if (config.project?.type !== "infra-contract") {
+    return;
+  }
+  if (!config.infra) {
+    throw new Error('project.type = "infra-contract" requires [infra]');
+  }
+  if (config.infra.desired.length === 0) {
+    throw new Error('project.type = "infra-contract" requires infra.desired');
+  }
+  if (config.infra.contract.length === 0) {
+    throw new Error('project.type = "infra-contract" requires infra.contract');
+  }
+  if (!Array.isArray(config.consumers) || config.consumers.length === 0) {
+    throw new Error('project.type = "infra-contract" requires at least one [[consumers]] entry');
+  }
+  if (config.infra.applyMode !== "disabled" && config.infra.adoptionMode !== "managed-apply") {
+    throw new Error("infra.apply requires infra.adoption_mode = managed-apply");
+  }
+  if (config.infra.applyMode !== "disabled" && !config.infra.environment) {
+    throw new Error("infra.apply requires infra.environment");
+  }
+  if (config.infra.applyMode !== "disabled" && !config.infra.identityRef) {
+    throw new Error("infra.apply requires infra.identity_ref");
+  }
+  if (config.infra.adapter === "manual-observed" && config.infra.applyMode !== "disabled") {
+    throw new Error('infra.adapter = "manual-observed" requires infra.apply = "disabled"');
+  }
+}
+
 function validateWebSurfaceSurfaces(config) {
   const surfaces = config.surfaces || {};
   for (const [name, surface] of Object.entries(surfaces)) {
@@ -891,6 +1014,20 @@ export function validateBuildchainConfig(
           ]),
         )
       : undefined,
+    infra: loadedConfig.config.infra
+      ? {
+          adapter: loadedConfig.config.infra.adapter,
+          adoptionMode: loadedConfig.config.infra.adoptionMode,
+          applyMode: loadedConfig.config.infra.applyMode,
+          environment: loadedConfig.config.infra.environment,
+          identityRef: loadedConfig.config.infra.identityRef,
+          desired: loadedConfig.config.infra.desired,
+          contract: loadedConfig.config.infra.contract,
+          secretRefs: loadedConfig.config.infra.secretRefs,
+          commands: loadedConfig.config.infra.commands,
+        }
+      : undefined,
+    consumers: loadedConfig.config.consumers,
     surfaces: loadedConfig.config.surfaces
       ? Object.fromEntries(
           Object.entries(loadedConfig.config.surfaces).map(([name, surface]) => [

package/scripts/generate-site-bundle.mjs

@@ -52,6 +52,7 @@ function buildSiteBundle() {
     docEntry("release-flow", "Release flow", "docs/release-flow.md", "verify"),
     docEntry("versioning", "Versioning", "docs/versioning.md", "why"),
     docEntry("web-surface-deployments", "Web surface deployments", "docs/web-surface-deployments.md", "use"),
+    docEntry("infra-contract", "Infra Contract", "docs/infra-contract.md", "use"),
   ];
 
   const cliRegistry = {
@@ -61,16 +62,18 @@ function buildSiteBundle() {
     npmPackage: packageJson.name,
     commands: [
       { id: "version", usage: "buildchain version", purpose: "Print the package or embedded binary version." },
-      { id: "init", usage: "buildchain init [--type package|native|web-surface|anchored-package]", purpose: "Bootstrap a repository with Buildchain configuration and caller workflow files." },
+      { id: "init", usage: "buildchain init [--type package|native|web-surface|infra-contract|anchored-package]", purpose: "Bootstrap a repository with Buildchain configuration and caller workflow files." },
       { id: "validate", usage: "buildchain validate [--require-version-state]", purpose: "Validate buildchain.toml and declared lifecycle surfaces." },
       { id: "doctor", usage: "buildchain doctor [--json]", purpose: "Report local integration readiness." },
       { id: "lifecycle", usage: "buildchain lifecycle run <stage>", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
       { id: "release-dry-run", usage: "buildchain release --dry-run --target-ref <ref>", purpose: "Explain what a channel merge would publish before the PR is merged." },
       { id: "collect-github-release", usage: "buildchain collect github-release --tag <tag>", purpose: "Collect release assets into a release passport." },
       { id: "verify-release-passport", usage: "buildchain verify release-passport <file-or-url>", purpose: "Fail closed unless a release passport and its evidence are complete." },
+      { id: "verify-infra-contract-evidence-bundle", usage: "buildchain verify infra-contract-evidence-bundle <file>", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
       { id: "logging", usage: "buildchain log|mark|span|verify observability-log", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
       { id: "diagnostics-summary", usage: "buildchain diagnostics summary <diagnostics.json>...", purpose: "Summarize small diagnostics artifacts into JSON and a cross-platform lifecycle timing table." },
       { id: "npm-dry-run", usage: "buildchain npm dry-run --json", purpose: "Verify npm publish shape before a release transaction." },
+      { id: "infra-contract", usage: "buildchain infra-contract --mode validate|ci|plan|contract|propagation-plan|propagation-apply|apply|evidence-bundle", purpose: "Validate and publish provider-neutral infrastructure contract evidence with a mutation-free CI evidence chain, provider command plans, configured provider command execution, saved-plan apply gates, dry-run-first propagation, and lifecycle evidence bundles." },
     ],
   };
 
@@ -135,6 +138,11 @@ function buildSiteBundle() {
       "release-provenance.json",
       "agent-index.json",
     ],
+    infraContract: [
+      "infra-contract-plan.json",
+      "buildchain.infra-contract.json",
+      "infra-contract-propagation.json",
+    ],
   };
 
   const productMechanism = {