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

package/scripts/run-lifecycle-core.mjs

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  loadBuildchainConfig,
+  normalizeLifecycleStage,
+  runLifecycleStage,
+} from "../packages/core/buildchain-config.js";
+import {
+  createArtifactSummary,
+  parseExpectedArtifactsJson,
+  validateExpectedArtifacts,
+} from "./build-contract-core.mjs";
+
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+function toPosix(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function listFiles(root, rel) {
+  const target = path.isAbsolute(rel) ? rel : path.join(root, rel);
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const stat = fs.statSync(target);
+  if (stat.isFile()) {
+    return [target];
+  }
+  return fs
+    .readdirSync(target, { withFileTypes: true })
+    .flatMap((entry) => listFiles(root, path.join(target, entry.name)));
+}
+
+function manifestPathFor(root, filePath) {
+  const relative = path.relative(root, filePath);
+  if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return toPosix(relative);
+  }
+  return toPosix(path.resolve(filePath));
+}
+
+function collectArtifactFiles(root, patterns) {
+  const files = new Set();
+  for (const pattern of patterns) {
+    const clean = pattern.replace(/\\/g, "/").replace(/\/\*\*\/?\*?$/, "");
+    for (const file of listFiles(root, clean)) {
+      files.add(path.resolve(file));
+    }
+  }
+  return [...files].sort();
+}
+
+export function runLifecycle({
+  cwd = process.cwd(),
+  stageName = "",
+  command = "",
+  required = false,
+  manifestPath = ".buildchain/artifacts/manifest.json",
+  summaryPath = ".buildchain/artifacts/summary.json",
+  artifactName = "buildchain-artifact",
+  platformId = os.platform(),
+  platformName = platformId,
+  artifactPaths = [],
+  expectedArtifactsJson = "",
+  workspace = process.cwd(),
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedWorkspace = path.resolve(workspace);
+  const resolvedManifestPath = path.resolve(resolvedWorkspace, manifestPath);
+  const resolvedSummaryPath = path.resolve(resolvedWorkspace, summaryPath);
+  const loadedConfig = loadBuildchainConfig(resolvedCwd);
+  let commandSource = "none";
+  let executed = false;
+
+  if (command.trim()) {
+    commandSource = "workflow-input";
+    execSync(command, {
+      cwd: resolvedCwd,
+      env: process.env,
+      shell: true,
+      stdio: "inherit",
+    });
+    executed = true;
+  } else if (stageName) {
+    commandSource = "buildchain.toml";
+    executed = runLifecycleStage({
+      cwd: resolvedCwd,
+      loadedConfig,
+      name: stageName,
+    });
+  }
+
+  if (required && !executed) {
+    throw new Error(`required lifecycle stage did not run: ${stageName || "command"}`);
+  }
+
+  fs.mkdirSync(path.dirname(resolvedManifestPath), { recursive: true });
+  const files = collectArtifactFiles(resolvedWorkspace, artifactPaths);
+  const manifestFiles = files.map((file) => {
+    const stat = fs.statSync(file);
+    return {
+      path: manifestPathFor(resolvedWorkspace, file),
+      size: stat.size,
+      sha256: sha256File(file),
+    };
+  });
+  const platform = {
+    id: platformId,
+    name: platformName,
+    os: process.env.RUNNER_OS || os.platform(),
+    arch: process.env.RUNNER_ARCH || os.arch(),
+  };
+  const summary = createArtifactSummary({
+    artifactName,
+    platform,
+    files: manifestFiles,
+  });
+  const expected = parseExpectedArtifactsJson(expectedArtifactsJson);
+  const expectedArtifacts = validateExpectedArtifacts({
+    expected,
+    files: manifestFiles,
+    summary,
+  });
+  const manifest = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-artifact",
+    artifactName,
+    platform,
+    git: {
+      repository: process.env.GITHUB_REPOSITORY || "",
+      sha: process.env.BUILDCHAIN_SOURCE_SHA || process.env.GITHUB_SHA || "",
+      ref: process.env.BUILDCHAIN_SOURCE_REF || process.env.GITHUB_REF || "",
+      runId: process.env.GITHUB_RUN_ID || "",
+      runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",
+    },
+    lifecycle: {
+      stage: stageName,
+      commandSource,
+      executed,
+    },
+    summary,
+    expectedArtifacts,
+    files: manifestFiles,
+  };
+
+  fs.writeFileSync(resolvedManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  fs.mkdirSync(path.dirname(resolvedSummaryPath), { recursive: true });
+  fs.writeFileSync(resolvedSummaryPath, `${JSON.stringify(summary, null, 2)}\n`);
+  console.log(`buildchain_manifest=${path.relative(resolvedWorkspace, resolvedManifestPath)}`);
+  return manifest;
+}
+
+export function normalizeCommandStage(commandText) {
+  return normalizeLifecycleStage({ command: commandText }, "workflow command");
+}

package/scripts/run-lifecycle.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import os from "node:os";
+import { pathToFileURL } from "node:url";
+import { runLifecycle } from "./run-lifecycle-core.mjs";
+
+function readArg(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return process.argv[index + 1] || "";
+}
+
+function parseList(value) {
+  return String(value || "")
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function runLifecycleCli() {
+  return runLifecycle({
+    cwd: readArg("cwd", process.cwd()),
+    stageName: readArg("stage"),
+    command: process.env.BUILDCHAIN_COMMAND || "",
+    required: readArg("required", "false") === "true",
+    manifestPath: readArg("manifest-path", ".buildchain/artifacts/manifest.json"),
+    summaryPath: readArg("summary-path", ".buildchain/artifacts/summary.json"),
+    artifactName: readArg("artifact-name", "buildchain-artifact"),
+    platformId: readArg("platform-id", os.platform()),
+    platformName: readArg("platform-name", readArg("platform-id", os.platform())),
+    artifactPaths: parseList(process.env.BUILDCHAIN_ARTIFACT_PATHS || ""),
+    expectedArtifactsJson: process.env.BUILDCHAIN_EXPECTED_ARTIFACTS_JSON || "",
+    workspace: process.cwd(),
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runLifecycleCli();
+}

package/scripts/strip-trailing-whitespace.mjs

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+
+const files = process.argv.slice(2);
+if (files.length === 0) {
+  throw new Error("usage: node scripts/strip-trailing-whitespace.mjs <file> [...]");
+}
+
+for (const file of files) {
+  const content = fs.readFileSync(file, "utf8");
+  const normalized = content.replace(/[ \t]+$/gm, "");
+  if (normalized !== content) {
+    fs.writeFileSync(file, normalized);
+  }
+}

package/scripts/tsup-action.config.mjs

@@ -0,0 +1,19 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  target: "node24",
+  platform: "node",
+  banner: {
+    js: "import { createRequire as __buildchainCreateRequire } from 'node:module';\nconst require = __buildchainCreateRequire(import.meta.url);",
+  },
+  splitting: false,
+  sourcemap: false,
+  minify: true,
+  clean: true,
+  outDir: "dist",
+  skipNodeModulesBundle: false,
+  noExternal: [/.*/],
+  esbuildOptions(options) {
+    options.legalComments = "none";
+  },
+});

package/scripts/verify-publish-source-lock.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { parsePublishSourceRef, verifyPublishSourceLock } from "./build-contract-core.mjs";
+import { normalizeSourceRef, resolvePublishSourceRefSha } from "./publish-source-ref-resolver.mjs";
+
+function readEnv(env, name, fallback = "") {
+  return env[name] || fallback;
+}
+
+export async function verifyPublishSourceLockCli({
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const sourceRef = normalizeSourceRef(readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_REF"));
+  const parsed = parsePublishSourceRef(sourceRef);
+  if (!parsed.enabled) {
+    return { ok: true, sourceRef, skipped: true };
+  }
+  const repository = readEnv(env, "BUILDCHAIN_SOURCE_REPOSITORY", readEnv(env, "GITHUB_REPOSITORY"));
+  const currentSha = readEnv(env, "BUILDCHAIN_CURRENT_SOURCE_SHA")
+    || await resolvePublishSourceRefSha({ repository, sourceRef: parsed.sourceRef, env, fetchImpl });
+  return verifyPublishSourceLock({
+    sourceRef: parsed.sourceRef,
+    expectedSha: readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_SHA"),
+    currentSha,
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await verifyPublishSourceLockCli();
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/verify-release-pr.mjs

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import os from "node:os";
+import { getBumpKeyword, normalizeRef, readCurrentVersion } from "./release-line-policy.mjs";
+
+function readEnv(name, fallback = "") {
+  return String(process.env[name] || fallback).trim();
+}
+
+function writeOutput(name, value) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) {
+    console.log(`${name}=${value}`);
+    return;
+  }
+  fs.appendFileSync(outputPath, `${name}=${value}${os.EOL}`);
+}
+
+const cwd = readEnv("BUILDCHAIN_SOURCE_CWD", process.cwd());
+const headRef = readEnv("BUILDCHAIN_HEAD_REF", process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME);
+const baseRef = readEnv("BUILDCHAIN_BASE_REF", process.env.GITHUB_BASE_REF || process.env.GITHUB_REF_NAME);
+
+if (!headRef || !baseRef) {
+  throw new Error("BUILDCHAIN_HEAD_REF/GITHUB_HEAD_REF and BUILDCHAIN_BASE_REF/GITHUB_BASE_REF are required");
+}
+
+const keyword = getBumpKeyword({ cwd, headRef, baseRef });
+const version = readCurrentVersion(cwd);
+
+writeOutput("keyword", keyword);
+writeOutput("version", version.version);
+writeOutput("head-ref", normalizeRef(headRef));
+writeOutput("base-ref", normalizeRef(baseRef));
+
+console.log(`release PR verified: ${normalizeRef(headRef)} -> ${normalizeRef(baseRef)} (${keyword}, ${version.version})`);

package/scripts/web-surface-core.mjs

@@ -0,0 +1,382 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { loadBuildchainConfig, validateBuildchainConfig } from "../packages/core/buildchain-config.js";
+
+const DEFAULT_RETENTION = Object.freeze({
+  preview: {
+    pr_days: 14,
+    sha_days: 90,
+  },
+  staging: {
+    days: 90,
+    keep_deploys: 10,
+  },
+  production: {
+    days: 365,
+  },
+});
+
+function assertWebSurfaceConfig(loadedConfig) {
+  if (loadedConfig?.config?.project?.type !== "web-surface") {
+    throw new Error('buildchain.toml project.type must be "web-surface"');
+  }
+  return loadedConfig.config;
+}
+
+function assertSha(value, label) {
+  const sha = String(value || "").trim();
+  if (!/^[0-9a-f]{40}$/i.test(sha)) {
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  }
+  return sha.toLowerCase();
+}
+
+function assertHash(value, label) {
+  const hash = String(value || "").trim();
+  if (!/^[0-9a-f]{64}$/i.test(hash)) {
+    throw new Error(`${label} must be a 64-character SHA-256 hash`);
+  }
+  return hash.toLowerCase();
+}
+
+function toPosix(value) {
+  return String(value || "").split(path.sep).join("/");
+}
+
+function listFiles(root, rel) {
+  const target = path.isAbsolute(rel) ? rel : path.join(root, rel);
+  if (!fs.existsSync(target)) {
+    throw new Error(`artifact path does not exist: ${rel}`);
+  }
+  const stat = fs.statSync(target);
+  if (stat.isFile()) {
+    return [target];
+  }
+  return fs
+    .readdirSync(target, { withFileTypes: true })
+    .flatMap((entry) => listFiles(root, path.join(target, entry.name)));
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+function addDays(iso, days) {
+  if (days === undefined || days === null) {
+    return "";
+  }
+  const date = new Date(iso);
+  date.setUTCDate(date.getUTCDate() + Number(days));
+  return date.toISOString();
+}
+
+function retentionConfig(config, channel) {
+  return {
+    ...(DEFAULT_RETENTION[channel] || {}),
+    ...(config.retention?.[channel] || {}),
+  };
+}
+
+function classifyPreviewAlias(alias) {
+  if (/^pr-\d+$/.test(alias)) {
+    return {
+      kind: "pr",
+      mutable: true,
+      retentionClass: "preview-pr-ephemeral",
+      retentionKey: "pr_days",
+    };
+  }
+  if (/^sha-[0-9a-f]{6,40}$/i.test(alias)) {
+    return {
+      kind: "sha",
+      mutable: false,
+      retentionClass: "preview-sha-immutable",
+      retentionKey: "sha_days",
+    };
+  }
+  return {
+    kind: "custom",
+    mutable: true,
+    retentionClass: "preview-custom-ephemeral",
+    retentionKey: "pr_days",
+  };
+}
+
+function resolveChannelUrl(channel, alias) {
+  if (channel.urlPattern) {
+    if (!alias) {
+      throw new Error(`channel ${channel.name} requires alias for url_pattern`);
+    }
+    return channel.urlPattern.replaceAll("{alias}", alias);
+  }
+  return channel.url;
+}
+
+function retentionFor({ config, channelName, alias, deployedAt }) {
+  if (channelName === "preview") {
+    const classified = classifyPreviewAlias(alias);
+    const days = retentionConfig(config, "preview")[classified.retentionKey];
+    return {
+      aliasKind: classified.kind,
+      mutableAlias: classified.mutable,
+      retentionClass: classified.retentionClass,
+      expiresAt: addDays(deployedAt, days),
+      retentionDays: days,
+    };
+  }
+  if (channelName === "staging") {
+    const retention = retentionConfig(config, "staging");
+    return {
+      aliasKind: "",
+      mutableAlias: true,
+      retentionClass: "staging-protected",
+      expiresAt: addDays(deployedAt, retention.days),
+      retentionDays: retention.days,
+      keepDeploys: retention.keep_deploys,
+    };
+  }
+  const retention = retentionConfig(config, "production");
+  return {
+    aliasKind: "",
+    mutableAlias: false,
+    retentionClass: "production-canonical",
+    expiresAt: addDays(deployedAt, retention.days),
+    retentionDays: retention.days,
+  };
+}
+
+export function validateWebSurfaceProject(cwd = process.cwd()) {
+  const summary = validateBuildchainConfig(cwd, {
+    requireConfig: true,
+  });
+  if (summary.project?.type !== "web-surface") {
+    throw new Error('buildchain.toml project.type must be "web-surface"');
+  }
+  return summary;
+}
+
+export function createWebSurfaceArtifactHash({ cwd = process.cwd(), artifactPath = "" } = {}) {
+  const root = path.resolve(cwd);
+  const files = listFiles(root, artifactPath || ".")
+    .sort()
+    .map((filePath) => {
+      const stat = fs.statSync(filePath);
+      const relative = toPosix(path.relative(root, filePath));
+      return {
+        path: relative,
+        size: stat.size,
+        sha256: sha256File(filePath),
+      };
+    });
+  const digest = crypto.createHash("sha256");
+  for (const file of files) {
+    digest.update(`${file.path}\0${file.size}\0${file.sha256}\n`);
+  }
+  return {
+    artifactHash: digest.digest("hex"),
+    files,
+  };
+}
+
+export function createWebSurfaceDeploymentManifest({
+  cwd = process.cwd(),
+  channel = "preview",
+  alias = "",
+  sourceSha = "",
+  artifactHash = "",
+  deployedAt = new Date().toISOString(),
+  deploymentId = "",
+  runtimeId = "",
+  configFingerprint = "",
+  healthCheck = "",
+  migrationState = "",
+  rollbackPointer = "",
+  rollbackLimitations = "",
+} = {}) {
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const channelConfig = config.channels?.[channel];
+  if (!channelConfig) {
+    throw new Error(`unknown web-surface channel: ${channel}`);
+  }
+  const deployConfig = config.deploy?.[channel];
+  if (!deployConfig) {
+    throw new Error(`missing deploy.${channel}`);
+  }
+  const retention = retentionFor({ config, channelName: channel, alias, deployedAt });
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-deployment",
+    site: config.project.site || config.project.name || "",
+    channel,
+    alias,
+    url: resolveChannelUrl(channelConfig, alias),
+    sourceSha: assertSha(sourceSha, "sourceSha"),
+    artifactHash: assertHash(artifactHash, "artifactHash"),
+    deployTarget: deployConfig.target || deployConfig.bucket || deployConfig.environment || deployConfig.service || "",
+    adapter: deployConfig.adapter,
+    deploymentId,
+    deployedAt,
+    retentionClass: retention.retentionClass,
+    expiresAt: retention.expiresAt,
+    mutableAlias: retention.mutableAlias,
+    runtimeId,
+    configFingerprint,
+    secretRefs: [
+      ...new Set([
+        ...(deployConfig.secretRefs || []),
+        ...(config.security?.[channel]?.secretRefs || []),
+      ]),
+    ],
+    healthCheck,
+    migrationState,
+    rollbackPointer,
+    rollbackLimitations,
+  };
+}
+
+export function planWebSurfaceDeploy({
+  cwd = process.cwd(),
+  channel = "preview",
+  alias = "",
+  sourceSha = "",
+  artifactHash = "",
+  artifactPath = "",
+  dryRun = true,
+  deployedAt = new Date().toISOString(),
+} = {}) {
+  if (!dryRun) {
+    throw new Error("web-surface deploy currently supports dry-run planning only");
+  }
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  const deployConfig = config.deploy?.[channel];
+  if (!deployConfig) {
+    throw new Error(`missing deploy.${channel}`);
+  }
+  const resolvedArtifact = artifactHash
+    ? { artifactHash: assertHash(artifactHash, "artifactHash"), files: [] }
+    : createWebSurfaceArtifactHash({
+        cwd,
+        artifactPath: artifactPath || deployConfig.artifactPath || ".",
+      });
+  const manifest = createWebSurfaceDeploymentManifest({
+    cwd,
+    channel,
+    alias,
+    sourceSha,
+    artifactHash: resolvedArtifact.artifactHash,
+    deployedAt,
+  });
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-deploy-plan",
+    dryRun: true,
+    adapter: deployConfig.adapter,
+    channel,
+    alias,
+    url: manifest.url,
+    artifact: {
+      path: artifactPath || deployConfig.artifactPath || ".",
+      hash: resolvedArtifact.artifactHash,
+      files: resolvedArtifact.files,
+    },
+    manifest,
+    steps: planAdapterSteps(deployConfig.adapter, deployConfig, manifest),
+  };
+}
+
+function planAdapterSteps(adapter, deployConfig, manifest) {
+  if (adapter === "aws-s3-cloudfront") {
+    return [
+      {
+        action: "sync-static-artifact",
+        target: deployConfig.bucket || deployConfig.target || "",
+        prefix: deployConfig.prefix || manifest.alias || manifest.channel,
+      },
+      {
+        action: "write-deployment-manifest",
+        target: deployConfig.manifest_prefix || ".buildchain/deployments",
+      },
+      {
+        action: "invalidate-cdn",
+        distribution: deployConfig.cloudfront_distribution || deployConfig.distribution || "",
+      },
+    ];
+  }
+  return [
+    {
+      action: "prepare-dynamic-environment",
+      target: manifest.deployTarget,
+    },
+    {
+      action: "write-deployment-manifest",
+      target: deployConfig.manifest_prefix || ".buildchain/deployments",
+    },
+  ];
+}
+
+export function planWebSurfaceCleanup({
+  cwd = process.cwd(),
+  aliases = [],
+  channel = "preview",
+  now = new Date().toISOString(),
+  dryRun = true,
+} = {}) {
+  if (!dryRun) {
+    throw new Error("web-surface cleanup currently supports dry-run planning only");
+  }
+  const loadedConfig = loadBuildchainConfig(cwd);
+  const config = assertWebSurfaceConfig(loadedConfig);
+  if (channel !== "preview") {
+    throw new Error("web-surface cleanup plan currently supports preview aliases only");
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-web-surface-cleanup-plan",
+    dryRun: true,
+    channel,
+    now,
+    entries: aliases.map((alias) => {
+      const classified = classifyPreviewAlias(alias);
+      const retention = retentionConfig(config, "preview");
+      return {
+        alias,
+        aliasKind: classified.kind,
+        mutableAlias: classified.mutable,
+        retentionClass: classified.retentionClass,
+        retentionDays: retention[classified.retentionKey],
+        action: "expire-preview-alias",
+      };
+    }),
+  };
+}
+
+export function defaultWebSurfaceAlias({ channel = "preview", sourceSha = "", pullNumber = "" } = {}) {
+  if (channel !== "preview") {
+    return "";
+  }
+  if (pullNumber) {
+    return `pr-${pullNumber}`;
+  }
+  const sha = assertSha(sourceSha, "sourceSha");
+  return `sha-${sha.slice(0, 12)}`;
+}
+
+export function localWebSurfaceContext() {
+  return {
+    sourceSha: process.env.BUILDCHAIN_SOURCE_SHA || process.env.GITHUB_SHA || "",
+    sourceRef: process.env.BUILDCHAIN_SOURCE_REF || process.env.GITHUB_REF || "",
+    repository: process.env.GITHUB_REPOSITORY || "",
+    runId: process.env.GITHUB_RUN_ID || "",
+    runAttempt: process.env.GITHUB_RUN_ATTEMPT || "",
+    runner: {
+      os: process.env.RUNNER_OS || os.platform(),
+      arch: process.env.RUNNER_ARCH || os.arch(),
+    },
+  };
+}