@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.55

package/packages/core/legacy-kfd-adopter-driver.js

@@ -0,0 +1,167 @@
+import {
+  ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+  adopterDeliveryGateDigest,
+  defineAdopterProtocolDriver,
+} from "./adopter-delivery-gate.js";
+import {
+  KFD_LEGACY_SUPPORT_MATRIX_CONTRACT,
+  validateKfdAdopterManifestGate,
+  validateKfdLegacySupportMatrixProjection,
+} from "./kfd-adopter-manifest.js";
+
+export const LEGACY_KFD_ADOPTER_PROTOCOL_ID =
+  "buildchain.kfd-adopter/legacy-support-matrix";
+export const LEGACY_KFD_ADOPTER_PROTOCOL_VERSION = "1.0.0";
+export const LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT =
+  "kungfu-buildchain-legacy-kfd-adopter-driver-report";
+
+function issue(code, path, message) {
+  return { code, path, message };
+}
+
+function normalizedIssues(entries) {
+  return (entries ?? []).map(({ code, path, message }) => ({
+    code,
+    path: path ? `/${path.replaceAll(".", "/")}` : "/declaration",
+    message,
+  }));
+}
+
+function sameJson(left, right) {
+  try {
+    return adopterDeliveryGateDigest(left) === adopterDeliveryGateDigest(right);
+  } catch {
+    return false;
+  }
+}
+
+function bindingIssues(request, manifest) {
+  const issues = [];
+  if (
+    request.project.instanceId !== manifest?.manifestId ||
+    request.project.adopterId !== manifest?.adopter?.id
+  ) {
+    issues.push(
+      issue(
+        "delivery-legacy-project-binding-mismatch",
+        "/project",
+        "Delivery project identity must match the standard adopter manifest.",
+      ),
+    );
+  }
+  if (!sameJson(request.artifact, manifest?.adopter?.artifact)) {
+    issues.push(
+      issue(
+        "delivery-legacy-artifact-binding-mismatch",
+        "/artifact",
+        "Delivery artifact must match the standard adopter manifest artifact.",
+      ),
+    );
+  }
+  return issues;
+}
+
+function invalidContextResult(issues) {
+  const report = {
+    schemaVersion: 1,
+    contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+    valid: false,
+    qualifying: false,
+    selfCertified: false,
+    independentlyCertified: false,
+    manifestRoot: null,
+    manifestGateRoot: null,
+    legacyProjectionRoot: null,
+    legacyProjection: null,
+    adapterIssues: issues,
+    nonClaims: [
+      "The legacy support matrix is a one-way projection, not declaration authority.",
+      "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+    ],
+  };
+  return {
+    valid: false,
+    report,
+    reportRoot: adopterDeliveryGateDigest(report),
+    issues,
+  };
+}
+
+export function createLegacyKfdAdopterProtocolDriver() {
+  return defineAdopterProtocolDriver({
+    interface: ADOPTER_PROTOCOL_DRIVER_INTERFACE,
+    id: LEGACY_KFD_ADOPTER_PROTOCOL_ID,
+    version: LEGACY_KFD_ADOPTER_PROTOCOL_VERSION,
+    verify({ request, context }) {
+      const manifest = context?.adopterManifest;
+      const manifestGate = context?.adopterManifestGate;
+      if (!manifest || !manifestGate) {
+        return invalidContextResult([
+          issue(
+            "delivery-legacy-verification-context-invalid",
+            "/protocol",
+            "The exact standard adopter manifest and manifest gate are required.",
+          ),
+        ]);
+      }
+
+      const source = manifest?.adopter?.artifact?.coordinate?.match(
+        /^([^@\s]+)@([0-9a-f]{40})$/,
+      );
+      const gateValidation = validateKfdAdopterManifestGate(manifestGate, {
+        expectedAdopterId: manifest?.adopter?.id,
+        expectedSourceRepository: source?.[1] ?? "",
+        expectedSourceSha: source?.[2] ?? "",
+        checkedAt: manifestGate?.checkedAt,
+      });
+      const projectionValidation = validateKfdLegacySupportMatrixProjection(
+        request.declaration,
+        { manifest, manifestGate },
+      );
+      const adapterIssues = [
+        ...bindingIssues(request, manifest),
+        ...normalizedIssues(gateValidation.issues),
+        ...normalizedIssues(projectionValidation.issues),
+      ];
+      if (
+        request.declaration?.contract !== KFD_LEGACY_SUPPORT_MATRIX_CONTRACT
+      ) {
+        adapterIssues.push(
+          issue(
+            "delivery-legacy-contract-invalid",
+            "/declaration/contract",
+            `Legacy declaration must use ${KFD_LEGACY_SUPPORT_MATRIX_CONTRACT}.`,
+          ),
+        );
+      }
+
+      const valid =
+        gateValidation.valid &&
+        projectionValidation.valid &&
+        adapterIssues.length === 0;
+      const report = {
+        schemaVersion: 1,
+        contract: LEGACY_KFD_ADOPTER_DRIVER_REPORT_CONTRACT,
+        valid,
+        qualifying: false,
+        selfCertified: false,
+        independentlyCertified: false,
+        manifestRoot: manifestGate?.authority?.manifestRoot ?? null,
+        manifestGateRoot: manifestGate?.gateRoot ?? null,
+        legacyProjectionRoot: adopterDeliveryGateDigest(request.declaration),
+        legacyProjection: structuredClone(request.declaration),
+        adapterIssues,
+        nonClaims: [
+          "The legacy support matrix is a one-way projection, not declaration authority.",
+          "Buildchain carries the existing standard manifest decision and does not certify KFD adoption.",
+        ],
+      };
+      return {
+        valid,
+        report,
+        reportRoot: adopterDeliveryGateDigest(report),
+        issues: adapterIssues,
+      };
+    },
+  });
+}

package/packages/core/paper-scaffold-content.js

@@ -1,3 +1,11 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  gitResult,
+  gitValue,
+  normalizeRepository,
+  sha256Text,
+} from "./paper-repository.js";
 function jsonText(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -161,3 +169,396 @@ Replace this section with the reviewed paper content.
 \\end{document}
 `;
 }
+function planPaperScaffold(
+  runtime,
+  {
+    cwd = process.cwd(),
+    buildchainRoot = process.cwd(),
+    buildchainVersion = "",
+    buildchainRef = "v3",
+    buildchainSha = "",
+    name = path.basename(path.resolve(cwd)),
+    title = "",
+    packageName = "",
+    repository = "",
+    version = "0.1.0-alpha.0",
+    siteBaseUrl = "",
+  } = {},
+) {
+  const resolvedCwd = path.resolve(cwd);
+  const normalizedName = String(name || "").trim();
+  if (!normalizedName) throw new Error("paper scaffold requires --name");
+  const normalizedPackage = runtime.normalizePackageName(packageName);
+  const normalizedRepository = normalizeRepository(repository);
+  if (!normalizedRepository) {
+    throw new Error("paper scaffold requires --repository <owner/repo>");
+  }
+  const normalizedVersion = String(version || "")
+    .trim()
+    .replace(/^v/, "");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(normalizedVersion)) {
+    throw new Error("paper scaffold --version must be semver");
+  }
+  const runtimeIdentity = runtime.buildchainPackageIdentity(
+    buildchainRoot,
+    buildchainVersion,
+  );
+  const runtimeSha =
+    buildchainSha ||
+    runtime.resolvePaperRuntimeGitSha(buildchainRoot, runtimeIdentity.version);
+  if (!runtime.GIT_SHA_PATTERN.test(runtimeSha)) {
+    throw new Error(
+      "paper scaffold cannot resolve the exact Buildchain runtime SHA; pass buildchainSha or use a published Buildchain package with npm gitHead provenance",
+    );
+  }
+  const files = runtime.scaffoldFiles({
+    buildchainRoot,
+    buildchainVersion: runtimeIdentity.version,
+    buildchainRef,
+    buildchainSha: runtimeSha,
+    cwd: resolvedCwd,
+    name: normalizedName,
+    title: title || normalizedName,
+    packageName: normalizedPackage,
+    repository: normalizedRepository,
+    version: normalizedVersion,
+    siteBaseUrl,
+  });
+  const changes = [...files.entries()].map(([relativePath, content]) => {
+    const filePath = path.resolve(resolvedCwd, relativePath);
+    const exists = fs.existsSync(filePath);
+    if (!exists) {
+      return {
+        path: relativePath,
+        action: "create",
+        sha256: sha256Text(content),
+        content,
+      };
+    }
+    if (!fs.statSync(filePath).isFile()) {
+      return {
+        path: relativePath,
+        action: "conflict",
+        reason: "path-exists-and-is-not-a-file",
+        sha256: sha256Text(content),
+        content,
+      };
+    }
+    const current = fs.readFileSync(filePath, "utf8");
+    return current === content
+      ? {
+          path: relativePath,
+          action: "unchanged",
+          sha256: sha256Text(content),
+          content,
+        }
+      : {
+          path: relativePath,
+          action: "conflict",
+          reason: "existing-content-differs",
+          currentSha256: sha256Text(current),
+          sha256: sha256Text(content),
+          content,
+        };
+  });
+  const publicChanges = changes.map(({ content: _content, ...entry }) => entry);
+  const conflicts = publicChanges.filter(
+    (entry) => entry.action === "conflict",
+  );
+  const result = {
+    schemaVersion: 1,
+    contract: runtime.PAPER_SCAFFOLD_CONTRACT,
+    ok: conflicts.length === 0,
+    cwd: resolvedCwd,
+    dryRun: true,
+    identity: {
+      project: normalizedName,
+      title: title || normalizedName,
+      package: normalizedPackage,
+      repository: normalizedRepository,
+      version: normalizedVersion,
+    },
+    buildchain: {
+      version: runtimeIdentity.version,
+      ref: runtimeSha,
+      resolvedSha: runtimeSha,
+    },
+    summary: {
+      create: publicChanges.filter((entry) => entry.action === "create").length,
+      unchanged: publicChanges.filter((entry) => entry.action === "unchanged")
+        .length,
+      conflict: conflicts.length,
+    },
+    changes: publicChanges,
+    conflicts,
+    nextActions:
+      conflicts.length > 0
+        ? [
+            {
+              id: "resolve-scaffold-conflicts",
+              command: "",
+              description:
+                "Resolve the listed semantic conflicts; scaffold never overwrites them.",
+            },
+          ]
+        : [
+            {
+              id: "write-scaffold",
+              command: "buildchain paper scaffold --write <same arguments>",
+              description:
+                "Write only missing files after the conflict-free plan is reviewed.",
+            },
+          ],
+  };
+  Object.defineProperty(result, "_plannedFiles", {
+    value: changes,
+    enumerable: false,
+  });
+  return result;
+}
+
+function writePaperScaffold(runtime, plan) {
+  if (!plan || plan.contract !== runtime.PAPER_SCAFFOLD_CONTRACT) {
+    throw new Error("paper scaffold plan contract mismatch");
+  }
+  if (!plan.ok || plan.conflicts.length > 0) {
+    return {
+      ...plan,
+      dryRun: false,
+      written: [],
+      ok: false,
+      errorCode: "paper-scaffold-conflict",
+    };
+  }
+  const resolvedCwd = path.resolve(plan.cwd);
+  const creates = plan._plannedFiles.filter(
+    (entry) => entry.action === "create",
+  );
+  for (const entry of creates) {
+    const target = path.resolve(resolvedCwd, entry.path);
+    if (fs.existsSync(target)) {
+      const current = fs.statSync(target).isFile()
+        ? fs.readFileSync(target, "utf8")
+        : undefined;
+      if (current !== entry.content) {
+        throw new Error(
+          `paper scaffold race detected at ${entry.path}; no file was overwritten`,
+        );
+      }
+      continue;
+    }
+  }
+  const written = [];
+  for (const entry of creates) {
+    const target = path.resolve(resolvedCwd, entry.path);
+    if (fs.existsSync(target)) continue;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, entry.content, { flag: "wx" });
+    written.push(entry.path);
+  }
+  return {
+    ...plan,
+    ok: true,
+    dryRun: false,
+    written,
+    idempotent: written.length === 0,
+    nextActions: [
+      {
+        id: "paper-preflight",
+        command: `buildchain paper preflight --cwd ${JSON.stringify(resolvedCwd)} --json`,
+        description:
+          "Verify the generated repository before any external mutation.",
+      },
+    ],
+  };
+}
+
+function planPaperMigration(
+  runtime,
+  {
+    cwd = process.cwd(),
+    buildchainRoot = process.cwd(),
+    buildchainVersion = "",
+    buildchainSha = "",
+  } = {},
+) {
+  const resolvedCwd = path.resolve(cwd);
+  const repositoryRoot = gitValue(resolvedCwd, [
+    "rev-parse",
+    "--show-toplevel",
+  ]);
+  const repositoryPrefix = gitValue(resolvedCwd, [
+    "rev-parse",
+    "--show-prefix",
+  ]).replace(/\/+$/u, "");
+  if (!repositoryRoot || repositoryPrefix) {
+    throw new Error("paper migration must target the exact repository root");
+  }
+  const source = {
+    head: gitValue(resolvedCwd, ["rev-parse", "HEAD"]),
+    clean: gitResult(resolvedCwd, ["status", "--porcelain"]).stdout === "",
+  };
+  if (!runtime.GIT_SHA_PATTERN.test(source.head)) {
+    throw new Error("paper migration requires a committed Git source");
+  }
+  const plannedFiles = [
+    ...runtime.migrationFiles({
+      cwd: resolvedCwd,
+      buildchainRoot,
+      buildchainVersion,
+      buildchainSha,
+    }),
+  ].map(([relativePath, content]) => {
+    const target = path.resolve(resolvedCwd, relativePath);
+    if (fs.existsSync(target) && !fs.statSync(target).isFile()) {
+      return {
+        path: relativePath,
+        action: "conflict",
+        currentSha256: "",
+        sha256: sha256Text(content),
+        content,
+      };
+    }
+    const current = fs.existsSync(target)
+      ? fs.readFileSync(target, "utf8")
+      : undefined;
+    return {
+      path: relativePath,
+      action:
+        current === undefined
+          ? "create"
+          : current === content
+            ? "unchanged"
+            : "update",
+      currentSha256: current === undefined ? "" : sha256Text(current),
+      sha256: sha256Text(content),
+      content,
+    };
+  });
+  const changes = plannedFiles.map(({ content: _content, ...entry }) => entry);
+  const conflicts = changes.filter((entry) => entry.action === "conflict");
+  const ok = source.clean && conflicts.length === 0;
+  const result = {
+    schemaVersion: 1,
+    contract: runtime.PAPER_MIGRATION_CONTRACT,
+    ok,
+    cwd: resolvedCwd,
+    dryRun: true,
+    source,
+    summary: {
+      create: changes.filter((entry) => entry.action === "create").length,
+      update: changes.filter((entry) => entry.action === "update").length,
+      unchanged: changes.filter((entry) => entry.action === "unchanged").length,
+      conflict: conflicts.length,
+    },
+    changes,
+    conflicts,
+    nextActions: !source.clean
+      ? [
+          {
+            id: "commit-source",
+            command: "git status --short",
+            description:
+              "Migration only rewrites Buildchain-owned control files from a clean committed source.",
+          },
+        ]
+      : conflicts.length > 0
+        ? [
+            {
+              id: "resolve-migration-conflicts",
+              command: "",
+              description:
+                "Resolve non-file targets; migration never replaces a directory or special path.",
+            },
+          ]
+        : [
+            {
+              id: "write-migration",
+              command: "buildchain paper migrate --write --json",
+              description:
+                "Write the reviewed Buildchain-owned control files without changing paper content or publication configuration.",
+            },
+            {
+              id: "refresh-pnpm-lock",
+              command: "pnpm install --lockfile-only",
+              description:
+                "Bind the exact Buildchain semantic dependency into pnpm-lock.yaml after the reviewed package update.",
+            },
+          ],
+  };
+  Object.defineProperty(result, "_plannedFiles", {
+    value: plannedFiles,
+    enumerable: false,
+  });
+  return result;
+}
+
+function writePaperMigration(runtime, plan) {
+  if (!plan || plan.contract !== runtime.PAPER_MIGRATION_CONTRACT) {
+    throw new Error("paper migration plan contract mismatch");
+  }
+  if (!plan.ok) {
+    return {
+      ...plan,
+      dryRun: false,
+      written: [],
+      updated: [],
+      ok: false,
+      errorCode: "paper-migration-blocked",
+    };
+  }
+  const written = [];
+  const updated = [];
+  for (const entry of plan._plannedFiles) {
+    if (entry.action === "unchanged") continue;
+    const target = path.resolve(plan.cwd, entry.path);
+    const exists = fs.existsSync(target);
+    const current =
+      exists && fs.statSync(target).isFile()
+        ? fs.readFileSync(target, "utf8")
+        : undefined;
+    const currentSha256 = current === undefined ? "" : sha256Text(current);
+    if (
+      (entry.action === "create" && exists) ||
+      (entry.action === "update" && currentSha256 !== entry.currentSha256)
+    ) {
+      throw new Error(
+        `paper migration race detected at ${entry.path}; no stale plan was applied`,
+      );
+    }
+  }
+  for (const entry of plan._plannedFiles) {
+    if (entry.action === "unchanged") continue;
+    const target = path.resolve(plan.cwd, entry.path);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, entry.content, {
+      flag: entry.action === "create" ? "wx" : "w",
+    });
+    (entry.action === "create" ? written : updated).push(entry.path);
+  }
+  return {
+    ...plan,
+    ok: true,
+    dryRun: false,
+    written,
+    updated,
+    idempotent: written.length === 0 && updated.length === 0,
+    nextActions: [
+      {
+        id: "paper-preflight",
+        command: `buildchain paper preflight --cwd ${JSON.stringify(plan.cwd)} --offline --json`,
+        description:
+          "Verify the migrated repository before any external mutation.",
+      },
+    ],
+  };
+}
+
+export function createPaperScaffoldOperations(runtime) {
+  return {
+    planPaperMigration: (options) => planPaperMigration(runtime, options),
+    planPaperScaffold: (options) => planPaperScaffold(runtime, options),
+    writePaperMigration: (plan) => writePaperMigration(runtime, plan),
+    writePaperScaffold: (plan) => writePaperScaffold(runtime, plan),
+  };
+}