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

package/packages/core/paper-fleet.js

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+import { planPaperMigration, writePaperMigration } from "./paper.js";
+import {
+  PAPER_PATHS,
+  PAPER_WORK_BRANCH_PATTERN,
+  gitValue,
+  paperWorkSource,
+  readJson,
+  rootedPlan,
+  sha256Text,
+  stableJson,
+  workCheck,
+} from "./paper-repository.js";
+
+export const PAPER_FLEET_AUDIT_CONTRACT = "kungfu-buildchain-paper-fleet-audit";
+export const PAPER_FLEET_UPDATE_PLAN_CONTRACT =
+  "kungfu-buildchain-paper-fleet-update-plan";
+
+export function discoverPaperFleet(root = process.cwd()) {
+  const resolvedRoot = path.resolve(root);
+  if (
+    !fs.existsSync(resolvedRoot) ||
+    !fs.statSync(resolvedRoot).isDirectory()
+  ) {
+    throw new Error("paper fleet root must be an existing directory");
+  }
+  return fs
+    .readdirSync(resolvedRoot, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        entry.name.startsWith("paper-") &&
+        fs.existsSync(path.join(resolvedRoot, entry.name, ".git")),
+    )
+    .map((entry) => path.join(resolvedRoot, entry.name))
+    .sort();
+}
+
+function plannedManagedSurfaces(options) {
+  try {
+    const plan = planPaperMigration(options);
+    return { changes: plan.changes, error: "" };
+  } catch (error) {
+    return { changes: [], error: error.message };
+  }
+}
+
+function paperFleetEntry({
+  cwd,
+  buildchainRoot,
+  buildchainVersion,
+  buildchainSha,
+}) {
+  const source = paperWorkSource(cwd);
+  const packageJson = readJson(path.resolve(cwd, "package.json")).value || {};
+  const pinPath = path.resolve(cwd, PAPER_PATHS.versionPin);
+  const lockPath = path.resolve(cwd, "pnpm-lock.yaml");
+  const expected = plannedManagedSurfaces({
+    cwd,
+    buildchainRoot,
+    buildchainVersion,
+    buildchainSha,
+  });
+  const managed = expected.changes.map((entry) => ({
+    path: entry.path,
+    status:
+      entry.action === "unchanged"
+        ? "current"
+        : entry.action === "create"
+          ? "missing"
+          : "drifted",
+    expectedSha256: entry.sha256,
+    currentSha256: entry.currentSha256,
+  }));
+  const dependency =
+    packageJson.devDependencies?.["@kungfu-tech/buildchain"] || "";
+  const lockText = fs.existsSync(lockPath)
+    ? fs.readFileSync(lockPath, "utf8")
+    : "";
+  const checks = [
+    workCheck(
+      "repository.canonical-origin",
+      source.canonical,
+      "Repository identity resolves to the canonical kungfu-systems origin.",
+      "git remote -v",
+    ),
+    workCheck(
+      "package.buildchain-v3",
+      dependency === buildchainVersion && /^3\./.test(dependency),
+      "package.json pins the exact Buildchain v3 runtime.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "package.pnpm-lock",
+      Boolean(lockText) &&
+        lockText.includes("@kungfu-tech/buildchain") &&
+        lockText.includes(buildchainVersion),
+      "pnpm-lock.yaml binds the Buildchain dependency.",
+      "pnpm install --lockfile-only",
+    ),
+    workCheck(
+      "runtime.version-pin",
+      fs.existsSync(pinPath) &&
+        fs.readFileSync(pinPath, "utf8").trim() === buildchainVersion,
+      "The repository version pin equals the exact Buildchain runtime.",
+      "buildchain paper migrate --write --json",
+    ),
+    workCheck(
+      "managed-surfaces.current",
+      !expected.error && managed.every((entry) => entry.status === "current"),
+      "Every Buildchain-owned paper control surface matches v3.",
+      "buildchain paper migrate --write --json",
+    ),
+  ];
+  return {
+    name: path.basename(cwd),
+    cwd,
+    repository: source.repository,
+    branch: source.branch,
+    head: source.head,
+    clean: source.clean,
+    package: packageJson.name || "",
+    buildchainDependency: dependency,
+    expectedError: expected.error,
+    managed,
+    checks,
+    ok: checks.every((entry) => entry.status === "pass"),
+  };
+}
+
+export function collectPaperFleetAudit({
+  root = process.cwd(),
+  repositories = [],
+  buildchainRoot = process.cwd(),
+  buildchainVersion = "",
+  buildchainSha = "",
+  governance = {},
+} = {}) {
+  const resolvedRoot = path.resolve(root);
+  const paths = (
+    repositories.length > 0
+      ? repositories.map((entry) => path.resolve(entry))
+      : discoverPaperFleet(resolvedRoot)
+  ).sort();
+  const entries = paths.map((cwd) =>
+    paperFleetEntry({ cwd, buildchainRoot, buildchainVersion, buildchainSha }),
+  );
+  const governanceEntries = entries.map((entry) => ({
+    repository: entry.repository,
+    ...(governance[entry.repository] || { status: "unobserved" }),
+  }));
+  const payload = {
+    schemaVersion: 1,
+    contract: PAPER_FLEET_AUDIT_CONTRACT,
+    ok:
+      entries.length > 0 &&
+      entries.every((entry) => entry.ok) &&
+      governanceEntries.every((entry) =>
+        ["pass", "unobserved"].includes(entry.status),
+      ),
+    root: resolvedRoot,
+    runtime: {
+      version: buildchainVersion,
+      sha: buildchainSha || gitValue(buildchainRoot, ["rev-parse", "HEAD"]),
+    },
+    summary: {
+      repositories: entries.length,
+      current: entries.filter((entry) => entry.ok).length,
+      drifted: entries.filter((entry) => !entry.ok).length,
+      governanceObserved: governanceEntries.filter(
+        (entry) => entry.status !== "unobserved",
+      ).length,
+    },
+    repositories: entries,
+    governance: governanceEntries,
+  };
+  return { ...payload, auditRoot: sha256Text(stableJson(payload)) };
+}
+
+export function planPaperFleetUpdate(options = {}) {
+  const audit = collectPaperFleetAudit(options);
+  const plans = audit.repositories.map((entry) => {
+    if (!PAPER_WORK_BRANCH_PATTERN.test(entry.branch)) {
+      return {
+        contract: "kungfu-buildchain-paper-migration",
+        ok: false,
+        cwd: entry.cwd,
+        dryRun: true,
+        error:
+          "paper fleet update requires an allowed non-protected work branch",
+        changes: [],
+      };
+    }
+    try {
+      return planPaperMigration({
+        cwd: entry.cwd,
+        buildchainRoot: options.buildchainRoot,
+        buildchainVersion: options.buildchainVersion,
+        buildchainSha: options.buildchainSha,
+      });
+    } catch (error) {
+      return {
+        contract: "kungfu-buildchain-paper-migration",
+        ok: false,
+        cwd: entry.cwd,
+        dryRun: true,
+        error: error.message,
+        changes: [],
+      };
+    }
+  });
+  const ok = plans.length > 0 && plans.every((entry) => entry.ok);
+  return rootedPlan({
+    schemaVersion: 1,
+    contract: PAPER_FLEET_UPDATE_PLAN_CONTRACT,
+    ok,
+    root: audit.root,
+    dryRun: true,
+    auditRoot: audit.auditRoot,
+    runtime: audit.runtime,
+    plans,
+    nextActions: ok
+      ? [
+          {
+            id: "write-fleet-update",
+            command: "buildchain paper fleet update --write --json",
+            description:
+              "Apply only reviewed Buildchain-owned control surfaces, then refresh each pnpm lockfile.",
+          },
+        ]
+      : [
+          {
+            id: "repair-blocked-repositories",
+            command: "git status --short",
+            description:
+              "Fleet update requires every target repository to be clean and rooted exactly.",
+          },
+        ],
+  });
+}
+
+export function writePaperFleetUpdate(plan) {
+  if (!plan || plan.contract !== PAPER_FLEET_UPDATE_PLAN_CONTRACT || !plan.ok) {
+    return {
+      ...plan,
+      ok: false,
+      dryRun: false,
+      results: [],
+      errorCode: "paper-fleet-update-blocked",
+    };
+  }
+  const results = plan.plans.map((entry) => writePaperMigration(entry));
+  return {
+    ...plan,
+    ok: results.every((entry) => entry.ok),
+    dryRun: false,
+    results,
+  };
+}

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 : "";
+}