rman 0.38.0 → 1.0.2

package/rmanrc.schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/panates/rman/main/schemas/rmanrc.schema.json",
+  "title": "rman configuration",
+  "description": "Schema for rman's .rmanrc (JSON) and .rman.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanyml for the full reference.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path/URL to this schema - not read by rman itself, purely for editor tooling."
+    },
+    "packageManager": {
+      "type": "string",
+      "enum": ["npm", "yarn", "pnpm", "bun"],
+      "default": "npm",
+      "description": "Package manager used by \"ci\"/\"publish\". Root-level only - an explicit --package-manager CLI flag wins over this."
+    },
+    "logLevel": {
+      "$ref": "#/definitions/logLevel",
+      "default": "info",
+      "description": "Default verbosity of the classic per-step log for run/build/test/ci/clean. Root-level only. An explicit --log-level CLI flag wins over this."
+    },
+    "allowBranch": {
+      "$ref": "#/definitions/stringOrStringArray",
+      "description": "Refuse to run a state-changing command unless the current git branch matches one of these globs. Root-level only. An explicit --allow-branch CLI flag replaces this entirely (never merges)."
+    },
+    "ignoreBranch": {
+      "$ref": "#/definitions/stringOrStringArray",
+      "description": "Refuse to run a state-changing command if the current git branch matches one of these globs. Root-level only. An explicit --ignore-branch CLI flag replaces this entirely (never merges)."
+    },
+    "group": {
+      "description": "Release-versioning group for \"version\"/\"publish\": true (default) puts the package in the implicit repo-wide group; a string joins exactly the other packages sharing that string; false makes it a solo, fully independent group. Per-package cascaded.",
+      "default": true,
+      "oneOf": [{ "type": "boolean" }, { "type": "string", "minLength": 1 }]
+    },
+    "version": {
+      "type": "object",
+      "description": "Options for the \"version\" command/VersionService.",
+      "additionalProperties": false,
+      "properties": {
+        "commitMessage": {
+          "type": "string",
+          "default": "chore(release): v{version}",
+          "description": "Commit message for every group a \"version\" run commits. \"{version}\" is substituted when every bumped package in that commit shares one version. Root-level only."
+        },
+        "script": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"version\" npm-lifecycle step, when its package.json does not define one itself."
+        },
+        "preScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"preversion\" step, when its package.json does not define one itself."
+        },
+        "postScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"postversion\" step, when its package.json does not define one itself."
+        }
+      }
+    },
+    "changelog": {
+      "type": "object",
+      "description": "Options for the \"changelog\" command/ChangelogService, and for \"version --changelog\".",
+      "additionalProperties": false,
+      "properties": {
+        "ignoreTypes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Conventional Commit types (e.g. \"chore\", \"ci\") dropped entirely from changelog output, instead of being folded into \"Other Changes\". Per-package cascaded."
+        },
+        "template": {
+          "type": "string",
+          "description": "Path (relative to the repository root) to a changelog template file - not the template text itself. Supports {{package}}/{{version}}/{{date}}/{{commits}} and {{features}}/{{fixes}}/{{other}}. Per-package cascaded."
+        },
+        "filePath": {
+          "type": "string",
+          "default": "CHANGELOG.md",
+          "description": "Where \"--write\" prepends this package's entry, relative to that package's own directory. Per-package cascaded."
+        },
+        "tagPattern": {
+          "type": "string",
+          "default": "v*",
+          "description": "Glob for this package's release tags. Include \"{name}\" for independent per-package tags (e.g. \"{name}@*\"); omit it for one shared repo-wide tag scheme. Per-package cascaded."
+        }
+      }
+    },
+    "clean": {
+      "type": "object",
+      "description": "Options for the \"clean\" command/CleanService.",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Extra glob(s) to remove, resolved relative to this package's own directory. Per-package cascaded (a package's own value replaces the root's, it does not merge)."
+        },
+        "exclude": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Glob(s) protected from \"include\" (and from the built-in TypeScript-artifact cleanup), relative to this package's own directory. Per-package cascaded."
+        },
+        "skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opts this package out of \"clean\" entirely. Per-package cascaded."
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "description": "Per-script options for \"run\"/\"build\"/\"test\"/RunService, keyed by npm script name (e.g. \"build\", \"lint\", \"test\").",
+      "additionalProperties": { "$ref": "#/definitions/runScriptConfig" }
+    },
+    "packages": {
+      "type": "object",
+      "description": "Per-package overrides, keyed by the in-repo package's own name.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "dependencies": {
+            "description": "Extra in-repo \"dependencies\" not present in this package's real package.json, purely for rman's own dependency graph (topo-sort, --deps/--dependents, run's task scheduling). An array defaults each entry's range to \"*\"; an object gives an explicit name -> range map.",
+            "oneOf": [
+              { "type": "array", "items": { "type": "string" } },
+              { "type": "object", "additionalProperties": { "type": "string" } }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "logLevel": {
+      "type": "string",
+      "enum": ["silent", "error", "info", "verbose"]
+    },
+    "stringOrStringArray": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      ]
+    },
+    "runScriptConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max packages built at once for this script. Default: CPU count."
+        },
+        "topo": {
+          "type": "boolean",
+          "default": true,
+          "description": "Respect the package dependency graph: a package waits for its dependencies and is skipped if one fails. Set false for independent scripts (lint/test) - alphabetical order, no failure skipping."
+        },
+        "bail": {
+          "type": "boolean",
+          "default": true,
+          "description": "Stop the whole batch on this package's own failure. Unusual precedence: this package-level value outranks even an explicit CLI --bail/--no-bail flag."
+        },
+        "progress": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show the live progress panel for this script (auto-disabled off a TTY)."
+        },
+        "logLevel": {
+          "$ref": "#/definitions/logLevel",
+          "description": "Verbosity of the classic per-step log for this package/script, when the live panel is off."
+        },
+        "changedSince": {
+          "type": "string",
+          "description": "Root-level fallback commit/hash for \"--changed-since\", used only when the CLI flag is not given."
+        },
+        "skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "Excludes this package (or the repository root's own pre/post hooks) from running this script entirely."
+        },
+        "if": {
+          "type": "string",
+          "description": "Conditional-execution expression: atoms \"changed\"/\"dirty\"/\"committed\" (optionally \"= <hash>\" or \"= {ENV_VAR}\"), combined with and/or/not/(...). E.g. \"changed\", \"(changed or dirty) and not committed\"."
+        },
+        "script": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own script, when its package.json does not define one for this script name."
+        },
+        "preScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"pre<script>\" hook, when its package.json does not define one."
+        },
+        "postScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"post<script>\" hook, when its package.json does not define one."
+        },
+        "override": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, \"script\"/\"preScript\"/\"postScript\" above replace the package's own package.json definition even when it already has one."
+        }
+      }
+    }
+  }
+}

