@naturalcycles/dev-lib 20.51.3 → 20.52.0

package/dist/bin/dev-lib.js

@@ -4,6 +4,7 @@ import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
 import { runScript } from '@naturalcycles/nodejs-lib/runScript';
 import { buildCopy, buildProd, eslintAll, lintStagedCommand, runCheck, runOxfmt, runOxlint, runTest, stylelintAll, typecheckWithTS, typecheckWithTSC, typecheckWithTSGO, } from '../check.util.js';
 import { runCommitlint } from '../commitlint.command.js';
+import { releaseCommand } from '../release/release.command.js';
 const commands = [
     { name: 'check', fn: runCheck, desc: '"Run all possible checks": lint, typecheck, then test.' },
     {
@@ -105,6 +106,12 @@ const commands = [
     },
     { name: 'stylelint-no-fix', cliOnly: true, fn: () => stylelintAll(false) },
     { name: 'commitlint', fn: runCommitlint, desc: 'Run commitlint.', cliOnly: true },
+    {
+        name: 'release',
+        fn: releaseCommand,
+        desc: 'Release packages: analyze commits, publish to npm, tag, create GitHub Release. Supports --dry-run.',
+        cliOnly: true,
+    },
     {
         name: 'exit',
         fn: () => console.log('see you!'),

package/dist/config.d.ts

@@ -4,6 +4,35 @@
 export declare function readDevLibConfigIfPresent(cwd?: string): Promise<DevLibConfig>;
 export interface DevLibConfig {
     commitlint?: DevLibCommitlintConfig;
+    release?: DevLibReleaseConfig;
+}
+/**
+ * Config for `dev-lib release`.
+ * The defaults are chosen so that a typical repo needs no config at all.
+ */
+export interface DevLibReleaseConfig {
+    /**
+     * 'monorepo' releases every non-private workspace package, tagged `<pkgName>-v<version>`.
+     * 'single' releases the root package, tagged `v<version>`.
+     * Defaults to auto-detection: 'monorepo' if pnpm-workspace.yaml exists, 'single' otherwise.
+     */
+    mode?: 'monorepo' | 'single';
+    /**
+     * Branches that produce stable releases (npm dist-tag `latest`).
+     * Defaults to ['main', 'master'].
+     */
+    branches?: string[];
+    /**
+     * Branch globs that produce prereleases, versioned `X.Y.Z-<branch>.N`
+     * and published under npm dist-tag = branch name.
+     * Defaults to ['beta-*'].
+     */
+    prereleaseBranches?: string[];
+    /**
+     * Post a ":tada: This PR is included in <release>" comment on each released PR.
+     * Defaults to true.
+     */
+    successComments?: boolean;
 }
 export interface DevLibCommitlintConfig {
     /**

package/dist/config.js

@@ -19,4 +19,12 @@ const devLibConfigSchema = j.object({
         allowedScopes: j.array(j.string()).optional(),
     })
         .optional(),
+    release: j.object
+        .infer({
+        mode: j.enum(['monorepo', 'single']).optional(),
+        branches: j.array(j.string()).optional(),
+        prereleaseBranches: j.array(j.string()).optional(),
+        successComments: j.boolean().optional(),
+    })
+        .optional(),
 });

package/dist/release/commit.util.d.ts

@@ -0,0 +1,14 @@
+import type { ParsedCommit, RawCommit, ReleaseType } from './release.model.js';
+/**
+ * Determine the release type from the commits since the last release.
+ * Returns the highest release type among the commits, or null if none of them warrants a release.
+ *
+ * Rules follow the `@semantic-release/commit-analyzer` defaults (conventional commits only):
+ * breaking change => major, feat => minor, fix/perf/revert => patch, everything else => no release.
+ */
+export declare function analyzeCommits(commits: ParsedCommit[]): ReleaseType | null;
+/**
+ * Parse a raw git commit into a conventional commit.
+ * https://www.conventionalcommits.org/
+ */
+export declare function parseCommit(raw: RawCommit): ParsedCommit;

package/dist/release/commit.util.js

@@ -0,0 +1,60 @@
+/**
+ * Determine the release type from the commits since the last release.
+ * Returns the highest release type among the commits, or null if none of them warrants a release.
+ *
+ * Rules follow the `@semantic-release/commit-analyzer` defaults (conventional commits only):
+ * breaking change => major, feat => minor, fix/perf/revert => patch, everything else => no release.
+ */
+export function analyzeCommits(commits) {
+    let result = null;
+    for (const commit of commits) {
+        const type = getCommitReleaseType(commit);
+        if (type === 'major')
+            return 'major';
+        if (type === 'minor')
+            result = 'minor';
+        else if (type === 'patch' && !result)
+            result = 'patch';
+    }
+    return result;
+}
+/**
+ * Parse a raw git commit into a conventional commit.
+ * https://www.conventionalcommits.org/
+ */
+export function parseCommit(raw) {
+    const { hash, subject, body } = raw;
+    // Same pattern as commitlint.util.ts: type(scope)!: description
+    const match = subject.match(/^(\w+)(?:\(([^)]+)\))?(!)?\s*:\s*(.+)$/);
+    const type = match?.[1];
+    const scope = match?.[2];
+    const bang = !!match?.[3];
+    const description = match?.[4] || subject;
+    // `BREAKING CHANGE:` (or `BREAKING-CHANGE:`) footer, per the conventional commits spec
+    const breakingMatch = body.match(/(?:^|\n)BREAKING[ -]CHANGE:\s*([\s\S]*)/);
+    const breaking = bang || !!breakingMatch;
+    // Detect both `revert:` conventional commits and git-generated `Revert "..."` commits
+    const revert = type === 'revert' || subject.startsWith('Revert ');
+    return {
+        hash,
+        subject,
+        body,
+        type,
+        scope,
+        description,
+        breaking,
+        breakingNote: breaking ? breakingMatch?.[1]?.trim() || description : undefined,
+        revert,
+    };
+}
+function getCommitReleaseType(commit) {
+    if (commit.breaking)
+        return 'major';
+    if (commit.revert)
+        return 'patch';
+    if (commit.type === 'feat')
+        return 'minor';
+    if (commit.type === 'fix' || commit.type === 'perf')
+        return 'patch';
+    return null;
+}

package/dist/release/git.util.d.ts

@@ -0,0 +1,35 @@
+import type { RawCommit, RepoInfo } from './release.model.js';
+/**
+ * Parse the `origin` remote into owner/repo.
+ * Supports both `git@github.com:Owner/repo.git` and `https://github.com/Owner/repo(.git)` remotes.
+ */
+export declare function getRepoInfo(): RepoInfo;
+export declare function getCurrentBranch(): string;
+/**
+ * Make sure the full git history and all tags are available:
+ * CI checkouts are often shallow and without tags, while release calculation is based on tags.
+ * Tolerates fetch failures (e.g. offline local dry-run) with a warning.
+ */
+export declare function ensureFullGitHistory(): void;
+/**
+ * Abort if someone pushed to the branch since this checkout - releasing from a stale HEAD
+ * would compute wrong versions/notes. No-op if the branch has no remote counterpart.
+ */
+export declare function checkHeadIsUpToDateWithRemote(branch: string): void;
+/**
+ * All git tags reachable from HEAD.
+ * Reachability matters: on a prerelease branch this naturally excludes tags of other
+ * prerelease branches, matching semantic-release (which uses `git tag --merged`).
+ */
+export declare function getReachableTags(): string[];
+/**
+ * Commits since the given tag (or all history when no tag), newest first,
+ * optionally limited to the given directory (monorepo mode).
+ */
+export declare function getCommitsSince(tag: string | undefined, relativeDir?: string): RawCommit[];
+/**
+ * Create the release tag on HEAD and push it to origin.
+ * Uses a token-authenticated url when GITHUB_TOKEN is available,
+ * since CI checkouts don't persist git credentials.
+ */
+export declare function createAndPushTag(tag: string, repo: RepoInfo): void;

package/dist/release/git.util.js

@@ -0,0 +1,110 @@
+import { _assert } from '@naturalcycles/js-lib/error/assert.js';
+import { dimGrey } from '@naturalcycles/nodejs-lib/colors';
+import { exec2 } from '@naturalcycles/nodejs-lib/exec2';
+/**
+ * Parse the `origin` remote into owner/repo.
+ * Supports both `git@github.com:Owner/repo.git` and `https://github.com/Owner/repo(.git)` remotes.
+ */
+export function getRepoInfo() {
+    const url = exec2.exec('git remote get-url origin').trim();
+    const match = url.match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
+    _assert(match, `Cannot parse GitHub repo from origin url: ${url}`);
+    const [, owner, repo] = match;
+    return { owner: owner, repo: repo, url: `https://github.com/${owner}/${repo}` };
+}
+export function getCurrentBranch() {
+    const branch = exec2.exec('git rev-parse --abbrev-ref HEAD').trim();
+    if (branch !== 'HEAD')
+        return branch;
+    // Detached HEAD (some CI checkouts) - fall back to the GitHub Actions ref
+    const { GITHUB_REF_NAME } = process.env;
+    _assert(GITHUB_REF_NAME, 'Cannot determine current git branch (detached HEAD)');
+    return GITHUB_REF_NAME;
+}
+/**
+ * Make sure the full git history and all tags are available:
+ * CI checkouts are often shallow and without tags, while release calculation is based on tags.
+ * Tolerates fetch failures (e.g. offline local dry-run) with a warning.
+ */
+export function ensureFullGitHistory() {
+    try {
+        const shallow = exec2.exec('git rev-parse --is-shallow-repository').trim() === 'true';
+        if (shallow) {
+            exec2.exec('git fetch --unshallow --tags --quiet', { log: true });
+        }
+        else {
+            exec2.exec('git fetch --tags --quiet', { log: true });
+        }
+    }
+    catch (err) {
+        console.log(dimGrey(`git fetch failed, continuing with local tags/history: ${err}`));
+    }
+}
+/**
+ * Abort if someone pushed to the branch since this checkout - releasing from a stale HEAD
+ * would compute wrong versions/notes. No-op if the branch has no remote counterpart.
+ */
+export function checkHeadIsUpToDateWithRemote(branch) {
+    let remoteSha;
+    try {
+        remoteSha = exec2.exec(`git ls-remote origin "refs/heads/${branch}"`).split('\t')[0]?.trim();
+    }
+    catch (err) {
+        console.log(dimGrey(`git ls-remote failed, skipping up-to-date check: ${err}`));
+        return;
+    }
+    if (!remoteSha)
+        return;
+    const headSha = exec2.exec('git rev-parse HEAD').trim();
+    _assert(remoteSha === headSha, `Local HEAD (${headSha.slice(0, 7)}) is not up to date with remote ${branch} (${remoteSha.slice(0, 7)}) - aborting release`);
+}
+/**
+ * All git tags reachable from HEAD.
+ * Reachability matters: on a prerelease branch this naturally excludes tags of other
+ * prerelease branches, matching semantic-release (which uses `git tag --merged`).
+ */
+export function getReachableTags() {
+    return exec2
+        .exec('git tag --merged HEAD')
+        .split('\n')
+        .map(t => t.trim())
+        .filter(Boolean);
+}
+/**
+ * Commits since the given tag (or all history when no tag), newest first,
+ * optionally limited to the given directory (monorepo mode).
+ */
+export function getCommitsSince(tag, relativeDir) {
+    // %x1f (unit separator) between fields, %x1e (record separator) between commits
+    const range = tag ? `"${tag}..HEAD"` : 'HEAD';
+    const pathFilter = relativeDir ? ` -- "${relativeDir}"` : '';
+    const out = exec2.exec(`git log --format="%H%x1f%s%x1f%b%x1e" ${range}${pathFilter}`);
+    return out
+        .split('\u001E')
+        .map(record => record.trim())
+        .filter(Boolean)
+        .map(record => {
+        const [hash = '', subject = '', body = ''] = record.split('\u001F');
+        return { hash, subject, body: body.trim() };
+    })
+        .filter(c => c.hash);
+}
+/**
+ * Create the release tag on HEAD and push it to origin.
+ * Uses a token-authenticated url when GITHUB_TOKEN is available,
+ * since CI checkouts don't persist git credentials.
+ */
+export function createAndPushTag(tag, repo) {
+    exec2.exec(`git tag "${tag}"`);
+    const token = process.env['GITHUB_TOKEN'] || process.env['GH_TOKEN'];
+    const pushUrl = token
+        ? `https://x-access-token:${token}@github.com/${repo.owner}/${repo.repo}.git`
+        : 'origin';
+    try {
+        exec2.exec(`git push "${pushUrl}" "refs/tags/${tag}"`);
+    }
+    catch {
+        // Sanitized rethrow: the original error message contains the failed command incl. the token
+        throw new Error(`Failed to push tag ${tag} to origin`);
+    }
+}

package/dist/release/github.util.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedCommit, RepoInfo } from './release.model.js';
+export declare class GithubApi {
+    private repo;
+    constructor(repo: RepoInfo, token: string);
+    private fetcher;
+    /**
+     * Create a GitHub Release for an existing tag. Returns the release html url.
+     */
+    createRelease(input: {
+        tag: string;
+        notes: string;
+        prerelease: boolean;
+    }): Promise<string>;
+    /**
+     * Comment on the merged PRs whose commits are part of this release.
+     * Failures are logged, not thrown - comments are not worth failing a published release over.
+     */
+    commentOnReleasedPrs(commits: ParsedCommit[], input: {
+        tag: string;
+        releaseUrl: string;
+    }): Promise<void>;
+}

package/dist/release/github.util.js

@@ -0,0 +1,65 @@
+import { getFetcher } from '@naturalcycles/js-lib/http';
+import { dimGrey } from '@naturalcycles/nodejs-lib/colors';
+export class GithubApi {
+    repo;
+    constructor(repo, token) {
+        this.repo = repo;
+        this.fetcher = getFetcher({
+            baseUrl: 'https://api.github.com',
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: 'application/vnd.github+json',
+                'user-agent': 'naturalcycles-dev-lib',
+            },
+        });
+    }
+    fetcher;
+    /**
+     * Create a GitHub Release for an existing tag. Returns the release html url.
+     */
+    async createRelease(input) {
+        const { repo } = this;
+        const { html_url: htmlUrl } = await this.fetcher.post(`/repos/${repo.owner}/${repo.repo}/releases`, {
+            json: {
+                tag_name: input.tag,
+                name: input.tag,
+                body: input.notes,
+                prerelease: input.prerelease,
+            },
+        });
+        return htmlUrl;
+    }
+    /**
+     * Comment on the merged PRs whose commits are part of this release.
+     * Failures are logged, not thrown - comments are not worth failing a published release over.
+     */
+    async commentOnReleasedPrs(commits, input) {
+        const { repo } = this;
+        const prNumbers = new Set();
+        for (const commit of commits) {
+            try {
+                const prs = await this.fetcher.get(`/repos/${repo.owner}/${repo.repo}/commits/${commit.hash}/pulls`);
+                for (const pr of prs) {
+                    if (pr.merged_at)
+                        prNumbers.add(pr.number);
+                }
+            }
+            catch (err) {
+                console.log(dimGrey(`Failed to look up PRs for commit ${commit.hash.slice(0, 7)}: ${err}`));
+            }
+        }
+        for (const prNumber of prNumbers) {
+            try {
+                await this.fetcher.post(`/repos/${repo.owner}/${repo.repo}/issues/${prNumber}/comments`, {
+                    json: {
+                        body: `:tada: This PR is included in [${input.tag}](${input.releaseUrl}) :tada:`,
+                    },
+                });
+                console.log(dimGrey(`Commented on PR #${prNumber}`));
+            }
+            catch (err) {
+                console.log(dimGrey(`Failed to comment on PR #${prNumber}: ${err}`));
+            }
+        }
+    }
+}

package/dist/release/notes.util.d.ts

@@ -0,0 +1,16 @@
+import type { ParsedCommit, RepoInfo } from './release.model.js';
+/**
+ * Generate release notes markdown for a GitHub Release,
+ * following the format of `@semantic-release/release-notes-generator` (angular preset):
+ * sections per commit type, entries linking to commits, compare link in the header.
+ */
+export declare function generateReleaseNotes(input: {
+    repo: RepoInfo;
+    commits: ParsedCommit[];
+    lastTag?: string;
+    nextTag: string;
+    /**
+     * `YYYY-MM-DD`, defaults to today. Injectable for tests.
+     */
+    date?: string;
+}): string;

package/dist/release/notes.util.js

@@ -0,0 +1,34 @@
+/**
+ * Generate release notes markdown for a GitHub Release,
+ * following the format of `@semantic-release/release-notes-generator` (angular preset):
+ * sections per commit type, entries linking to commits, compare link in the header.
+ */
+export function generateReleaseNotes(input) {
+    const { repo, commits, lastTag, nextTag } = input;
+    const date = input.date || new Date().toISOString().slice(0, 10);
+    const header = lastTag
+        ? `## [${nextTag}](${repo.url}/compare/${lastTag}...${nextTag}) (${date})`
+        : `## ${nextTag} (${date})`;
+    const sections = [header];
+    addSection(sections, '### Features', commits.filter(c => c.type === 'feat'), repo);
+    addSection(sections, '### Bug Fixes', commits.filter(c => c.type === 'fix'), repo);
+    addSection(sections, '### Performance Improvements', commits.filter(c => c.type === 'perf'), repo);
+    addSection(sections, '### Reverts', commits.filter(c => c.revert && c.type !== 'feat' && c.type !== 'fix' && c.type !== 'perf'), repo);
+    const breaking = commits.filter(c => c.breaking);
+    if (breaking.length) {
+        sections.push('### ⚠ BREAKING CHANGES', breaking.map(c => `* ${scopePrefix(c)}${c.breakingNote}`).join('\n'));
+    }
+    return sections.join('\n\n') + '\n';
+}
+function addSection(sections, title, commits, repo) {
+    if (!commits.length)
+        return;
+    sections.push(title, commits.map(c => formatCommitEntry(c, repo)).join('\n'));
+}
+function formatCommitEntry(c, repo) {
+    const shortHash = c.hash.slice(0, 7);
+    return `* ${scopePrefix(c)}${c.description} ([${shortHash}](${repo.url}/commit/${c.hash}))`;
+}
+function scopePrefix(c) {
+    return c.scope ? `**${c.scope}:** ` : '';
+}

package/dist/release/release.command.d.ts

@@ -0,0 +1,17 @@
+import type { ReleaseChannel } from './release.model.js';
+/**
+ * Release workspace packages (or the root package in single-repo mode):
+ * analyze conventional commits since the last release tag, compute the next semver,
+ * publish to npm via `pnpm publish`, push the release tag and create a GitHub Release.
+ *
+ * A lean replacement for semantic-release. Git tags are the source of truth for versions -
+ * the package.json version bump happens in the working tree only and is never committed.
+ *
+ * Must be run from the repo root.
+ */
+export declare function releaseCommand(): Promise<void>;
+/**
+ * Resolve the release channel from the current branch, or undefined if the branch
+ * is not configured for release.
+ */
+export declare function resolveChannel(branch: string, stableBranches: string[], prereleaseBranches: string[]): ReleaseChannel | undefined;

package/dist/release/release.command.js

@@ -0,0 +1,159 @@
+import { _assert } from '@naturalcycles/js-lib/error/assert.js';
+import { _parseArgs } from '@naturalcycles/nodejs-lib/args';
+import { dimGrey, white } from '@naturalcycles/nodejs-lib/colors';
+import { appendToGithubOutput } from '@naturalcycles/nodejs-lib/env';
+import { exec2 } from '@naturalcycles/nodejs-lib/exec2';
+import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
+import picomatch from 'picomatch';
+import { readDevLibConfigIfPresent } from '../config.js';
+import { analyzeCommits, parseCommit } from './commit.util.js';
+import { checkHeadIsUpToDateWithRemote, createAndPushTag, ensureFullGitHistory, getCommitsSince, getCurrentBranch, getReachableTags, getRepoInfo, } from './git.util.js';
+import { GithubApi } from './github.util.js';
+import { generateReleaseNotes } from './notes.util.js';
+import { getLastRelease, getNextVersion, getVersionsFromTags } from './version.util.js';
+import { discoverReleasePackages, resolveReleaseMode } from './workspace.util.js';
+/**
+ * Release workspace packages (or the root package in single-repo mode):
+ * analyze conventional commits since the last release tag, compute the next semver,
+ * publish to npm via `pnpm publish`, push the release tag and create a GitHub Release.
+ *
+ * A lean replacement for semantic-release. Git tags are the source of truth for versions -
+ * the package.json version bump happens in the working tree only and is never committed.
+ *
+ * Must be run from the repo root.
+ */
+export async function releaseCommand() {
+    const argv = _parseArgs({
+        'dry-run': {
+            type: 'boolean',
+            default: false,
+            desc: 'Compute and print the release plan without publishing anything',
+        },
+        filter: {
+            type: 'string',
+            desc: 'Only release the given package (name, name without scope, or directory)',
+        },
+    });
+    const dryRun = argv['dry-run'];
+    const { release: cfg = {} } = await readDevLibConfigIfPresent();
+    const stableBranches = cfg.branches || ['main', 'master'];
+    const prereleaseBranches = cfg.prereleaseBranches || ['beta-*'];
+    const successComments = cfg.successComments !== false;
+    const repo = getRepoInfo();
+    const branch = getCurrentBranch();
+    const channel = resolveChannel(branch, stableBranches, prereleaseBranches);
+    if (!channel) {
+        console.log(`Branch "${branch}" is not configured for release - nothing to do`);
+        return;
+    }
+    const token = process.env['GITHUB_TOKEN'] || process.env['GH_TOKEN'];
+    if (!dryRun) {
+        _assert(token, 'GITHUB_TOKEN (or GH_TOKEN) is required to release, or use --dry-run');
+    }
+    ensureFullGitHistory();
+    if (!dryRun) {
+        checkHeadIsUpToDateWithRemote(branch);
+    }
+    const mode = resolveReleaseMode(cfg.mode);
+    const packages = discoverReleasePackages(mode, argv.filter);
+    const tags = getReachableTags();
+    console.log(`Releasing from branch ${white(branch)} (dist-tag ${white(channel.distTag)}), ${mode} mode, ${packages.length} package(s)${dryRun ? dimGrey(' [dry-run]') : ''}`);
+    const released = [];
+    for (const pkg of packages) {
+        const plan = planPackageRelease(pkg, tags, channel, repo);
+        if (!plan) {
+            console.log(dimGrey(`${pkg.name}: no release-worthy commits`));
+            continue;
+        }
+        console.log(white(`${pkg.name}: ${plan.lastRelease?.version || '(first release)'} -> ${plan.nextVersion} (${plan.releaseType}, ${plan.commits.length} commits)`));
+        if (dryRun) {
+            console.log(dimGrey(plan.notes));
+        }
+        else {
+            await executeRelease(plan, repo, { token: token, successComments });
+        }
+        released.push(plan);
+    }
+    console.log(released.length
+        ? `${dryRun ? 'Would release' : 'Released'}: ${released.map(p => `${p.pkg.name}@${p.nextVersion}`).join(', ')}`
+        : 'Nothing to release');
+}
+/**
+ * Resolve the release channel from the current branch, or undefined if the branch
+ * is not configured for release.
+ */
+export function resolveChannel(branch, stableBranches, prereleaseBranches) {
+    if (stableBranches.includes(branch)) {
+        return { distTag: 'latest' };
+    }
+    if (prereleaseBranches.some(glob => picomatch.isMatch(branch, glob))) {
+        _assert(/^[0-9A-Za-z-]+$/.test(branch), `Branch name "${branch}" cannot be used as a prerelease identifier - only letters, numbers and dashes are allowed`);
+        return { distTag: branch, prereleaseId: branch };
+    }
+    return undefined;
+}
+function planPackageRelease(pkg, tags, channel, repo) {
+    const versions = getVersionsFromTags(tags, pkg.tagPrefix);
+    const lastRelease = getLastRelease(versions, pkg.tagPrefix, channel);
+    const commits = getCommitsSince(lastRelease?.tag, pkg.relativeDir || undefined).map(parseCommit);
+    const releaseType = analyzeCommits(commits);
+    if (!releaseType)
+        return null;
+    const pkgJson = fs2.readJson(`${pkg.dir}/package.json`);
+    const nextVersion = getNextVersion({
+        lastRelease,
+        allVersions: versions,
+        releaseType,
+        channel,
+        firstReleaseVersion: pkgJson.version,
+    });
+    const nextTag = `${pkg.tagPrefix}${nextVersion}`;
+    const notes = generateReleaseNotes({ repo, commits, lastTag: lastRelease?.tag, nextTag });
+    return { pkg, lastRelease, releaseType, nextVersion, nextTag, channel, commits, notes };
+}
+async function executeRelease(plan, repo, opt) {
+    const { pkg, nextVersion, nextTag, channel, notes, commits } = plan;
+    bumpPackageJsonVersion(pkg.dir, nextVersion);
+    // Publish before tagging: a failed publish must not leave a tag behind,
+    // as the tag would make the next run consider this version already released.
+    // pnpm rewrites workspace:* deps and handles npm OIDC trusted publishing + provenance.
+    exec2.spawn(`pnpm publish --tag ${channel.distTag} --no-git-checks`, { cwd: pkg.dir });
+    createAndPushTag(nextTag, repo);
+    const github = new GithubApi(repo, opt.token);
+    let releaseUrl;
+    try {
+        releaseUrl = await github.createRelease({
+            tag: nextTag,
+            notes,
+            prerelease: !!channel.prereleaseId,
+        });
+    }
+    catch (err) {
+        throw new Error(`${pkg.name}@${nextVersion} was published and tagged, but GitHub Release creation failed - create it manually for tag ${nextTag}. Cause: ${err}`, { cause: err });
+    }
+    console.log(`GitHub Release created: ${releaseUrl}`);
+    if (opt.successComments) {
+        await github.commentOnReleasedPrs(commits, { tag: nextTag, releaseUrl });
+    }
+    writeGithubOutputs(pkg.name, nextVersion);
+}
+function bumpPackageJsonVersion(dir, version) {
+    const packageJsonPath = `${dir}/package.json`;
+    const pkgJson = fs2.readJson(packageJsonPath);
+    pkgJson['version'] = version;
+    fs2.writeJson(packageJsonPath, pkgJson, { spaces: 2 });
+}
+/**
+ * Expose the release result to subsequent GitHub Actions steps,
+ * e.g. `shared_released=true`, `shared_version=7.660.0`.
+ */
+function writeGithubOutputs(pkgName, version) {
+    const key = pkgName
+        .split('/')
+        .pop()
+        .replaceAll(/[^a-zA-Z0-9_]/g, '_');
+    appendToGithubOutput({
+        [`${key}_released`]: 'true',
+        [`${key}_version`]: version,
+    });
+}

package/dist/release/release.model.d.ts

@@ -0,0 +1,81 @@
+export type ReleaseType = 'major' | 'minor' | 'patch';
+/**
+ * Release channel, resolved from the current git branch and the release config.
+ */
+export interface ReleaseChannel {
+    /**
+     * npm dist-tag to publish under: `latest` on stable branches, the branch name on prerelease branches.
+     */
+    distTag: string;
+    /**
+     * Prerelease identifier (the branch name, e.g. `beta-my-feature`).
+     * Undefined on stable branches.
+     */
+    prereleaseId?: string;
+}
+export interface ReleasePackage {
+    name: string;
+    /**
+     * Absolute path to the package directory.
+     */
+    dir: string;
+    /**
+     * Package directory relative to the repo root, e.g. `packages/js-lib`.
+     * Empty string in single-repo mode (the root package) - means "no path filtering".
+     */
+    relativeDir: string;
+    /**
+     * Git tag prefix: `<name>-v` in monorepo mode, `v` in single-repo mode.
+     * Full tag is `<tagPrefix><version>`, e.g. `@naturalcycles/js-lib-v15.80.0` or `v7.660.0`.
+     */
+    tagPrefix: string;
+}
+export interface RepoInfo {
+    owner: string;
+    repo: string;
+    /**
+     * e.g. `https://github.com/NaturalCycles/js-libs`
+     */
+    url: string;
+}
+export interface RawCommit {
+    hash: string;
+    subject: string;
+    body: string;
+}
+export interface ParsedCommit {
+    hash: string;
+    subject: string;
+    body: string;
+    /**
+     * Conventional commit type, e.g. `feat`, `fix`.
+     * Undefined if the subject is not a valid conventional commit.
+     */
+    type?: string;
+    scope?: string;
+    /**
+     * Subject without the `type(scope):` prefix.
+     * Falls back to the full subject for non-conventional commits.
+     */
+    description: string;
+    breaking: boolean;
+    /**
+     * Text of the `BREAKING CHANGE:` footer, or the description when marked with `!` only.
+     */
+    breakingNote?: string;
+    revert: boolean;
+}
+export interface LastRelease {
+    version: string;
+    tag: string;
+}
+export interface ReleasePlan {
+    pkg: ReleasePackage;
+    lastRelease?: LastRelease;
+    releaseType: ReleaseType;
+    nextVersion: string;
+    nextTag: string;
+    channel: ReleaseChannel;
+    commits: ParsedCommit[];
+    notes: string;
+}

package/dist/release/release.model.js

@@ -0,0 +1 @@
+export {};

package/dist/release/version.util.d.ts

@@ -0,0 +1,38 @@
+import type { LastRelease, ReleaseChannel, ReleaseType } from './release.model.js';
+/**
+ * Extract versions from git tags matching the package's tag prefix.
+ * Non-semver tags (and tags of other packages) are ignored.
+ */
+export declare function getVersionsFromTags(tags: string[], tagPrefix: string): string[];
+/**
+ * Determine the last release relevant to the given channel,
+ * replicating semantic-release `getLastRelease` semantics:
+ *
+ * - stable channel: the highest stable version
+ * - prerelease channel: the highest among stable versions and prereleases of this channel
+ *   (a prerelease belongs to the channel when its prerelease components include the identifier,
+ *   e.g. `7.660.0-beta-x.4` belongs to channel `beta-x`)
+ */
+export declare function getLastRelease(versions: string[], tagPrefix: string, channel: ReleaseChannel): LastRelease | undefined;
+/**
+ * Compute the next version, replicating semantic-release `getNextVersion` semantics.
+ *
+ * On a prerelease channel, when the last release is already a prerelease of this channel,
+ * the next version is the highest of:
+ * - the prerelease increment (`7.660.0-beta-x.4` => `7.660.0-beta-x.5`)
+ * - the increment of the latest overall version (incl. prereleases) with a reset counter
+ *   (jumps the base when a bigger change type lands mid-prerelease, e.g. to `8.0.0-beta-x.1`)
+ */
+export declare function getNextVersion(input: {
+    lastRelease?: LastRelease;
+    /**
+     * All versions of the package reachable from HEAD (any channel, any stability).
+     */
+    allVersions: string[];
+    releaseType: ReleaseType;
+    channel: ReleaseChannel;
+    /**
+     * Used when the package has no release tags yet. Defaults to `1.0.0`.
+     */
+    firstReleaseVersion?: string;
+}): string;

package/dist/release/version.util.js

@@ -0,0 +1,72 @@
+import semver from 'semver';
+/**
+ * Extract versions from git tags matching the package's tag prefix.
+ * Non-semver tags (and tags of other packages) are ignored.
+ */
+export function getVersionsFromTags(tags, tagPrefix) {
+    const versions = [];
+    for (const tag of tags) {
+        if (!tag.startsWith(tagPrefix))
+            continue;
+        const version = tag.slice(tagPrefix.length);
+        if (semver.valid(version))
+            versions.push(version);
+    }
+    return versions;
+}
+/**
+ * Determine the last release relevant to the given channel,
+ * replicating semantic-release `getLastRelease` semantics:
+ *
+ * - stable channel: the highest stable version
+ * - prerelease channel: the highest among stable versions and prereleases of this channel
+ *   (a prerelease belongs to the channel when its prerelease components include the identifier,
+ *   e.g. `7.660.0-beta-x.4` belongs to channel `beta-x`)
+ */
+export function getLastRelease(versions, tagPrefix, channel) {
+    const candidates = versions.filter(v => {
+        const prerelease = semver.prerelease(v);
+        if (!prerelease)
+            return true; // stable versions are always candidates
+        return !!channel.prereleaseId && prerelease.includes(channel.prereleaseId);
+    });
+    const [version] = candidates.sort(semver.rcompare);
+    if (!version)
+        return;
+    return { version, tag: `${tagPrefix}${version}` };
+}
+/**
+ * Compute the next version, replicating semantic-release `getNextVersion` semantics.
+ *
+ * On a prerelease channel, when the last release is already a prerelease of this channel,
+ * the next version is the highest of:
+ * - the prerelease increment (`7.660.0-beta-x.4` => `7.660.0-beta-x.5`)
+ * - the increment of the latest overall version (incl. prereleases) with a reset counter
+ *   (jumps the base when a bigger change type lands mid-prerelease, e.g. to `8.0.0-beta-x.1`)
+ */
+export function getNextVersion(input) {
+    const { lastRelease, allVersions, releaseType, channel } = input;
+    const { prereleaseId } = channel;
+    if (!lastRelease) {
+        const { firstReleaseVersion } = input;
+        const first = (firstReleaseVersion &&
+            !semver.prerelease(firstReleaseVersion) &&
+            semver.valid(firstReleaseVersion)) ||
+            '1.0.0';
+        return prereleaseId ? `${first}-${prereleaseId}.1` : first;
+    }
+    const lastVersion = lastRelease.version;
+    if (!prereleaseId) {
+        return semver.inc(lastVersion, releaseType);
+    }
+    if (semver.prerelease(lastVersion)) {
+        // The last release is a prerelease of this channel (guaranteed by getLastRelease)
+        const latestOverall = allVersions.toSorted(semver.rcompare)[0];
+        return highest(semver.inc(lastVersion, 'prerelease'), `${semver.inc(latestOverall, releaseType)}-${prereleaseId}.1`);
+    }
+    // The last release is stable - start a new prerelease sequence off it
+    return `${semver.inc(lastVersion, releaseType)}-${prereleaseId}.1`;
+}
+function highest(v1, v2) {
+    return semver.gt(v1, v2) ? v1 : v2;
+}

package/dist/release/workspace.util.d.ts

@@ -0,0 +1,13 @@
+import type { ReleasePackage } from './release.model.js';
+export type ReleaseMode = 'monorepo' | 'single';
+/**
+ * Detect the release mode: 'monorepo' when a pnpm workspace is present, 'single' otherwise.
+ */
+export declare function resolveReleaseMode(configured?: ReleaseMode): ReleaseMode;
+/**
+ * Discover the packages to release. Must be run from the repo root.
+ *
+ * - monorepo: every non-private workspace package, tagged as `<name>-v<version>`
+ * - single: the root package, tagged as `v<version>`
+ */
+export declare function discoverReleasePackages(mode: ReleaseMode, filter?: string): ReleasePackage[];

package/dist/release/workspace.util.js

@@ -0,0 +1,49 @@
+import path from 'node:path';
+import { _assert } from '@naturalcycles/js-lib/error/assert.js';
+import { exec2 } from '@naturalcycles/nodejs-lib/exec2';
+import { fs2 } from '@naturalcycles/nodejs-lib/fs2';
+/**
+ * Detect the release mode: 'monorepo' when a pnpm workspace is present, 'single' otherwise.
+ */
+export function resolveReleaseMode(configured) {
+    return configured || (fs2.pathExists('pnpm-workspace.yaml') ? 'monorepo' : 'single');
+}
+/**
+ * Discover the packages to release. Must be run from the repo root.
+ *
+ * - monorepo: every non-private workspace package, tagged as `<name>-v<version>`
+ * - single: the root package, tagged as `v<version>`
+ */
+export function discoverReleasePackages(mode, filter) {
+    const packages = mode === 'monorepo' ? discoverWorkspacePackages() : [getRootPackage()];
+    if (!filter)
+        return packages;
+    const filtered = packages.filter(p => p.name === filter || p.name.split('/').pop() === filter || p.relativeDir === filter);
+    _assert(filtered.length, `--filter "${filter}" matched none of the release packages: ${packages.map(p => p.name).join(', ')}`);
+    return filtered;
+}
+function discoverWorkspacePackages() {
+    const root = process.cwd();
+    const out = exec2.exec('pnpm -r ls --depth -1 --json');
+    const list = JSON.parse(out);
+    return list
+        .filter(p => p.name && !p.private && p.path !== root)
+        .map(p => ({
+        name: p.name,
+        dir: p.path,
+        relativeDir: path.relative(root, p.path),
+        tagPrefix: `${p.name}-v`,
+    }));
+}
+function getRootPackage() {
+    const dir = process.cwd();
+    const pkg = fs2.readJson(`${dir}/package.json`);
+    _assert(pkg.name, 'package.json has no "name" - cannot release');
+    _assert(!pkg.private, `${pkg.name} is private - cannot release`);
+    return {
+        name: pkg.name,
+        dir,
+        relativeDir: '',
+        tagPrefix: 'v',
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/dev-lib",
   "type": "module",
-  "version": "20.51.3",
+  "version": "20.52.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@naturalcycles/nodejs-lib": "^15",
@@ -14,6 +14,7 @@
     "oxlint-tsgolint": "0.23.0",
     "picomatch": "^4",
     "prompts": "^2",
+    "semver": "^7",
     "std-env": "^4"
   },
   "peerDependencies": {
@@ -47,7 +48,9 @@
   },
   "devDependencies": {
     "@types/node": "^26",
+    "@types/picomatch": "^4",
     "@types/prompts": "^2",
+    "@types/semver": "^7",
     "typescript": "rc"
   },
   "exports": {