@kungfu-tech/buildchain 4.0.10-alpha.0 → 4.1.0-alpha.1

package/packages/core/release/commands/ensure-github-release.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+function classifyPublicationChannel(channel = "") {
+  const normalized = String(channel || "").trim().toLowerCase();
+  if (!normalized) return undefined;
+  if (normalized === "alpha") return true;
+  if (["release", "stable", "major"].includes(normalized)) return false;
+  throw new Error(`Unsupported GitHub Release publication channel: ${channel}`);
+}
+
+export function classifyReleaseTag(tag, { channel = "" } = {}) {
+  const normalized = String(tag || "").trim();
+  const match = normalized.match(/^v\d+\.\d+\.\d+(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?$/);
+  if (!match) {
+    throw new Error(`Unsupported semver release tag: ${tag}`);
+  }
+  const channelPrerelease = classifyPublicationChannel(channel);
+  const prerelease = channelPrerelease ?? normalized.includes("-");
+  return {
+    tag: normalized,
+    prerelease,
+    makeLatest: prerelease ? "false" : "true",
+  };
+}
+
+function parseArgs(argv) {
+  const args = {
+    apiUrl: process.env.GITHUB_API_URL || "https://api.github.com",
+    repository: process.env.GITHUB_REPOSITORY || "",
+    tag: "",
+    title: "",
+    notes: "",
+    target: "",
+    channel: "",
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const readValue = () => {
+      index += 1;
+      if (index >= argv.length) {
+        throw new Error(`${arg} requires a value`);
+      }
+      return argv[index];
+    };
+    if (arg === "--repository") args.repository = readValue();
+    else if (arg === "--tag") args.tag = readValue();
+    else if (arg === "--title") args.title = readValue();
+    else if (arg === "--notes") args.notes = readValue();
+    else if (arg === "--target") args.target = readValue();
+    else if (arg === "--channel") args.channel = readValue();
+    else if (arg === "--api-url") args.apiUrl = readValue();
+    else if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return args;
+}
+
+function usage() {
+  return [
+    "usage: node packages/core/release/commands/ensure-github-release.mjs --repository <owner/repo> --tag <tag> [--channel alpha|release]",
+    "",
+    "Ensures Buildchain GitHub Release metadata is deterministic:",
+    "- explicit alpha => prerelease=true, make_latest=false",
+    "- explicit release/stable/major => prerelease=false, make_latest=true",
+    "- without --channel, semver prerelease syntax remains the fallback",
+  ].join("\n");
+}
+
+function requireToken() {
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error("GH_TOKEN or GITHUB_TOKEN is required");
+  }
+  return token;
+}
+
+function splitRepository(repository) {
+  const match = String(repository || "").trim().match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error("--repository must be in owner/repo form");
+  }
+  return { owner: match[1], repo: match[2] };
+}
+
+async function githubRequest({ apiUrl, token, method = "GET", path, body }) {
+  const response = await fetch(`${apiUrl.replace(/\/$/, "")}${path}`, {
+    method,
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+      "x-github-api-version": "2022-11-28",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (response.status === 404) {
+    return { status: 404, data: undefined };
+  }
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : undefined;
+  if (!response.ok) {
+    throw new Error(
+      `GitHub API ${method} ${path} failed with ${response.status}: ${data?.message || text}`,
+    );
+  }
+  return { status: response.status, data };
+}
+
+export async function ensureGitHubRelease({
+  apiUrl = "https://api.github.com",
+  token,
+  repository,
+  tag,
+  title = "",
+  notes = "",
+  target = "",
+  channel = "",
+} = {}) {
+  const { owner, repo } = splitRepository(repository);
+  const metadata = classifyReleaseTag(tag, { channel });
+  const encodedTag = encodeURIComponent(metadata.tag);
+  const releasePath = `/repos/${owner}/${repo}/releases/tags/${encodedTag}`;
+  const refPath = `/repos/${owner}/${repo}/git/ref/tags/${encodedTag}`;
+  const existing = await githubRequest({ apiUrl, token, path: releasePath });
+  if (existing.status === 404) {
+    const tagRef = await githubRequest({ apiUrl, token, path: refPath });
+    if (tagRef.status === 404) {
+      throw new Error(`Git tag ${metadata.tag} does not exist in ${repository}`);
+    }
+    // Existing exact tags are authoritative; target_commitish is redundant and
+    // can require workflow mutation authority for workflow-changing commits.
+    const created = await githubRequest({
+      apiUrl,
+      token,
+      method: "POST",
+      path: `/repos/${owner}/${repo}/releases`,
+      body: {
+        tag_name: metadata.tag,
+        name: title || metadata.tag,
+        body: notes || `Buildchain release passport assets for ${metadata.tag}.`,
+        prerelease: metadata.prerelease,
+        make_latest: metadata.makeLatest,
+      },
+    });
+    return { action: "created", release: created.data, metadata };
+  }
+  if (metadata.prerelease === true && existing.data?.tag_name === metadata.tag && existing.data?.name === (title || metadata.tag) && existing.data?.body === (notes || `Buildchain release passport assets for ${metadata.tag}.`) && existing.data?.prerelease === true && existing.data?.draft !== true && (!target || existing.data?.target_commitish === target)) return { action: "existing", release: existing.data, metadata };
+  const patched = await githubRequest({
+    apiUrl,
+    token,
+    method: "PATCH",
+    path: `/repos/${owner}/${repo}/releases/${existing.data.id}`,
+    body: {
+      name: title || existing.data.name || metadata.tag,
+      prerelease: metadata.prerelease,
+      make_latest: metadata.makeLatest,
+    },
+  });
+  return { action: "updated", release: patched.data, metadata };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+  const result = await ensureGitHubRelease({
+    apiUrl: args.apiUrl,
+    token: requireToken(),
+    repository: args.repository,
+    tag: args.tag,
+    title: args.title,
+    notes: args.notes,
+    target: args.target,
+    channel: args.channel,
+  });
+  console.log(`github-release-${result.action}=${result.metadata.tag}`);
+  console.log(`github-release-prerelease=${result.metadata.prerelease}`);
+  console.log(`github-release-make-latest=${result.metadata.makeLatest}`);
+}
+
+function isCliEntrypoint() {
+  const entry = process.argv[1] || "";
+  return (
+    entry.replace(/\\/g, "/").endsWith("/ensure-github-release.mjs") &&
+    import.meta.url === pathToFileURL(entry).href
+  );
+}
+
+if (isCliEntrypoint()) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/packages/core/release/commands/next-development-review.mjs

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { REPOSITORY } from "../next-development/review-policy.js";
+import { verifyNextDevelopmentReview } from "../next-development/verification.js";
+import { approveNextDevelopment } from "../next-development/approval.js";
+import { enqueueVerifiedDevelopmentReview } from "../next-development/enqueue.js";
+import { verifyVersionStateDelta } from "../version-state/verification.js";
+import { readBinaryPublicationEvidence } from "../../publication/binary/evidence.js";
+import { releaseAssetClient } from "../../providers/github/release-assets.js";
+import { createGitHubCliApi } from "../../providers/github-cli-api.js";
+async function main(mode) {
+  const repository = process.env.GITHUB_REPOSITORY;
+  const runId = process.env.VERIFY_RUN_ID;
+  if (!/^\d+$/u.test(runId || "") || repository !== REPOSITORY)
+    throw new Error("exact repository and verification run required");
+  const client = createGitHubCliApi(undefined, { ...process.env, GH_TOKEN: process.env.GH_TOKEN });
+  const file = ".buildchain/next-development-review.json";
+  if (mode === "verify") {
+    if (process.env.BUILDCHAIN_APPROVAL_TOKEN)
+      throw new Error("verification must not receive the approval credential");
+    const git = (...args) =>
+      execFileSync("git", args, {
+        encoding: "utf8",
+        maxBuffer: 8 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim();
+    const plan = await verifyNextDevelopmentReview({
+      client,
+      repository,
+      runId,
+      git,
+      verifyDelta: verifyVersionStateDelta,
+      publication: (args) =>
+        readBinaryPublicationEvidence({
+          ...args,
+          client: releaseAssetClient(repository, { token: process.env.GH_TOKEN }),
+          attempts: 1,
+        }),
+    });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(plan, null, 2)}\n`);
+  } else if (mode === "approve") {
+    if (!process.env.BUILDCHAIN_APPROVAL_TOKEN)
+      throw new Error("independent approval credential missing");
+    const plan = JSON.parse(fs.readFileSync(file));
+    if (plan.repository !== repository || String(plan.runId) !== runId)
+      throw new Error("review plan is from another invocation");
+    const result = await approveNextDevelopment({
+      client,
+      plan,
+      reviewer: createGitHubCliApi(undefined, { ...process.env, GH_TOKEN: process.env.BUILDCHAIN_APPROVAL_TOKEN }),
+    });
+    fs.writeFileSync(file, `${JSON.stringify(result, null, 2)}\n`);
+    console.log(
+      JSON.stringify({ reviewId: result.reviewId, headSha: result.headSha }),
+    );
+  } else if (mode === "enqueue") {
+    const plan = JSON.parse(fs.readFileSync(file));
+    if (
+      plan.repository !== repository ||
+      String(plan.runId) !== runId ||
+      !plan.reviewId
+    )
+      throw new Error(
+        "exact independent review readback required before enqueue",
+      );
+    await enqueueVerifiedDevelopmentReview({ client, repository, runId, plan, mergeFinalization: ({ repository, number, headSha }) => execFileSync("gh", ["pr", "merge", String(number), "--repo", repository, "--merge", "--auto", "--match-head-commit", headSha], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) });
+  } else throw new Error("expected verify, approve or enqueue");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  main(process.argv[2]).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });

package/packages/core/release/commands/next-development-transition.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { materializeNextDevelopmentTransition } from "../next-development-transition.js";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index === -1 ? fallback : String(args[index + 1] || "");
+}
+
+function usage() {
+  return `usage: node packages/core/release/commands/next-development-transition.mjs materialize --input <request.json> [--cwd <checkout>] [--write]\n`;
+}
+
+export function runNextDevelopmentAdapter(args = process.argv.slice(2)) {
+  const [command] = args;
+  if (command !== "materialize") throw new Error(usage().trim());
+  const inputPath = flag(args, "input");
+  if (!inputPath)
+    throw new Error(
+      "next-development materialize requires --input <request.json>",
+    );
+  const cwd = path.resolve(flag(args, "cwd", process.cwd()));
+  const request = JSON.parse(fs.readFileSync(path.resolve(inputPath), "utf8"));
+  return materializeNextDevelopmentTransition({
+    cwd,
+    request,
+    write: args.includes("--write"),
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    process.stdout.write(
+      `${JSON.stringify(runNextDevelopmentAdapter(), null, 2)}\n`,
+    );
+  } catch (error) {
+    process.stderr.write(`next-development transition: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/packages/core/release/commands/promotion-channel-router.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { parseArgs } from "node:util";
+import { resolvePromotionChannel } from "../promotion/channel.js";
+
+try {
+  const { values } = parseArgs({ options: {
+    "target-ref": { type: "string" },
+    "publication-channel": { type: "string" },
+  }});
+  const result = resolvePromotionChannel({ targetRef: values["target-ref"], publicationChannel: values["publication-channel"] });
+  if (process.env.GITHUB_OUTPUT) fs.appendFileSync(process.env.GITHUB_OUTPUT,
+    Object.entries({ "target-ref": result.targetRef, "publication-channel": result.publicationChannel, channel: result.channel }).map(([k,v]) => `${k}=${v}\n`).join(""));
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+} catch (error) {
+  console.error(`promotion-channel-router: ${error.message}`);
+  process.exitCode = 1;
+}

package/packages/core/release/commands/publish-source-ref-resolver.mjs

@@ -0,0 +1,113 @@
+const DEFAULT_GITHUB_API_URL = "https://api.github.com";
+
+function readEnv(env, name, fallback = "") {
+  return env[name] || fallback;
+}
+
+function assertGitSha(sha, label = "sourceSha") {
+  const value = String(sha || "").trim();
+  if (!/^[0-9a-f]{40}$/i.test(value)) {
+    throw new Error(`${label} must be a 40-character Git SHA`);
+  }
+  return value;
+}
+
+export function normalizeSourceRef(value, fallback = "") {
+  return String(value || fallback || "")
+    .trim()
+    .replace(/^refs\/heads\//, "")
+    .replace(/^refs\/tags\//, "");
+}
+
+function splitRepository(repository) {
+  const value = String(repository || "").trim();
+  const match = value.match(/^([^/\s]+)\/([^/\s]+)$/);
+  if (!match) {
+    throw new Error(`BUILDCHAIN_SOURCE_REPOSITORY must be owner/repo, got: ${value || "<empty>"}`);
+  }
+  return { owner: match[1], repo: match[2] };
+}
+
+function encodeRefPath(ref) {
+  return String(ref)
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function sourceRefFromEnv(env = process.env) {
+  const configured = normalizeSourceRef(readEnv(env, "BUILDCHAIN_PUBLISH_SOURCE_REF"));
+  if (configured) {
+    return configured;
+  }
+  const refName = normalizeSourceRef(readEnv(env, "GITHUB_REF_NAME"));
+  if (refName.startsWith("publish-gate/")) {
+    return refName;
+  }
+  return "";
+}
+
+export function currentGitHubRefSha(sourceRef, env = process.env) {
+  const ref = normalizeSourceRef(sourceRef);
+  const githubRefName = normalizeSourceRef(readEnv(env, "GITHUB_REF_NAME"));
+  const githubRef = String(readEnv(env, "GITHUB_REF")).trim();
+  if (ref && ref === githubRefName && githubRef === `refs/heads/${ref}`) {
+    return assertGitSha(readEnv(env, "GITHUB_SHA"), "GITHUB_SHA");
+  }
+  return "";
+}
+
+export async function resolveRemoteGitHubRefSha({
+  repository,
+  sourceRef,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const ref = normalizeSourceRef(sourceRef);
+  if (!ref) {
+    throw new Error("publish source ref is required");
+  }
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch is required to resolve publish source ref through GitHub REST API");
+  }
+
+  const { owner, repo } = splitRepository(repository);
+  const apiBase = String(readEnv(env, "GITHUB_API_URL", DEFAULT_GITHUB_API_URL)).replace(/\/+$/, "");
+  const url = `${apiBase}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/ref/heads/${encodeRefPath(ref)}`;
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "buildchain-publish-source-resolver",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  const token = readEnv(env, "GITHUB_TOKEN");
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+
+  const response = await fetchImpl(url, { headers });
+  if (!response?.ok) {
+    let detail = "";
+    try {
+      const body = await response.json();
+      detail = body?.message ? `: ${body.message}` : "";
+    } catch {
+      detail = "";
+    }
+    throw new Error(`publish source ref not found: ${ref} (GitHub API ${response?.status || "unknown"}${detail})`);
+  }
+  const body = await response.json();
+  return assertGitSha(body?.object?.sha, `GitHub ref ${ref} object.sha`);
+}
+
+export async function resolvePublishSourceRefSha({
+  repository,
+  sourceRef,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const currentSha = currentGitHubRefSha(sourceRef, env);
+  if (currentSha) {
+    return currentSha;
+  }
+  return await resolveRemoteGitHubRefSha({ repository, sourceRef, env, fetchImpl });
+}

package/packages/core/release/commands/release-candidate-resolver.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { writeGitHubOutputs } from "../../providers/commands/github-output.mjs";
+import { resolveReleaseCandidateArtifacts } from "../candidate/resolve.js";
+import {
+  optionalText,
+  releaseCandidateDownloadEnabled,
+} from "../candidate/selection.js";
+const DEFAULT_WORKFLOW_FILE = "self-build-fixture.yml";
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function candidatePayloadOutputs(result) {
+  return {
+    "release-candidate-payload-dir": result.paths?.payloads || "",
+    "release-candidate-platform-manifest-paths": (
+      result.paths?.platformManifests || []
+    ).join(","),
+    "release-candidate-platform-manifest-count": String(
+      result.platformManifestCount || 0,
+    ),
+    "release-candidate-github-artifact-attestation-policy-paths": (
+      result.paths?.githubArtifactAttestationPolicies || []
+    ).join(","),
+    "release-candidate-github-artifact-attestation-policy-count": String(
+      result.githubArtifactAttestationPolicyCount || 0,
+    ),
+    "release-candidate-npm-tarball-paths": (
+      result.paths?.npmTarballs || []
+    ).join(","),
+    "release-candidate-npm-tarball-count": String(result.npmTarballCount || 0),
+    "release-candidate-github-release-artifact-paths": (
+      result.paths?.releaseAssets || []
+    ).join("\n"),
+    "publish-required-artifacts-json": JSON.stringify(
+      result.publishRequiredArtifacts || [],
+    ),
+    "publish-required-artifacts-path":
+      result.paths?.publishRequiredArtifacts || "",
+    "publish-sealed-bundle-root": result.paths?.sealedBundleRoot || "",
+    "publish-sealed-bundle-manifest": result.paths?.sealedBundleManifest || "",
+  };
+}
+
+function candidateOutputs(result) {
+  return {
+    "promote-only-release-candidate": String(result.enabled === true),
+    "release-candidate-passport-path": result.paths?.passport || "",
+    "release-candidate-build-summary-path": result.paths?.buildSummary || "",
+    "release-candidate-stage-capsules-path": result.paths?.stageCapsules || "",
+    "release-candidate-publication-qualification-path":
+      result.paths?.publicationQualification || "",
+    "release-candidate-publication-qualification-root":
+      result.publicationQualificationRoot || "",
+    "release-candidate-version": result.version || "",
+    "release-candidate-publication-version": optionalText(
+      result.publicationVersion,
+    ),
+    "release-candidate-source-sha": result.artifacts?.sourceSha || "",
+    "release-candidate-artifact": result.artifacts?.passport || "",
+    "release-candidate-build-summary-artifact": result.artifacts?.summary || "",
+    "release-candidate-payload-artifacts": (
+      result.artifacts?.payloads || []
+    ).join(","),
+    ...candidatePayloadOutputs(result),
+    "release-candidate-run-id": result.run?.id || "",
+    "release-candidate-run-url": result.run?.url || "",
+    "release-candidate-pr": result.pullRequest?.number
+      ? String(result.pullRequest.number)
+      : "",
+    "release-candidate-diagnosis": result.enabled
+      ? `Resolved PR-stage RC passport ${result.artifacts.passport} from ${result.run.url || `run ${result.run.id}`}`
+      : result.reason || "",
+  };
+}
+
+export async function resolveReleaseCandidateArtifactsCli() {
+  const result = await resolveReleaseCandidateArtifacts({
+    token: env("GITHUB_TOKEN"),
+    apiUrl: env("GITHUB_API_URL", "https://api.github.com"),
+    repository: env("BUILDCHAIN_SOURCE_REPOSITORY", env("GITHUB_REPOSITORY")),
+    targetRef: env("BUILDCHAIN_TARGET_REF"),
+    targetSha: env("BUILDCHAIN_TARGET_SHA"),
+    workflowFile: env("BUILDCHAIN_RC_WORKFLOW_FILE", DEFAULT_WORKFLOW_FILE),
+    workflowName: env("BUILDCHAIN_RC_WORKFLOW_NAME", ""),
+    artifactName: env("BUILDCHAIN_ARTIFACT_NAME"),
+    artifactPatterns: env("BUILDCHAIN_ARTIFACT_PATTERNS"),
+    githubReleasePayloadPatterns: env(
+      "BUILDCHAIN_GITHUB_RELEASE_PAYLOAD_PATTERNS",
+    ),
+    requiredArtifactCount: env("BUILDCHAIN_REQUIRED_ARTIFACT_COUNT", "0"),
+    publishArtifactKind: env("BUILDCHAIN_PUBLISH_ARTIFACT_KIND", "npm"),
+    publishPackageMain: env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN"),
+    runtimeSha: env(
+      "BUILDCHAIN_CURRENT_RUNTIME_SHA",
+      env("BUILDCHAIN_RUNTIME_SHA", env("BUILDCHAIN_TARGET_SHA")),
+    ),
+    outputDir: env("BUILDCHAIN_RC_OUTPUT_DIR", ".buildchain/release-candidate"),
+    download: releaseCandidateDownloadEnabled(
+      env("BUILDCHAIN_RC_DOWNLOAD", "true"),
+    ),
+    waitSeconds: env("BUILDCHAIN_RC_WAIT_SECONDS", "600"),
+    pollIntervalMs: env("BUILDCHAIN_RC_POLL_INTERVAL_MS", "15000"),
+  });
+  writeGitHubOutputs(candidateOutputs(result));
+  console.log(JSON.stringify(result, null, 2));
+  return result;
+}
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    await resolveReleaseCandidateArtifactsCli();
+  } catch (error) {
+    console.error(
+      `::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`,
+    );
+    process.exitCode = 1;
+  }
+}

package/packages/core/release/commands/release-line-dry-run.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import {
+  explainReleaseLineDryRun,
+  formatReleaseLineDryRun,
+} from "../release-line-dry-run.js";
+
+function readFlag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) {
+    return fallback;
+  }
+  return args[index + 1] || "";
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function usage() {
+  return `Usage:
+  node packages/core/release/commands/release-line-dry-run.mjs --target-ref <ref> [--cwd <dir>]
+                                        [--sha <sha>] [--source-ref <ref>]
+                                        [--tags <comma-list>] [--json]
+`;
+}
+
+function main(argv = process.argv.slice(2)) {
+  if (hasFlag(argv, "help") || argv.includes("-h")) {
+    process.stdout.write(usage());
+    return;
+  }
+  const plan = explainReleaseLineDryRun({
+    cwd: readFlag(argv, "cwd", process.cwd()),
+    targetRef: readFlag(argv, "target-ref", ""),
+    sourceRef: readFlag(argv, "source-ref", ""),
+    sha: readFlag(argv, "sha", ""),
+    tags: readFlag(argv, "tags", ""),
+    publishTransaction: hasFlag(argv, "publish-transaction"),
+    publishCommand: readFlag(argv, "publish-command", ""),
+  });
+  if (hasFlag(argv, "json")) {
+    process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+  } else {
+    process.stdout.write(formatReleaseLineDryRun(plan));
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`release-line-dry-run: ${error.message}`);
+  process.exitCode = 1;
+}