package/services/changelog.service.d.ts

@@ -0,0 +1,99 @@
+import type { Package } from '../core/package.js';
+import type { Repository } from '../core/repository.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace ChangelogService {
+    /** Injectable dependencies shared by `getEntries`/`generate` - currently just the npm registry lookup
+     *  `detectChangeHash` otherwise makes for itself; overridable so tests (and advanced callers)
+     *  aren't forced through a real network call. */
+    interface Deps {
+        npmViewVersion?: (name: string, cwd: string) => Promise<string | undefined>;
+    }
+    interface Options extends PackageFilterOptions {
+        /** Generate the changelog since this commit/hash - applied the same way to every package.
+         *  Default (also `"npm"` explicitly): auto-detect it per package instead, from that package's
+         *  currently-published npm version (see `detectChangeHash`); a package this can't be resolved
+         *  for (unpublished, no network, no matching tag) falls back to its own commits not yet
+         *  pushed to the current branch's upstream (same reference point `--changed`/
+         *  `--changed-since` use). */
+        from?: string;
+        /** Generate for the whole repository even when the current directory is inside a single
+         *  package (which otherwise scopes it to just that package) - see `Repository.currentPackage`. */
+        root?: boolean;
+        /** Where a package's changelog file lives, relative to *that package's own* directory -
+         *  default `'CHANGELOG.md'`. Applies the same way to every package; for a package that wants
+         *  its own filename instead, use `.rmanrc changelog.filePath` (cascaded, per-package
+         *  overridable) rather than this option - see `resolveFilePath`. Consulted even without
+         *  `write`: when auto-detecting, if this file already exists its own last-modifying commit
+         *  also lower-bounds the boundary, so a stale file (last updated for an older version than
+         *  what's actually published) doesn't get changes silently skipped over - see
+         *  `detectChangeHash`'s `catchUpFile`. */
+        filePath?: string;
+    }
+    /** One package's (root included) generated changelog entry - what `getEntries`/`generate`
+     *  return. */
+    interface Entry {
+        package: Package;
+        /** Display name for this entry's heading - `"<repo dir name> repository"` for the root
+         *  package, its own name otherwise (see `getEntries`'s doc comment on `{{package}}`). */
+        label: string;
+        /** Resolved from git tags, not package.json - see `resolveVersion`. */
+        version: string;
+        features: string[];
+        fixes: string[];
+        other: string[];
+        /** The fully rendered entry, via `.rmanrc changelog.template` (or the built-in default). */
+        content: string;
+        /** Where this entry would be (or, with `options.write`, was) written, relative to the
+         *  package's own directory - see `GetOptions.filePath`. */
+        filePath: string;
+    }
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    function generateToFile(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
+     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
+     * `VERSION_BUMP_PATTERN`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
+     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
+     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
+     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     */
+    function getEntries(repository: Repository, options?: Options, deps?: Deps): Promise<Entry[]>;
+}

