@kb-labs/release-manager-core 2.104.0 → 2.105.0

package/dist/index.d.ts

@@ -134,6 +134,14 @@ interface FlowConfig {
     versioningStrategy?: 'lockstep' | 'independent' | 'adaptive';
     /** If set, replaces global checks for this flow. */
     checks?: CustomCheckConfig[];
+    /**
+     * Git tag template for this flow's stable releases. Tokens: `{flow}`
+     * (the flow's config key, e.g. "platform") and `{version}` (the release
+     * version). Default: `{flow}-v{version}` (e.g. `platform-v2.105.0`).
+     * Used both to generate the tag (`buildReleaseTag`) and to parse a tag
+     * back into a flow (`resolveFlowFromTag`) — see `./tag.ts`.
+     */
+    tagPattern?: string;
 }
 interface PackagesFilter {
     /** Glob dirs to scan, e.g. ['packages/*', 'apps/*'].
@@ -204,6 +212,12 @@ interface ReleaseConfig {
     };
     changelog?: {
         enabled?: boolean;
+        /**
+         * Where the consolidated repo-root changelog is written, relative to
+         * repoRoot. Default: '.kb/release/CHANGELOG.md'. Set to 'CHANGELOG.md'
+         * to write it at the repo root instead.
+         */
+        outputPath?: string;
         includeTypes?: string[];
         excludeTypes?: string[];
         ignoreAuthors?: string[];
@@ -313,6 +327,14 @@ interface PipelineOptions {
     skipChecks?: boolean;
     skipBuild?: boolean;
     skipVerify?: boolean;
+    /**
+     * Prepare-only mode: run checks/build/verify/version-bump/changelog and
+     * commit+tag git, but never call the publisher. No npm credentials are
+     * required. Intended for a local/CI "prepare" step whose git tag is the
+     * trigger for a separate CI job that runs `kb release promote` to do the
+     * actual npm publish. See plugins/release/docs/adr/0001-*.
+     */
+    skipPublish?: boolean;
     /** Custom check configs from kb.config.json */
     checks?: CustomCheckConfig[];
     /** Injected publisher (CLI = interactive OTP, REST = programmatic token) */
@@ -402,9 +424,18 @@ declare function copyChangelogToPackages(options: {
     plan: ReleasePlan;
     changelog: string;
 }): Promise<void>;
+/** Default location of the consolidated repo-root changelog, relative to repoRoot. */
+declare const DEFAULT_ROOT_CHANGELOG_PATH = ".kb/release/CHANGELOG.md";
+/**
+ * Resolve the repo-relative path of the consolidated root changelog.
+ * Config-driven via `release.changelog.outputPath` so teams can point it at
+ * the conventional `CHANGELOG.md` repo root instead of the default.
+ */
+declare function resolveRootChangelogRelPath(outputPath?: string): string;
 /**
  * Merge the generated changelog for this release into the repo-root
- * `.kb/release/CHANGELOG.md`, prepending/deduplicating the same way
+ * changelog file (default `.kb/release/CHANGELOG.md`, configurable via
+ * `release.changelog.outputPath`), prepending/deduplicating the same way
  * `copyChangelogToPackages` does for per-package changelogs — this file is
  * cumulative history, not a per-run snapshot, so it must never be overwritten.
  */
@@ -412,6 +443,8 @@ declare function mergeRootChangelog(options: {
     repoRoot: string;
     plan: ReleasePlan;
     changelog: string;
+    /** Repo-relative output path. Defaults to DEFAULT_ROOT_CHANGELOG_PATH. */
+    outputPath?: string;
 }): Promise<void>;
 /**
  * Commit and tag release changes
@@ -433,6 +466,19 @@ declare function commitAndTagRelease(options: {
         tagged: string[];
         pushed: boolean;
     }>;
+    /** Repo-relative path to the consolidated root changelog. Defaults to DEFAULT_ROOT_CHANGELOG_PATH. */
+    changelogOutputPath?: string;
+    /**
+     * The flow this release came from (e.g. "platform", "sdk"). Drives the
+     * tag grammar (`{flow}-v{version}`, see ./tag.ts). If omitted (ran
+     * without `--flow`), falls back to `"release"` and — for a genuinely
+     * divergent multi-version independent release — to the old one-tag-
+     * per-package behavior, since a single flow-level tag can't represent
+     * packages at different versions.
+     */
+    flowName?: string;
+    /** Per-flow tag template override, from `FlowConfig.tagPattern`. */
+    tagPattern?: string;
 }): Promise<{
     committed: boolean;
     tagged: string[];
@@ -531,6 +577,35 @@ declare function applyCanarySuffix(packages: PackageVersion[], shortSha: string)
 declare function resolvePublishTag(config: ReleaseConfig, channel: ReleaseChannel): string;
 declare function resolvePublishRegistry(config: ReleaseConfig, channel: ReleaseChannel): string;
 
+/**
+ * Git tag grammar for release flows — one place that both generates a
+ * flow's release tag and parses a tag back into a flow. Keeping generation
+ * and resolution on the same template prevents them from drifting apart
+ * (previously tag-building was inlined ad hoc in `commitAndTagRelease` and
+ * nothing parsed a tag back into a flow at all — CI guessed via bash).
+ *
+ * Only stable-channel releases ever produce a git tag (canary is ephemeral,
+ * npm-only — see pipeline.ts), so a resolved tag always implies `channel:
+ * 'stable'`; it is never inferred from the tag itself.
+ */
+
+declare const DEFAULT_TAG_PATTERN = "{flow}-v{version}";
+/**
+ * Build the release tag for a flow. `tagPattern` defaults to
+ * `{flow}-v{version}` (e.g. `platform-v2.105.0`) when omitted.
+ */
+declare function buildReleaseTag(flowName: string, version: string, tagPattern?: string): string;
+/**
+ * Resolve a git tag back into the flow (and channel) that produced it, by
+ * matching it against every configured flow's tag pattern. Returns `null`
+ * if no configured flow's pattern matches — callers (e.g. `deliver`) must
+ * treat that as a hard failure, never a guess.
+ */
+declare function resolveFlowFromTag(config: ReleaseConfig, tag: string): {
+    flowName: string;
+    channel: ReleaseChannel;
+} | null;
+
 /**
  * Unified release pipeline — single orchestrator for CLI and REST.
  *
@@ -640,6 +715,13 @@ interface VerifyAgainstRegistryOptions {
     registry: string;
     /** Timeout (ms) for the registry HTTP check and the `npm pack` round-trip. Default: 30000. */
     timeout?: number;
+    /**
+     * Extra attempts for the "is it published yet" check before giving up —
+     * each retry waits `retryDelaysMs[attempt]` (capped at the last entry).
+     * Default: 0 (single attempt, matches pre-existing Verdaccio behavior).
+     */
+    retries?: number;
+    retryDelaysMs?: readonly number[];
     logger?: Pick<PluginLogger, 'info' | 'warn'>;
 }
 /**
@@ -674,4 +756,4 @@ declare function verifyAgainstRegistry(packages: PublishablePackage[], options:
  */
 declare function resolveScopePath(repoRoot: string, scope: string): Promise<string>;
 
