@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/paper/paper-npm-bootstrap.js

@@ -0,0 +1,492 @@
+function executePaperNpmBootstrap(options = {}, runtime) {
+  const {
+    DEFAULT_BOOTSTRAP_VERSION,
+    NPM_REGISTRY,
+    PAPER_NPM_BOOTSTRAP_CONTRACT,
+    PAPER_PATHS,
+    bootstrapPackageShape,
+    commandResult,
+    expectedPaperTrustedPublisher,
+    extractUrls,
+    fs,
+    jsonText,
+    liveNpmAuthObservation,
+    liveNpmPackageObservation,
+    liveNpmTrustObservation,
+    normalizePackageName,
+    normalizeRepository,
+    os,
+    paperConfig,
+    path,
+    resolvePaperRepository,
+    safeParseJson,
+    toPosix,
+    validatePaperProvisioningAuthority,
+    writePaperReceipt,
+  } = runtime;
+  const {
+    cwd = process.cwd(),
+    packageName = "",
+    bootstrapVersion = DEFAULT_BOOTSTRAP_VERSION,
+    registry = NPM_REGISTRY,
+    repository = "",
+    workflow = "public-release-paper.yml",
+    environment = "",
+    execute = false,
+    confirmedPackage = "",
+    userconfig = "",
+    offline = false,
+  } = options;
+  const resolvedCwd = path.resolve(cwd);
+  if (registry !== NPM_REGISTRY) {
+    throw new Error(
+      `paper npm bootstrap requires the official registry ${NPM_REGISTRY}`,
+    );
+  }
+  if (bootstrapVersion !== DEFAULT_BOOTSTRAP_VERSION) {
+    throw new Error(
+      `paper npm bootstrap version is fixed at ${DEFAULT_BOOTSTRAP_VERSION}`,
+    );
+  }
+  const configResult = paperConfig(resolvedCwd);
+  if (configResult.error) throw new Error(configResult.error);
+  const name = normalizePackageName(
+    packageName ||
+      configResult.loaded.config.publish?.package ||
+      configResult.loaded.config.publish?.mainPackage,
+  );
+  const repo = normalizeRepository(
+    repository || resolvePaperRepository(resolvedCwd),
+  );
+  const provisioning = validatePaperProvisioningAuthority(resolvedCwd);
+  if (!provisioning.valid) {
+    throw new Error(
+      `paper npm bootstrap requires a valid provisioning authority: ${provisioning.errors.join("; ")}`,
+    );
+  }
+  const expectedPublisher = expectedPaperTrustedPublisher(provisioning.value);
+  if (
+    provisioning.value.package?.name !== name ||
+    expectedPublisher.repository !== repo ||
+    expectedPublisher.workflow !== toPosix(workflow).replace(/^\/+/, "") ||
+    expectedPublisher.environment !== String(environment || "")
+  ) {
+    throw new Error(
+      "paper npm bootstrap coordinates differ from the exact provisioning authority",
+    );
+  }
+  if (execute && confirmedPackage !== name) {
+    throw new Error(
+      `real npm bootstrap requires --confirm-public-package ${name}`,
+    );
+  }
+  if (execute && offline) {
+    throw new Error("real npm bootstrap cannot run with --offline");
+  }
+  if (execute && (!repo || !workflow)) {
+    throw new Error(
+      "real npm bootstrap requires GitHub repository and workflow coordinates",
+    );
+  }
+  const packageObservation = offline
+    ? {
+        status: "unknown",
+        exists: null,
+        version: "",
+        registry,
+        errorCode: "offline",
+      }
+    : liveNpmPackageObservation(name, registry, resolvedCwd);
+  const auth = offline
+    ? {
+        status: "unknown",
+        authenticated: null,
+        identity: "",
+        errorCode: "offline",
+      }
+    : liveNpmAuthObservation(registry, resolvedCwd);
+  const plan = {
+    schemaVersion: 1,
+    contract: PAPER_NPM_BOOTSTRAP_CONTRACT,
+    ok: true,
+    dryRun: !execute,
+    externalMutation: execute,
+    package: {
+      name,
+      bootstrapVersion,
+      registry,
+      existsBefore: packageObservation.exists,
+      observedVersion: packageObservation.version,
+    },
+    repository: {
+      github: repo,
+      workflow,
+      environment,
+    },
+    authority: {
+      digest: provisioning.value.authorityDigest,
+      policyDigest: provisioning.value.policy.policyDigest,
+    },
+    auth: {
+      authenticated: auth.authenticated,
+      identity: auth.identity,
+      errorCode: auth.errorCode,
+    },
+    publish: {
+      status: packageObservation.exists === true ? "existing" : "planned",
+      distTag: "bootstrap",
+      access: "public",
+    },
+    trust: {
+      status: "planned",
+      urls: [],
+    },
+    receipts: [],
+    nextActions: execute
+      ? []
+      : [
+          {
+            id: "confirm-public-bootstrap",
+            command: `buildchain paper bootstrap npm --execute --confirm-public-package ${name} --json`,
+            description:
+              "After reviewing this dry-run, bootstrap the exact public package and configure GitHub Trusted Publishing.",
+          },
+        ],
+  };
+  if (!execute) {
+    const dryRunRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), "buildchain-paper-bootstrap-dry-run-"),
+    );
+    try {
+      fs.writeFileSync(
+        path.join(dryRunRoot, "package.json"),
+        jsonText(
+          bootstrapPackageShape({
+            packageName: name,
+            version: bootstrapVersion,
+          }),
+        ),
+      );
+      const configArgs = userconfig ? ["--userconfig", userconfig] : [];
+      const pack = commandResult(
+        "npm",
+        [
+          "pack",
+          "--dry-run",
+          "--json",
+          "--ignore-scripts",
+          `--registry=${registry}`,
+          ...configArgs,
+        ],
+        { cwd: dryRunRoot },
+      );
+      const publish = commandResult(
+        "npm",
+        [
+          "publish",
+          "--dry-run",
+          "--ignore-scripts",
+          "--access",
+          "public",
+          "--tag",
+          "bootstrap",
+          `--registry=${registry}`,
+          ...configArgs,
+        ],
+        { cwd: dryRunRoot },
+      );
+      return {
+        ...plan,
+        ok: pack.ok && publish.ok,
+        errorCode: !pack.ok
+          ? "npm-pack-dry-run-failed"
+          : !publish.ok
+            ? "npm-publish-dry-run-failed"
+            : "",
+        dryRunChecks: {
+          minimalPackageOnly: true,
+          pack: {
+            status: pack.ok ? "pass" : "fail",
+            entryCount: (() => {
+              const parsed = safeParseJson(pack.stdout);
+              const value = Array.isArray(parsed) ? parsed[0] : parsed;
+              return Array.isArray(value?.files) ? value.files.length : 0;
+            })(),
+          },
+          publish: {
+            status: publish.ok ? "pass" : "fail",
+            registry,
+            access: "public",
+            distTag: "bootstrap",
+          },
+        },
+      };
+    } finally {
+      fs.rmSync(dryRunRoot, { recursive: true, force: true });
+    }
+  }
+  if (packageObservation.exists === null) {
+    return {
+      ...plan,
+      ok: false,
+      errorCode: "npm-package-status-unknown",
+      publish: {
+        ...plan.publish,
+        status: "blocked",
+      },
+      trust: {
+        status: "blocked",
+        urls: [],
+      },
+      nextActions: [
+        {
+          id: "verify-npm-package",
+          command: `npm view ${name} version --json --registry=${registry}`,
+          description:
+            "Resolve whether the exact public package exists before any publish mutation.",
+        },
+      ],
+    };
+  }
+  if (auth.authenticated !== true) {
+    return {
+      ...plan,
+      ok: false,
+      errorCode: "npm-auth-required",
+      publish: {
+        ...plan.publish,
+        status: "blocked",
+      },
+      trust: {
+        status: "blocked",
+        urls: [],
+      },
+      nextActions: [
+        {
+          id: "authenticate-npm",
+          command: `npm whoami --registry=${registry}`,
+          description:
+            "Authenticate npm without sharing token contents, then rerun the exact bootstrap command.",
+        },
+      ],
+    };
+  }
+  const tempRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-paper-bootstrap-"),
+  );
+  try {
+    fs.writeFileSync(
+      path.join(tempRoot, "package.json"),
+      jsonText(
+        bootstrapPackageShape({ packageName: name, version: bootstrapVersion }),
+      ),
+    );
+    const configArgs = userconfig ? ["--userconfig", userconfig] : [];
+    const pack = commandResult(
+      "npm",
+      [
+        "pack",
+        "--dry-run",
+        "--json",
+        "--ignore-scripts",
+        `--registry=${registry}`,
+        ...configArgs,
+      ],
+      { cwd: tempRoot },
+    );
+    if (!pack.ok) {
+      return {
+        ...plan,
+        ok: false,
+        errorCode: "npm-pack-dry-run-failed",
+        publish: { ...plan.publish, status: "blocked" },
+        trust: { status: "blocked", urls: [] },
+      };
+    }
+    const publishDryRun = commandResult(
+      "npm",
+      [
+        "publish",
+        "--dry-run",
+        "--ignore-scripts",
+        "--access",
+        "public",
+        "--tag",
+        "bootstrap",
+        `--registry=${registry}`,
+        ...configArgs,
+      ],
+      { cwd: tempRoot },
+    );
+    if (!publishDryRun.ok) {
+      return {
+        ...plan,
+        ok: false,
+        errorCode: "npm-publish-dry-run-failed",
+        publish: { ...plan.publish, status: "blocked" },
+        trust: { status: "blocked", urls: [] },
+      };
+    }
+    let publishStatus =
+      packageObservation.exists === true ? "existing" : "published";
+    if (packageObservation.exists !== true) {
+      const published = commandResult(
+        "npm",
+        [
+          "publish",
+          "--ignore-scripts",
+          "--access",
+          "public",
+          "--tag",
+          "bootstrap",
+          `--registry=${registry}`,
+          ...configArgs,
+        ],
+        { cwd: tempRoot, timeout: 60000 },
+      );
+      if (!published.ok) {
+        const failure = {
+          ...plan,
+          ok: false,
+          errorCode: "npm-publish-failed",
+          publish: { ...plan.publish, status: "failed" },
+          trust: { status: "blocked", urls: [] },
+        };
+        failure.receipts = [
+          writePaperReceipt(resolvedCwd, PAPER_PATHS.npmBootstrap, failure),
+        ];
+        return failure;
+      }
+    }
+    const trustArgs = [
+      "trust",
+      "github",
+      name,
+      "--repo",
+      repo,
+      "--file",
+      workflow,
+      ...(environment ? ["--env", environment] : []),
+      "--allow-publish",
+      "--yes",
+      "--json",
+      `--registry=${registry}`,
+      ...configArgs,
+    ];
+    const trustCommand = commandResult("npm", trustArgs, {
+      cwd: resolvedCwd,
+      timeout: 60000,
+    });
+    const parsedTrust = safeParseJson(trustCommand.stdout);
+    const urls = [
+      ...extractUrls(
+        parsedTrust || `${trustCommand.stdout}\n${trustCommand.stderr}`,
+      ),
+    ];
+    const trustList =
+      trustCommand.ok && urls.length === 0
+        ? liveNpmTrustObservation(
+            name,
+            registry,
+            resolvedCwd,
+            expectedPublisher,
+          )
+        : {
+            status: "unknown",
+            configured: null,
+            publishers: [],
+            errorCode:
+              urls.length > 0 ? "web-action-required" : "npm-trust-failed",
+          };
+    const trustStatus =
+      trustCommand.ok && trustList.configured === true
+        ? "configured"
+        : urls.length > 0
+          ? "action-required"
+          : "failed";
+    const packageAfter = liveNpmPackageObservation(name, registry, resolvedCwd);
+    const packageVerified = packageAfter.exists === true;
+    const receipt = {
+      ...plan,
+      ok: trustStatus !== "failed" && packageVerified,
+      dryRun: false,
+      externalMutation: true,
+      errorCode:
+        trustStatus === "failed"
+          ? "npm-trust-failed"
+          : packageVerified
+            ? ""
+            : "npm-package-readback-failed",
+      package: {
+        ...plan.package,
+        existsAfter: packageAfter.exists,
+        observedVersionAfter: packageAfter.version,
+        readbackStatus: packageAfter.status,
+      },
+      publish: {
+        ...plan.publish,
+        status: publishStatus,
+      },
+      trust: {
+        status: trustStatus,
+        urls,
+        expectedPublisher,
+        exactBinding: trustList.exactBinding === true,
+        publishers: trustList.publishers,
+      },
+      nextActions:
+        trustStatus === "configured" && packageVerified
+          ? [
+              {
+                id: "paper-preflight",
+                command: "buildchain paper preflight --json",
+                description:
+                  "Verify package existence and Trusted Publisher binding from live read-only sources.",
+              },
+            ]
+          : trustStatus === "action-required" && packageVerified
+            ? [
+                {
+                  id: "complete-npm-web-action",
+                  command: "",
+                  description:
+                    "Open the exact npm URL returned below, complete the web step, then rerun preflight.",
+                  urls,
+                },
+              ]
+            : !packageVerified
+              ? [
+                  {
+                    id: "verify-npm-package-readback",
+                    command: `npm view ${name} version --json --registry=${registry}`,
+                    description:
+                      "The mutation returned but the official registry did not prove package existence; do not infer success.",
+                  },
+                ]
+              : [
+                  {
+                    id: "retry-npm-trust",
+                    command: `buildchain paper bootstrap npm --execute --confirm-public-package ${name} --json`,
+                    description:
+                      "The package exists; retry only the idempotent Trusted Publisher configuration path.",
+                  },
+                ],
+    };
+    receipt.receipts = [
+      writePaperReceipt(resolvedCwd, PAPER_PATHS.npmBootstrap, receipt),
+    ];
+    if (
+      packageVerified &&
+      (trustStatus === "configured" || trustStatus === "action-required")
+    ) {
+      receipt.receipts.push(
+        writePaperReceipt(resolvedCwd, PAPER_PATHS.npmTrust, receipt),
+      );
+    }
+    return receipt;
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+export { executePaperNpmBootstrap };

package/packages/core/paper/paper-repository.js

@@ -0,0 +1,214 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadBuildchainConfig } from "../consumer/buildchain-config.js";
+import { spawnSyncCommand } from "../runtime/spawn-command.js";
+
+export const PAPER_PATHS = Object.freeze({
+  config: ".buildchain/buildchain.toml",
+  agentEntry: ".buildchain/paper/agent-entry.json",
+  agentInstructions: "AGENTS.md",
+  versionPin: ".buildchain-version",
+  contractLock: ".buildchain/contract-lock.json",
+  buildWorkflow: ".github/workflows/build.yml",
+  verifyWorkflow: ".github/workflows/verify.yml",
+  releaseWorkflow: ".github/workflows/public-release-paper.yml",
+  pnpmWorkspace: "pnpm-workspace.yaml",
+  reproducibilityReceipt:
+    ".buildchain/publication/reproducibility-receipt.json",
+  sealedBundle: ".buildchain/admitted/sealed-bundle.json",
+  admission: ".buildchain/admitted/publication-admission.json",
+  capability: ".buildchain/admitted/publication-capability.json",
+  npmBootstrap: ".buildchain/paper/npm-bootstrap.json",
+  npmTrust: ".buildchain/paper/npm-trust.json",
+  provisioningAuthority: ".buildchain/paper/provisioning-authority.json",
+  visibility: ".buildchain/paper/visibility.json",
+});
+
+export const PAPER_WORK_BRANCH_PATTERN =
+  /^(?:feature|fix|docs|chore|ci|refactor)\/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?)*$/;
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function sha256Text(value) {
+  return `sha256:${crypto.createHash("sha256").update(String(value)).digest("hex")}`;
+}
+
+export function readJson(filePath) {
+  if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+    return { exists: false, value: undefined, error: "" };
+  }
+  try {
+    return {
+      exists: true,
+      value: JSON.parse(fs.readFileSync(filePath, "utf8")),
+      error: "",
+    };
+  } catch (error) {
+    return { exists: true, value: undefined, error: error.message };
+  }
+}
+
+export function normalizeRepository(value) {
+  const normalized = String(value || "")
+    .trim()
+    .replace(/^git\+/, "")
+    .replace(/^git@github\.com:/, "")
+    .replace(/^ssh:\/\/git@github\.com\//, "")
+    .replace(/^https?:\/\/github\.com\//, "")
+    .replace(/\.git$/, "")
+    .replace(/^\/+|\/+$/g, "");
+  return /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalized)
+    ? normalized
+    : "";
+}
+
+export function commandResult(
+  command,
+  args,
+  { cwd, env = process.env, timeout = 15000 } = {},
+) {
+  const result = spawnSyncCommand(command, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    timeout,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status ?? 1,
+    stdout: String(result.stdout || "").trim(),
+    stderr: String(result.stderr || "").trim(),
+    error: result.error?.message || "",
+  };
+}
+
+export function gitResult(cwd, args) {
+  return commandResult("git", args, { cwd });
+}
+
+export function gitValue(cwd, args) {
+  const result = gitResult(cwd, args);
+  return result.ok ? result.stdout : "";
+}
+
+export function paperConfig(cwd) {
+  const loaded = loadBuildchainConfig(cwd);
+  if (!loaded)
+    return { loaded: undefined, error: `${PAPER_PATHS.config} is missing` };
+  if (loaded.config.project?.type !== "publication-artifact") {
+    return { loaded, error: 'project.type must be "publication-artifact"' };
+  }
+  if (!loaded.config.publication)
+    return { loaded, error: "[publication] is missing" };
+  return { loaded, error: "" };
+}
+
+export function parsePaperVersion(version) {
+  const normalized = String(version || "")
+    .trim()
+    .replace(/^v/, "");
+  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match)
+    throw new Error("publication.version must be semver before planning Alpha");
+  return {
+    version: normalized,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] || "",
+  };
+}
+
+export function resolvePaperRepository(cwd = process.cwd()) {
+  const sourcePackage = readJson(path.resolve(cwd, "package.json")).value;
+  const configured =
+    typeof sourcePackage?.repository === "string"
+      ? sourcePackage.repository
+      : sourcePackage?.repository?.url;
+  return (
+    normalizeRepository(configured) ||
+    normalizeRepository(gitValue(cwd, ["config", "--get", "remote.origin.url"]))
+  );
+}
+
+export function paperDevelopmentRef(cwd) {
+  const configResult = paperConfig(cwd);
+  if (configResult.error) throw new Error(configResult.error);
+  const parsed = parsePaperVersion(
+    configResult.loaded.config.publication.version,
+  );
+  return `dev/v${parsed.major}/v${parsed.major}.${parsed.minor}`;
+}
+
+export function remoteBranchObservation(cwd, branch) {
+  const result = gitResult(cwd, [
+    "ls-remote",
+    "--heads",
+    "origin",
+    `refs/heads/${branch}`,
+  ]);
+  const sha = result.stdout.split(/\s+/)[0] || "";
+  return {
+    observed: result.ok,
+    ok: result.ok && /^[0-9a-f]{40}$/i.test(sha),
+    sha: /^[0-9a-f]{40}$/i.test(sha) ? sha : "",
+    error: result.error || result.stderr,
+  };
+}
+
+export function paperWorkSource(cwd) {
+  const repository = resolvePaperRepository(cwd);
+  const remotes = gitValue(cwd, ["remote"]).split(/\s+/).filter(Boolean).sort();
+  const originUrl = gitValue(cwd, ["config", "--get", "remote.origin.url"]);
+  const originRepository = normalizeRepository(originUrl);
+  return {
+    repository,
+    remotes,
+    originUrl,
+    originRepository,
+    canonical:
+      remotes.length === 1 &&
+      remotes[0] === "origin" &&
+      Boolean(repository) &&
+      repository === originRepository &&
+      repository.startsWith("kungfu-systems/"),
+    branch: gitValue(cwd, ["branch", "--show-current"]),
+    head: gitValue(cwd, ["rev-parse", "HEAD"]),
+    clean: gitResult(cwd, ["status", "--porcelain"]).stdout === "",
+  };
+}
+
+export function rootedPlan(payload) {
+  return { ...payload, planRoot: sha256Text(stableJson(payload)) };
+}
+
+export function workCheck(id, ok, message, correctiveCommand = "") {
+  return {
+    id,
+    status: ok ? "pass" : "fail",
+    message,
+    correctiveCommand: ok ? "" : correctiveCommand,
+  };
+}
+
+export function normalizedWorkBranch(topic, explicitBranch = "") {
+  const candidate = explicitBranch
+    ? String(explicitBranch).trim()
+    : `feature/${String(topic || "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._/-]+/g, "-")
+        .replace(/^-+|-+$/g, "")}`;
+  return PAPER_WORK_BRANCH_PATTERN.test(candidate) ? candidate : "";
+}