rman 1.0.7 → 1.0.9

package/services/github-release.service.js

@@ -0,0 +1,265 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import fastGlob from 'fast-glob';
+import semver from 'semver';
+import { expandTag, tagPattern } from '../utils/change-hash.js';
+import { GitHelper } from '../utils/git.js';
+import { expandReleaseTag, isCalendarVersion, releaseTagPattern } from '../utils/release-version.js';
+import { ChangelogService } from './changelog.service.js';
+export var GithubReleaseService;
+(function (GithubReleaseService) {
+    /**
+     * Computes what `publish --target github` *would* do - **one** release per run, or none.
+     *
+     * A GitHub Release is a property of the repository, not of a package: the tag covers the whole
+     * source tree, so everything that shipped under it belongs in it. That makes the `"github"`
+     * target a repository-level opt-in (typically in the root `.rmanrc`, alongside `"npm"`); it's
+     * honored as soon as *any* package resolves it, since a per-package release would have to invent
+     * a tag no package owns.
+     *
+     * The release is identified by the repository's own version (the root's - see
+     * `VersionService`'s `buildRootEntry`): its release tag when that version is a calendar one, and
+     * otherwise the tag of the single shared version, which is the group's own tag - so a repo with
+     * one version line gets no second name for the release it already has. Whether a release exists
+     * for that tag decides `'up-to-date'` vs `'publish'`.
+     *
+     * Uncommitted changes anywhere make it `'error'` unless `options.ignoreDirty` downgrades it to
+     * `'skip'`. An unresolvable `owner/repo`, or a lookup that fails for any reason other than "no
+     * such release", is `'error'` too - a blocking misconfiguration rather than a silent "not
+     * released yet" that only fails later.
+     */
+    async function getPlan(repository, options = {}, deps = {}) {
+        const root = repository.rootPackage;
+        const wanted = [root, ...repository.getPackages()].some(pkg => targetsGithub(pkg) && !pkg.config.publish?.skip);
+        if (!wanted)
+            return [];
+        const git = new GitHelper({ cwd: repository.dirname });
+        const base = { package: root, version: root.version };
+        const repo = options.repository ?? root.config?.publish?.github?.repository ?? repoFromRemoteUrl(await git.remoteUrl());
+        if (!repo) {
+            return [
+                {
+                    ...base,
+                    status: 'error',
+                    reason: 'cannot resolve "owner/repo" - set "publish.github.repository" or an "origin" remote',
+                },
+            ];
+        }
+        const tag = releaseTagFor(root);
+        if ((await git.listDirtyFiles()).length) {
+            return [
+                {
+                    ...base,
+                    tag,
+                    repository: repo,
+                    status: options.ignoreDirty ? 'skip' : 'error',
+                    reason: 'uncommitted local changes',
+                },
+            ];
+        }
+        // The tag is `version`'s to create, so a missing one means either it never ran or this clone
+        // simply doesn't have the tags. Both are refused rather than released: the notes are bounded by
+        // the *previous* release tag, which can't be found without it either, so the release would
+        // silently come out covering the entire history instead of what actually shipped.
+        if (!(await git.tagExists(tag))) {
+            return [
+                {
+                    ...base,
+                    tag,
+                    repository: repo,
+                    status: 'error',
+                    reason: `release tag "${tag}" does not exist here - run "version" first, or fetch tags into this clone`,
+                },
+            ];
+        }
+        const releaseExists = deps.releaseExists ?? defaultReleaseExists;
+        try {
+            const exists = await releaseExists(repo, tag);
+            return [
+                {
+                    ...base,
+                    tag,
+                    repository: repo,
+                    status: exists ? 'up-to-date' : 'publish',
+                    reason: exists ? `${repo} already has a release for ${tag}` : 'never released',
+                },
+            ];
+        }
+        catch (e) {
+            return [{ ...base, tag, repository: repo, status: 'error', reason: e.message }];
+        }
+    }
+    GithubReleaseService.getPlan = getPlan;
+    /**
+     * Creates the repository's GitHub Release, then uploads whatever `publish.github.assets` globs
+     * match. The body covers **every** package that shipped under this release - not just the ones
+     * naming `"github"` as a target - since the tag covers all of their code either way.
+     *
+     * Each package's notes are bounded by the *previous repository release*, and headed with that
+     * package's own version, so a repo whose packages sit on different version lines still reads
+     * correctly. A package with nothing in that range simply contributes no section, which is also
+     * how a package that didn't ship in this release is left out - no ancestry arithmetic needed.
+     *
+     * An existing release for the tag is updated rather than treated as a failure, so a re-run after
+     * a partial failure converges.
+     */
+    async function applyPlan(repository, plan) {
+        const entry = plan.find(e => e.status === 'publish');
+        if (!entry)
+            return plan;
+        const git = new GitHelper({ cwd: repository.dirname });
+        try {
+            const body = await buildReleaseNotes(repository, git, entry.tag);
+            const release = await createOrUpdateRelease(entry.repository, entry.tag, {
+                name: entry.tag,
+                body,
+                draft: !!repository.rootPackage.config?.publish?.github?.draft,
+                prerelease: resolvePrerelease(repository.rootPackage, entry.version),
+            });
+            await uploadAssets(repository, entry.repository, release.id);
+            return plan;
+        }
+        catch (e) {
+            return plan.map(e2 => (e2 === entry ? { ...e2, status: 'error', reason: e.message } : e2));
+        }
+    }
+    GithubReleaseService.applyPlan = applyPlan;
+})(GithubReleaseService || (GithubReleaseService = {}));
+const GITHUB_API = 'https://api.github.com';
+const GITHUB_UPLOADS = 'https://uploads.github.com';
+function targetsGithub(pkg) {
+    const target = pkg.config.publish?.target;
+    const targets = Array.isArray(target) ? target : target ? [target] : ['npm'];
+    return targets.includes('github');
+}
+/** The tag naming this repository's release. A calendar root version means several version lines,
+ *  so the release needs a name of its own (`release-*`); a plain one means every package shares it,
+ *  and that shared version's tag already *is* the release. */
+function releaseTagFor(root) {
+    return isCalendarVersion(root.version) ? expandReleaseTag(root, root.version) : expandTag(root, root.version);
+}
+/** The glob matching the tags `releaseTagFor` produces - for stepping back to the previous one. */
+function releaseTagGlob(root) {
+    const pattern = isCalendarVersion(root.version) ? releaseTagPattern(root) : tagPattern(root);
+    return pattern.replace('{name}', root.name);
+}
+function resolvePrerelease(root, version) {
+    const configured = root.config?.publish?.github?.prerelease;
+    // A calendar version's time part is a semver prerelease identifier by construction - it says
+    // nothing about the release being a preview, so it must not be read as one.
+    return configured ?? (!isCalendarVersion(version) && !!semver.prerelease(version));
+}
+/** `owner/repo` out of either remote URL form git hands back - `git@github.com:owner/repo.git`
+ *  (SSH) or `https://github.com/owner/repo.git` (HTTPS, credentials and all). `undefined` for
+ *  anything that isn't recognizably a GitHub remote. */
+function repoFromRemoteUrl(url) {
+    if (!url)
+        return undefined;
+    const match = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(url.trim());
+    return match ? `${match[1]}/${match[2]}` : undefined;
+}
+function githubToken() {
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (!token)
+        throw new Error('GITHUB_TOKEN (or GH_TOKEN) environment variable is required to publish to GitHub');
+    return token;
+}
+function githubHeaders() {
+    return {
+        Authorization: `Bearer ${githubToken()}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+}
+/** `GET /repos/{owner}/{repo}/releases/tags/{tag}` - `false` only for a genuine 404 (no release
+ *  for that tag yet). Anything else throws rather than reading as "not published": a bad token or
+ *  a typo'd repository would otherwise silently plan a publish that only fails much later. */
+async function defaultReleaseExists(repository, tag) {
+    const res = await fetch(`${GITHUB_API}/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`, {
+        headers: githubHeaders(),
+    });
+    if (res.ok)
+        return true;
+    if (res.status === 404)
+        return false;
+    throw new Error(`GitHub release lookup for "${tag}" failed: ${res.status} ${res.statusText}`);
+}
+/**
+ * The release body: one changelog section per package that shipped since the previous repository
+ * release. Generated per package rather than in one call, because each carries its own version -
+ * under independent versioning they differ, and a single shared label would misname all but one.
+ *
+ * The boundary is deliberately the previous *release*, not `changelog`'s own auto-detection: the
+ * tag being released already exists by the time `publish` runs, so auto-detection would resolve to
+ * it and correctly report nothing at all.
+ */
+async function buildReleaseNotes(repository, git, releaseTag) {
+    const root = repository.rootPackage;
+    const previous = (await git.describeTag(releaseTagGlob(root), `${releaseTag}^`)) ?? (await git.rootCommit());
+    if (!previous)
+        return '';
+    const sections = [];
+    for (const pkg of [...repository.getPackages(), root]) {
+        const entries = await ChangelogService.getEntries(repository, {
+            from: previous,
+            root: true,
+            includeSkipped: true,
+            scope: pkg.name,
+            version: pkg.version,
+        });
+        for (const entry of entries)
+            sections.push(entry.content.trim());
+    }
+    return sections.join('\n\n');
+}
+async function createOrUpdateRelease(repository, tag, fields) {
+    const res = await fetch(`${GITHUB_API}/repos/${repository}/releases`, {
+        method: 'POST',
+        headers: { ...githubHeaders(), 'Content-Type': 'application/json' },
+        body: JSON.stringify({ tag_name: tag, ...fields }),
+    });
+    if (res.ok)
+        return (await res.json());
+    // 422 is how the API reports "a release for this tag already exists" - converge onto it instead
+    // of failing, so re-running after a partially failed release finishes the job.
+    if (res.status !== 422) {
+        throw new Error(`Unable to create GitHub release "${tag}": ${res.status} ${res.statusText}`);
+    }
+    const existing = await fetch(`${GITHUB_API}/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`, {
+        headers: githubHeaders(),
+    });
+    if (!existing.ok) {
+        throw new Error(`Unable to create GitHub release "${tag}": ${res.status} ${res.statusText}`);
+    }
+    const release = (await existing.json());
+    const updated = await fetch(`${GITHUB_API}/repos/${repository}/releases/${release.id}`, {
+        method: 'PATCH',
+        headers: { ...githubHeaders(), 'Content-Type': 'application/json' },
+        body: JSON.stringify(fields),
+    });
+    if (!updated.ok) {
+        throw new Error(`Unable to update GitHub release "${tag}": ${updated.status} ${updated.statusText}`);
+    }
+    return release;
+}
+/** Every `publish.github.assets` glob across the repository, each resolved against its own
+ *  package's directory - an app ships its artifacts from its own folder, but they all land on the
+ *  one release the repository cut. */
+async function uploadAssets(repository, repo, releaseId) {
+    for (const pkg of [repository.rootPackage, ...repository.getPackages()]) {
+        const patterns = pkg.config.publish?.github?.assets;
+        if (!patterns?.length)
+            continue;
+        const files = await fastGlob(patterns, { cwd: pkg.dirname, absolute: true, onlyFiles: true });
+        for (const file of files) {
+            const name = path.basename(file);
+            const res = await fetch(`${GITHUB_UPLOADS}/repos/${repo}/releases/${releaseId}/assets?name=${encodeURIComponent(name)}`, {
+                method: 'POST',
+                headers: { ...githubHeaders(), 'Content-Type': 'application/octet-stream' },
+                body: fs.readFileSync(file),
+            });
+            if (!res.ok)
+                throw new Error(`Unable to upload asset "${name}": ${res.status} ${res.statusText}`);
+        }
+    }
+}

package/services/list.service.d.ts

@@ -1,5 +1,5 @@
-import type { RmanConfig } from '../core/config.js';
 import type { Repository } from '../core/repository.js';
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 import { type PackageFilterOptions } from '../utils/package-filter.js';
 export declare namespace ListService {
     interface Options extends PackageFilterOptions {

package/services/publish.service.js

@@ -41,7 +41,15 @@ export var PublishService;
         const entries = new Map();
         const toCheck = [];
         for (const pkg of packages) {
-            if (pkg.isPrivate) {
+            if (pkg.config.publish?.skip) {
+                entries.set(pkg.name, {
+                    package: pkg,
+                    version: pkg.version,
+                    status: 'skip',
+                    reason: 'excluded via .rmanrc "publish.skip"',
+                });
+            }
+            else if (pkg.isPrivate) {
                 entries.set(pkg.name, { package: pkg, version: pkg.version, status: 'skip', reason: 'private package' });
             }
             else if (isDirty(pkg)) {

package/services/version.service.d.ts

@@ -20,6 +20,13 @@ export declare namespace VersionService {
          *  `incVersion`. Has no effect when `bump` is an explicit semver version rather than a keyword
          *  (there's no severity left to "pre-fix" at that point). */
         preid?: string;
+        /** Overrides the npm registry lookup `detectChangeHash` falls back to for a package that has
+         *  no release tag yet - mainly for tests, so they don't depend on network access or a real
+         *  published package. Same shape as `ChangelogService.Deps`/`PublishService.Deps`' own. */
+        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
+        /** Clock behind a monorepo root's calendar release version - injectable so tests are
+         *  deterministic. Default `() => new Date()`. */
+        now?: () => Date;
     }
     interface ApplyOptions {
         /** Push the resulting commit(s) and tag(s) to the remote once applied. Default false - same
@@ -61,8 +68,8 @@ export declare namespace VersionService {
      * version currently found among its own members (never persisted anywhere) - see
      * `resolveGroupKey`.
      *
-     * Within a group, a member with real commits since its own last release tag (or an explicit
-     * `bump`) sets the group's severity to the highest found among changed members; the new version
+     * Within a group, a member with real commits since its own last release (or an explicit `bump`)
+     * sets the group's severity to the highest found among changed members; the new version
      * is that current version bumped by that severity. Which members actually receive it depends on
      * the severity: **patch** only the changed member(s) (a caret dependency range already tolerates
      * a patch bump, no republish needed downstream); **minor** also every transitive in-group
@@ -75,8 +82,12 @@ export declare namespace VersionService {
      * on, until nothing new is affected - see `rippleCrossGroup`.
      *
      * A monorepo's root package is never a real member of any group (it's never published on its
-     * own) - it gets one trailing informational entry instead, always `'bump'`ed to whatever single
-     * version every group ended up sharing, or the overall highest version when groups diverged.
+     * own) - it gets one trailing entry instead, carrying the repository's own release identity: the
+     * single group's version when there is one, a calendar version once there are several - see
+     * `buildRootEntry`.
+     *
+     * "Since its own last release" is resolved by the shared `detectChangeHash` - the same boundary
+     * `changelog` measures from, so the two never disagree about which commits are unreleased.
      */
     function getPlan(repository: Repository, options?: Options): Promise<Entry[]>;
     /**

package/services/version.service.js

@@ -1,10 +1,11 @@
 import path from 'node:path';
 import semver from 'semver';
-import { findLatestTag, tagPattern } from '../utils/change-hash.js';
-import { hasBreakingChangeFooter, parseConventionalCommit, parseReleaseAs, VERSION_BUMP_PATTERN, } from '../utils/conventional-commits.js';
+import { detectChangeHash, expandTag } from '../utils/change-hash.js';
+import { hasBreakingChangeFooter, isReleaseCommit, parseConventionalCommit, parseReleaseAs, } from '../utils/conventional-commits.js';
 import { exec } from '../utils/exec.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
+import { expandReleaseTag, findLastReleaseVersion, formatCalendarVersion, isCalendarVersion, usesCalendarVersion, } from '../utils/release-version.js';
 import { parseWorkspaceRange } from '../utils/workspace-range.js';
 import { ChangelogService } from './changelog.service.js';
 export var VersionService;
@@ -25,8 +26,8 @@ export var VersionService;
      * version currently found among its own members (never persisted anywhere) - see
      * `resolveGroupKey`.
      *
-     * Within a group, a member with real commits since its own last release tag (or an explicit
-     * `bump`) sets the group's severity to the highest found among changed members; the new version
+     * Within a group, a member with real commits since its own last release (or an explicit `bump`)
+     * sets the group's severity to the highest found among changed members; the new version
      * is that current version bumped by that severity. Which members actually receive it depends on
      * the severity: **patch** only the changed member(s) (a caret dependency range already tolerates
      * a patch bump, no republish needed downstream); **minor** also every transitive in-group
@@ -39,8 +40,12 @@ export var VersionService;
      * on, until nothing new is affected - see `rippleCrossGroup`.
      *
      * A monorepo's root package is never a real member of any group (it's never published on its
-     * own) - it gets one trailing informational entry instead, always `'bump'`ed to whatever single
-     * version every group ended up sharing, or the overall highest version when groups diverged.
+     * own) - it gets one trailing entry instead, carrying the repository's own release identity: the
+     * single group's version when there is one, a calendar version once there are several - see
+     * `buildRootEntry`.
+     *
+     * "Since its own last release" is resolved by the shared `detectChangeHash` - the same boundary
+     * `changelog` measures from, so the two never disagree about which commits are unreleased.
      */
     async function getPlan(repository, options = {}) {
         const bump = options.bump?.trim();
@@ -69,21 +74,22 @@ export var VersionService;
             }
             eligible.push(pkg);
         }
+        const commitMessage = repository.rootPackage.config?.version?.commitMessage;
         const changeByPackage = new Map();
         await Promise.all(eligible.map(async (pkg) => {
             if (explicitVersion) {
                 changeByPackage.set(pkg.name, { severity: undefined, reason: `explicit version ${explicitVersion}` });
                 return;
             }
-            const tag = await findLatestTag(git, pkg);
-            const commits = tag ? await git.listCommits({ hash: tag }) : await git.listAllCommits();
+            const since = await detectChangeHash(git, pkg, { npmViewVersion: options.npmViewVersion });
+            const commits = since ? await git.listCommits({ hash: since }) : await git.listAllCommits();
             const belongsToPkg = (c) => c.files.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
-            const real = commits.filter(c => belongsToPkg(c) && !VERSION_BUMP_PATTERN.test(c.subject));
+            const real = commits.filter(c => belongsToPkg(c) && !isReleaseCommit(c.subject, commitMessage));
             if (!real.length)
                 return;
             changeByPackage.set(pkg.name, {
                 severity: explicitSeverity ?? detectSeverity(real),
-                reason: tag ? `changed since ${tag}` : 'unreleased commits',
+                reason: since ? `changed since ${since}` : 'unreleased commits',
             });
         }));
         const groups = new Map();
@@ -100,8 +106,13 @@ export var VersionService;
         }
         rippleCrossGroup(packages, entries, options.preid);
         const result = packages.map(pkg => entries.get(pkg.name));
-        if (repository.monorepo)
-            result.push(buildRootEntry(repository, result));
+        if (repository.monorepo) {
+            result.push(buildRootEntry(repository, result, {
+                groupCount: groups.size,
+                lastReleaseVersion: await findLastReleaseVersion(git, repository.rootPackage),
+                now: options.now ?? (() => new Date()),
+            }));
+        }
         return result;
     }
     VersionService.getPlan = getPlan;
@@ -172,12 +183,27 @@ export var VersionService;
                     scope: entry.package.name,
                     root: true,
                     from,
+                    // The tag for this release doesn't exist yet (it's created below), so changelog's own
+                    // tag-derived version would resolve to the *previous* release and label the entry with it.
+                    version: entry.to,
+                    // version doesn't consult "publish.skip" at all (a package can still be meaningfully
+                    // versioned/changelogged without ever being published) - this entry was already decided
+                    // to bump, so its folded-in changelog shouldn't then be silently dropped by that flag.
+                    includeSkipped: true,
                 });
                 for (const ce of changelogEntries) {
                     changelogFileByPackage.set(ce.package.name, path.relative(repository.dirname, path.join(ce.package.dirname, ce.filePath)));
                 }
             }
         }
+        /** The root's own informational version write isn't part of any group's release, but still
+         *  needs to land in *some* commit rather than being left as an uncommitted local edit. Committed
+         *  *before* the group commits, so the last commit this makes is always a tagged release commit -
+         *  otherwise the tag sits one commit behind HEAD and every `git tag --points-at HEAD` consumer
+         *  (CI capturing the tag it just released, say) comes up empty in a monorepo. */
+        if (rootEntry?.status === 'bump') {
+            await git.commit([path.relative(repository.dirname, repository.rootPackage.jsonFileName)], `chore: sync root version to ${rootEntry.to}`);
+        }
         const byGroup = new Map();
         for (const entry of bumped) {
             const list = byGroup.get(entry.groupKey);
@@ -199,10 +225,18 @@ export var VersionService;
                 if (!(await git.tagExists(tag)))
                     await git.createTag(tag);
         }
-        /** The root's own informational version write isn't part of any group's release, but still
-         *  needs to land in *some* commit rather than being left as an uncommitted local edit. */
-        if (rootEntry?.status === 'bump') {
-            await git.commit([path.relative(repository.dirname, repository.rootPackage.jsonFileName)], `chore: sync root version to ${rootEntry.to}`);
+        /** A repository release tag, on top of the per-group ones - but only once the root is on a
+         *  calendar version. With a single version line the group's own tag already *is* the release
+         *  (same version, same commit), and a second name for it would only add noise to every existing
+         *  repo's tag space. Created last, so it lands on HEAD rather than behind whichever group
+         *  happened to be committed last. */
+        if (rootEntry?.status === 'bump' && isCalendarVersion(rootEntry.to)) {
+            const releaseTag = expandReleaseTag(repository.rootPackage, rootEntry.to);
+            if (await git.tagExists(releaseTag)) {
+                throw new Error(`Release tag "${releaseTag}" already exists - a second release within the same minute. ` +
+                    'Wait a moment and run again.');
+            }
+            await git.createTag(releaseTag);
         }
         if (options.push && bumped.length)
             await git.push();
@@ -377,19 +411,33 @@ function rippleCrossGroup(packages, entries, preid) {
         }
     }
 }
-/** The root's own `version` field is purely informational in a monorepo (it's never published on
- *  its own) - it always reflects whatever single version every group ended up sharing, or the
- *  overall highest version when groups diverged onto different numbers. Reports `'no-change'`
- *  (not `'bump'`) when nothing in the repository changed at all. */
-function buildRootEntry(repository, memberEntries) {
+/**
+ * A monorepo root is never published on its own, but its version is still the repository's release
+ * identity - what a GitHub Release is named after. How it's computed depends on how many version
+ * lines the repo has, derived rather than configured (see `usesCalendarVersion`):
+ *
+ * - **One group**: the root simply follows it, so the repo and its packages share one number.
+ * - **Several groups** (or a repo already on calendar): a calendar version (`2026.9.15-1430`).
+ *   There is no meaningful shared number to report - the old "highest version among the groups"
+ *   rule would leave the root standing still whenever a *lower* line released, so a release could
+ *   happen with no identity of its own, and a semver-looking identity would anyway claim something
+ *   untrue about packages sitting on entirely different lines.
+ *
+ * Reports `'no-change'` (not `'bump'`) when nothing in the repository changed at all.
+ */
+function buildRootEntry(repository, memberEntries, context) {
     const root = repository.rootPackage;
     const anyBumped = memberEntries.some(e => e.status === 'bump');
     if (!anyBumped) {
         return { package: root, groupKey: '__root__', group: 'root', status: 'no-change', from: root.version };
     }
+    const calendar = usesCalendarVersion({
+        groupCount: context.groupCount,
+        rootVersion: root.version,
+        lastReleaseVersion: context.lastReleaseVersion,
+    });
     const finalVersions = memberEntries.map(e => e.to ?? e.from);
-    const unique = new Set(finalVersions);
-    const to = unique.size === 1 ? finalVersions[0] : maxVersion(finalVersions);
+    const to = calendar ? formatCalendarVersion(context.now()) : maxVersion(finalVersions);
     return {
         package: root,
         groupKey: '__root__',
@@ -397,7 +445,9 @@ function buildRootEntry(repository, memberEntries) {
         status: 'bump',
         from: root.version,
         to,
-        reason: 'informational - monorepo root is never published on its own',
+        reason: calendar
+            ? 'repository release identity - several version lines, so no shared number to report'
+            : 'informational - monorepo root is never published on its own',
     };
 }
 /** `.rmanrc version.commitMessage` (root-level; `{version}` is replaced when every bumped package
@@ -417,14 +467,6 @@ function buildCommitMessage(repository, entries, messageOverride) {
         return messageOverride;
     return `chore(release): ${entries.map(e => `${e.package.name}@${e.to}`).join(', ')}`;
 }
-/** Expands `pkg`'s (cascaded) `.rmanrc changelog.tagPattern` into a concrete tag name for
- *  `version` - the same pattern `changelog` reads tags back with (see `findLatestTag`), just run
- *  forward: `{name}` becomes the package's own name, and `*` becomes `version`. */
-function expandTag(pkg, version) {
-    const pattern = tagPattern(pkg).replace('{name}', pkg.name);
-    const starIdx = pattern.indexOf('*');
-    return starIdx === -1 ? pattern : pattern.slice(0, starIdx) + version + pattern.slice(starIdx + 1);
-}
 /** A `version.<key>` value: one command, or several to run in sequence - same shape as
  *  `run.<script>.script`/`.preScript`/`.postScript`. */
 function normalizeScriptValue(value) {

package/services.d.ts

@@ -3,6 +3,7 @@ export { CiService } from './services/ci.service.js';
 export { CleanService } from './services/clean.service.js';
 export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
+export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';
 export { ListService } from './services/list.service.js';
 export { PublishService } from './services/publish.service.js';

package/services.js

@@ -3,6 +3,7 @@ export { CiService } from './services/ci.service.js';
 export { CleanService } from './services/clean.service.js';
 export { DockerPublishService } from './services/docker-publish.service.js';
 export { ExecService } from './services/exec.service.js';
+export { GithubReleaseService } from './services/github-release.service.js';
 export { ImportService } from './services/import.service.js';
 export { ListService } from './services/list.service.js';
 export { PublishService } from './services/publish.service.js';

package/utils/change-hash.d.ts

@@ -13,6 +13,16 @@ export declare function tagPattern(pkg: Package): string;
  *  (reading the last-documented version) and `version` (finding the boundary a bump measures
  *  "since"). */
 export declare function findLatestTag(git: GitHelper, pkg: Package): Promise<string | undefined>;
+/** The forward direction of `findLatestTag`: expands `pkg`'s (cascaded) `.rmanrc
+ *  changelog.tagPattern` into the concrete tag name `version` belongs under - `{name}` becomes the
+ *  package's own name, `*` becomes `version`. Shared by `version` (creating the tag), `publish
+ *  --target github` (finding the release that tag belongs to), and `detectChangeHash`'s own npm
+ *  fallback (mapping a published version back onto a tag), so all three name tags identically. */
+export declare function expandTag(pkg: Package, version: string): string;
+/** The pattern expansion `expandTag` performs, on any pattern - `{name}` becomes `name`, `*` becomes
+ *  `version`. Shared with the repository's own release tag, which uses a different pattern (see
+ *  `releaseTagPattern`) but names tags the same way. */
+export declare function applyTagPattern(pattern: string, name: string, version: string): string;
 /** Strips the pattern's literal prefix (everything before its first `*`) from `tag` to get just
  *  the version part - e.g. tag `@sqb/builder@1.2.3` against pattern `@sqb/builder@*` -> `1.2.3`.
  *  A pattern with no `*` is returned as its own "version" verbatim (an exact tag, nothing to strip). */
@@ -43,13 +53,16 @@ export interface DetectChangeHashOptions {
  * Resolves the commit/hash a package's changes should be measured "since" - the boundary
  * `changelog --from` uses, but reusable anywhere a command wants to answer "what changed for this
  * package". An explicit `options.from` (anything but `"npm"`) is returned as-is, applying the same
- * way to every package. Otherwise, it's auto-detected from the package's currently-published npm
- * version: looked up via `npmViewVersion`, then mapped to a git tag using `.rmanrc
- * changelog.tagPattern` (so independent and fixed monorepo versioning schemes both work - see
- * `tagPattern`) - and, if `catchUpFile` is given and exists, widened to also cover anything that
- * file hasn't caught up on yet (see its doc comment). Returns `undefined` when nothing can be
- * resolved at all (unpublished, no network, no matching tag, no catch-up file) - callers should
- * fall back to their own default in that case (e.g. `GitHelper.listCommits`'s "not yet pushed"
- * default when no hash is given).
+ * way to every package. Otherwise, it's auto-detected in order: (1) this package's own most recent
+ * release tag - the same network-free `findLatestTag` lookup `version`/`changed` themselves use,
+ * so all three commands agree on "since when" for any repo whose tags are the ones `rman version`
+ * actually created; (2) failing that (no tag at all yet - e.g. onboarding `rman` onto a repo with
+ * real npm history but no `rman`-created tags), the package's currently-published npm version -
+ * looked up via `npmViewVersion`, then mapped to a git tag using `.rmanrc changelog.tagPattern`
+ * (see `tagPattern`). Either way, if `catchUpFile` is given and exists, the result is widened to
+ * also cover anything that file hasn't caught up on yet (see its doc comment). Returns `undefined`
+ * when nothing can be resolved at all (never tagged *and* never published, no catch-up file - a
+ * genuinely first-ever release) - callers should fall back to their own default in that case (e.g.
+ * the whole history, since nothing has ever been released).
  */
 export declare function detectChangeHash(git: GitHelper, pkg: Package, options?: DetectChangeHashOptions): Promise<string | undefined>;