-export { type AuditSummary, type BuildResult, type ChangelogGenerator, type CheckId, type CheckResult, type CheckResultDetails, type CustomCheckConfig, 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, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolvePublishRegistry, resolvePublishTag, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyExtractedTarball, verifyPackage, verifyPackages };
+export { type AuditSummary, type BuildResult, type ChangelogGenerator, type CheckId, type CheckResult, type CheckResultDetails, 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, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyExtractedTarball, verifyPackage, verifyPackages };

package/dist/index.js

@@ -507,6 +507,32 @@ function isCheckpointResumable(checkpoint, flow, version) {
   return checkpoint.publishedPackages.length > 0 && Object.values(checkpoint.gitRoots).some((s) => !s.pushed);
 }
 
+// src/tag.ts
+var DEFAULT_TAG_PATTERN = "{flow}-v{version}";
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var SEMVER_SRC = "\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?";
+function buildReleaseTag(flowName, version, tagPattern) {
+  const pattern = tagPattern ?? DEFAULT_TAG_PATTERN;
+  return pattern.replace("{flow}", flowName).replace("{version}", version);
+}
+function buildTagRegex(flowName, tagPattern) {
+  const escapedPattern = escapeRegex(tagPattern);
+  const src = escapedPattern.replace(escapeRegex("{flow}"), escapeRegex(flowName)).replace(escapeRegex("{version}"), `(${SEMVER_SRC})`);
+  return new RegExp(`^${src}$`);
+}
+function resolveFlowFromTag(config, tag) {
+  const flows = config.flows ?? {};
+  for (const [flowName, flowConfig] of Object.entries(flows)) {
+    const regex = buildTagRegex(flowName, flowConfig.tagPattern ?? DEFAULT_TAG_PATTERN);
+    if (regex.test(tag)) {
+      return { flowName, channel: "stable" };
+    }
+  }
+  return null;
+}
+
 // src/publisher.ts
 async function updatePackageVersion(pkg) {
   const packageJsonPath = join(pkg.path, "package.json");
@@ -594,8 +620,12 @@ function mergeChangelogBlock(existingChangelog, newBlock, versionPattern) {
   }
   return newBlock + (existingChangelog ? "\n" + existingChangelog : "");
 }
