@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.0

package/scripts/materialize-self-release-candidate-version.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  getVersionStrategy,
+  loadConfiguredAnchorManifest,
+} from "../packages/core/buildchain-config.js";
+import {
+  alignMajorBootstrapReleaseImpact,
+  currentConfiguredVersion,
+  discoverVersionStateFiles,
+  runVersionVerification,
+  updateVersionStateContents,
+  versionVerificationAllowedPathsForPromotion,
+  versionVerificationEnv,
+} from "../actions/promote-buildchain-ref/internal/version-state.js";
+
+function required(value, name) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${name} is required`);
+  return normalized;
+}
+
+function parseArgs(argv) {
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) throw new Error(`unexpected argument: ${argument}`);
+    const name = argument.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`--${name} requires a value`);
+    options[name] = value;
+    index += 1;
+  }
+  return options;
+}
+
+export function materializeSelfReleaseCandidateVersion({
+  cwd = process.cwd(),
+  version,
+  channel,
+  sourceSha,
+  generatedAt,
+} = {}) {
+  const resolvedVersion = required(version, "version");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(resolvedVersion)) {
+    throw new Error(`version must be an exact semantic version: ${resolvedVersion}`);
+  }
+  const resolvedChannel = required(channel, "channel");
+  if (!new Set(["alpha", "release", "major"]).has(resolvedChannel)) {
+    throw new Error(`channel must be alpha, release, or major: ${resolvedChannel}`);
+  }
+  const resolvedSourceSha = required(sourceSha, "sourceSha");
+  if (!/^[0-9a-f]{40}$/i.test(resolvedSourceSha)) {
+    throw new Error("sourceSha must be a 40-character Git SHA");
+  }
+  const resolvedGeneratedAt = required(generatedAt, "generatedAt");
+  if (Number.isNaN(Date.parse(resolvedGeneratedAt))) {
+    throw new Error(`generatedAt must be an ISO timestamp: ${resolvedGeneratedAt}`);
+  }
+
+  const discovered = discoverVersionStateFiles(cwd);
+  if (discovered.files.length === 0) {
+    throw new Error("self-release candidate requires declared version state");
+  }
+  const discoveredPaths = discovered.files.map((file) => file.path);
+  const versionStrategy = getVersionStrategy(discovered.config);
+  const anchorManifest = loadConfiguredAnchorManifest(cwd, discovered.config);
+  const lifecycleEnv = versionVerificationEnv(versionStrategy, anchorManifest, {
+    generatedAt: resolvedGeneratedAt,
+    sourceSha: resolvedSourceSha,
+  });
+  if (resolvedChannel === "major") {
+    lifecycleEnv.BUILDCHAIN_MAJOR_VERSION_BOOTSTRAP = "true";
+  }
+
+  let changedFiles = updateVersionStateContents(discovered.files, resolvedVersion);
+  if (resolvedChannel === "major") {
+    changedFiles = alignMajorBootstrapReleaseImpact(changedFiles, {
+      version: resolvedVersion,
+    });
+  }
+  const materializedFiles = runVersionVerification({
+    cwd,
+    loadedConfig: discovered.config,
+    version: resolvedVersion,
+    changedFiles,
+    allowedPaths: versionVerificationAllowedPathsForPromotion(
+      resolvedChannel,
+      discoveredPaths,
+    ),
+    env: lifecycleEnv,
+    runLifecycleVerify: false,
+  });
+  const materialized = discoverVersionStateFiles(cwd);
+  const actualVersion = currentConfiguredVersion(materialized.files);
+  if (actualVersion !== resolvedVersion) {
+    throw new Error(
+      `materialized self-release candidate version mismatch: expected ${resolvedVersion}, got ${actualVersion || "<empty>"}`,
+    );
+  }
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-self-release-candidate-version/v1",
+    version: resolvedVersion,
+    channel: resolvedChannel,
+    sourceSha: resolvedSourceSha,
+    generatedAt: resolvedGeneratedAt,
+    files: materializedFiles.map((file) => file.path),
+  };
+}
+
+export function materializeSelfReleaseCandidateVersionCli(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const result = materializeSelfReleaseCandidateVersion({
+    cwd: path.resolve(options.cwd || process.cwd()),
+    version: options.version,
+    channel: options.channel,
+    sourceSha: options["source-sha"],
+    generatedAt: options["generated-at"],
+  });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
+) {
+  materializeSelfReleaseCandidateVersionCli();
+}

package/scripts/release-tail.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  compileReleaseTailDeclaration,
+  createReleaseTailTransaction,
+  readReleaseTailTransaction,
+  validateReleaseTailTransaction,
+  writeReleaseTailTransaction,
+} from "../packages/core/release-tail-provider-plane.js";
+import { diagnoseLegacyReleaseTailHooks } from "../packages/core/release-tail-compatibility.js";
+import {
+  executePublicationRehearsal,
+  publicationRehearsalDiagnostic,
+} from "../packages/core/publication-rehearsal-runtime.js";
+
+function flag(args, name, fallback = "") {
+  const index = args.indexOf(`--${name}`);
+  return index < 0 ? fallback : args[index + 1] || "";
+}
+
+function readJson(value, label) {
+  if (!value) throw new Error(`${label} is required`);
+  const filePath = path.resolve(value);
+  if (fs.existsSync(filePath))
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  return JSON.parse(value);
+}
+
+function output(value, filePath = "") {
+  if (filePath) {
+    const resolved = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, `${JSON.stringify(value, null, 2)}\n`);
+  }
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function runReleaseTailCli(args = process.argv.slice(2)) {
+  const [mode = "status", ...options] = args;
+  if (mode === "rehearse") {
+    const capsulePath = flag(options, "capsule");
+    const capsuleRoot = flag(options, "capsule-root");
+    const statePath = flag(options, "state");
+    const evidencePath = flag(options, "evidence");
+    for (const [name, value] of Object.entries({
+      "--capsule": capsulePath,
+      "--capsule-root": capsuleRoot,
+      "--state": statePath,
+      "--evidence": evidencePath,
+    })) {
+      if (!value || !path.isAbsolute(value)) {
+        throw new Error(`${name} must be an explicit absolute path`);
+      }
+    }
+    const capsule = readJson(capsulePath, "--capsule");
+    const rehearsalMode = flag(options, "mode", "simulate");
+    if (!new Set(["simulate", "replay"]).has(rehearsalMode)) {
+      throw new Error("local rehearsal --mode must be simulate or replay");
+    }
+    const environment = flag(options, "environment-json")
+      ? readJson(flag(options, "environment-json"), "--environment-json")
+      : {};
+    let result;
+    try {
+      result = await executePublicationRehearsal({
+        capsule,
+        capsuleRoot,
+        mode: rehearsalMode,
+        environment,
+        checkpoint: (transaction) =>
+          writeReleaseTailTransaction(statePath, transaction),
+      });
+    } catch (error) {
+      const diagnostic = publicationRehearsalDiagnostic(error, { capsule });
+      output(diagnostic, evidencePath);
+      throw error;
+    }
+    writeReleaseTailTransaction(statePath, result.transaction);
+    output(result.evidence, evidencePath);
+    return result;
+  }
+  if (mode === "plan") {
+    const plan = compileReleaseTailDeclaration(
+      readJson(flag(options, "declaration"), "--declaration"),
+    );
+    output(plan, flag(options, "output"));
+    return plan;
+  }
+  if (mode === "init") {
+    const transaction = createReleaseTailTransaction(
+      readJson(flag(options, "declaration"), "--declaration"),
+    );
+    const statePath = flag(
+      options,
+      "state",
+      ".buildchain/release-tail/state.json",
+    );
+    writeReleaseTailTransaction(statePath, transaction);
+    output(transaction);
+    return transaction;
+  }
+  if (mode === "status" || mode === "verify") {
+    const statePath = flag(
+      options,
+      "state",
+      ".buildchain/release-tail/state.json",
+    );
+    const transaction = readReleaseTailTransaction(statePath);
+    const validation = validateReleaseTailTransaction(transaction);
+    const nextOperation = transaction.operations.find(
+      (entry) => entry.status === "pending",
+    );
+    const report = {
+      schema: "kungfu.buildchain.release-tail.status/v1",
+      ok: validation.valid,
+      state: transaction.state,
+      stateRoot: transaction.stateRoot,
+      transactionRoot: transaction.transactionRoot,
+      nextOperation: nextOperation
+        ? {
+            operationId: nextOperation.operationId,
+            capabilityId: nextOperation.capabilityId,
+            adapter: nextOperation.effect.adapter,
+          }
+        : null,
+      receiptRoots: transaction.receipts.map((receipt) => receipt.receiptRoot),
+      issues: validation.issues,
+    };
+    output(report, flag(options, "output"));
+    return report;
+  }
+  if (mode === "compat") {
+    const report = diagnoseLegacyReleaseTailHooks(
+      readJson(flag(options, "hooks-json"), "--hooks-json"),
+    );
+    output(report, flag(options, "output"));
+    if (!report.compatible) process.exitCode = 1;
+    return report;
+  }
+  throw new Error(
+    "usage: buildchain release-tail <plan|init|status|verify|compat|rehearse> [--declaration <json-or-path>] [--capsule <path>] [--capsule-root <absolute-path>] [--mode <simulate|replay>] [--state <path>] [--evidence <path>] [--hooks-json <json-or-path>] [--output <path>]",
+  );
+}
+
+if (
+  !process.env.BUILDCHAIN_EMBEDDED_ENTRYPOINT &&
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    await runReleaseTailCli();
+  } catch (error) {
+    console.error(`release-tail: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/site-capability-metadata.mjs