package/services/changelog.service.js

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectChangeHash, extractVersion, findLatestTag, tagPattern } from '../utils/change-hash.js';
+import { parseConventionalCommit, VERSION_BUMP_PATTERN } from '../utils/conventional-commits.js';
+import { GitHelper } from '../utils/git.js';
+import { filterPackages } from '../utils/package-filter.js';
+export var ChangelogService;
+(function (ChangelogService) {
+    /**
+     * Same as `getEntries`, and additionally - for every returned entry, when `options.write` is
+     * set - prepends `entry.content` into that package's own changelog file (see `Entry.filePath`).
+     * Still pure with respect to console output: writing a file is a real, callable-for-its-own-
+     * sake side effect (a "save this" request), not presentation, so it stays here rather than in
+     * the CLI command - printing what happened is the command's job.
+     */
+    async function generateToFile(repository, options = {}, deps = {}) {
+        const entries = await getEntries(repository, options, deps);
+        for (const entry of entries)
+            prependToChangelogFile(entry.package, entry.filePath, entry.content);
+        return entries;
+    }
+    ChangelogService.generateToFile = generateToFile;
+    /**
+     * Computes a changelog entry per package (root included) from real commits only - either
+     * everything since a given `--from <hash>` (applied the same way to every package), or, by
+     * default, auto-detected per package instead (see `detectChangeHash`). Pure: returns the
+     * entries, never prints or touches `CHANGELOG.md` - see `generate` for that.
+     *
+     * A commit is attributed to every package its files fall under (root included, for anything
+     * outside every package) - unless it's broad enough to count as a repo-wide change (see
+     * `BROAD_COMMIT_THRESHOLD`/`ownersOf`), in which case it goes to root alone instead of being
+     * repeated verbatim across most of the repository. Subject lines are grouped ✨ Features/🐛 Bug
+     * Fixes/🔧 Other Changes on a best-effort Conventional Commits read; anything that doesn't parse
+     * just lands in Other Changes as-is, so a repo that doesn't follow that convention still gets a
+     * usable list. `.rmanrc changelog.ignoreTypes` (cascaded, e.g. `[chore, dev]`) drops commits of
+     * those types entirely instead - see `ignoreTypesConfig`. A bare version-bump commit
+     * (`"6.0.1"`) is always dropped outright, regardless of `ignoreTypes` - see
+     * `VERSION_BUMP_PATTERN`.
+     *
+     * By default (or with `--from npm` explicitly), the boundary is auto-detected per package
+     * instead of one shared one - see `detectChangeHash`. A package that can't be resolved this way
+     * (unpublished, no network, no matching tag) falls back to its own commits not yet pushed to
+     * the current branch's upstream (the same reference point `--changed`/`--changed-since` use
+     * elsewhere, via `GitHelper.listCommits`) - so the command still produces something useful even
+     * for a repo that's never been published or tagged at all. Packages that end up resolving to
+     * the same hash (an explicit one, or several packages sharing one tag under fixed versioning)
+     * only have their commits fetched once, not once per package.
+     *
+     * Formatting comes from `.rmanrc changelog.template` - a *path* to a template file (not the
+     * template text itself, to keep `.rmanrc` readable), with `{{package}}`/`{{version}}`/
+     * `{{date}}`/`{{commits}}` (the full grouped block) and `{{features}}`/`{{fixes}}`/`{{other}}`
+     * (their bullet lists alone, for templates that want their own headings/order) - see
+     * `resolveTemplate`. `{{package}}` for the repository root is `"<repo dir name> repository"`
+     * (e.g. "sqb repository"), not its raw package.json name - which is often a private,
+     * non-published placeholder (`"sqb.v4"`) that reads like a stray version marker rather than a
+     * recognizable label. `{{version}}` comes from git tags, not package.json (which can drift out
+     * of sync with what's actually been released) - see `resolveVersion`/`.rmanrc
+     * changelog.tagPattern`.
+     *
+     * Run from inside a single package's own directory, it only covers that package unless
+     * `options.root` says otherwise (see `Repository.currentPackage`).
+     */
+    async function getEntries(repository, options = {}, deps = {}) {
+        const cwdScope = options.root ? undefined : repository.currentPackage;
+        const packages = repository.getPackages().filter(p => p !== repository.rootPackage);
+        const targets = cwdScope ? [cwdScope] : filterPackages([repository.rootPackage, ...packages], options);
+        const git = new GitHelper({ cwd: repository.dirname });
+        // dropped up front, not just while grouping - a package whose only commits are version bumps
+        // should get no entry at all, rather than a heading with nothing real underneath it.
+        const dropVersionBumps = (commits) => commits.filter(c => !VERSION_BUMP_PATTERN.test(c.subject));
+        // Several packages often resolve to the identical hash (an explicit --from <hash> applies to
+        // all of them the same way; under fixed versioning, npm auto-detection usually does too) - so
+        // the git fetch for a given hash is cached, run once no matter how many packages share it.
+        const commitsByHash = new Map();
+        const listCommitsCached = (hash) => {
+            const key = hash ?? '';
+            let promise = commitsByHash.get(key);
+            if (!promise) {
+                promise = git.listCommits({ hash }).then(dropVersionBumps);
+                commitsByHash.set(key, promise);
+            }
+            return promise;
+        };
+        const commitsByTarget = await Promise.all(targets.map(async (pkg) => {
+            const catchUpFile = path.join(pkg.dirname, resolveFilePath(pkg, options.filePath));
+            const from = await detectChangeHash(git, pkg, {
+                from: options.from,
+                npmViewVersion: deps.npmViewVersion,
+                catchUpFile: fs.existsSync(catchUpFile) ? catchUpFile : undefined,
+            });
+            return listCommitsCached(from);
+        }));
+        const entries = [];
+        for (let i = 0; i < targets.length; i++) {
+            const pkg = targets[i];
+            const ownCommits = commitsByTarget[i].filter(c => ownersOf(repository, c).has(pkg));
+            if (!ownCommits.length)
+                continue;
+            const grouped = groupCommits(ownCommits.map(c => c.subject), ignoreTypesConfig(pkg));
+            // every commit could have been dropped by ignoreTypes - skip this package's entry entirely
+            // rather than rendering a heading with nothing real underneath it.
+            if (!grouped.features.length && !grouped.fixes.length && !grouped.other.length)
+                continue;
+            const label = pkg === repository.rootPackage ? `${path.basename(repository.dirname)} repository` : pkg.name;
+            const { version, content } = await renderEntry(repository, pkg, label, grouped, git);
+            entries.push({
+                package: pkg,
+                label,
+                version,
+                features: grouped.features,
+                fixes: grouped.fixes,
+                other: grouped.other,
+                content,
+                filePath: resolveFilePath(pkg, options.filePath),
+            });
+        }
+        return entries;
+    }
+    ChangelogService.getEntries = getEntries;
+})(ChangelogService || (ChangelogService = {}));
+/** `.rmanrc changelog.ignoreTypes` (cascaded, per-package overridable) - Conventional Commits
+ *  `type`s to drop entirely (e.g. `[chore, dev]`), not just fold into "Other Changes". Only
+ *  applies to commits that actually parse as `type: ...` - a non-conventional message always
+ *  still lands in Other Changes, since it has no `type` to match against. */
+function ignoreTypesConfig(pkg) {
+    const v = pkg.config?.changelog?.ignoreTypes;
+    return new Set(Array.isArray(v) ? v.map(t => String(t).toLowerCase()) : []);
+}
+function groupCommits(subjects, ignoreTypes = new Set()) {
+    const grouped = { features: [], fixes: [], other: [] };
+    for (const subject of subjects) {
+        if (VERSION_BUMP_PATTERN.test(subject))
+            continue;
+        const parsed = parseConventionalCommit(subject);
+        if (!parsed) {
+            grouped.other.push(subject);
+            continue;
+        }
+        const { type, scope, description } = parsed;
+        if (ignoreTypes.has(type))
+            continue;
+        const line = scope ? `**${scope}:** ${description}` : description;
+        if (type === 'feat')
+            grouped.features.push(line);
+        else if (type === 'fix')
+            grouped.fixes.push(line);
+        else
+            grouped.other.push(subject);
+    }
+    return grouped;
+}
+function bulletList(lines) {
+    return lines.map(l => `- ${l}`).join('\n');
+}
+function renderCommitsBlock(grouped) {
+    const sections = [];
+    if (grouped.features.length)
+        sections.push(`### ✨ Features\n\n${bulletList(grouped.features)}`);
+    if (grouped.fixes.length)
+        sections.push(`### 🐛 Bug Fixes\n\n${bulletList(grouped.fixes)}`);
+    if (grouped.other.length)
+        sections.push(`### 🔧 Other Changes\n\n${bulletList(grouped.other)}`);
+    return sections.join('\n\n');
+}
+const DEFAULT_TEMPLATE = '## {{package}} {{version}} ({{date}})\n\n{{commits}}\n';
+/** `.rmanrc changelog.template` is a *path* to a template file (resolved relative to the
+ *  repository root, regardless of which level's `.rmanrc` declared it), not the template text
+ *  itself - keeping multi-line Markdown out of `.rmanrc` so it stays readable. Falls back to a
+ *  small built-in template when unset. */
+function resolveTemplate(repository, pkg) {
+    const templatePath = pkg.config?.changelog?.template;
+    if (typeof templatePath !== 'string' || !templatePath)
+        return DEFAULT_TEMPLATE;
+    const abs = path.resolve(repository.dirname, templatePath);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`changelog.template not found for "${pkg.name}": "${templatePath}" (resolved to "${abs}")`);
+    }
+    return fs.readFileSync(abs, 'utf-8');
+}
+function render(template, values) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => values[key] ?? '');
+}
+const DEFAULT_CHANGELOG_FILE = 'CHANGELOG.md';
+/** Where `write` prepends this package's entry, relative to its own directory. An explicit
+ *  `optionsFilePath` (`Changelog.Options.filePath`, CLI `--file-path`) applies the same way to
+ *  every package and wins over `.rmanrc changelog.filePath` (cascaded, per-package overridable),
+ *  which in turn wins over the default `'CHANGELOG.md'`. */
+function resolveFilePath(pkg, optionsFilePath) {
+    if (optionsFilePath)
+        return optionsFilePath;
+    const cfg = pkg.config?.changelog?.filePath;
+    return typeof cfg === 'string' && cfg ? cfg : DEFAULT_CHANGELOG_FILE;
+}
+/**
+ * This package's current version, from git tags rather than its (possibly stale - see the
+ * `{{version}}` doc on `Changelog.getEntries`) package.json. Falls back to package.json's version
+ * if no matching tag exists at all (never tagged, or a fresh package) - see `findLatestTag`.
+ */
+async function resolveVersion(git, pkg) {
+    const tag = await findLatestTag(git, pkg);
+    return tag ? extractVersion(tag, tagPattern(pkg).replace('{name}', pkg.name)) : pkg.version || '';
+}
+/** The most specific package whose directory contains `file` - the repository root itself as the
+ *  fallback for anything outside every package (e.g. root-level config files). Mirrors
+ *  `Repository.currentPackage`'s longest-prefix logic, but always resolves to *something*
+ *  (root), rather than `undefined`, since every file belongs to some changelog. */
+function owningPackage(repository, file) {
+    let best = repository.rootPackage;
+    for (const pkg of repository.packages) {
+        const rel = path.relative(pkg.dirname, file);
+        const isSelfOrDescendant = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+        if (isSelfOrDescendant && pkg.dirname.length > best.dirname.length)
+            best = pkg;
+    }
+    return best;
+}
+/** A commit touching more than this fraction of all packages (a repo-wide relicense, a doc
+ *  update stamped into every package's README, ...) is treated as a repo-wide change rather than
+ *  attributed to each of them - see `ownersOf`. Without this, one such commit would show up
+ *  verbatim in every single package's changelog, making them all look identical. */
+const BROAD_COMMIT_THRESHOLD = 0.5;
+/** ...but only once at least this many packages are actually touched - without a floor, a repo
+ *  with only 1 or 2 packages would have *every* normal commit look "broad" (100% > 50% of a
+ *  1-package repo is trivially true), wrongly attributing ordinary changes to root alone. */
+const BROAD_COMMIT_MIN_PACKAGES = 3;
+/**
+ * A commit can touch more than one package at once (or a package plus root-level files) - it's
+ * attributed to every package its files map to, not just one. The exception is a commit broad
+ * enough to touch at least `BROAD_COMMIT_MIN_PACKAGES` packages *and* more than
+ * `BROAD_COMMIT_THRESHOLD` of all of them: that's a repo-wide maintenance change (relicensing, a
+ * doc pass across every package, ...), not something that belongs in each package's own release
+ * notes individually - it's attributed to the root alone.
+ */
+function ownersOf(repository, commit) {
+    const owners = new Set();
+    for (const f of commit.files)
+        owners.add(owningPackage(repository, f));
+    const totalPackages = repository.packages.length;
+    const nonRootOwners = [...owners].filter(p => p !== repository.rootPackage).length;
+    if (totalPackages > 0 &&
+        nonRootOwners >= BROAD_COMMIT_MIN_PACKAGES &&
+        nonRootOwners > totalPackages * BROAD_COMMIT_THRESHOLD) {
+        return new Set([repository.rootPackage]);
+    }
+    return owners;
+}
+async function renderEntry(repository, pkg, label, grouped, git) {
+    const template = resolveTemplate(repository, pkg);
+    const version = await resolveVersion(git, pkg);
+    const content = render(template, {
+        package: label,
+        version,
+        date: new Date().toISOString().slice(0, 10),
+        commits: renderCommitsBlock(grouped),
+        features: bulletList(grouped.features),
+        fixes: bulletList(grouped.fixes),
+        other: bulletList(grouped.other),
+    });
+    return { version, content };
+}
+/** Prepends `content` right after the top-level "# Changelog" heading if the file already has
+ *  one, otherwise creates the file (and any missing parent directory - `relFilePath` can nest one,
+ *  e.g. `'docs/CHANGELOG.md'`) with one. Leaves everything already in the file untouched below it. */
+function prependToChangelogFile(pkg, relFilePath, content) {
+    const file = path.join(pkg.dirname, relFilePath);
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+    const headerMatch = /^# Changelog\r?\n+/.exec(existing);
+    const header = headerMatch ? headerMatch[0] : '# Changelog\n\n';
+    const rest = headerMatch ? existing.slice(headerMatch[0].length) : existing;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, header + content.trimEnd() + '\n\n' + rest);
+}

