@kungfu-tech/buildchain 4.0.1-alpha.8 → 4.0.1

package/packages/core/paper.js

@@ -38,6 +38,7 @@ import {
   resolvePaperBuildchainSha,
 } from "./paper-agent-entry.js";
 import {
+  createPaperScaffoldOperations,
   managedPaperPackageJson,
   scaffoldMainTex,
   scaffoldMakefile,
@@ -704,207 +705,6 @@ function scaffoldFiles({
   ]);
 }
 
-export function planPaperScaffold({
-  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 = 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 = buildchainPackageIdentity(
-    buildchainRoot,
-    buildchainVersion,
-  );
-  const runtimeSha =
-    buildchainSha ||
-    resolvePaperRuntimeGitSha(buildchainRoot, runtimeIdentity.version);
-  if (!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 = 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: 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;
-}
-
-export function writePaperScaffold(plan) {
-  if (!plan || plan.contract !== 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 migrationFiles({
   cwd,
   buildchainRoot,
@@ -1021,183 +821,17 @@ function migrationFiles({
   return files;
 }
 
-export function planPaperMigration({
-  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 (!GIT_SHA_PATTERN.test(source.head)) {
-    throw new Error("paper migration requires a committed Git source");
-  }
-  const plannedFiles = [
-    ...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: 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;
-}
-
-export function writePaperMigration(plan) {
-  if (!plan || plan.contract !== 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.",
-      },
-    ],
-  };
-}
+const {
+  planPaperMigration,
+  planPaperScaffold,
+  writePaperMigration,
+  writePaperScaffold,
+} = createPaperScaffoldOperations({
+  PAPER_MIGRATION_CONTRACT, PAPER_SCAFFOLD_CONTRACT, GIT_SHA_PATTERN,
+  buildchainPackageIdentity, migrationFiles, normalizePackageName,
+  resolvePaperRuntimeGitSha, scaffoldFiles,
+});
+export { planPaperMigration, planPaperScaffold, writePaperMigration, writePaperScaffold };
 
 function state(id, status, reason, evidence = []) {
   return {