@@ -12,6 +12,11 @@ function capabilityGroup(id) {
 export function cliCommandMeta(id) {
   const map = new Map(Object.entries({
     audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
+    architecture: { group: "governance-versioning", purpose: "Inspect and qualify the Buildchain v4 capability and state-machine architecture contract." },
+    "architecture-list": { group: "governance-versioning", purpose: "Generate the Agent-readable capability list from the validated v4 architecture manifest." },
+    "architecture-qualify": { group: "governance-versioning", purpose: "Qualify an exact candidate against a distinct N-1 Git authority revision without candidate self-qualification." },
+    "architecture-show": { group: "governance-versioning", purpose: "Generate one capability and its state-machine details from the validated v4 architecture manifest." },
+    "architecture-validate": { group: "governance-versioning", purpose: "Validate v4 dependency direction, ownership, writers, budgets, recovery declarations, and exception policy." },
     "audit-publication-control-plane": { group: "release-passport-trust", purpose: "Read GitHub publication controls, bind provider-enforced npm identity, and emit a sanitized expiring receipt." },
     "audit-github-governance": { group: "governance-versioning", purpose: "Read the managed GitHub zone, aggregate native protection and ownership, and emit sanitized fail-closed governance receipts." },
     badges: { group: "distribution-indexes", purpose: "Inspect README badge command families." },
@@ -134,6 +139,7 @@ export function cliCommandMeta(id) {
     "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
     "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
     "release-propagation": { group: "site-and-propagation", purpose: "Route exact Paper, KFD, Buildchain, or Core Site updates through one resumable propagation Work." },
+    "release-tail": { group: "release-passport-trust", purpose: "Plan, initialize, rehearse, resume, and verify one declarative provider-owned release-tail transaction." },
     "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
     sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
     "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
@@ -197,6 +203,11 @@ export function nodeApiMeta(exportName) {
     "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
     "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
     "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
+    "./release-tail-provider-plane": { group: "release-passport-trust", summary: "Versioned declarative release-tail parsing, deterministic effect planning, durable transaction execution, readback, retry, and rooted receipt APIs." },
+    "./release-tail-provider-adapters": { group: "release-passport-trust", summary: "Buildchain-owned GitHub Release, signed-channel, activation, and released-evidence provider adapters." },
+    "./release-tail-compatibility": { group: "release-passport-trust", summary: "Bounded v3 release-hook compatibility diagnostics that reject new executable release-tail inputs." },
+    "./publication-rehearsal-runtime": { group: "release-passport-trust", summary: "Content-addressed local, replay, and provider-recording publication rehearsal over the shared release-tail core." },
+    "./publication-rehearsal-projection": { group: "release-passport-trust", summary: "Canonical generated config, workflow, and Agent projections for release local constructibility." },
     "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
     "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
     "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },