@kb-labs/release-manager-core 2.116.13 → 2.117.0

package/dist/index.d.ts

@@ -9,6 +9,19 @@ interface PluginLogger {
     warn?(message: string, meta?: Record<string, unknown>): void;
     error?(message: string, error?: Error, meta?: Record<string, unknown>): void;
 }
+/** Governed process facade supplied by the plugin runtime. */
+interface ReleaseShell {
+    exec(command: string, args?: string[], options?: {
+        cwd?: string;
+        timeout?: number;
+        env?: Record<string, string>;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+        ok: boolean;
+    }>;
+}
 type ReleaseStage = 'planning' | 'checking' | 'versioning' | 'publishing' | 'verifying' | 'rollback';
 type VersionBump = 'patch' | 'minor' | 'major' | 'auto';
 /**
@@ -38,6 +51,14 @@ interface PackageVersion {
     bump: VersionBump;
     isPublished: boolean;
     dependencies?: string[];
+    /**
+     * `nextVersion` was adopted as-is from a bump that already exists on disk
+     * (see the trust-disk branch in planner.ts) rather than derived by bumping
+     * `currentVersion`. Downstream version resolution — notably lockstep — must
+     * treat it as final: re-deriving it would bump a second time on top of an
+     * already-applied bump.
+     */
+    versionPinned?: boolean;
 }
 interface ReleasePlan {
     packages: PackageVersion[];
@@ -45,6 +66,14 @@ interface ReleasePlan {
     registry: string;
     rollbackEnabled: boolean;
     channel: ReleaseChannel;
+    /**
+     * The flow/scope this plan was computed for. Persisted with the plan
+     * artifact so a later pipeline step can tell whether the plan on disk is
+     * the one it is supposed to consume, instead of silently reusing another
+     * flow's plan (all flows share one scope-derived artifact path).
+     */
+    flow?: string;
+    scope?: string;
 }
 interface CheckResultDetails {
     /** Which package path this failure came from (for perPackage checks). */
@@ -61,6 +90,8 @@ interface CheckResultDetails {
 interface CheckResult {
     id: CheckId;
     ok: boolean;
+    /** Mirrors CustomCheckConfig.optional — a failed optional check must not fail the overall run. */
+    optional?: boolean;
     /** Structured failure details — present when ok=false. */
     details?: CheckResultDetails;
     hint?: string;
@@ -360,6 +391,7 @@ interface PipelineOptions {
     /** Pass --no-verify to git push and pushTags. Default: false (hooks run normally). */
     noVerify?: boolean;
     logger?: PluginLogger;
+    shell: ReleaseShell;
     onProgress?: (stage: ReleaseStage, message: string) => void;
 }
 interface PipelineResult {
@@ -655,29 +687,20 @@ declare function runReleasePipeline(options: PipelineOptions): Promise<PipelineR
  * dependant can fail to resolve the dependency's subpath exports in a
  * fresh worktree where nothing has a pre-existing dist/ yet.
  */
-declare function buildPackages(packages: PackageVersion[], options?: {
+declare function buildPackages(packages: PackageVersion[], options: {
     logger?: PluginLogger;
+    shell: ReleaseShell;
     onProgress?: (pkg: string, result: BuildResult) => void;
 }): Promise<BuildResult[]>;
 /**
  * Run build for a single package using safe temp-dir strategy when tsup is detected.
  * Falls back to regular `pnpm run build` for non-tsup packages.
  */
-declare function runSafeBuild(packagePath: string, packageName: string): Promise<BuildResult>;
+declare function runSafeBuild(packagePath: string, packageName: string, shell: ReleaseShell): Promise<BuildResult>;
 /**
  * Check if a shell command is a build command that should use safe build.
  */
 declare function isBuildCommand(command: string, args?: string[]): boolean;
-interface SpawnResult extends Omit<BuildResult, 'name'> {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}
-/**
- * Spawn a shell command and collect results.
- * Captures both stdout and stderr — build tools often write errors to stdout.
- */
-declare function spawnCommand(command: string, cwd: string, timeoutMs?: number): Promise<SpawnResult>;
 
 /**
  * Unified check runner for release manager.
@@ -689,7 +712,21 @@ interface CheckRunnerOptions {
     packagePaths: string[];
     scopePath?: string;
     logger?: Pick<PluginLogger, 'info' | 'warn'>;
+    shell: ReleaseShell;
 }
+/**
+ * Max parallel shell.exec calls for perPackage checks.
+ * Must match the plugin manifest's `shell.maxConcurrent` permission
+ * (plugins/release/manager-cli/src/manifest.ts) — the platform's process
+ * broker admits at most that many concurrent shells for this plugin, so
+ * batching above it just queues and can blow the per-check timeout.
+ *
+ * Kept low (not e.g. 8) because pack-install is not a cheap script: it packs
+ * the tarball and runs a real `npm install` of it into a throwaway consumer
+ * per package. At higher concurrency those installs contend for CPU/disk/npm
+ * registry and start blowing their own per-check timeout under load.
+ */
+declare const CHECKS_CONCURRENCY = 2;
 /**
  * Run all configured checks against packages.
  * Handles: parser evaluation, script path resolution, perPackage/scopePath/repoRoot routing.
@@ -821,4 +858,4 @@ declare function verifyCleanInstall(tarballPath: string, packageName: string, ad
  */
 declare function resolveScopePath(repoRoot: string, scope: string): Promise<string>;
 
-export { type AuditSummary, type BuildConfig, type BuildResult, type ChangelogGenerator, type CheckId, type CheckResult, type CheckResultDetails, type CleanInstallResult, type CustomCheckConfig, DEFAULT_ROOT_CHANGELOG_PATH, DEFAULT_TAG_PATTERN, type FlowConfig, type PackagePublisher, type PackageVersion, type PackagesFilter, type PipelineOptions, type PipelineResult, type PlannerOptions, type PluginLogger, type PublishResult, type PublishablePackage, type ReleaseChannel, type ReleaseConfig, type ReleaseContext, type ReleasePlan, type ReleaseReport, type ReleaseResult, type ReleaseStage, type RollbackSnapshot, type StrategyOptions, type VerifyResult, type VersionBump, type VersionStrategy, applyCanarySuffix, applyVersionStrategy, buildPackages, buildReleaseTag, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, findForbiddenDependencyProtocols, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyCleanInstall, verifyExtractedTarball, verifyPackage, verifyPackages };
+export { type AuditSummary, type BuildConfig, type BuildResult, CHECKS_CONCURRENCY, type ChangelogGenerator, type CheckId, type CheckResult, type CheckResultDetails, type CleanInstallResult, type CustomCheckConfig, DEFAULT_ROOT_CHANGELOG_PATH, DEFAULT_TAG_PATTERN, type FlowConfig, type PackagePublisher, type PackageVersion, type PackagesFilter, type PipelineOptions, type PipelineResult, type PlannerOptions, type PluginLogger, type PublishResult, type PublishablePackage, type ReleaseChannel, type ReleaseConfig, type ReleaseContext, type ReleasePlan, type ReleaseReport, type ReleaseResult, type ReleaseShell, type ReleaseStage, type RollbackSnapshot, type StrategyOptions, type VerifyResult, type VersionBump, type VersionStrategy, applyCanarySuffix, applyVersionStrategy, buildPackages, buildReleaseTag, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, findForbiddenDependencyProtocols, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyCleanInstall, verifyExtractedTarball, verifyPackage, verifyPackages };

package/dist/index.js

@@ -6,9 +6,9 @@ import semver2 from 'semver';
 import globby from 'globby';
 import { discoverSubRepoPaths, useEnv } from '@kb-labs/sdk';
 import { execa } from 'execa';
-import { spawn, spawnSync } from 'child_process';
 import { tmpdir } from 'os';
 import { randomBytes } from 'crypto';
+import { spawnSync } from 'child_process';
 
 // src/planner.ts
 function applyVersionStrategy(packages, options) {
@@ -24,12 +24,16 @@ function applyLockstep(packages) {
   if (packages.length === 0) {
     return packages;
   }
-  const alreadyPublished = packages.filter((p) => p.isPublished);
-  if (alreadyPublished.length > 0) {
-    const sharedVersion = alreadyPublished.reduce(
-      (max, p) => semver2.gt(p.nextVersion, max) ? p.nextVersion : max,
-      alreadyPublished[0].nextVersion
-    );
+  const pinned = packages.filter((p) => p.isPublished || p.versionPinned);
+  if (pinned.length > 0) {
+    const resolved = [...new Set(pinned.map((p) => p.nextVersion))];
+    if (resolved.length > 1) {
+      const detail = pinned.map((p) => `${p.name}@${p.nextVersion}`).join(", ");
+      throw new Error(
+        `Lockstep release has conflicting already-resolved versions: ${resolved.join(", ")} (${detail}). Reconcile package.json versions before releasing.`
+      );
+    }
+    const sharedVersion = resolved[0];
     return packages.map((pkg) => ({ ...pkg, nextVersion: sharedVersion }));
   }
   const maxBump = getMaxBump(packages);
@@ -214,16 +218,19 @@ async function planRelease(options) {
     })() : null;
     if (headVersion && headVersion !== pkg.currentVersion) {
       const alreadyPublished = await isVersionPublished(pkg.name, pkg.currentVersion, registry);
-      if (alreadyPublished) {
-        planPackages.push({
-          ...pkg,
-          gitRoot,
-          nextVersion: pkg.currentVersion,
-          bump: detectBumpType(headVersion, pkg.currentVersion),
-          isPublished: true
-        });
-        continue;
-      }
+      planPackages.push({
+        ...pkg,
+        gitRoot,
+        nextVersion: pkg.currentVersion,
+        bump: detectBumpType(headVersion, pkg.currentVersion),
+        isPublished: alreadyPublished,
+        // Mark the version as final so lockstep/adaptive resolution below
+        // doesn't re-derive (and thus re-bump) it. `isPublished` alone is not
+        // enough to signal this: the bump can legitimately be on disk but not
+        // yet published — exactly the `release:version` → `release:git` case.
+        versionPinned: true
+      });
+      continue;
     }
     const nextVersion = await computeNextVersion(
       pkg.path,
@@ -256,7 +263,9 @@ async function planRelease(options) {
     strategy: config.strategy || "semver",
     registry: config.registry || "https://registry.npmjs.org",
     rollbackEnabled: config.rollback?.enabled ?? true,
-    channel
+    channel,
+    flow: options.flow,
+    scope
   };
 }
 function mapBumpStrategyToVersionStrategy(bumpStrategy) {
@@ -625,6 +634,12 @@ function mergeChangelogBlock(existingChangelog, newBlock, versionPattern) {
   }
   return newBlock + (existingChangelog ? "\n" + existingChangelog : "");
 }
+function removeHistoricalDuplicateBullets(existingChangelog, newBlock) {
+  const historicalBullets = new Set(
+    existingChangelog.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- "))
+  );
+  return newBlock.split("\n").filter((line) => !line.trim().startsWith("- ") || !historicalBullets.has(line.trim())).join("\n");
+}
 var DEFAULT_ROOT_CHANGELOG_PATH = ".kb/release/CHANGELOG.md";
 function resolveRootChangelogRelPath(outputPath) {
   return outputPath && outputPath.trim().length > 0 ? outputPath : DEFAULT_ROOT_CHANGELOG_PATH;
@@ -647,7 +662,8 @@ async function mergeRootChangelog(options) {
     existingChangelog = await readFile(changelogPath, "utf-8");
   } catch {
   }
-  const updatedChangelog = mergeChangelogBlock(existingChangelog, changelog.trim(), versionPattern);
+  const deduplicatedBlock = versionPattern.test(existingChangelog) ? changelog.trim() : removeHistoricalDuplicateBullets(existingChangelog, changelog.trim());
+  const updatedChangelog = mergeChangelogBlock(existingChangelog, deduplicatedBlock, versionPattern);
   await mkdir(dirname(changelogPath), { recursive: true });
   await writeFile(changelogPath, updatedChangelog.trim() + "\n", "utf-8");
 }
@@ -1101,7 +1117,7 @@ async function buildPackages(packages, options) {
   const ordered = topoSortForBuild(packages);
   for (const pkg of ordered) {
     options?.logger?.info?.(`Building ${pkg.name}...`);
-    const result = await runSafeBuild(pkg.path, pkg.name);
+    const result = await runSafeBuild(pkg.path, pkg.name, options.shell);
     results.push({ ...result, name: pkg.name });
     options?.onProgress?.(pkg.name, { ...result, name: pkg.name });
     if (!result.success) {
@@ -1112,25 +1128,25 @@ async function buildPackages(packages, options) {
   }
   return results;
 }
-async function runSafeBuild(packagePath, packageName) {
+async function runSafeBuild(packagePath, packageName, shell) {
   const usesTsup = existsSync(join(packagePath, "tsup.config.ts")) || existsSync(join(packagePath, "tsup.config.js"));
   if (usesTsup) {
-    return runTsupSafeBuild(packagePath, packageName);
+    return runTsupSafeBuild(packagePath, packageName, shell);
   }
-  return runDirectBuild(packagePath, packageName);
+  return runDirectBuild(packagePath, packageName, shell);
 }
 function isBuildCommand(command, args) {
   const full = [command, ...args ?? []].join(" ").trim();
   return /\b(pnpm|npm|yarn)\s+(run\s+)?build\b/.test(full);
 }
-async function runTsupSafeBuild(packagePath, packageName) {
+async function runTsupSafeBuild(packagePath, packageName, shell) {
   const startTime = Date.now();
   const buildId = randomBytes(6).toString("hex");
   const tempDir = join(tmpdir(), `kb-release-build-${buildId}`);
   const distDir = join(packagePath, "dist");
   const backupDir = join(packagePath, `dist.bak-${buildId}`);
   try {
-    const buildResult = await spawnCommand(`npx tsup -d ${tempDir}`, packagePath);
+    const buildResult = await executeCommand(shell, "npx", ["tsup", "-d", tempDir], packagePath, 5 * 60 * 1e3);
     if (!buildResult.success) {
       await rm(tempDir, { recursive: true, force: true }).catch(() => {
       });
@@ -1164,54 +1180,25 @@ async function runTsupSafeBuild(packagePath, packageName) {
     };
   }
 }
-async function runDirectBuild(packagePath, packageName) {
-  const result = await spawnCommand("pnpm run build", packagePath);
+async function runDirectBuild(packagePath, packageName, shell) {
+  const result = await executeCommand(shell, "pnpm", ["run", "build"], packagePath, 5 * 60 * 1e3);
   return { ...result, name: packageName };
 }
-function spawnCommand(command, cwd, timeoutMs = 5 * 60 * 1e3) {
+async function executeCommand(shell, command, args, cwd, timeoutMs) {
   const startTime = Date.now();
-  return new Promise((resolve3) => {
-    const child = spawn(command, [], {
-      cwd,
-      stdio: "pipe",
-      shell: true,
-      env: { ...process.env }
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout?.on("data", (data) => {
-      stdout += data.toString();
-    });
-    child.stderr?.on("data", (data) => {
-      stderr += data.toString();
-    });
-    child.on("close", (code) => {
-      const exitCode = code ?? 1;
-      const durationMs = Date.now() - startTime;
-      if (exitCode === 0) {
-        resolve3({ success: true, durationMs, stdout, stderr, exitCode });
-        return;
-      }
-      const combined = (stderr || stdout).trim();
-      const tail = combined.split("\n").slice(-30).join("\n");
-      resolve3({
-        success: false,
-        error: tail || `Build failed with exit code ${exitCode}`,
-        durationMs,
-        stdout,
-        stderr,
-        exitCode
-      });
-    });
-    child.on("error", (err) => {
-      resolve3({ success: false, error: err.message, durationMs: Date.now() - startTime, stdout: "", stderr: "", exitCode: 1 });
-    });
-    setTimeout(() => {
-      child.kill();
-      resolve3({ success: false, error: `Timed out after ${timeoutMs / 1e3}s`, durationMs: Date.now() - startTime, stdout: "", stderr: "", exitCode: 1 });
-    }, timeoutMs);
-  });
+  const result = await shell.exec(command, args, { cwd, timeout: timeoutMs });
+  const exitCode = result.code;
+  const combined = (result.stderr || result.stdout).trim();
+  return {
+    success: result.ok,
+    error: result.ok ? void 0 : combined.split("\n").slice(-30).join("\n") || `Build failed with exit code ${exitCode}`,
+    durationMs: Date.now() - startTime,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode
+  };
 }
+var CHECKS_CONCURRENCY = 2;
 async function runReleaseChecks(checks, options) {
   const results = [];
   for (const check of checks) {
@@ -1234,33 +1221,32 @@ async function runSingleCheck(check, options) {
   } else {
     pathsToRun = options.packagePaths.length > 0 ? options.packagePaths : [options.repoRoot];
   }
-  const CONCURRENCY = 8;
   const resolvedArgs = (check.args ?? []).map(
     (arg) => arg.match(/\.(sh|js|ts|mjs|cjs)$/) ? join(options.repoRoot, arg) : arg
   );
-  const fullCommand = [check.command, ...resolvedArgs].join(" ");
   const timeoutMs = check.timeoutMs ?? 12e4;
   async function runForPath(pkgPath) {
-    const result = await spawnCommand(fullCommand, pkgPath, timeoutMs);
-    const ok = evaluateParser(check, result.stdout, result.stderr, result.exitCode);
+    const startedAt = Date.now();
+    const result = await options.shell.exec(check.command, resolvedArgs, { cwd: pkgPath, timeout: timeoutMs });
+    const ok = evaluateParser(check, result.stdout, result.stderr, result.code);
     return {
       path: pkgPath,
       ok,
-      durationMs: result.durationMs,
+      durationMs: Date.now() - startedAt,
       details: {
         packagePath: pkgPath,
         stdout: result.stdout || void 0,
         stderr: result.stderr || void 0,
-        exitCode: result.exitCode,
-        error: result.error ?? (!ok ? `exit code ${result.exitCode}` : void 0)
+        exitCode: result.code,
+        error: !ok ? `exit code ${result.code}` : void 0
       }
     };
   }
   let pkgResults;
   if (runIn === "perPackage" && pathsToRun.length > 1) {
     pkgResults = [];
-    for (let i = 0; i < pathsToRun.length; i += CONCURRENCY) {
-      const batch = pathsToRun.slice(i, i + CONCURRENCY);
+    for (let i = 0; i < pathsToRun.length; i += CHECKS_CONCURRENCY) {
+      const batch = pathsToRun.slice(i, i + CHECKS_CONCURRENCY);
       pkgResults.push(...await Promise.all(batch.map(runForPath)));
     }
   } else {
@@ -1273,6 +1259,7 @@ async function runSingleCheck(check, options) {
   return {
     id: check.id,
     ok: allOk,
+    optional: check.optional,
     details: firstFailure,
     hint: check.optional ? "optional" : void 0,
     timingMs: totalDurationMs,
@@ -1662,7 +1649,8 @@ async function _runPipeline(ctx) {
     changelogGen,
     logger,
     startTime,
-    progress
+    progress,
+    options
   } = ctx;
   const channel = config.channel ?? "stable";
   const publishTag = resolvePublishTag(config, channel);
@@ -1746,7 +1734,8 @@ async function _runPipeline(ctx) {
       repoRoot,
       packagePaths,
       scopePath: scopeCwd,
-      logger
+      logger,
+      shell: options.shell
     });
     const failed = checkResults.filter((r) => !r.ok && r.hint !== "optional");
     if (failed.length > 0) {
@@ -1789,7 +1778,7 @@ async function _runPipeline(ctx) {
   }
   if (!skipBuild && !dryRun) {
     progress("versioning", `Building ${plan.packages.length} package(s)...`);
-    const buildResults = await buildPackages(plan.packages, { logger });
+    const buildResults = await buildPackages(plan.packages, { logger, shell: options.shell });
     const buildFailed = buildResults.filter((r) => !r.success);
     if (buildFailed.length > 0) {
       await restoreSnapshot(repoRoot);
@@ -2090,6 +2079,6 @@ async function resolveScopePath(repoRoot, scope) {
   return join(repoRoot, scope);
 }
 
-export { DEFAULT_ROOT_CHANGELOG_PATH, DEFAULT_TAG_PATTERN, applyCanarySuffix, applyVersionStrategy, buildPackages, buildReleaseTag, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, findForbiddenDependencyProtocols, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyCleanInstall, verifyExtractedTarball, verifyPackage, verifyPackages };
+export { CHECKS_CONCURRENCY, DEFAULT_ROOT_CHANGELOG_PATH, DEFAULT_TAG_PATTERN, applyCanarySuffix, applyVersionStrategy, buildPackages, buildReleaseTag, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, findForbiddenDependencyProtocols, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyCleanInstall, verifyExtractedTarball, verifyPackage, verifyPackages };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map