@kb-labs/release-manager-core 2.100.0 → 2.101.0

package/dist/index.d.ts

@@ -11,6 +11,16 @@ interface PluginLogger {
 }
 type ReleaseStage = 'planning' | 'checking' | 'versioning' | 'publishing' | 'verifying' | 'rollback';
 type VersionBump = 'patch' | 'minor' | 'major' | 'auto';
+/**
+ * Release track. Orthogonal to VersionBump — bump decides how much to
+ * increment, channel decides which track a release ships on.
+ * - 'stable': normal versioned release, committed to git, publishes to
+ *   `config.registry` (typically Verdaccio for pre-promote validation).
+ * - 'canary': prerelease published straight to real npm under a dist-tag,
+ *   with an in-memory `-canary.<shortsha>` version that is never committed
+ *   to package.json/git.
+ */
+type ReleaseChannel = 'stable' | 'canary';
 interface ReleaseContext {
     repo: string;
     cwd: string;
@@ -34,6 +44,7 @@ interface ReleasePlan {
     strategy: 'semver';
     registry: string;
     rollbackEnabled: boolean;
+    channel: ReleaseChannel;
 }
 interface CheckResultDetails {
     /** Which package path this failure came from (for perPackage checks). */
@@ -137,6 +148,8 @@ interface ReleaseConfig {
     registry?: string;
     strategy?: 'semver';
     bump?: VersionBump;
+    /** Release track. Defaults to 'stable' when omitted. See ReleaseChannel. */
+    channel?: ReleaseChannel;
     versioningStrategy?: 'lockstep' | 'independent' | 'adaptive';
     strict?: boolean;
     verify?: CheckId[];
@@ -148,6 +161,20 @@ interface ReleaseConfig {
         access?: 'public' | 'restricted';
         /** Package manager to use for publishing. Default: 'pnpm'. */
         packageManager?: 'pnpm' | 'npm' | 'yarn';
+        /** npm dist-tag for canary publishes. Default: 'canary'. */
+        canaryTag?: string;
+        /** npm dist-tag for stable promote-to-npm. Default: 'latest'. */
+        stableTag?: string;
+        /**
+         * Real npm registry used for canary publishes and for `kb release
+         * promote`. Deliberately separate from `registry` (which controls
+         * where a 'stable' `release run` publishes — typically Verdaccio) so a
+         * stale Verdaccio `registry` value can't accidentally swallow a canary
+         * publish or a promote. Default: 'https://registry.npmjs.org'.
+         */
+        npmRegistry?: string;
+        /** Timeout (ms) for registry-verification HTTP calls before promoting a stable release. Default: 30000. */
+        verifyRegistryTimeoutMs?: number;
     };
     /** Workspace configuration — package manager used for publishing. */
     workspace?: {
@@ -259,6 +286,8 @@ interface PackagePublisher {
     publish(packages: PublishablePackage[], options: {
         dryRun?: boolean;
         access?: string;
+        tag?: string;
+        registry?: string;
     }): Promise<PublishResult>;
 }
 /** Injected by caller — generates changelog */
@@ -312,6 +341,8 @@ interface PlannerOptions {
     /** Named flow — selects a release config profile. Completely replaces global packages/versioning/checks. */
     flow?: string;
     bumpOverride?: VersionBump;
+    /** Release track. Defaults to 'stable'. See ReleaseChannel. */
+    channel?: ReleaseChannel;
 }
 /**
  * Merge base config with a named flow's config.
@@ -319,6 +350,19 @@ interface PlannerOptions {
  * All other config fields (registry, publish, rollback, git, changelog) remain from global.
  */
 declare function mergeConfigWithFlow(config: ReleaseConfig, flowName: string): ReleaseConfig;
+/**
+ * Check whether a specific package version is already published on the npm registry.
+ * Fail-open: returns false on any network/registry error.
+ */
+declare function isVersionPublished(name: string, version: string, registry: string): Promise<boolean>;
+/**
+ * Discover release-candidate packages for a scope, at their CURRENT
+ * package.json version — no git-diff-based bump computation. Shared by
+ * planRelease() (which then computes bumps on top) and `kb release
+ * promote` (which needs the already-released versions as-is, since
+ * recomputing bumps from git history would be wrong for a promote).
+ */
+declare function discoverCurrentPackages(cwd: string, scope: string | undefined, config: ReleaseConfig): Promise<PackageVersion[]>;
 /**
  * Plan release by detecting changes and computing version bumps
  */
@@ -331,28 +375,10 @@ declare function planRelease(options: PlannerOptions): Promise<ReleasePlan>;
  */
 declare function matchesPackagePattern(pkgName: string, relativePath: string, patterns: string[]): boolean;
 
-interface PublisherOptions {
-    cwd: string;
-    plan: ReleasePlan;
-    dryRun?: boolean;
-    shell?: ShellAPI;
-    config?: ReleaseConfig;
-}
-interface PublishingResult {
-    published: string[];
-    skipped: string[];
-    errors: string[];
-    versionUpdates: Array<{
-        package: string;
-        from: string;
-        to: string;
-        updated: boolean;
-    }>;
-}
 /**
- * Publish packages according to plan
+ * Publisher - handles package publishing and changelog updates
  */
-declare function publishPackages(options: PublisherOptions): Promise<PublishingResult>;
+
 /**
  * Update package.json version to nextVersion
  * Should be called BEFORE generating changelog so versions match
@@ -367,30 +393,6 @@ declare function updatePackageVersions(plan: ReleasePlan): Promise<Array<{
     to: string;
     updated: boolean;
 }>>;
-/**
- * Generate changelog entry for release
- * Note: This is a simplified wrapper. Full changelog generation is handled by @kb-labs/release-manager-changelog
- */
-declare function generateChangelog(options: {
-    cwd: string;
-    plan: ReleasePlan;
-}): Promise<string>;
-/**
- * Generate enhanced changelog using @kb-labs/release-manager-changelog
- * This is the recommended approach for full-featured changelog generation
- *
- * Note: Full integration available via @kb-labs/release-manager-changelog package and CLI command
- */
-declare function generateEnhancedChangelog(options: {
-    cwd: string;
-    plan: ReleasePlan;
-    from?: string;
-    to?: string;
-    config?: ReleaseConfig;
-}): Promise<{
-    changelog: string;
-    manifest: unknown;
-}>;
 /**
  * Copy changelog to each package directory
  * This writes CHANGELOG.md per package with proper header
@@ -446,22 +448,6 @@ declare function saveSnapshot(options: {
  */
 declare function restoreSnapshot(cwd: string): Promise<void>;
 
-/**
- * Main release runner - orchestrates full release lifecycle
- */
-
-interface RunnerOptions {
-    config: ReleaseConfig;
-    context: ReleaseContext;
-    runChecks?: (stage: ReleaseStage) => Promise<Partial<Record<CheckId, CheckResult>>>;
-    executePlan?: () => Promise<void>;
-    onStageChange?: (stage: ReleaseStage) => void;
-}
-/**
- * Run full release process
- */
-declare function runRelease(options: RunnerOptions): Promise<ReleaseResult>;
-
 /**
  * JSON reporter for release reports
  */
@@ -508,6 +494,31 @@ interface StrategyOptions {
  * Apply versioning strategy to packages
  */
 declare function applyVersionStrategy(packages: PackageVersion[], options: StrategyOptions): PackageVersion[];
+/**
+ * Apply a canary prerelease suffix to already-computed nextVersion values.
+ *
+ * Runs AFTER applyVersionStrategy() (lockstep/independent/adaptive) has
+ * resolved the base bump — canary is orthogonal to bump size, so it's a
+ * pure post-processing step rather than a VersionBump variant. Given a
+ * short git SHA, `1.2.3` (base next version) becomes `1.2.3-canary.<sha>`.
+ *
+ * Deterministic per (nextVersion, shortSha) pair — retrying the same commit
+ * reproduces the same canary version, so publish-side idempotency handling
+ * (already-published patterns) makes retries safe without extra state.
+ */
+declare function applyCanarySuffix(packages: PackageVersion[], shortSha: string): PackageVersion[];
+
+/**
+ * Resolve the npm dist-tag and target registry for a release channel.
+ *
+ * Shared by CLI (run.ts), REST (run-handler.ts) and the pipeline itself so
+ * "canary always goes to real npm under a canary tag, stable uses whatever
+ * config.registry says" is defined once, config-driven, not hardcoded at
+ * each call site.
+ */
+
+declare function resolvePublishTag(config: ReleaseConfig, channel: ReleaseChannel): string;
+declare function resolvePublishRegistry(config: ReleaseConfig, channel: ReleaseChannel): string;
 
 /**
  * Unified release pipeline — single orchestrator for CLI and REST.
@@ -593,6 +604,40 @@ declare function verifyPackages(packages: PackageVersion[], options?: {
  * npm pack → extract → check exports, directory imports, test leaks, syntax.
  */
 declare function verifyPackage(packagePath: string, packageName?: string): VerifyResult;
+/**
+ * Run the static artifact checks (test-file leaks, exports existence,
+ * directory-import detection, syntax validation) against an already
+ * extracted package tarball. Shared by verifyPackage() (local npm pack)
+ * and verdaccio-verify.ts (npm pack pulled from a registry) so both
+ * "verify before publish" and "verify after publish" use identical checks.
+ */
+declare function verifyExtractedTarball(extractedDir: string): string[];
+
+/**
+ * Registry-side artifact verification — confirms a package actually landed
+ * on a registry (Verdaccio) with the expected content, before it's promoted
+ * to npm `latest`.
+ *
+ * Deliberately separate from verifier.ts: that module is pure local
+ * validation (npm pack from the working tree, no registry I/O) so it stays
+ * usable offline/in restricted CI. This module does registry round-trips —
+ * it's the "did the publish actually work, and is what landed still sane"
+ * check that only makes sense to run *after* a publish.
+ */
+
+interface VerifyAgainstRegistryOptions {
+    registry: string;
+    /** Timeout (ms) for the registry HTTP check and the `npm pack` round-trip. Default: 30000. */
+    timeout?: number;
+    logger?: Pick<PluginLogger, 'info' | 'warn'>;
+}
+/**
+ * Verify that each package landed on `registry` at its expected version,
+ * and that the tarball actually published there passes the same static
+ * checks verifyPackage() runs pre-publish (catches publish-time corruption
+ * distinct from pre-publish source issues).
+ */
+declare function verifyAgainstRegistry(packages: PublishablePackage[], options: VerifyAgainstRegistryOptions): Promise<VerifyResult[]>;
 
 /**
  * Scope utilities — resolve scope name to filesystem path.
@@ -618,4 +663,4 @@ declare function verifyPackage(packagePath: string, packageName?: string): Verif
  */
 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 PublisherOptions, type PublishingResult, type ReleaseConfig, type ReleaseContext, type ReleasePlan, type ReleaseReport, type ReleaseResult, type ReleaseStage, type RollbackSnapshot, type RunnerOptions, type StrategyOptions, type VerifyResult, type VersionBump, type VersionStrategy, applyVersionStrategy, buildPackages, commitAndTagRelease, copyChangelogToPackages, createExecaShellAdapter, generateChangelog, generateEnhancedChangelog, isBuildCommand, matchesPackagePattern, mergeConfigWithFlow, planRelease, publishPackages, renderJson, renderMarkdown, renderText, resolveScopePath, restoreSnapshot, runRelease, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyPackage, verifyPackages };
+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, planRelease, renderJson, renderMarkdown, renderText, resolvePublishRegistry, resolvePublishTag, resolveScopePath, restoreSnapshot, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyAgainstRegistry, verifyExtractedTarball, verifyPackage, verifyPackages };