@kungfu-tech/buildchain 3.0.3-alpha.1 → 3.0.3-alpha.2

package/packages/core/paper-repository.js

@@ -0,0 +1,210 @@
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadBuildchainConfig } from "./buildchain-config.js";
+
+export const PAPER_PATHS = Object.freeze({
+  config: ".buildchain/buildchain.toml",
+  versionPin: ".buildchain-version",
+  contractLock: ".buildchain/contract-lock.json",
+  buildWorkflow: ".github/workflows/build.yml",
+  releaseWorkflow: ".github/workflows/paper-release.yml",
+  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 = spawnSync(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 : "";
+}

package/packages/core/paper-work.js

@@ -0,0 +1,365 @@
+import path from "node:path";
+import {
+  PAPER_WORK_BRANCH_PATTERN,
+  gitResult,
+  gitValue,
+  normalizedWorkBranch,
+  paperDevelopmentRef,
+  paperWorkSource,
+  remoteBranchObservation,
+  rootedPlan,
+  workCheck,
+} from "./paper-repository.js";
+
+export const PAPER_WORK_START_PLAN_CONTRACT =
+  "kungfu-buildchain-paper-work-start-plan";
+export const PAPER_WORK_SUBMIT_PLAN_CONTRACT =
+  "kungfu-buildchain-paper-work-submit-plan";
+
+function failedActions(checks) {
+  return checks
+    .filter((entry) => entry.status === "fail")
+    .map((entry) => ({
+      id: `repair-${entry.id}`,
+      command: entry.correctiveCommand,
+      description: entry.message,
+    }));
+}
+
+export function createPaperWorkStartPlan({
+  cwd = process.cwd(),
+  topic = "",
+  branch = "",
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const source = paperWorkSource(resolvedCwd);
+  const targetBranch = normalizedWorkBranch(topic, branch);
+  const developmentRef = paperDevelopmentRef(resolvedCwd);
+  const remoteDevelopment = remoteBranchObservation(
+    resolvedCwd,
+    developmentRef,
+  );
+  const remoteTarget = targetBranch
+    ? remoteBranchObservation(resolvedCwd, targetBranch)
+    : { observed: false, sha: "" };
+  const localTarget = targetBranch
+    ? gitValue(resolvedCwd, [
+        "rev-parse",
+        "--verify",
+        `refs/heads/${targetBranch}`,
+      ])
+    : "";
+  const remoteCommitPresent = remoteDevelopment.sha
+    ? gitResult(resolvedCwd, [
+        "cat-file",
+        "-e",
+        `${remoteDevelopment.sha}^{commit}`,
+      ]).ok
+    : false;
+  const checks = [
+    workCheck(
+      "repository.canonical-origin",
+      source.canonical,
+      "The paper repository has exactly one canonical kungfu-systems origin.",
+      "git remote -v",
+    ),
+    workCheck(
+      "source.clean",
+      source.clean,
+      "The worktree is clean.",
+      "git status --short",
+    ),
+    workCheck(
+      "source.development-ref",
+      source.branch === developmentRef,
+      `The current branch is the configured development ref ${developmentRef}.`,
+      `git switch ${developmentRef}`,
+    ),
+    workCheck(
+      "remote.development-ref",
+      remoteDevelopment.ok,
+      `origin/${developmentRef} resolves to an exact commit.`,
+      `git fetch origin ${developmentRef}`,
+    ),
+    workCheck(
+      "source.remote-aligned",
+      Boolean(remoteDevelopment.sha) && source.head === remoteDevelopment.sha,
+      "HEAD equals the exact remote development commit.",
+      `git fetch origin ${developmentRef} && git merge --ff-only origin/${developmentRef}`,
+    ),
+    workCheck(
+      "source.remote-commit-present",
+      remoteCommitPresent,
+      "The exact remote development commit is present locally.",
+      `git fetch origin ${developmentRef}`,
+    ),
+    workCheck(
+      "target.safe-name",
+      Boolean(targetBranch),
+      "The work branch uses an allowed non-protected prefix and safe slug.",
+      "use feature|fix|docs|chore|ci|refactor/<slug>",
+    ),
+    workCheck(
+      "target.absent",
+      Boolean(targetBranch) &&
+        remoteTarget.observed &&
+        !localTarget &&
+        !remoteTarget.sha,
+      "The work branch does not already exist locally or remotely.",
+      "choose a fresh work branch name",
+    ),
+  ];
+  const ok = checks.every((entry) => entry.status === "pass");
+  return rootedPlan({
+    schemaVersion: 1,
+    contract: PAPER_WORK_START_PLAN_CONTRACT,
+    ok,
+    cwd: resolvedCwd,
+    dryRun: true,
+    source: {
+      ...source,
+      developmentRef,
+      remoteDevelopmentSha: remoteDevelopment.sha,
+    },
+    target: { branch: targetBranch, startSha: remoteDevelopment.sha },
+    checks,
+    mutation: {
+      kind: "local-branch-create",
+      force: false,
+      command: targetBranch
+        ? `git switch -c ${targetBranch} ${remoteDevelopment.sha || `<origin/${developmentRef}>`}`
+        : "",
+    },
+    nextActions: ok
+      ? [
+          {
+            id: "create-work-branch",
+            command: `buildchain paper work start ${targetBranch} --branch ${targetBranch} --execute --json`,
+            description:
+              "Create the local work branch from the exact observed remote development commit.",
+          },
+        ]
+      : failedActions(checks),
+  });
+}
+
+export function executePaperWorkStart(plan) {
+  if (!plan || plan.contract !== PAPER_WORK_START_PLAN_CONTRACT || !plan.ok) {
+    return {
+      ...plan,
+      ok: false,
+      dryRun: false,
+      errorCode: "paper-work-start-blocked",
+    };
+  }
+  const fresh = createPaperWorkStartPlan({
+    cwd: plan.cwd,
+    branch: plan.target.branch,
+  });
+  if (!fresh.ok || fresh.planRoot !== plan.planRoot) {
+    return {
+      ...fresh,
+      ok: false,
+      dryRun: false,
+      errorCode: "paper-work-start-race",
+    };
+  }
+  const switched = gitResult(plan.cwd, [
+    "switch",
+    "-c",
+    plan.target.branch,
+    plan.target.startSha,
+  ]);
+  return {
+    ...fresh,
+    ok: switched.ok,
+    dryRun: false,
+    created: switched.ok,
+    errorCode: switched.ok ? "" : "paper-work-branch-create-failed",
+    stderr: switched.ok ? "" : switched.error || switched.stderr,
+  };
+}
+
+export function createPaperWorkSubmitPlan({
+  cwd = process.cwd(),
+  pullRequests = [],
+  pullRequestObservation = { ok: true },
+} = {}) {
+  const resolvedCwd = path.resolve(cwd);
+  const source = paperWorkSource(resolvedCwd);
+  const developmentRef = paperDevelopmentRef(resolvedCwd);
+  const remoteDevelopment = remoteBranchObservation(
+    resolvedCwd,
+    developmentRef,
+  );
+  const remoteWork = source.branch
+    ? remoteBranchObservation(resolvedCwd, source.branch)
+    : { observed: false, sha: "" };
+  const developmentAncestor =
+    Boolean(remoteDevelopment.sha) &&
+    gitResult(resolvedCwd, [
+      "merge-base",
+      "--is-ancestor",
+      remoteDevelopment.sha,
+      source.head,
+    ]).ok;
+  const remoteWorkAncestor =
+    remoteWork.observed &&
+    (!remoteWork.sha ||
+      gitResult(resolvedCwd, [
+        "merge-base",
+        "--is-ancestor",
+        remoteWork.sha,
+        source.head,
+      ]).ok);
+  const wrongBasePullRequests = pullRequests.filter(
+    (entry) =>
+      entry.headRefName === source.branch &&
+      entry.baseRefName !== developmentRef,
+  );
+  const matchingPullRequest = pullRequests.find(
+    (entry) =>
+      entry.headRefName === source.branch &&
+      entry.baseRefName === developmentRef,
+  );
+  const checks = [
+    workCheck(
+      "repository.canonical-origin",
+      source.canonical,
+      "The paper repository has exactly one canonical kungfu-systems origin.",
+      "git remote -v",
+    ),
+    workCheck(
+      "source.clean",
+      source.clean,
+      "The worktree is clean.",
+      "git status --short",
+    ),
+    workCheck(
+      "source.safe-work-branch",
+      PAPER_WORK_BRANCH_PATTERN.test(source.branch),
+      "The current branch is an allowed non-protected work branch.",
+      "buildchain paper work start <topic>",
+    ),
+    workCheck(
+      "source.committed",
+      /^[0-9a-f]{40}$/i.test(source.head),
+      "The submitted source resolves to an exact commit.",
+      "git status --short",
+    ),
+    workCheck(
+      "remote.development-ref",
+      remoteDevelopment.ok,
+      `origin/${developmentRef} resolves to an exact commit.`,
+      `git fetch origin ${developmentRef}`,
+    ),
+    workCheck(
+      "source.contains-development",
+      developmentAncestor,
+      "The work branch contains the exact remote development commit.",
+      `git fetch origin ${developmentRef} && git rebase origin/${developmentRef}`,
+    ),
+    workCheck(
+      "remote.work-fast-forward",
+      remoteWorkAncestor,
+      "The remote work branch is absent or can be advanced without force.",
+      `git fetch origin ${source.branch}`,
+    ),
+    workCheck(
+      "pull-request.target",
+      wrongBasePullRequests.length === 0,
+      `No open pull request targets a branch other than ${developmentRef}.`,
+      "close or retarget the conflicting pull request",
+    ),
+    workCheck(
+      "pull-request.observed",
+      pullRequestObservation.ok === true,
+      "Open pull requests for the source branch were observed successfully.",
+      "gh auth status",
+    ),
+  ];
+  const ok = checks.every((entry) => entry.status === "pass");
+  return rootedPlan({
+    schemaVersion: 1,
+    contract: PAPER_WORK_SUBMIT_PLAN_CONTRACT,
+    ok,
+    cwd: resolvedCwd,
+    dryRun: true,
+    repository: source.repository,
+    source: {
+      branch: source.branch,
+      sha: source.head,
+      remoteSha: remoteWork.sha,
+    },
+    target: { branch: developmentRef, sha: remoteDevelopment.sha },
+    pullRequest: matchingPullRequest || null,
+    checks,
+    mutation: {
+      kind: "normal-push-and-pull-request",
+      force: false,
+      pushCommand: `git push --set-upstream origin HEAD:refs/heads/${source.branch}`,
+      pullRequestCommand: matchingPullRequest
+        ? ""
+        : `gh pr create --repo ${source.repository} --base ${developmentRef} --head ${source.branch}`,
+    },
+    nextActions: ok
+      ? [
+          {
+            id: matchingPullRequest ? "reuse-pull-request" : "submit-work",
+            command: matchingPullRequest
+              ? ""
+              : "buildchain paper work submit --execute --json",
+            description: matchingPullRequest
+              ? "Continue the existing correctly targeted pull request."
+              : "Push without force and open a pull request to the configured development ref.",
+            url: matchingPullRequest?.url || "",
+          },
+        ]
+      : failedActions(checks),
+  });
+}
+
+export function executePaperWorkSubmitPush(plan) {
+  if (!plan || plan.contract !== PAPER_WORK_SUBMIT_PLAN_CONTRACT || !plan.ok) {
+    return {
+      ...plan,
+      ok: false,
+      dryRun: false,
+      pushed: false,
+      errorCode: "paper-work-submit-blocked",
+    };
+  }
+  const currentHead = gitValue(plan.cwd, ["rev-parse", "HEAD"]);
+  const currentBranch = gitValue(plan.cwd, ["branch", "--show-current"]);
+  const currentClean =
+    gitResult(plan.cwd, ["status", "--porcelain"]).stdout === "";
+  const target = remoteBranchObservation(plan.cwd, plan.target.branch);
+  if (
+    currentHead !== plan.source.sha ||
+    currentBranch !== plan.source.branch ||
+    !currentClean ||
+    target.sha !== plan.target.sha
+  ) {
+    return {
+      ...plan,
+      ok: false,
+      dryRun: false,
+      pushed: false,
+      errorCode: "paper-work-submit-race",
+    };
+  }
+  const pushed = gitResult(plan.cwd, [
+    "push",
+    "--set-upstream",
+    "origin",
+    `HEAD:refs/heads/${plan.source.branch}`,
+  ]);
+  return {
+    ...plan,
+    ok: pushed.ok,
+    dryRun: false,
+    pushed: pushed.ok,
+    errorCode: pushed.ok ? "" : "paper-work-push-failed",
+    stderr: pushed.ok ? "" : pushed.error || pushed.stderr,
+  };
+}