@kungfu-tech/buildchain 0.0.0-bootstrap.0 → 2.0.13-alpha.10

package/packages/core/buildchain-config.js

@@ -0,0 +1,721 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parse, stringify } from "smol-toml";
+
+const CONFIG_FILE = "buildchain.toml";
+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 WEB_SURFACE_CHANNELS = ["preview", "staging", "production"];
+const SUPPORTED_CHANNEL_VISIBILITY = new Set(["ephemeral", "protected", "public", "internal"]);
+const SUPPORTED_DEPLOY_ADAPTERS = new Set([
+  "aws-s3-cloudfront",
+  "aws-elastic-beanstalk",
+  "aws-ecs-service",
+]);
+
+function posixPath(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a table`);
+  }
+  return value;
+}
+
+function assertString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalBoolean(value, fallback) {
+  return value === undefined ? fallback : Boolean(value);
+}
+
+function normalizeStringArray(value, label) {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value.map((entry, index) => assertString(entry, `${label}[${index}]`));
+}
+
+function getByDottedKey(target, key) {
+  return String(key)
+    .split(".")
+    .reduce((current, segment) => current?.[segment], target);
+}
+
+function setByDottedKey(target, key, value) {
+  const segments = String(key).split(".");
+  let current = target;
+  for (const segment of segments.slice(0, -1)) {
+    if (!current[segment] || typeof current[segment] !== "object" || Array.isArray(current[segment])) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  current[segments[segments.length - 1]] = value;
+}
+
+export function loadBuildchainConfig(cwd = process.cwd()) {
+  const filePath = path.join(cwd, CONFIG_FILE);
+  if (!fs.existsSync(filePath)) {
+    return undefined;
+  }
+  const source = fs.readFileSync(filePath, "utf8");
+  let config;
+  try {
+    config = parse(source);
+  } catch (error) {
+    throw new Error(`${CONFIG_FILE} parse failed: ${error.message}`);
+  }
+  if (config.schema !== 1) {
+    throw new Error(`${CONFIG_FILE} schema must be 1`);
+  }
+  return {
+    path: CONFIG_FILE,
+    filePath,
+    config: normalizeBuildchainConfig(config),
+  };
+}
+
+export function normalizeBuildchainConfig(config) {
+  assertPlainObject(config, CONFIG_FILE);
+  const normalized = { ...config };
+  if (normalized.project !== undefined) {
+    normalized.project = normalizeProjectSection(normalized.project);
+  }
+  if (normalized.version !== undefined) {
+    normalized.version = normalizeVersionSection(normalized.version);
+  }
+  if (normalized.lifecycle !== undefined) {
+    normalized.lifecycle = normalizeLifecycleSection(normalized.lifecycle);
+  }
+  if (normalized.channels !== undefined) {
+    normalized.channels = normalizeChannelsSection(normalized.channels, normalized.project);
+  }
+  if (normalized.deploy !== undefined) {
+    normalized.deploy = normalizeDeploySection(normalized.deploy, normalized.project);
+  }
+  if (normalized.retention !== undefined) {
+    normalized.retention = normalizeRetentionSection(normalized.retention);
+  }
+  if (normalized.security !== undefined) {
+    normalized.security = normalizeSecuritySection(normalized.security);
+  }
+  validateWebSurfaceConfig(normalized);
+  return normalized;
+}
+
+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");
+  }
+  const normalized = { type };
+  for (const key of ["name", "site"]) {
+    if (project[key] !== undefined) {
+      normalized[key] = assertString(project[key], `project.${key}`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeChannelsSection(channels) {
+  assertPlainObject(channels, "channels");
+  return Object.fromEntries(
+    Object.entries(channels).map(([name, channel]) => [
+      name,
+      normalizeChannelConfig(name, channel),
+    ]),
+  );
+}
+
+function normalizeChannelConfig(name, channel) {
+  assertPlainObject(channel, `channels.${name}`);
+  const hasUrl = channel.url !== undefined;
+  const hasUrlPattern = channel.url_pattern !== undefined;
+  if (hasUrl && hasUrlPattern) {
+    throw new Error(`channels.${name} must define only one of url or url_pattern`);
+  }
+  if (!hasUrl && !hasUrlPattern) {
+    throw new Error(`channels.${name} must define url or url_pattern`);
+  }
+  const visibility = channel.visibility === undefined
+    ? defaultChannelVisibility(name)
+    : assertString(channel.visibility, `channels.${name}.visibility`);
+  if (!SUPPORTED_CHANNEL_VISIBILITY.has(visibility)) {
+    throw new Error(`channels.${name}.visibility must be one of ephemeral, protected, public, or internal`);
+  }
+  const normalized = {
+    name,
+    visibility,
+    requiresAuth: optionalBoolean(channel.requires_auth, name === "staging"),
+    noindex: optionalBoolean(channel.noindex, name !== "production"),
+    promotable: optionalBoolean(channel.promotable, name === "staging"),
+    canonical: optionalBoolean(channel.canonical, name === "production"),
+  };
+  if (hasUrl) {
+    normalized.url = assertString(channel.url, `channels.${name}.url`);
+  }
+  if (hasUrlPattern) {
+    normalized.urlPattern = assertString(channel.url_pattern, `channels.${name}.url_pattern`);
+  }
+  return normalized;
+}
+
+function defaultChannelVisibility(name) {
+  if (name === "preview") {
+    return "ephemeral";
+  }
+  if (name === "staging") {
+    return "protected";
+  }
+  if (name === "production") {
+    return "public";
+  }
+  return "internal";
+}
+
+function normalizeDeploySection(deploy) {
+  assertPlainObject(deploy, "deploy");
+  return Object.fromEntries(
+    Object.entries(deploy).map(([name, config]) => [
+      name,
+      normalizeDeployConfig(name, config),
+    ]),
+  );
+}
+
+function normalizeDeployConfig(name, config) {
+  assertPlainObject(config, `deploy.${name}`);
+  const adapter = assertString(config.adapter, `deploy.${name}.adapter`);
+  if (!SUPPORTED_DEPLOY_ADAPTERS.has(adapter)) {
+    throw new Error(`deploy.${name}.adapter must be one of aws-s3-cloudfront, aws-elastic-beanstalk, or aws-ecs-service`);
+  }
+  const normalized = {
+    ...config,
+    adapter,
+    artifactPath: config.artifact_path === undefined
+      ? undefined
+      : posixPath(assertString(config.artifact_path, `deploy.${name}.artifact_path`)),
+    secretRefs: normalizeStringArray(config.secret_refs, `deploy.${name}.secret_refs`),
+  };
+  delete normalized.artifact_path;
+  delete normalized.secret_refs;
+  for (const [key, value] of Object.entries(config)) {
+    if (key === "secret_refs" || key.endsWith("_ref") || key.endsWith("_refs")) {
+      continue;
+    }
+    if (/(secret|token|password)/i.test(key) && value !== undefined) {
+      throw new Error(`deploy.${name}.${key} must be declared as a secret reference, not a secret value`);
+    }
+  }
+  return normalized;
+}
+
+function normalizeRetentionSection(retention) {
+  assertPlainObject(retention, "retention");
+  return Object.fromEntries(
+    Object.entries(retention).map(([name, config]) => [
+      name,
+      normalizeRetentionConfig(name, config),
+    ]),
+  );
+}
+
+function normalizeRetentionConfig(name, config) {
+  assertPlainObject(config, `retention.${name}`);
+  const normalized = {};
+  for (const [key, value] of Object.entries(config)) {
+    const numberValue = Number(value);
+    if (!Number.isInteger(numberValue) || numberValue < 0) {
+      throw new Error(`retention.${name}.${key} must be a non-negative integer`);
+    }
+    normalized[key] = numberValue;
+  }
+  return normalized;
+}
+
+function normalizeSecuritySection(security) {
+  assertPlainObject(security, "security");
+  return Object.fromEntries(
+    Object.entries(security).map(([name, config]) => [
+      name,
+      normalizeSecurityConfig(name, config),
+    ]),
+  );
+}
+
+function normalizeSecurityConfig(name, config) {
+  assertPlainObject(config, `security.${name}`);
+  return {
+    requiresAuth: optionalBoolean(config.requires_auth, undefined),
+    noindex: optionalBoolean(config.noindex, undefined),
+    isolatedProviders: optionalBoolean(config.isolated_providers, undefined),
+    sandboxData: optionalBoolean(config.sandbox_data, undefined),
+    secretRefs: normalizeStringArray(config.secret_refs, `security.${name}.secret_refs`),
+  };
+}
+
+function validateWebSurfaceConfig(config) {
+  if (config.project?.type !== "web-surface") {
+    return;
+  }
+  for (const name of WEB_SURFACE_CHANNELS) {
+    if (!config.channels?.[name]) {
+      throw new Error(`project.type = "web-surface" requires channels.${name}`);
+    }
+    if (!config.deploy?.[name]) {
+      throw new Error(`project.type = "web-surface" requires deploy.${name}`);
+    }
+  }
+  if (!config.channels.preview.urlPattern) {
+    throw new Error("channels.preview.url_pattern is required for web-surface preview aliases");
+  }
+  for (const name of ["staging", "production"]) {
+    if (!config.channels[name].url) {
+      throw new Error(`channels.${name}.url is required for web-surface`);
+    }
+  }
+  if (!config.channels.staging.requiresAuth) {
+    throw new Error("channels.staging.requires_auth must be true for web-surface");
+  }
+  if (!config.channels.staging.noindex) {
+    throw new Error("channels.staging.noindex must be true for web-surface");
+  }
+  const stagingSecurity = config.security?.staging;
+  if (stagingSecurity) {
+    if (stagingSecurity.requiresAuth === false) {
+      throw new Error("security.staging.requires_auth must not disable staging auth");
+    }
+    if (stagingSecurity.noindex === false) {
+      throw new Error("security.staging.noindex must not disable staging noindex");
+    }
+    if (stagingSecurity.isolatedProviders === false) {
+      throw new Error("security.staging.isolated_providers must not be false for web-surface");
+    }
+  }
+}
+
+function normalizeVersionSection(version) {
+  assertPlainObject(version, "version");
+  const files = version.files === undefined ? [] : version.files;
+  if (!Array.isArray(files)) {
+    throw new Error("version.files must be an array of tables");
+  }
+  const strategy = version.strategy === undefined
+    ? "semver"
+    : assertString(version.strategy, "version.strategy");
+  if (!SUPPORTED_VERSION_STRATEGIES.has(strategy)) {
+    throw new Error("version.strategy must be one of semver or anchored");
+  }
+  const next = version.next === undefined
+    ? "auto"
+    : assertString(version.next, "version.next");
+  if (!SUPPORTED_VERSION_NEXT.has(next)) {
+    throw new Error("version.next must be one of auto or manual");
+  }
+  if (strategy === "semver" && next !== "auto") {
+    throw new Error('version.next = "manual" requires version.strategy = "anchored"');
+  }
+  if (strategy === "anchored" && next !== "manual") {
+    throw new Error('version.strategy = "anchored" requires version.next = "manual"');
+  }
+  return {
+    required: version.required === undefined ? false : Boolean(version.required),
+    strategy,
+    next,
+    manifest: version.manifest === undefined
+      ? undefined
+      : posixPath(assertString(version.manifest, "version.manifest")),
+    files: files.map((file, index) => normalizeVersionFile(file, index)),
+  };
+}
+
+function normalizeVersionFile(file, index) {
+  assertPlainObject(file, `version.files[${index}]`);
+  const type = assertString(file.type, `version.files[${index}].type`);
+  if (!SUPPORTED_VERSION_FILE_TYPES.has(type)) {
+    throw new Error(`version.files[${index}].type must be one of json, toml, or regex`);
+  }
+  const normalized = {
+    type,
+    path: posixPath(assertString(file.path, `version.files[${index}].path`)),
+  };
+  if (type === "json" || type === "toml") {
+    normalized.key = assertString(file.key, `version.files[${index}].key`);
+  }
+  if (type === "regex") {
+    normalized.pattern = assertString(file.pattern, `version.files[${index}].pattern`);
+    normalized.replacement = assertString(file.replacement, `version.files[${index}].replacement`);
+  }
+  return normalized;
+}
+
+function normalizeLifecycleSection(lifecycle) {
+  assertPlainObject(lifecycle, "lifecycle");
+  const normalized = {};
+  if (lifecycle.shell !== undefined) {
+    normalized.shell = assertString(lifecycle.shell, "lifecycle.shell");
+  }
+  if (lifecycle.env !== undefined) {
+    normalized.env = normalizeEnv(lifecycle.env, "lifecycle.env");
+  }
+  for (const [name, value] of Object.entries(lifecycle)) {
+    if (RESERVED_LIFECYCLE_KEYS.has(name)) {
+      continue;
+    }
+    normalized[name] = normalizeLifecycleStage(value, `lifecycle.${name}`, normalized);
+  }
+  return normalized;
+}
+
+function normalizeEnv(env, label) {
+  assertPlainObject(env, label);
+  return Object.fromEntries(
+    Object.entries(env).map(([key, value]) => [key, String(value)]),
+  );
+}
+
+export function normalizeLifecycleStage(stage, label = "lifecycle stage", lifecycle = {}) {
+  assertPlainObject(stage, label);
+  const hasCommand = stage.command !== undefined;
+  const hasCommands = stage.commands !== undefined;
+  const hasScript = stage.script !== undefined;
+  const modeCount = [hasCommand, hasCommands, hasScript].filter(Boolean).length;
+  if (modeCount !== 1) {
+    throw new Error(`${label} must define exactly one of command, commands, or script`);
+  }
+  const normalized = {
+    shell: stage.shell === undefined ? lifecycle.shell : assertString(stage.shell, `${label}.shell`),
+    env: stage.env === undefined ? undefined : normalizeEnv(stage.env, `${label}.env`),
+    timeoutMinutes: stage.timeout_minutes === undefined ? undefined : Number(stage.timeout_minutes),
+    retries: stage.retries === undefined ? 1 : Number(stage.retries),
+  };
+  if (normalized.timeoutMinutes !== undefined && (!Number.isFinite(normalized.timeoutMinutes) || normalized.timeoutMinutes <= 0)) {
+    throw new Error(`${label}.timeout_minutes must be a positive number`);
+  }
+  if (!Number.isInteger(normalized.retries) || normalized.retries < 1) {
+    throw new Error(`${label}.retries must be a positive integer`);
+  }
+  if (hasCommand) {
+    normalized.commands = [assertString(stage.command, `${label}.command`)];
+    normalized.mode = "command";
+  } else if (hasCommands) {
+    if (!Array.isArray(stage.commands) || stage.commands.length === 0) {
+      throw new Error(`${label}.commands must be a non-empty array`);
+    }
+    normalized.commands = stage.commands.map((command, index) =>
+      assertString(command, `${label}.commands[${index}]`),
+    );
+    normalized.mode = "commands";
+  } else {
+    normalized.script = assertString(stage.script, `${label}.script`);
+    normalized.mode = "script";
+  }
+  return normalized;
+}
+
+export function getLifecycleStage(loadedConfig, name) {
+  return loadedConfig?.config?.lifecycle?.[name];
+}
+
+export function runLifecycleStage({ cwd = process.cwd(), loadedConfig, name, stage, env: extraEnv }) {
+  const lifecycle = loadedConfig?.config?.lifecycle || {};
+  const selected = stage || getLifecycleStage(loadedConfig, name);
+  if (!selected) {
+    return false;
+  }
+  const env = {
+    ...process.env,
+    ...(lifecycle.env || {}),
+    ...(selected.env || {}),
+    ...(extraEnv || {}),
+  };
+  const timeout = selected.timeoutMinutes ? selected.timeoutMinutes * 60_000 : undefined;
+  const execOptions = {
+    cwd,
+    env,
+    stdio: "inherit",
+    shell: selected.shell || true,
+    timeout,
+  };
+  const runOnce = () => {
+    if (selected.mode === "script") {
+      execSync(selected.script, execOptions);
+      return;
+    }
+    for (const command of selected.commands) {
+      execSync(command, execOptions);
+    }
+  };
+  let lastError;
+  for (let attempt = 1; attempt <= selected.retries; attempt += 1) {
+    try {
+      runOnce();
+      return true;
+    } catch (error) {
+      lastError = error;
+      if (attempt < selected.retries) {
+        console.log(`> lifecycle ${name || "stage"} failed, retry ${attempt + 1}/${selected.retries}`);
+      }
+    }
+  }
+  throw lastError;
+}
+
+export function discoverConfiguredVersionStateFiles(cwd = process.cwd(), loadedConfig = loadBuildchainConfig(cwd)) {
+  const configured = loadedConfig?.config?.version?.files || [];
+  const files = configured.map((entry) => {
+    const filePath = path.join(cwd, entry.path);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Configured version file does not exist: ${entry.path}`);
+    }
+    const source = fs.readFileSync(filePath, "utf8");
+    const file = { ...entry, source };
+    if (entry.type === "json") {
+      const content = JSON.parse(source);
+      if (typeof getByDottedKey(content, entry.key) !== "string") {
+        throw new Error(`Configured JSON version key is missing or not a string: ${entry.path}:${entry.key}`);
+      }
+      return { ...file, content };
+    }
+    if (entry.type === "toml") {
+      const content = parse(source);
+      if (typeof getByDottedKey(content, entry.key) !== "string") {
+        throw new Error(`Configured TOML version key is missing or not a string: ${entry.path}:${entry.key}`);
+      }
+      return { ...file, content };
+    }
+    const pattern = new RegExp(entry.pattern, "m");
+    const match = source.match(pattern);
+    if (!match) {
+      throw new Error(`Configured regex version pattern did not match: ${entry.path}`);
+    }
+    if (typeof match.groups?.version !== "string") {
+      throw new Error(`Configured regex version pattern must define a named capture group called version: ${entry.path}`);
+    }
+    return { ...file, pattern };
+  });
+  if (loadedConfig?.config?.version?.required && files.length === 0) {
+    throw new Error("version.required is true but no version.files are configured");
+  }
+  return files;
+}
+
+function summarizeManifestFields(content) {
+  assertPlainObject(content, "version.manifest content");
+  return Object.fromEntries(
+    Object.entries(content).map(([key, value]) => {
+      if (value === null || ["string", "number", "boolean"].includes(typeof value)) {
+        return [key, value];
+      }
+      return [key, JSON.stringify(value)];
+    }),
+  );
+}
+
+export function getVersionStrategy(loadedConfig) {
+  const version = loadedConfig?.config?.version;
+  return {
+    strategy: version?.strategy || "semver",
+    next: version?.next || "auto",
+    manifest: version?.manifest,
+  };
+}
+
+export function loadConfiguredAnchorManifest(cwd = process.cwd(), loadedConfig = loadBuildchainConfig(cwd)) {
+  const manifest = loadedConfig?.config?.version?.manifest;
+  if (!manifest) {
+    return undefined;
+  }
+  const filePath = path.join(cwd, manifest);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Configured anchor manifest does not exist: ${manifest}`);
+  }
+  const source = fs.readFileSync(filePath, "utf8");
+  let content;
+  if (manifest.endsWith(".json")) {
+    content = JSON.parse(source);
+  } else if (manifest.endsWith(".toml")) {
+    content = parse(source);
+  } else {
+    throw new Error("version.manifest must point to a .json or .toml file");
+  }
+  return {
+    path: manifest,
+    filePath,
+    fields: summarizeManifestFields(content),
+  };
+}
+
+function configuredLifecycleStages(loadedConfig) {
+  const lifecycle = loadedConfig?.config?.lifecycle || {};
+  return Object.entries(lifecycle)
+    .filter(([, stage]) => stage && typeof stage === "object" && typeof stage.mode === "string")
+    .map(([name, stage]) => ({
+      name,
+      mode: stage.mode,
+      timeoutMinutes: stage.timeoutMinutes,
+      retries: stage.retries,
+      commandCount: stage.mode === "script" ? 1 : stage.commands.length,
+    }));
+}
+
+export function validateBuildchainConfig(
+  cwd = process.cwd(),
+  {
+    requireConfig = true,
+    requireVersionState = false,
+    requireLifecycleStages = [],
+  } = {},
+) {
+  const loadedConfig = loadBuildchainConfig(cwd);
+  if (!loadedConfig) {
+    if (requireConfig) {
+      throw new Error(`${CONFIG_FILE} is required`);
+    }
+    return {
+      config: undefined,
+      versionFiles: [],
+      lifecycleStages: [],
+    };
+  }
+
+  const versionFiles = loadedConfig.config.version
+    ? discoverConfiguredVersionStateFiles(cwd, loadedConfig)
+    : [];
+  const anchorManifest = loadConfiguredAnchorManifest(cwd, loadedConfig);
+  if (requireVersionState && versionFiles.length === 0) {
+    throw new Error("version state is required but no version.files are configured");
+  }
+
+  const lifecycleStages = configuredLifecycleStages(loadedConfig);
+  const stageNames = new Set(lifecycleStages.map((stage) => stage.name));
+  const missingStages = requireLifecycleStages.filter((stage) => !stageNames.has(stage));
+  if (missingStages.length > 0) {
+    throw new Error(`required lifecycle stage missing: ${missingStages.join(", ")}`);
+  }
+
+  return {
+    config: {
+      path: loadedConfig.path,
+      filePath: loadedConfig.filePath,
+      schema: loadedConfig.config.schema,
+    },
+    project: loadedConfig.config.project,
+    channels: loadedConfig.config.channels
+      ? Object.fromEntries(
+          Object.entries(loadedConfig.config.channels).map(([name, channel]) => [
+            name,
+            {
+              visibility: channel.visibility,
+              requiresAuth: channel.requiresAuth,
+              noindex: channel.noindex,
+              promotable: channel.promotable,
+              canonical: channel.canonical,
+              url: channel.url,
+              urlPattern: channel.urlPattern,
+            },
+          ]),
+        )
+      : undefined,
+    deploy: loadedConfig.config.deploy
+      ? Object.fromEntries(
+          Object.entries(loadedConfig.config.deploy).map(([name, deploy]) => [
+            name,
+            {
+              adapter: deploy.adapter,
+              artifactPath: deploy.artifactPath,
+              secretRefs: deploy.secretRefs,
+            },
+          ]),
+        )
+      : undefined,
+    retention: loadedConfig.config.retention,
+    security: loadedConfig.config.security,
+    version: loadedConfig.config.version
+      ? getVersionStrategy(loadedConfig)
+      : undefined,
+    anchorManifest: anchorManifest
+      ? {
+          path: anchorManifest.path,
+          fields: anchorManifest.fields,
+        }
+      : undefined,
+    versionFiles: versionFiles.map((file) => ({
+      path: file.path,
+      type: file.type,
+      key: file.key,
+      pattern: file.pattern?.source,
+    })),
+    lifecycleStages,
+  };
+}
+
+export function updateConfiguredVersionStateContents(files, version) {
+  return files
+    .map((file) => {
+      let content;
+      if (file.type === "json") {
+        const next = structuredClone(file.content);
+        setByDottedKey(next, file.key, version);
+        content = `${JSON.stringify(next, null, 2)}\n`;
+      } else if (file.type === "toml") {
+        const next = structuredClone(file.content);
+        setByDottedKey(next, file.key, version);
+        content = stringify(next);
+      } else if (file.type === "regex") {
+        content = file.source.replace(file.pattern, (...args) => {
+          const groups = args.at(-1) || {};
+          const current = groups.version;
+          if (typeof current !== "string") {
+            throw new Error(`Configured regex version pattern must define a named capture group called version: ${file.path}`);
+          }
+          return args[0].replace(current, file.replacement.replaceAll("${version}", version));
+        });
+      } else {
+        throw new Error(`Unsupported configured version file type: ${file.type}`);
+      }
+      return {
+        path: file.path,
+        kind: file.type,
+        changed: content !== file.source,
+        content,
+      };
+    })
+    .filter((file) => file.changed);
+}
+
+export function writeLifecycleScriptFixture(cwd, name, script) {
+  const filePath = path.join(cwd, `${name}-${Date.now()}.sh`);
+  fs.writeFileSync(filePath, script.replace(/\$\{TMPDIR\}/g, os.tmpdir()));
+  return filePath;
+}
+
+export default {
+  discoverConfiguredVersionStateFiles,
+  getVersionStrategy,
+  getLifecycleStage,
+  loadConfiguredAnchorManifest,
+  loadBuildchainConfig,
+  normalizeBuildchainConfig,
+  normalizeLifecycleStage,
+  runLifecycleStage,
+  updateConfiguredVersionStateContents,
+  validateBuildchainConfig,
+  writeLifecycleScriptFixture,
+};