+var DEFAULT_ROOT_CHANGELOG_PATH = ".kb/release/CHANGELOG.md";
+function resolveRootChangelogRelPath(outputPath) {
+  return outputPath && outputPath.trim().length > 0 ? outputPath : DEFAULT_ROOT_CHANGELOG_PATH;
+}
 async function mergeRootChangelog(options) {
-  const { repoRoot, plan, changelog } = options;
+  const { repoRoot, plan, changelog, outputPath } = options;
   if (!changelog || changelog.trim().length === 0 || plan.packages.length === 0) {
     return;
   }
@@ -606,15 +636,14 @@ async function mergeRootChangelog(options) {
     `^##\\s+${primary.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s+${primary.nextVersion.replace(/\./g, "\\.")}`,
     "m"
   );
-  const releaseDir = join(repoRoot, ".kb", "release");
-  const changelogPath = join(releaseDir, "CHANGELOG.md");
+  const changelogPath = join(repoRoot, resolveRootChangelogRelPath(outputPath));
   let existingChangelog = "";
   try {
     existingChangelog = await readFile(changelogPath, "utf-8");
   } catch {
   }
   const updatedChangelog = mergeChangelogBlock(existingChangelog, changelog.trim(), versionPattern);
-  await mkdir(releaseDir, { recursive: true });
+  await mkdir(dirname(changelogPath), { recursive: true });
   await writeFile(changelogPath, updatedChangelog.trim() + "\n", "utf-8");
 }
 function createPackageChangelog(pkg, changelog) {
@@ -644,7 +673,7 @@ function createPackageChangelog(pkg, changelog) {
   return changelog.substring(startIdx, endIdx).trim();
 }
 async function commitAndTagRelease(options) {
-  const { cwd, plan, dryRun, noVerify = false, repoRoot, checkpointGitRoots } = options;
+  const { cwd, plan, dryRun, noVerify = false, repoRoot, checkpointGitRoots, changelogOutputPath, flowName = "release", tagPattern } = options;
   const simpleGit2 = (await import('simple-git')).default;
   const result = {
     committed: false,
@@ -668,7 +697,7 @@ async function commitAndTagRelease(options) {
       rootToPkgs.set(root, list);
     }
     const uniqueVersions = new Set(plan.packages.map((p) => p.nextVersion));
-    const isLockstep = plan.packages.length > 1 && uniqueVersions.size === 1;
+    const singleVersionAcrossPlan = uniqueVersions.size === 1;
     const pushFlags = noVerify ? ["--no-verify"] : [];
     for (const [root, pkgs] of rootToPkgs) {
       const prior = checkpointGitRoots?.[root];
@@ -692,9 +721,10 @@ async function commitAndTagRelease(options) {
           }
         }
         if (repoRoot && root === repoRoot) {
-          const rootChangelogPath = join(repoRoot, ".kb", "release", "CHANGELOG.md");
+          const rootChangelogRelPath = resolveRootChangelogRelPath(changelogOutputPath);
+          const rootChangelogPath = join(repoRoot, rootChangelogRelPath);
           if (existsSync(rootChangelogPath)) {
-            filesToStage.push(".kb/release/CHANGELOG.md");
+            filesToStage.push(rootChangelogRelPath);
           }
         }
         await rootGit.add(filesToStage);
@@ -712,8 +742,8 @@ async function commitAndTagRelease(options) {
         result.committed = true;
       }
       if (rootTagged.length === 0) {
-        if (isLockstep) {
-          const tagName = `v${plan.packages[0].nextVersion}`;
+        if (singleVersionAcrossPlan) {
+          const tagName = buildReleaseTag(flowName, plan.packages[0].nextVersion, tagPattern);
           await rootGit.addTag(tagName);
           rootTagged = [tagName];
         } else {
@@ -1356,18 +1386,36 @@ function findFiles(dir, predicate) {
   return results;
 }
 var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_POLL_RETRY_DELAYS_MS = [2e3, 4e3, 8e3, 16e3, 3e4];
 async function verifyAgainstRegistry(packages, options) {
-  const { registry, timeout = DEFAULT_TIMEOUT_MS, logger } = options;
+  const { registry, timeout = DEFAULT_TIMEOUT_MS, retries = 0, retryDelaysMs = DEFAULT_POLL_RETRY_DELAYS_MS, logger } = options;
   const results = [];
   for (const pkg of packages) {
-    results.push(await verifyOneAgainstRegistry(pkg, registry, timeout, logger));
+    results.push(await verifyOneAgainstRegistry(pkg, registry, timeout, retries, retryDelaysMs, logger));
   }
   return results;
 }
-async function verifyOneAgainstRegistry(pkg, registry, timeout, logger) {
-  const published = await isVersionPublished(pkg.name, pkg.version, registry);
+async function waitUntilPublished(pkg, registry, retries, retryDelaysMs, logger) {
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (await isVersionPublished(pkg.name, pkg.version, registry)) {
+      return true;
+    }
+    if (attempt < retries) {
+      const delay = retryDelaysMs[Math.min(attempt, retryDelaysMs.length - 1)];
+      logger?.warn?.(
+        `${pkg.name}@${pkg.version} not yet visible on ${registry} (attempt ${attempt + 1}/${retries + 1}), retrying in ${(delay / 1e3).toFixed(0)}s \u2014 likely registry propagation lag`
+      );
+      await new Promise((r) => {
+        setTimeout(r, delay);
+      });
+    }
+  }
+  return false;
+}
+async function verifyOneAgainstRegistry(pkg, registry, timeout, retries, retryDelaysMs, logger) {
+  const published = await waitUntilPublished(pkg, registry, retries, retryDelaysMs, logger);
   if (!published) {
-    return { name: pkg.name, success: false, issues: [`${pkg.name}@${pkg.version} was not found on ${registry} after publish`] };
+    return { name: pkg.name, success: false, issues: [`${pkg.name}@${pkg.version} was not found on ${registry} after publish (waited through ${retries} retr${retries === 1 ? "y" : "ies"})`] };
   }
   logger?.info?.(`${pkg.name}@${pkg.version} confirmed on ${registry}`);
   const tmpDir = join(tmpdir(), `kb-verdaccio-verify-${randomBytes(6).toString("hex")}`);
@@ -1451,6 +1499,7 @@ async function runReleasePipeline(options) {
     skipChecks = false,
     skipBuild = false,
     skipVerify = false,
+    skipPublish = false,
     noVerify = false,
     checks: checkConfigs,
     publisher,
@@ -1476,6 +1525,7 @@ async function runReleasePipeline(options) {
       skipChecks,
       skipBuild,
       skipVerify,
+      skipPublish,
       noVerify,
       checkConfigs,
       publisher,
@@ -1500,6 +1550,7 @@ async function _runPipeline(ctx) {
     skipChecks,
     skipBuild,
     skipVerify,
+    skipPublish,
     noVerify,
     checkConfigs,
     publisher,
@@ -1511,7 +1562,7 @@ async function _runPipeline(ctx) {
   const channel = config.channel ?? "stable";
   const publishTag = resolvePublishTag(config, channel);
   const publishRegistry = resolvePublishRegistry(config, channel);
-  if (!dryRun) {
+  if (!dryRun && !skipPublish) {
     const registry = publishRegistry;
     const authError = await verifyNpmAuth(registry);
     if (authError) {
@@ -1549,7 +1600,7 @@ async function _runPipeline(ctx) {
     };
   }
   progress("planning", `Found ${plan.packages.length} package(s) to release`);
-  if (!dryRun) {
+  if (!dryRun && !skipPublish) {
     const existingCheckpoint = loadCheckpoint(repoRoot);
     if (existingCheckpoint) {
       const uniqueVersions = new Set(plan.packages.map((p) => p.nextVersion));
@@ -1562,7 +1613,10 @@ async function _runPipeline(ctx) {
           dryRun: false,
           noVerify,
           repoRoot,
-          checkpointGitRoots: existingCheckpoint.gitRoots
+          checkpointGitRoots: existingCheckpoint.gitRoots,
+          changelogOutputPath: config.changelog?.outputPath,
+          flowName: flow,
+          tagPattern: flow ? config.flows?.[flow]?.tagPattern : void 0
         });
         deleteCheckpoint(repoRoot);
         const resumeReport = buildReport("verifying", plan, repoRoot, dryRun, startTime, {
@@ -1696,15 +1750,21 @@ async function _runPipeline(ctx) {
   }
   if (changelogMd && !dryRun) {
     await copyChangelogToPackages({ plan, changelog: changelogMd });
-    await mergeRootChangelog({ repoRoot, plan, changelog: changelogMd });
+    await mergeRootChangelog({ repoRoot, plan, changelog: changelogMd, outputPath: config.changelog?.outputPath });
   }
-  progress("publishing", dryRun ? "Simulating publish (dry-run)..." : "Publishing packages...");
+  progress("publishing", dryRun ? "Simulating publish (dry-run)..." : skipPublish ? "Skipping publish (prepare-only)..." : "Publishing packages...");
   const packagesToPublish = plan.packages.map((pkg) => ({
     name: pkg.name,
     version: pkg.nextVersion,
     path: pkg.path
   }));
-  const publishResult = await publisher.publish(packagesToPublish, {
+  const publishResult = skipPublish ? {
+    published: [],
+    alreadyPublished: [],
+    failed: [],
+    skipped: packagesToPublish.map((p) => `${p.name}@${p.version} (prepared, not published)`),
+    errors: []
+  } : await publisher.publish(packagesToPublish, {
     dryRun,
     access: config.publish?.access ?? "public",
     tag: publishTag,
@@ -1727,7 +1787,7 @@ async function _runPipeline(ctx) {
       })
     };
   }
-  if (!dryRun && channel === "stable") {
+  if (!dryRun && !skipPublish && channel === "stable") {
     const uniqueVersions = new Set(plan.packages.map((p) => p.nextVersion));
     const cpVersion = uniqueVersions.size === 1 ? plan.packages[0].nextVersion : "independent";
     writeCheckpoint(repoRoot, {
@@ -1742,7 +1802,7 @@ async function _runPipeline(ctx) {
       gitRoots: {}
     });
   }
-  if (!dryRun && channel === "stable") {
+  if (!dryRun && !skipPublish && channel === "stable") {
     progress("verifying", "Verifying published artifacts against the registry...");
     const registryVerifyResults = await verifyAgainstRegistry(packagesToPublish, {
       registry: publishRegistry,
@@ -1768,7 +1828,16 @@ async function _runPipeline(ctx) {
   let gitResult;
   if (!dryRun && channel === "stable") {
     progress("verifying", "Committing and tagging release...");
-    gitResult = await commitAndTagRelease({ cwd: scopeCwd, plan, dryRun, noVerify, repoRoot });
+    gitResult = await commitAndTagRelease({
+      cwd: scopeCwd,
+      plan,
+      dryRun,
+      noVerify,
+      repoRoot,
+      changelogOutputPath: config.changelog?.outputPath,
+      flowName: flow,
+      tagPattern: flow ? config.flows?.[flow]?.tagPattern : void 0
+    });
     deleteCheckpoint(repoRoot);
   }
   const report = buildReport("verifying", plan, repoRoot, dryRun, startTime, {
@@ -1838,6 +1907,6 @@ async function resolveScopePath(repoRoot, scope) {
   return join(repoRoot, scope);
 }
 
-export { applyCanarySuffix, applyVersionStrategy, buildPackages, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolvePublishRegistry, resolvePublishTag, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyExtractedTarball, verifyPackage, verifyPackages };
+export { DEFAULT_ROOT_CHANGELOG_PATH, DEFAULT_TAG_PATTERN, applyCanarySuffix, applyVersionStrategy, buildPackages, buildReleaseTag, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, discoverCurrentPackages, isBuildCommand, isVersionPublished, matchesPackagePattern, mergeConfigWithFlow, mergeRootChangelog, planRelease, renderJson, renderMarkdown, renderText, resolveFlowFromTag, resolvePublishRegistry, resolvePublishTag, resolveRootChangelogRelPath, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyExtractedTarball, verifyPackage, verifyPackages };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map