@kungfu-tech/buildchain 4.1.3-alpha.1 → 4.1.3-alpha.3

package/packages/core/build/standalone/build.js

@@ -11,7 +11,12 @@ import {
   readLogPath,
   noopLogger,
 } from "./logging.js";
-import { platformTriple, copyNodeBinary, sourceSha } from "./identity.js";
+import {
+  platformTriple,
+  copyNodeBinary,
+  sourceSha,
+  packageVersion,
+} from "./identity.js";
 import { bundleCli, postjectArgs } from "./bundle.js";
 import { run } from "./process.js";
 function prepareStandaloneExecutable({
@@ -124,6 +129,7 @@ export function buildStandaloneBinary({
   nodePath = process.execPath,
   nodeVersion = process.version,
 } = {}) {
+  version ||= packageVersion(cwd);
   const resolvedOutputDir = path.resolve(cwd, outputDir);
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-sea-"));
   try {

package/packages/core/consumer/buildchain-config.js

@@ -5,8 +5,8 @@ import { isDeepStrictEqual } from "node:util";
 import { parse } from "smol-toml";
 import {
   BUILDCHAIN_CONFIG_PATH,
-  resolveBuildchainConfigPath,
 } from "../contracts/buildchain-layout.js";
+import { readProductConfiguration } from "./contract/reader.js";
 import { runShellCommandSync } from "../runtime/spawn-command.js";
 import { normalizeBuildConfiguration } from "../build/build-configuration.js";
 
@@ -181,26 +181,7 @@ function updateTomlStringValuePreservingSource({ source, content, key, value, fi
 }
 
 export function loadBuildchainConfig(cwd = process.cwd()) {
-  const configPath = resolveBuildchainConfigPath(cwd);
-  const filePath = path.join(cwd, configPath);
-  if (!fs.existsSync(filePath)) {
-    return undefined;
-  }
-  const source = fs.readFileSync(filePath, "utf8");
-  let config;
-  try {
-    config = parse(source);
-  } catch (error) {
-    throw new Error(`${configPath} parse failed: ${error.message}`);
-  }
-  if (config.schema !== 1) {
-    throw new Error(`${configPath} schema must be 1`);
-  }
-  return {
-    path: configPath,
-    filePath,
-    config: normalizeBuildchainConfig(config),
-  };
+  return readProductConfiguration(cwd, normalizeBuildchainConfig);
 }
 
 export function normalizeBuildchainConfig(config) {

package/packages/core/consumer/contract/entries.js

@@ -0,0 +1,85 @@
+import { choice, object, relativePath, text } from "./shape.js";
+import { CONFIG_PATH } from "./plan.js";
+
+export const PIPELINE_ENTRY = ".github/workflows/public-ops-pipeline.yml";
+export const RECOVERY_ENTRY = ".github/workflows/public-ops-recover.yml";
+export const PIPELINE_EVENTS = {
+  pull_request: [
+    "opened",
+    "reopened",
+    "synchronize",
+    "ready_for_review",
+    "converted_to_draft",
+    "closed",
+    "labeled",
+    "unlabeled",
+    "edited",
+    "enqueued",
+    "dequeued",
+  ],
+  pull_request_review: ["submitted", "dismissed"],
+  pull_request_target: ["closed"],
+  merge_group: ["checks_requested"],
+  push: [],
+  repository_dispatch: ["buildchain-attempt-wake"],
+};
+
+export function normalInputs(value = {}) {
+  object(value, [], ["config-path"], "inputs");
+  const configPath = relativePath(
+    value["config-path"] ?? CONFIG_PATH,
+    "inputs.config-path",
+  );
+  if (!configPath.endsWith(".toml") || configPath.includes("*"))
+    throw new Error("inputs.config-path: expected one TOML path");
+  return { configPath };
+}
+
+export function recoveryInputs(value) {
+  object(value, ["attempt"], ["runtime-ref"], "inputs");
+  text(value.attempt, "inputs.attempt", /^attempt-[0-9a-f]{64}$/u);
+  const runtimeRef = value["runtime-ref"] ?? "";
+  if (runtimeRef !== "")
+    text(
+      runtimeRef,
+      "inputs.runtime-ref",
+      /^(?:[0-9a-f]{40}|v4(?:-alpha)?|train\/v4\/v4\.[0-9]+\/[a-z0-9][a-z0-9-]*)$/u,
+    );
+  return { attempt: value.attempt, runtimeRef };
+}
+
+export function admitEvent(name, action = "") {
+  choice(name, Object.keys(PIPELINE_EVENTS), "event.name");
+  choice(
+    action,
+    PIPELINE_EVENTS[name].length ? PIPELINE_EVENTS[name] : [""],
+    "event.action",
+  );
+  return { name, action };
+}
+
+function call(entry, channel, extra = "") {
+  return `permissions:\n  contents: read\njobs:\n  buildchain:\n    uses: kungfu-systems/buildchain/${entry}@${channel}\n${extra}    secrets: inherit\n    permissions:\n      actions: write\n      attestations: write\n      checks: write\n      contents: write\n      discussions: write\n      id-token: write\n      pull-requests: write\n      statuses: write\n`;
+}
+
+// Product-independent source of the two caller bytes. Public entry publication
+// is qualified separately; rendering this contract is not an execution receipt.
+export function consumerWorkflows(channel = "v4", configPath = CONFIG_PATH) {
+  choice(channel, ["v4", "v4-alpha"], "entry.channel");
+  normalInputs({ "config-path": configPath });
+  const configInput =
+    configPath === CONFIG_PATH
+      ? ""
+      : `    with:\n      config-path: ${configPath}\n`;
+  const events = Object.entries(PIPELINE_EVENTS)
+    .map(([name, types]) => {
+      return types.length
+        ? `  ${name}:\n    types: [${types.join(", ")}]\n`
+        : `  ${name}:\n`;
+    })
+    .join("");
+  return {
+    ".github/workflows/buildchain.yml": `name: Buildchain pipeline\non:\n${events}${call(PIPELINE_ENTRY, channel, configInput)}`,
+    ".github/workflows/buildchain-recover.yml": `name: Buildchain recovery\non:\n  workflow_dispatch:\n    inputs:\n      attempt:\n        description: Exact Buildchain attempt to recover\n        required: true\n        type: string\n      runtime-ref:\n        description: Optional repaired runtime\n        required: false\n        type: string\n${call(RECOVERY_ENTRY, channel, "    with:\n      attempt: ${{ inputs.attempt }}\n      runtime-ref: ${{ inputs.runtime-ref }}\n")}`,
+  };
+}

package/packages/core/consumer/contract/examples.js

@@ -0,0 +1,96 @@
+import { choice } from "./shape.js";
+import { consumerWorkflows } from "./entries.js";
+import { CONFIG_PATH } from "./plan.js";
+import { PRODUCT_TYPES } from "./products.js";
+
+const ARTIFACTS = {
+  npm: { path: "dist/package", kind: "npm-package", provider: "npm" },
+  binary: {
+    path: "dist/hello.tar.gz",
+    kind: "archive",
+    provider: "github-release",
+  },
+  paper: { path: "dist/paper.pdf", kind: "pdf", provider: "github-release" },
+};
+
+function productSource(type) {
+  const prefix =
+    'import fs from "node:fs";\nfs.mkdirSync("dist", { recursive: true });\n';
+  if (type === "npm")
+    return `${prefix}fs.mkdirSync("dist/package", { recursive: true });\nfs.writeFileSync("dist/package/index.js", 'export const hello = "hello";\\n');\nfs.writeFileSync("dist/package/package.json", JSON.stringify({ name: "@example/minimal", version: JSON.parse(fs.readFileSync("package.json")).version, type: "module", exports: "./index.js" }));\n`;
+  if (type === "binary")
+    return `${prefix}import { execFileSync } from "node:child_process";\nexecFileSync("cc", ["src/hello.c", "-o", "dist/hello"], { stdio: "inherit" });\nexecFileSync("tar", ["-czf", "dist/hello.tar.gz", "-C", "dist", "hello"], { stdio: "inherit" });\n`;
+  return `${prefix}const stream = "BT /F1 24 Tf 50 700 Td (Minimal Paper) Tj ET";
+const objects = ["<< /Type /Catalog /Pages 2 0 R >>", "<< /Type /Pages /Kids [3 0 R] /Count 1 >>", "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>", "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>", \`<< /Length \${stream.length} >>\\nstream\\n\${stream}\\nendstream\`];
+let pdf = "%PDF-1.4\\n";
+const offsets = [0];
+for (const [index, object] of objects.entries()) { offsets.push(Buffer.byteLength(pdf)); pdf += \`\${index + 1} 0 obj\\n\${object}\\nendobj\\n\`; }
+const xref = Buffer.byteLength(pdf);
+pdf += \`xref\\n0 \${offsets.length}\\n0000000000 65535 f \\n\`;
+for (const offset of offsets.slice(1)) pdf += \`\${String(offset).padStart(10, "0")} 00000 n \\n\`;
+pdf += \`trailer\\n<< /Size \${offsets.length} /Root 1 0 R >>\\nstartxref\\n\${xref}\\n%%EOF\\n\`;
+fs.writeFileSync("dist/paper.pdf", pdf);
+`;
+}
+
+export function standardConsumerExample(type, channel = "v4") {
+  choice(type, PRODUCT_TYPES, "product.type");
+  const artifact = ARTIFACTS[type];
+  const npmAccess = type === "npm" ? 'access = "public"\n' : "";
+  const files = {
+    ...consumerWorkflows(channel),
+    "package.json": `${JSON.stringify({ name: `minimal-${type}`, private: true, version: "1.0.0-alpha.1", type: "module" }, null, 2)}\n`,
+    "src/build.mjs": productSource(type),
+    "src/verify.mjs": `import assert from "node:assert/strict";\nimport fs from "node:fs";\nassert.ok(fs.statSync(${JSON.stringify(artifact.path)}).${type === "npm" ? "isDirectory()" : "size > 0"});\n`,
+    [CONFIG_PATH]: `schema = 2
+
+[[products]]
+id = "main"
+type = "${type}"
+platforms = ["linux-x64"]
+build = ["node src/build.mjs"]
+verify = ["node src/verify.mjs"]
+
+[[products.artifacts]]
+id = "main"
+path = "${artifact.path}"
+kind = "${artifact.kind}"
+
+[[products.targets]]
+provider = "${artifact.provider}"
+artifacts = ["main"]
+${npmAccess}
+[version]
+strategy = "semver"
+
+[[version.files]]
+path = "package.json"
+format = "json"
+key = "version"
+
+[[channels]]
+from = "feature/*"
+to = "dev/v1/v1.0"
+operation = "develop"
+
+[[channels]]
+from = "dev/v1/v1.0"
+to = "alpha/v1/v1.0"
+operation = "alpha"
+
+[[channels]]
+from = "alpha/v1/v1.0"
+to = "release/v1/v1.0"
+operation = "stable"
+
+[review]
+minimum_approvals = 1
+code_owners = true
+merge_queue = true
+`,
+  };
+  if (type === "binary")
+    files["src/hello.c"] =
+      '#include <stdio.h>\nint main(void) { puts("hello"); return 0; }\n';
+  return files;
+}

package/packages/core/consumer/contract/identity.js

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { object, relativePath, text } from "./shape.js";
+import { compileConsumerPlan, CONSUMER_CONTRACT } from "./plan.js";
+
+export function contentDigest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+// Source identities are prepared from trusted GitHub readback, never caller inputs.
+export function bindConsumerSource(source, configBytes) {
+  object(
+    source,
+    ["repository", "commit", "tree", "configPath", "configBlob"],
+    [],
+    "source",
+  );
+  text(
+    source.repository,
+    "source.repository",
+    /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u,
+  );
+  for (const key of ["commit", "tree", "configBlob"])
+    text(source[key], `source.${key}`, /^[0-9a-f]{40}$/u);
+  relativePath(source.configPath, "source.configPath");
+  const bytes = Buffer.from(configBytes);
+  const blob = createHash("sha1")
+    .update(`blob ${bytes.length}\0`)
+    .update(bytes)
+    .digest("hex");
+  if (blob !== source.configBlob)
+    throw new Error("source.configBlob: config bytes do not match Git blob");
+  const plan = compileConsumerPlan(bytes.toString("utf8"));
+  const identity = {
+    schema: "buildchain.consumer-source/v1",
+    repository: source.repository,
+    commit: source.commit,
+    tree: source.tree,
+    configPath: source.configPath,
+    configBlob: blob,
+    configDigest: contentDigest(bytes),
+    contract: CONSUMER_CONTRACT,
+  };
+  return {
+    identity,
+    identityDigest: contentDigest(JSON.stringify(identity)),
+    plan,
+  };
+}
+
+export function consumerContractLock({ entry, runtime, configDigest }) {
+  for (const [name, value] of Object.entries({ entry, runtime })) {
+    object(value, ["repository", "sha"], [], name);
+    if (value.repository !== "kungfu-systems/buildchain")
+      throw new Error(`${name}: untrusted Buildchain repository`);
+    text(value.sha, `${name}.sha`, /^[0-9a-f]{40}$/u);
+  }
+  text(configDigest, "configDigest", /^sha256:[0-9a-f]{64}$/u);
+  return {
+    schema: "buildchain.consumer-contract-lock/v2",
+    contract: CONSUMER_CONTRACT,
+    entry: { ...entry },
+    runtime: { ...runtime },
+    configDigest,
+  };
+}

package/packages/core/consumer/contract/inspection.js

@@ -0,0 +1,45 @@
+import { consumerWorkflows } from "./entries.js";
+import { compileConsumerPlan, CONFIG_PATH } from "./plan.js";
+
+const INTERNAL_WIRING = [
+  /\b(?:request-json|native-roots-json|used-nonces-json|warrant-result|source-proof|integration-proof)\b/iu,
+  /\bbuildchain\s+(?:dev\s+(?:warrant|proof)|release|promote|recover|publish)\b/iu,
+  /\b(?:npm\s+publish|gh\s+release\s+(?:create|upload)|gh\s+run\s+download)\b/iu,
+  /actions\/download-artifact@/u,
+  /\.buildchain\/runtime\/|packages\/core\/(?:publication|release|dev-delivery)\//u,
+  /\b(?:fencingToken|candidateRoot|sourceProofRoot|usedNonces|generationRoot|compareAndSwap)\b/u,
+  /buildchain[-./][\w-]*(?:warrant|proof|fence|nonce|candidate|authority|transaction)/iu,
+];
+
+// The supplied file map must be the complete tracked consumer tree, including
+// package scripts and the source files they invoke. Runtime source is never run.
+export function inspectConsumerContract(
+  files,
+  { channel = "v4", configPath = CONFIG_PATH } = {},
+) {
+  const issues = [];
+  let plan;
+  try {
+    plan = compileConsumerPlan(files[configPath]);
+  } catch (error) {
+    issues.push(`${configPath}: ${error.message}`);
+  }
+  const workflows = consumerWorkflows(channel, configPath);
+  for (const [file, expected] of Object.entries(workflows))
+    if (files[file] !== expected)
+      issues.push(`${file}: must match the generated thin caller`);
+  for (const [file, source] of Object.entries(files)) {
+    if (
+      /^\.github\/workflows\/.*\.ya?ml$/u.test(file) &&
+      !Object.hasOwn(workflows, file)
+    )
+      issues.push(`${file}: extra consumer workflow is forbidden`);
+    if (!/\.(?:toml|json|ya?ml|[cm]?js|ts|py|sh|ps1|rb)$/u.test(file)) continue;
+    for (const pattern of INTERNAL_WIRING)
+      if (pattern.test(String(source)))
+        issues.push(
+          `${file}: consumer owns internal orchestration (${pattern.source})`,
+        );
+  }
+  return { ok: issues.length === 0, issues, plan };
+}

package/packages/core/consumer/contract/plan.js

@@ -0,0 +1,146 @@
+import { parse } from "smol-toml";
+import { choice, list, object, relativePath, text, unique } from "./shape.js";
+import { compileProducts } from "./products.js";
+
+export const CONSUMER_CONTRACT = "buildchain.consumer-contract/v2";
+export const CONSUMER_PLAN = "buildchain.consumer-plan/v1";
+export const CONFIG_PATH = ".buildchain/buildchain.toml";
+
+function compileVersion(value) {
+  object(value, ["strategy", "files"], ["derived_files"], "version");
+  choice(value.strategy, ["semver", "anchored"], "version.strategy");
+  list(value.files, "version.files", (item, field) => {
+    object(item, ["path", "format", "key"], [], field);
+    relativePath(item.path, `${field}.path`);
+    choice(item.format, ["json", "toml"], `${field}.format`);
+    text(item.key, `${field}.key`, /^[A-Za-z0-9_.-]+$/u);
+  });
+  unique(
+    value.files.map((item) => `${item.path}:${item.key}`),
+    "version.files",
+  );
+  if (value.derived_files !== undefined)
+    list(value.derived_files, "version.derived_files", relativePath);
+  return structuredClone(value);
+}
+
+function compileChannels(values) {
+  const channels = list(values, "channels", (value, field) => {
+    object(value, ["from", "to", "operation"], [], field);
+    text(
+      value.from,
+      `${field}.from`,
+      /^(?:feature|dev|alpha|release)\/[A-Za-z0-9/*._-]+$/u,
+    );
+    text(
+      value.to,
+      `${field}.to`,
+      /^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u,
+    );
+    choice(
+      value.operation,
+      ["develop", "alpha", "stable", "major"],
+      `${field}.operation`,
+    );
+    const source = value.from.split("/")[0],
+      target = value.to.split("/")[0];
+    const legal = {
+      develop: source === "feature" && target === "dev",
+      alpha: source === "dev" && target === "alpha",
+      stable: source === "alpha" && target === "release",
+      major: source === "release" && value.to === "publish-gate/major",
+    };
+    if (
+      !legal[value.operation] ||
+      value.from.includes("..") ||
+      value.to.includes("..")
+    )
+      throw new Error(`${field}: unlawful channel route`);
+    return { ...value };
+  });
+  unique(
+    channels.map((value) => `${value.from}:${value.to}`),
+    "channels",
+  );
+  return channels;
+}
+
+function compileReview(value) {
+  object(
+    value,
+    ["minimum_approvals", "code_owners", "merge_queue"],
+    [],
+    "review",
+  );
+  if (!Number.isInteger(value.minimum_approvals) || value.minimum_approvals < 1)
+    throw new Error(
+      "review.minimum_approvals: independent approval is required",
+    );
+  if (value.code_owners !== true || value.merge_queue !== true)
+    throw new Error(
+      "review: code owners and protected merge queue are required",
+    );
+  return { ...value };
+}
+
+function compileStable(value) {
+  object(
+    value,
+    [
+      "minimum_interval_seconds",
+      "minimum_soak_seconds",
+      "product_paths",
+      "impact_file",
+      "require_published_entry",
+    ],
+    [],
+    "stable",
+  );
+  for (const field of ["minimum_interval_seconds", "minimum_soak_seconds"])
+    if (!Number.isSafeInteger(value[field]) || value[field] < 0)
+      throw new Error(
+        `stable.${field}: expected non-negative safe integer seconds`,
+      );
+  const paths = list(
+    value.product_paths,
+    "stable.product_paths",
+    (item, field) => {
+      text(item, field);
+      relativePath(item.endsWith("/") ? item.slice(0, -1) : item, field);
+      if (item.includes("*"))
+        throw new Error(`${field}: expected a literal product path`);
+      return item;
+    },
+  );
+  unique(paths, "stable.product_paths");
+  relativePath(value.impact_file, "stable.impact_file");
+  if (!value.impact_file.endsWith(".json") || value.impact_file.includes("*"))
+    throw new Error(
+      "stable.impact_file: expected one product impact JSON file",
+    );
+  if (typeof value.require_published_entry !== "boolean")
+    throw new Error("stable.require_published_entry: expected a boolean");
+  return structuredClone(value);
+}
+
+// This compiler receives bytes. It has no filesystem, process, network or provider port.
+export function compileConsumerPlan(source) {
+  const config = parse(source);
+  object(
+    config,
+    ["schema", "products", "version", "channels", "review"],
+    ["stable"],
+  );
+  choice(config.schema, [2], "schema");
+  return {
+    schema: CONSUMER_PLAN,
+    contract: CONSUMER_CONTRACT,
+    products: compileProducts(config.products),
+    version: compileVersion(config.version),
+    channels: compileChannels(config.channels),
+    review: compileReview(config.review),
+    ...(config.stable === undefined
+      ? {}
+      : { stable: compileStable(config.stable) }),
+  };
+}

package/packages/core/consumer/contract/products.js

@@ -0,0 +1,119 @@
+import {
+  choice,
+  list,
+  object,
+  relativePath,
+  slug,
+  text,
+  unique,
+} from "./shape.js";
+
+export const PRODUCT_TYPES = ["npm", "binary", "paper"];
+export const PLATFORMS = [
+  "linux-x64",
+  "linux-arm64",
+  "macos-arm64",
+  "macos-x64",
+  "windows-x64",
+];
+
+function artifact(value, location) {
+  object(value, ["id", "path", "kind"], ["filename"], location);
+  slug(value.id, `${location}.id`);
+  if (value.path !== "." || value.kind !== "npm-package")
+    relativePath(value.path, `${location}.path`);
+  choice(value.kind, ["npm-package", "archive", "pdf"], `${location}.kind`);
+  if (value.filename !== undefined) {
+    text(
+      value.filename,
+      `${location}.filename`,
+      /^[A-Za-z0-9][A-Za-z0-9._-]{0,254}$/u,
+    );
+    const extension =
+      value.kind === "npm-package"
+        ? /\.tgz$/u
+        : value.kind === "pdf"
+          ? /\.pdf$/u
+          : /\.(?:tar\.gz|tar\.xz|tgz|zip|tar)$/u;
+    if (!extension.test(value.filename))
+      throw new Error(
+        `${location}.filename: artifact extension does not match its kind`,
+      );
+  }
+  return { ...value };
+}
+
+function target(value, location) {
+  object(value, ["provider", "artifacts"], ["access"], location);
+  choice(value.provider, ["npm", "github-release"], `${location}.provider`);
+  list(value.artifacts, `${location}.artifacts`, slug);
+  unique(value.artifacts, `${location}.artifacts`);
+  if (value.provider === "npm")
+    choice(value.access, ["public", "restricted"], `${location}.access`);
+  else if (Object.hasOwn(value, "access"))
+    throw new Error(`${location}.access: npm only`);
+  return structuredClone(value);
+}
+
+export function compileProducts(values) {
+  const products = list(values, "products", (value, location) => {
+    object(
+      value,
+      ["id", "type", "platforms", "build", "verify", "artifacts", "targets"],
+      ["install", "directory"],
+      location,
+    );
+    slug(value.id, `${location}.id`);
+    choice(value.type, PRODUCT_TYPES, `${location}.type`);
+    list(value.platforms, `${location}.platforms`, (item, field) =>
+      choice(item, PLATFORMS, field),
+    );
+    unique(value.platforms, `${location}.platforms`);
+    for (const operation of [
+      "build",
+      "verify",
+      ...(value.install !== undefined ? ["install"] : []),
+    ])
+      list(value[operation], `${location}.${operation}`, text);
+    if (value.directory !== undefined)
+      relativePath(value.directory, `${location}.directory`);
+    const artifacts = list(value.artifacts, `${location}.artifacts`, artifact);
+    unique(
+      artifacts.map((item) => item.id),
+      `${location}.artifacts`,
+    );
+    const targets = list(value.targets, `${location}.targets`, target);
+    unique(
+      targets.map((item) => item.provider),
+      `${location}.targets`,
+    );
+    const expectedKind = {
+      npm: "npm-package",
+      binary: "archive",
+      paper: "pdf",
+    }[value.type];
+    if (artifacts.some((item) => item.kind !== expectedKind))
+      throw new Error(`${location}: artifact kind does not match product type`);
+    const published = targets.flatMap((item) => item.artifacts);
+    if (
+      artifacts.some((item) => !published.includes(item.id)) ||
+      published.some((id) => !artifacts.some((item) => item.id === id))
+    )
+      throw new Error(
+        `${location}: publication targets must cover exactly declared artifacts`,
+      );
+    if (
+      targets.some((item) => item.provider === "npm") !==
+      (value.type === "npm")
+    )
+      throw new Error(
+        `${location}: npm products require an npm target; other products cannot publish to npm`,
+      );
+    return structuredClone({ ...value, artifacts, targets });
+  });
+  unique(
+    products.map((item) => item.id),
+    "products",
+  );
+  return products;
+}

package/packages/core/consumer/contract/reader.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "smol-toml";
+import { resolveBuildchainConfigPath } from "../../contracts/buildchain-layout.js";
+import { compileConsumerPlan } from "./plan.js";
+
+function productConfiguration(source, config) {
+  const plan = compileConsumerPlan(source);
+  // Read-only version tooling uses the established normalized field names.
+  // Product commands remain in the plan; no publish lifecycle is synthesized.
+  return {
+    ...config,
+    version: {
+      required: true,
+      strategy: plan.version.strategy,
+      next: plan.version.strategy === "anchored" ? "manual" : "auto",
+      files: plan.version.files.map(({ format, ...file }) => ({
+        ...file,
+        type: format,
+      })),
+      derivedFiles: plan.version.derived_files || [],
+    },
+  };
+}
+
+export function readProductConfiguration(cwd, normalizeLegacy) {
+  const configPath = resolveBuildchainConfigPath(cwd);
+  const filePath = path.join(cwd, configPath);
+  if (!fs.existsSync(filePath)) return undefined;
+  const source = fs.readFileSync(filePath, "utf8");
+  let config;
+  try {
+    config = parse(source);
+  } catch (error) {
+    throw new Error(`${configPath} parse failed: ${error.message}`);
+  }
+  if (![1, 2].includes(config.schema))
+    throw new Error(`${configPath} schema must be 1 or 2`);
+  return {
+    path: configPath,
+    filePath,
+    config:
+      config.schema === 2
+        ? productConfiguration(source, config)
+        : normalizeLegacy(config),
+  };
+}