@kb-labs/release-manager-core 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,550 @@
+import { ShellAPI } from '@kb-labs/sdk';
+
+/**
+ * Core types for @kb-labs/release-manager-core
+ */
+type ReleaseStage = 'planning' | 'checking' | 'versioning' | 'publishing' | 'verifying' | 'rollback';
+type VersionBump = 'patch' | 'minor' | 'major' | 'auto';
+interface ReleaseContext {
+    repo: string;
+    cwd: string;
+    branch: string;
+    profile?: string;
+    dryRun?: boolean;
+}
+interface PackageVersion {
+    name: string;
+    path: string;
+    currentVersion: string;
+    nextVersion: string;
+    bump: VersionBump;
+    isPublished: boolean;
+    dependencies?: string[];
+}
+interface ReleasePlan {
+    packages: PackageVersion[];
+    strategy: 'semver';
+    registry: string;
+    rollbackEnabled: boolean;
+}
+interface CheckResult {
+    id: CheckId;
+    ok: boolean;
+    details?: unknown;
+    hint?: string;
+    timingMs?: number;
+}
+type CheckId = string;
+/**
+ * Custom check configuration
+ * Allows defining checks declaratively through config
+ */
+interface CustomCheckConfig {
+    id: string;
+    /** Human-readable name shown in UI. Falls back to id if not set. */
+    name?: string;
+    command: string;
+    args?: string[];
+    parser?: 'json' | 'exitcode' | ((stdout: string, stderr: string, exitCode: number) => boolean);
+    timeoutMs?: number;
+    optional?: boolean;
+    /**
+     * Run this check once in a single directory instead of once per package.
+     * "repoRoot" — run in the git repo root (default for monorepo builds)
+     * "scopePath" — run in the scope directory (monorepo root like kb-labs-core/)
+     * If omitted, check runs in each package directory (original behaviour).
+     */
+    runIn?: 'repoRoot' | 'scopePath' | 'perPackage';
+}
+interface ReleaseResult {
+    ok: boolean;
+    version?: string;
+    published?: string[];
+    skipped?: string[];
+    changelog?: string;
+    checks?: Partial<Record<CheckId, CheckResult>>;
+    checksPerPackage?: Record<string, Partial<Record<CheckId, CheckResult>>>;
+    versionUpdates?: Array<{
+        package: string;
+        from: string;
+        to: string;
+        updated: boolean;
+    }>;
+    git?: {
+        committed: boolean;
+        tagged: string[];
+        pushed: boolean;
+    };
+    timingMs: number;
+    errors?: string[];
+}
+interface ReleaseReport {
+    schemaVersion: '1.0';
+    ts: string;
+    context: ReleaseContext;
+    stage: ReleaseStage;
+    plan?: ReleasePlan;
+    result: ReleaseResult;
+}
+interface PackagesFilter {
+    /** Glob dirs to scan, e.g. ['packages/*', 'apps/*'].
+     *  Defaults to full tree scan when omitted. */
+    paths?: string[];
+    /** If set — only packages matching any pattern are included. */
+    include?: string[];
+    /** Packages matching any pattern are excluded (applied after include). */
+    exclude?: string[];
+}
+interface ReleaseConfig {
+    registry?: string;
+    strategy?: 'semver';
+    bump?: VersionBump;
+    versioningStrategy?: 'lockstep' | 'independent' | 'adaptive';
+    strict?: boolean;
+    verify?: CheckId[];
+    checks?: CustomCheckConfig[];
+    publish?: {
+        npm?: boolean;
+        github?: boolean;
+        /** npm publish --access. Default: 'public'. */
+        access?: 'public' | 'restricted';
+        /** Package manager to use for publishing. Default: 'pnpm'. */
+        packageManager?: 'pnpm' | 'npm' | 'yarn';
+    };
+    /** Filter which packages are discovered and released. */
+    packages?: PackagesFilter;
+    /** Per-scope overrides — packages filter merged with global, checks replace global entirely. */
+    scopes?: Record<string, {
+        packages?: PackagesFilter;
+        /** If set, replaces global `checks` for this scope. */
+        checks?: CustomCheckConfig[];
+    }>;
+    rollback?: {
+        enabled?: boolean;
+        maxHistory?: number;
+    };
+    output?: {
+        json?: boolean;
+        md?: boolean;
+        text?: boolean;
+    };
+    changelog?: {
+        enabled?: boolean;
+        includeTypes?: string[];
+        excludeTypes?: string[];
+        ignoreAuthors?: string[];
+        scopeMap?: Record<string, string>;
+        collapseMerges?: boolean;
+        collapseReverts?: boolean;
+        preferMergeSummary?: boolean;
+        bumpStrategy?: 'independent' | 'ripple' | 'lockstep';
+        workspace?: boolean;
+        perPackage?: boolean;
+        format?: 'json' | 'md' | 'both';
+        level?: 'compact' | 'standard' | 'detailed';
+        template?: string | null;
+        locale?: 'en' | 'ru';
+        cache?: boolean;
+        requireAudit?: boolean;
+        requireSignedTags?: boolean;
+        redactPatterns?: string[];
+        maxBodyLength?: number;
+        stabilityGuards?: {
+            experimental?: {
+                allowMajor?: boolean;
+            };
+        };
+        ignoreSubmodules?: boolean;
+        metadata?: Record<string, unknown>;
+    };
+    git?: {
+        provider?: 'auto' | 'github' | 'gitlab' | 'generic';
+        baseUrl?: string | null;
+        autoUnshallow?: boolean;
+        requireSignedTags?: boolean;
+    };
+}
+interface AuditSummary {
+    ok: boolean;
+    checks: Partial<Record<string, {
+        ok: boolean;
+        code?: string;
+        hint?: string;
+    }>>;
+    overall?: {
+        ok: boolean;
+        failReasons: string[];
+    };
+}
+interface BuildResult {
+    name: string;
+    success: boolean;
+    error?: string;
+    durationMs: number;
+}
+interface VerifyResult {
+    name: string;
+    success: boolean;
+    issues: string[];
+}
+interface PublishablePackage {
+    name: string;
+    version: string;
+    path: string;
+}
+interface PublishResult {
+    published: string[];
+    skipped: string[];
+    errors: string[];
+}
+/** Injected by CLI (OTP) or REST (token-based) */
+interface PackagePublisher {
+    publish(packages: PublishablePackage[], options: {
+        dryRun?: boolean;
+        access?: string;
+    }): Promise<PublishResult>;
+}
+/** Injected by caller — generates changelog */
+interface ChangelogGenerator {
+    generate(plan: ReleasePlan, options: {
+        repoRoot: string;
+        gitCwd: string;
+        config: ReleaseConfig;
+    }): Promise<string>;
+}
+interface PipelineOptions {
+    cwd: string;
+    repoRoot: string;
+    /** Resolved absolute path to the monorepo being released (e.g. infra/kb-labs-adapters).
+     *  Planner uses this as cwd for package discovery. */
+    scopeCwd: string;
+    /** Original scope name for display/reporting only */
+    scope?: string;
+    config: ReleaseConfig;
+    dryRun?: boolean;
+    skipChecks?: boolean;
+    skipBuild?: boolean;
+    skipVerify?: boolean;
+    /** Custom check configs from kb.config.json */
+    checks?: CustomCheckConfig[];
+    /** Injected publisher (CLI = interactive OTP, REST = programmatic token) */
+    publisher: PackagePublisher;
+    /** Injected changelog generator (with or without LLM) */
+    changelog?: ChangelogGenerator;
+    logger?: {
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+        error?: (...args: any[]) => void;
+    };
+    onProgress?: (stage: ReleaseStage, message: string) => void;
+}
+interface PipelineResult {
+    success: boolean;
+    report: ReleaseReport;
+    plan: ReleasePlan;
+}
+
+/**
+ * Release planner - detects changes and suggests version bumps
+ */
+
+interface PlannerOptions {
+    cwd: string;
+    config: ReleaseConfig;
+    scope?: string;
+    bumpOverride?: VersionBump;
+}
+/**
+ * Plan release by detecting changes and computing version bumps
+ */
+declare function planRelease(options: PlannerOptions): Promise<ReleasePlan>;
+/**
+ * Match a package against a list of patterns.
+ * - Patterns starting with '@' or without '/' → matched against package name.
+ * - Patterns containing '/' (non-scoped) → matched against relative path.
+ * - Supports '*' wildcard (single path segment, not separator).
+ */
+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
+ */
+declare function publishPackages(options: PublisherOptions): Promise<PublishingResult>;
+/**
+ * Update package.json version to nextVersion
+ * Should be called BEFORE generating changelog so versions match
+ */
+declare function updatePackageVersion(pkg: PackageVersion): Promise<void>;
+/**
+ * Update versions for all packages in the plan
+ */
+declare function updatePackageVersions(plan: ReleasePlan): Promise<Array<{
+    package: string;
+    from: string;
+    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?: any;
+}): Promise<{
+    changelog: string;
+    manifest: any;
+}>;
+/**
+ * Copy changelog to each package directory
+ * This writes CHANGELOG.md per package with proper header
+ */
+declare function copyChangelogToPackages(options: {
+    cwd: string;
+    plan: ReleasePlan;
+    changelog: string;
+}): Promise<void>;
+/**
+ * Commit and tag release changes
+ *
+ * Each package is committed inside its own git repo (supports submodules).
+ * After all packages are committed, tags are created in cwd (the monorepo root).
+ */
+declare function commitAndTagRelease(options: {
+    cwd: string;
+    plan: ReleasePlan;
+    dryRun?: boolean;
+}): Promise<{
+    committed: boolean;
+    tagged: string[];
+    pushed: boolean;
+}>;
+
+/**
+ * Rollback - manages release snapshots and recovery
+ */
+
+interface RollbackSnapshot {
+    ts: string;
+    packages: PackageVersion[];
+}
+/**
+ * Save current state for potential rollback
+ */
+declare function saveSnapshot(options: {
+    cwd: string;
+    plan: ReleasePlan;
+}): Promise<void>;
+/**
+ * Restore from snapshot
+ */
+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
+ */
+
+declare function renderJson(report: ReleaseReport): string;
+
+/**
+ * Markdown reporter for release reports
+ */
+
+declare function renderMarkdown(report: ReleaseReport): string;
+
+/**
+ * Text reporter for release reports
+ */
+
+declare function renderText(report: ReleaseReport): string;
+
+/**
+ * @module @kb-labs/release-manager-core/shell-adapter
+ * Shell adapter for release-core - wraps execa with SDK types
+ */
+
+/**
+ * Create a ShellAPI adapter using execa
+ * This is used in core libraries where ctx.runtime.shell is not available
+ */
+declare function createExecaShellAdapter(): ShellAPI;
+
+/**
+ * Versioning strategies for monorepo package releases
+ *
+ * - lockstep: All packages get the same version (maximum bump)
+ * - independent: Each package has its own version
+ * - adaptive: Lockstep if breaking changes, otherwise independent
+ */
+
+type VersionStrategy = 'lockstep' | 'independent' | 'adaptive';
+interface StrategyOptions {
+    strategy: VersionStrategy;
+    umbrellaPath?: string;
+}
+/**
+ * Apply versioning strategy to packages
+ */
+declare function applyVersionStrategy(packages: PackageVersion[], options: StrategyOptions): PackageVersion[];
+
+/**
+ * Unified release pipeline — single orchestrator for CLI and REST.
+ *
+ * Flow: plan → snapshot → checks → build → verify → version bump → changelog → publish → git → report
+ */
+
+/**
+ * Run the complete release pipeline.
+ * Both CLI and REST call this with different injected publishers/changelog generators.
+ */
+declare function runReleasePipeline(options: PipelineOptions): Promise<PipelineResult>;
+
+/**
+ * Safe build — builds into temp dir, then atomically swaps dist/.
+ * Prevents crashing running services whose dist/ is wiped by tsup's `clean: true`.
+ */
+
+/**
+ * Build all packages in a plan using safe build strategy.
+ * Stops on first failure.
+ */
+declare function buildPackages(packages: PackageVersion[], options?: {
+    logger?: {
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+        error?: (...args: any[]) => void;
+    };
+    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>;
+/**
+ * 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.
+ * Reads config.checks[], supports parser field, script path resolution, perPackage routing.
+ */
+
+interface CheckRunnerOptions {
+    repoRoot: string;
+    packagePaths: string[];
+    scopePath?: string;
+    logger?: {
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+    };
+}
+/**
+ * Run all configured checks against packages.
+ * Handles: parser evaluation, script path resolution, perPackage/scopePath/repoRoot routing.
+ */
+declare function runReleaseChecks(checks: CustomCheckConfig[], options: CheckRunnerOptions): Promise<CheckResult[]>;
+
+/**
+ * Package verifier — npm pack → extract → verify artifacts before publish.
+ * Catches: directory imports, test file leaks, missing exports, syntax errors.
+ */
+
+/**
+ * Verify all packages in a plan are publishable.
+ */
+declare function verifyPackages(packages: PackageVersion[], options?: {
+    logger?: {
+        info?: (...args: any[]) => void;
+    };
+    onProgress?: (pkg: string, result: VerifyResult) => void;
+}): Promise<VerifyResult[]>;
+/**
+ * Verify a single package is publishable.
+ * npm pack → extract → check exports, directory imports, test leaks, syntax.
+ */
+declare function verifyPackage(packagePath: string, packageName?: string): VerifyResult;
+
+/**
+ * Scope utilities — resolve scope name to filesystem path.
+ *
+ * "scope" is a filter/selector concept (e.g. "@kb-labs/release-manager", "installer/kb-labs-create").
+ * "scopePath" is the resolved absolute filesystem path used for checks (runIn: scopePath) and git ops.
+ *
+ * Discovery (planRelease) always uses repoRoot + scope filter — never scopePath directly.
+ */
+/**
+ * Resolve a scope name to an absolute filesystem path.
+ *
+ * - 'root' → repoRoot
+ * - '@kb-labs/foo' → directory containing package.json with that name
+ * - 'installer/kb-labs-create' → repoRoot/installer/kb-labs-create (direct path)
+ *
+ * Used only where a physical path is required:
+ *   - checks with runIn: 'scopePath'
+ *   - git commit/tag cwd
+ *   - changelog gitCwd
+ *
+ * NOT used for package discovery — planRelease always takes (repoRoot, scope).
+ */
+declare function resolveScopePath(repoRoot: string, scope: string): Promise<string>;
+
+export { type AuditSummary, type BuildResult, type ChangelogGenerator, type CheckId, type CheckResult, type CustomCheckConfig, type PackagePublisher, type PackageVersion, type PackagesFilter, type PipelineOptions, type PipelineResult, type PlannerOptions, 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, planRelease, publishPackages, renderJson, renderMarkdown, renderText, resolveScopePath, restoreSnapshot, runRelease, runReleaseChecks, runReleasePipeline, runSafeBuild, saveSnapshot, spawnCommand, updatePackageVersion, updatePackageVersions, verifyPackage, verifyPackages };