package/services/ci.service.d.ts

@@ -0,0 +1,40 @@
+import type { Repository } from '../core/repository.js';
+import { type LogLevel } from '../utils/logger.js';
+import { type PackageFilterOptions } from '../utils/package-filter.js';
+export declare namespace CiService {
+    type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+    interface Options extends PackageFilterOptions {
+        packageManager?: PackageManager;
+        /** Show the live progress panel while running. Default true, same as `run`/`build`; auto-disabled
+         *  when stdout isn't a TTY. Doesn't affect what's printed once done - see `run`. */
+        progress?: boolean;
+        /** Verbosity of the classic per-step log (only applies when the live panel is off). Falls back to
+         *  the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+    }
+    /** `.rmanrc packageManager` (root only) picks the package manager used for the final install;
+     *  explicit CLI value wins over it. Defaults to 'npm'. */
+    function resolvePackageManager(repository: Repository, cliValue?: PackageManager): PackageManager;
+    /** Deletes `node_modules` and any known lockfile directly under `dirname`. Returns the names
+     *  that actually existed (and were removed), so the caller can log only those. */
+    function wipe(dirname: string): Promise<string[]>;
+    /**
+     * `ci`: a from-scratch, reproducible install for CI pipelines. For every package (root
+     * included), deletes `node_modules` and any lockfile - or, if the package defines its own
+     * `"ci"` script, runs that instead. Once every package is clean, installs once at the root
+     * with the configured package manager (`npm`/`yarn`/`pnpm`/`bun`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) while it
+     * runs, falling back to a plain rmdir/clean/run/install log line per step when the panel is off.
+     *
+     * Unlike `run`/`build`, it does *not* end with a per-package success tally: `ci`'s packages don't
+     * have independently meaningful outcomes the way a build or test run does - wiping a package is
+     * trivial and the one step that can genuinely fail, the install, is a single operation for the
+     * whole repository. Counting "N succeeded" across packages would just be noise, so only actual
+     * failures get called out (by name, with whatever output they produced), followed by one plain
+     * completed/failed line.
+     */
+    function reinstall(repository: Repository, options?: Options): Promise<void>;
+}
+declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "bun"];
+export {};