@williamthorsen/release-kit 12.0.0 → 13.0.0

package/dist/esm/deriveReleaseNotesConfig.js

@@ -0,0 +1,21 @@
+import { DEFAULT_CHANGELOG_JSON_CONFIG, DEFAULT_RELEASE_NOTES_CONFIG } from "./defaults.js";
+import { resolveWorkTypes } from "./loadConfig.js";
+export function deriveDependenciesHeader(workTypes) {
+    const header = workTypes['deps']?.header;
+    if (header === undefined) {
+        throw new Error("Resolved work types do not contain a 'deps' entry");
+    }
+    return header;
+}
+export function deriveReleaseNotesConfig(config) {
+    return {
+        releaseNotes: {
+            shouldInjectIntoReadme: config?.releaseNotes?.shouldInjectIntoReadme ?? DEFAULT_RELEASE_NOTES_CONFIG.shouldInjectIntoReadme,
+        },
+        changelogJsonOutputPath: config?.changelogJson?.outputPath ?? DEFAULT_CHANGELOG_JSON_CONFIG.outputPath,
+        sectionOrder: deriveSectionOrder(resolveWorkTypes(config?.workTypes)),
+    };
+}
+export function deriveSectionOrder(workTypes) {
+    return Object.values(workTypes).map((entry) => entry.header);
+}

package/dist/esm/deriveWorkspaceConfig.d.ts

@@ -2,10 +2,8 @@ import type { WorkspaceConfig } from './types.js';
 /**
  * Derives a workspace configuration from a workspace-relative path.
  *
- * Reads `package.json` at the workspace path to derive the tag identifier from the
- * package's `name` field (with any leading `@scope/` stripped). The `dir` field remains
- * the basename of the path — it is the stable internal identifier used for `--only`,
- * config overrides, and dependency-graph lookups. The `tagPrefix` is `${unscopedName}-v`,
- * so tags reflect the package identity rather than the directory layout.
+ * The tag prefix is `${unscopedName}-v`, from the `name` in the workspace's `package.json`, so that tags follow the
+ * package's identity rather than the directory layout. `dir` is the basename of the path: the stable internal
+ * identifier for `--only`, config overrides, and dependency-graph lookups.
  */
 export declare function deriveWorkspaceConfig(workspacePath: string): WorkspaceConfig;

package/dist/esm/detectPackageManager.d.ts

@@ -1,8 +1,6 @@
 export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'yarn-berry';
 /**
- * Detect the repo's package manager by checking the `packageManager` field in root `package.json`,
- * then falling back to lockfile detection, then defaulting to `npm`.
- *
- * Yarn v2+ is returned as `'yarn-berry'` to distinguish it from Yarn Classic.
+ * Detects the repo's package manager from the `packageManager` field of the root `package.json`, then from lockfiles,
+ * and otherwise returns `npm`. Yarn v2+ is `'yarn-berry'`, to distinguish it from Yarn Classic.
  */
 export declare function detectPackageManager(): PackageManager;

package/dist/esm/detectUndeclaredTagPrefixes.d.ts

@@ -14,12 +14,10 @@ export interface UndeclaredTagPrefix {
     suggestedDir: string;
 }
 /**
- * Scan local git tags for release-shaped tags whose prefix is not in the known set.
+ * Scans local git tags for release-shaped tags whose prefix is not in `knownPrefixes`, the union of derived and
+ * declared prefixes across all workspaces.
  *
- * Reads only the local tag list; callers expecting to see recently-fetched remote tags
- * should `git fetch --tags` first. Returns an empty array when the repo has no tags
- * or no candidate-shaped tags outside the known set.
- *
- * @param knownPrefixes - Union of derived and declared prefixes across all workspaces.
+ * Reads only the local tag list, so a remote tag that has not been fetched is not reported. Returns an empty array
+ * when the repo doesn't have any tags, or any candidate-shaped tags outside the known set.
  */
 export declare function detectUndeclaredTagPrefixes(knownPrefixes: readonly string[]): UndeclaredTagPrefix[];

package/dist/esm/detectUndeclaredTagPrefixes.js

@@ -42,7 +42,7 @@ export function detectUndeclaredTagPrefixes(knownPrefixes) {
             suggestedDir: stripTrailingTagMarker(prefix),
         });
     }
-    return results.sort((a, b) => a.prefix.localeCompare(b.prefix));
+    return results.toSorted((a, b) => a.prefix.localeCompare(b.prefix));
 }
 function stripTrailingTagMarker(prefix) {
     return prefix.endsWith('-v') ? prefix.slice(0, -2) : prefix;

package/dist/esm/determineBumpType.d.ts

@@ -5,7 +5,7 @@ export interface BumpSignal {
     breaking: boolean;
 }
 /**
- * Determines the overall bump type from a set of changes, returning undefined when none has a known work type.
+ * Determines the overall bump type from a set of changes, returning undefined when none triggers a bump.
  *
  * Uses `versionPatterns` to decide which types trigger major/minor bumps.
  * The `'!'` sentinel in `versionPatterns.major` means "any breaking change triggers major".

package/dist/esm/discoverWorkspaces.d.ts

@@ -5,8 +5,8 @@ export type { EmptyWorkspaceCause } from '@williamthorsen/nmr-core/workspace';
  * set of package directories, or it declares a workspace that resolves to none and the cause says which
  * condition emptied it.
  *
- * Held apart from nmr-core's `WorkspaceResolution`, whose `packageDirs` are absolute, because these are
- * relative to the monorepo root. The two carry incompatible path contracts, and a distinct `kind` for the
+ * Kept separate from nmr-core's `WorkspaceResolution`, whose `packageDirs` are absolute, because these are
+ * relative to the monorepo root. The two have incompatible path contracts, and a distinct `kind` for the
  * single-package case keeps either from standing in for the other.
  */
 export type WorkspaceDiscovery = {
@@ -20,39 +20,38 @@ export type WorkspaceDiscovery = {
 } | {
     kind: 'single-package';
 };
-/** A workspace that resolved to no package directory, which every release-kit command treats as a failure. */
+/** A workspace that did not resolve to any package directory, which every release-kit command treats as a failure. */
 export type EmptyWorkspace = Extract<WorkspaceDiscovery, {
     kind: 'empty';
 }>;
 /**
- * The empty-workspace causes that reach a command as a failure.
+ * The empty-workspace causes that every release-kit command treats as a failure.
  *
- * `no-packages-list` is absent because a manifest declaring nothing releases as a single package, so no
- * command ever composes a message for it.
+ * `no-packages-list` is absent because a manifest declaring nothing releases as a single package, so
+ * release-kit's commands never compose a message for it.
  */
 export type FailingWorkspaceCause = Exclude<EmptyWorkspaceCause, 'no-packages-list'>;
 /**
- * Returns the sentence naming which of the five conditions left a workspace holding no package directory, and
- * the remedy for that one. Each quotes the `packages` list the manifest declares, apart from the two that
- * reach the matcher with no list to quote.
+ * Returns the sentence naming which condition left a workspace without a package directory, and the remedy for
+ * it. A message quotes the manifest's `packages` list whenever the manifest declares one that the resolver read.
  *
  * The `package.json` requirement is stated under `no-package` because it is a divergence from pnpm, which
- * recognizes two further manifests, and the reader of a workspace that pnpm resolves has no way to infer it.
+ * recognizes two further manifests, and the reader of a workspace that pnpm resolves cannot infer it.
  */
 export declare function describeEmptyWorkspace(workspace: EmptyWorkspace): string;
 /**
  * Reads `pnpm-workspace.yaml` at `monorepoRoot` and resolves its `packages` patterns, applying pnpm's
- * semantics — `!`-prefixed exclusions included.
+ * semantics, `!`-prefixed exclusions included.
  *
- * A directory holding no manifest, and one whose manifest declares no `packages` list, both release as a
+ * A directory without a manifest, and one whose manifest does not declare a `packages` list, both release as a
  * single package: pnpm resolves each to the root package alone, and a workspace file kept for `catalog:`,
  * `overrides:`, or `onlyBuiltDependencies:` is the second of them. Every other empty resolution is a failure,
- * whether the reader declared patterns that matched nothing or a `packages` value the resolver could not read
+ * whether the manifest declares patterns that match nothing or a `packages` value that the resolver cannot read
  * as patterns at all.
  *
  * `packageDirs` come back relative to `monorepoRoot` as POSIX paths, because that is what every consumer
  * needs: `WorkspaceConfig.paths` feeds `git log -- <paths>`, and `packageFiles` and `changelogPaths` are read
- * from disk relative to the working directory. The workspace root itself relativizes to `.`, the path
- * `deriveWorkspaceConfig` reads a root package's manifest through.
+ * from disk relative to the working directory. The workspace root itself relativizes to `.`, the path through
+ * which `deriveWorkspaceConfig` reads a root package's manifest.
  */
 export declare function discoverWorkspaces(monorepoRoot?: string): WorkspaceDiscovery;

package/dist/esm/discoverWorkspaces.js

@@ -7,21 +7,21 @@ export function describeEmptyWorkspace(workspace) {
             return (`pnpm-workspace.yaml ${declaredClause}, whose \`!\` entries exclude every directory matched by the ` +
                 'positive patterns. Drop or narrow the exclusion.');
         case 'no-package':
-            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher found no directory holding a \`package.json\`. ` +
-                'Add one to the directory that should be a package, or declare a pattern reaching a directory that ' +
-                'holds one.');
+            return (`pnpm-workspace.yaml ${declaredClause}, and the matcher did not find any directory containing a ` +
+                '`package.json`. Add one to the directory that should be a package, or declare a pattern matching a ' +
+                'directory that contains one.');
         case 'no-pattern':
-            return (`pnpm-workspace.yaml ${declaredClause}, so no pattern reaches the matcher. Declare a positive pattern ` +
-                'such as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string where ' +
-                'it stands bare.');
+            return (`pnpm-workspace.yaml ${declaredClause}, so the matcher does not receive any pattern. Declare a positive ` +
+                'pattern such as `packages/*`, and quote any `!` entry, which YAML reads as a tag rather than a string ' +
+                'when it is unquoted.');
         case 'unreadable-manifest':
-            return ('pnpm-workspace.yaml holds no valid YAML, so nothing it declares reaches the matcher. Repair the ' +
-                'syntax error and run the command again. An unterminated quoted string and a mis-indented entry are ' +
-                'the usual ones.');
+            return ('pnpm-workspace.yaml does not contain valid YAML, so the matcher does not receive anything that it ' +
+                'declares. Repair the syntax error and run the command again. An unterminated quoted string and a ' +
+                'mis-indented entry are the usual ones.');
         case 'unreadable-packages':
-            return ('pnpm-workspace.yaml declares a `packages` value that is not a list of strings, so nothing it ' +
-                'declares reaches the matcher. Make it a list whose every entry is a quoted pattern; a bare value ' +
-                'and an entry YAML read as a number or a map are the usual ones.');
+            return ('pnpm-workspace.yaml declares a `packages` value that is not a list of strings, so the matcher does ' +
+                'not receive anything that it declares. Make it a list whose every entry is a quoted pattern; a bare ' +
+                'value and an entry that YAML read as a number or a map are the usual ones.');
         default: {
             const unhandledCause = workspace.cause;
             throw new Error(`Unhandled empty-workspace cause: ${String(unhandledCause)}`);

package/dist/esm/enterRepoRoot.d.ts

@@ -0,0 +1,12 @@
+/** The directory from which `release-kit` was invoked, and the repo root in which it now runs. */
+export interface RepoLocation {
+    invocationDir: string;
+    root: string;
+}
+/**
+ * Locates the repo root from `startDir` and makes it the process working directory.
+ *
+ * The root is the nearest ancestor containing `pnpm-workspace.yaml`, or else `startDir` itself when it contains a
+ * `package.json`. A single-package repo is therefore found only from its own root. Throws when neither applies.
+ */
+export declare function enterRepoRoot(startDir?: string): RepoLocation;

package/dist/esm/enterRepoRoot.js

@@ -0,0 +1,16 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { findMonorepoRoot } from '@williamthorsen/nmr-core/workspace';
+export function enterRepoRoot(startDir = process.cwd()) {
+    const invocationDir = path.resolve(startDir);
+    const root = findMonorepoRoot(invocationDir) ?? findSinglePackageRoot(invocationDir);
+    if (root === undefined) {
+        throw new Error(`No repo root found from ${invocationDir}: expected a pnpm-workspace.yaml in it or any parent directory, ` +
+            'or a package.json in it. Run release-kit from inside a monorepo or at the root of a single-package repo.');
+    }
+    process.chdir(root);
+    return { invocationDir, root };
+}
+function findSinglePackageRoot(dir) {
+    return existsSync(path.join(dir, 'package.json')) ? dir : undefined;
+}

package/dist/esm/enumerateReleaseWindows.d.ts

@@ -1,15 +1,15 @@
 /** A commit as git records it, before any parsing or filtering. */
 export interface RawCommit {
-    /** The full 40-character hash, which `changelogOverrides` keys on. */
+    /** The full 40-character hash. */
     hash: string;
     /** The first line, with a wrapped subject folded onto one line by git. */
     subject: string;
-    /** The message after its first blank line, empty when the commit carries no body. */
+    /** The message after its first blank line, empty when the commit does not have a body. */
     body: string;
     /** The raw commit message, subject and body together. */
     message: string;
 }
-/** The commits one release contains, with the version and date under which they shipped. */
+/** The commits that one release contains, with the version and date under which they were released. */
 export interface ReleaseWindow {
     /** The tag name for a released window, the caller's unreleased-tag name for the newest one. */
     version: string;
@@ -32,19 +32,19 @@ export interface EnumerateReleaseWindowsOptions {
 /**
  * Splits the history reachable from HEAD into release windows, newest first.
  *
- * The newest window is always the unreleased one, empty when HEAD sits on a tag. Released
+ * The newest window is always the unreleased one, empty when HEAD is at a matching tag. Released
  * windows follow in descending order, one per reachable tag matching a prefix. A tag that
  * HEAD cannot reach is dropped.
  *
  * A commit belongs to the oldest matching tag that contains it, and to the unreleased window
- * when no matching tag does. Containment is read from the ancestry graph rather than from a
- * position in a linear walk, because a branch commit authored before a tag and merged after it
- * is not in that tag's release.
+ * when it is not contained by any matching tag. Containment is read from the ancestry graph
+ * rather than from a position in a linear walk, because a branch commit authored before a tag
+ * and merged after it is not in that tag's release.
  *
  * Three git invocations serve any number of tags: `git rev-list --topo-order --parents` for the
  * ancestry graph, `git for-each-ref` for the tag names with their creation dates and target
  * commits, and one path-filtered `git log` for the commits themselves.
  *
- * @throws If `tagPrefixes` is empty, or if any git invocation fails.
+ * Throws if `tagPrefixes` is empty, or if any git invocation fails.
  */
 export declare function enumerateReleaseWindows(options: EnumerateReleaseWindowsOptions): ReleaseWindow[];

package/dist/esm/extractMigration.d.ts

@@ -1,14 +1,12 @@
 /**
  * Extracts the instruction from a commit body's `Migration:` paragraph.
  *
- * The first paragraph opening with the label wins: the lede doctrine specifies one labeled
- * paragraph per body, so a second is ignored rather than appended. The match is anchored and
- * case-sensitive, so `migration:` and `**Migration:**` yield nothing; the doctrine calls the
- * label literal, and tolerating variants would let the form drift.
+ * The commit convention defines one literal `Migration:` label per body, so the first paragraph
+ * opening with it is read and a second is ignored. Because the match is anchored and
+ * case-sensitive, `migration:` and `**Migration:**` yield nothing.
  *
- * Newlines inside the paragraph are preserved. The first character is capitalized, which is
- * inert for the imperative the doctrine requires and repairs the lowercase continuation of a
- * paragraph written before it. Returns `undefined` when no paragraph carries the label, or when
- * the label is followed by nothing.
+ * Newlines inside the paragraph are preserved. The first character is capitalized, which repairs
+ * an instruction that continues the label in lowercase. Returns `undefined` when the body does not
+ * contain a paragraph opening with the label, or when the label is followed by nothing.
  */
 export declare function extractMigration(body: string | undefined): string | undefined;

package/dist/esm/findUnroutedEntryScopes.d.ts

@@ -0,0 +1,16 @@
+import type { RawCommit } from './enumerateReleaseWindows.js';
+import type { UnroutedEntryScope } from './types.js';
+/** A workspace's `dir` with the commits of its unreleased window. */
+export interface WorkspaceWindow {
+    commits: readonly RawCommit[];
+    dir: string;
+}
+/**
+ * Finds the change-record entry scopes of the unreleased windows that do not route their entry to any workspace whose
+ * window contains the commit, and returns the findings keyed by the `dir` of every workspace whose window contains it.
+ *
+ * A scope resolves through `scopeAliases` first. It is not reported when it resolves to `*`, to a workspace whose
+ * window contains the commit, or to a `configuredDirs` workspace absent from `windows`, which the run did not read.
+ * `root` is not reported unless a configured workspace has that `dir`, in which case it matches as that workspace.
+ */
+export declare function findUnroutedEntryScopes(windows: readonly WorkspaceWindow[], configuredDirs: readonly string[], scopeAliases: Readonly<Record<string, string>>): Map<string, UnroutedEntryScope[]>;

package/dist/esm/findUnroutedEntryScopes.js

@@ -0,0 +1,57 @@
+import { isNonChangeSubject } from "./classifyChangelogCommit.js";
+import { parseChangeRecordBlock } from "./parseChangeRecordBlock.js";
+export function findUnroutedEntryScopes(windows, configuredDirs, scopeAliases) {
+    const readDirs = new Set(windows.map((window) => window.dir));
+    const unreadDirs = new Set(configuredDirs.filter((dir) => !readDirs.has(dir)));
+    const isRootReserved = !configuredDirs.includes('root');
+    const findings = new Map();
+    for (const { commit, windowDirs } of indexCommits(windows).values()) {
+        for (const finding of findCommitUnroutedScopes(commit, windowDirs, unreadDirs, isRootReserved, scopeAliases)) {
+            for (const dir of windowDirs) {
+                const list = findings.get(dir) ?? [];
+                list.push(finding);
+                findings.set(dir, list);
+            }
+        }
+    }
+    return findings;
+}
+function findCommitUnroutedScopes(commit, windowDirs, unreadDirs, isRootReserved, scopeAliases) {
+    if (isNonChangeSubject(commit.subject)) {
+        return [];
+    }
+    const reading = parseChangeRecordBlock(commit.message);
+    if (reading.kind !== 'read') {
+        return [];
+    }
+    const findings = [];
+    for (const [index, entry] of reading.entries.entries()) {
+        const scopes = new Set(entry.scopes);
+        for (const scope of scopes) {
+            const resolved = scopeAliases[scope] ?? scope;
+            const isRouted = resolved === '*' ||
+                windowDirs.has(resolved) ||
+                unreadDirs.has(resolved) ||
+                (resolved === 'root' && isRootReserved);
+            if (!isRouted) {
+                findings.push({ commitHash: commit.hash, commitSubject: commit.subject, entryPosition: index + 1, scope });
+            }
+        }
+    }
+    return findings;
+}
+function indexCommits(windows) {
+    const index = new Map();
+    for (const window of windows) {
+        for (const commit of window.commits) {
+            const indexed = index.get(commit.hash);
+            if (indexed === undefined) {
+                index.set(commit.hash, { commit, windowDirs: new Set([window.dir]) });
+            }
+            else {
+                indexed.windowDirs.add(window.dir);
+            }
+        }
+    }
+    return index;
+}

package/dist/esm/formatExcludedSkip.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedTag } from './resolveReleaseTags.js';
+/** Formats the warning emitted when a release tag's workspace is excluded by config and therefore skipped. */
+export declare function formatExcludedSkip(resolvedTag: Pick<ResolvedTag, 'tag' | 'workspacePath'>): string;

package/dist/esm/formatExcludedSkip.js

@@ -0,0 +1,3 @@
+export function formatExcludedSkip(resolvedTag) {
+    return `Skipping ${resolvedTag.tag} (${resolvedTag.workspacePath}): excluded by config (shouldExclude: true).`;
+}

package/dist/esm/formatPrivateSkip.d.ts

@@ -1,8 +1,3 @@
 import type { ResolvedTag } from './resolveReleaseTags.js';
-/**
- * Format the warning emitted when a release tag's workspace is private and therefore skipped.
- *
- * Shared by `release-kit publish` and `release-kit create-github-release` so the skip wording
- * is defined once and stays identical across both commands.
- */
+/** Formats the warning emitted when a release tag's workspace is private and therefore skipped. */
 export declare function formatPrivateSkip(resolvedTag: Pick<ResolvedTag, 'tag' | 'workspacePath'>): string;

package/dist/esm/generateChangelogs.d.ts

@@ -1,14 +1,19 @@
 import type { WorkspaceConfig } from './types.js';
+/** Returns the workspace's derived tag prefix followed by each declared legacy-identity tag prefix. */
+export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
 /**
- * Return the workspace's derived tag prefix followed by each declared legacy-identity tag
- * prefix. Shared by `releasePrepareMono` (the production prepare path) and
- * `validateOverridesCommand` so the two compute byte-equal per-workspace tag-prefix unions.
+ * Options for `readReleaseHistory`: the tag prefixes and pathspecs that bound its release windows, and the workspace
+ * to which it routes change-record entries.
  */
-export declare function getAllTagPrefixes(workspace: WorkspaceConfig): string[];
-/** Options for `buildChangelogEntries`: the tag prefixes and pathspecs that bound its release windows. */
 export interface GenerateChangelogOptions {
     /** Tag prefixes to match as a union; must contain at least one entry. */
     tagPrefixes: readonly string[];
     /** Git pathspecs restricting the history to commits that touch them; all paths when omitted. */
     paths?: readonly string[];
+    /**
+     * The `dir` of the workspace being read. When set, the read includes a change-record entry only when its scopes,
+     * after `scopeAliases` resolution, name this `dir`, are empty, or contain `*`; when omitted, the read includes every
+     * entry.
+     */
+    workspaceDir?: string;
 }

package/dist/esm/glyphs.d.ts

@@ -1,3 +1,3 @@
-/** Glyphs that name no status; a status marker comes from nmr-core's `STATUS_GLYPHS`. */
+/** Glyphs that do not name a status; a status marker comes from nmr-core's `STATUS_GLYPHS`. */
 export declare const RELEASE_GLYPHS: Readonly<Record<"plain" | "rich", Readonly<Record<"tag" | "bump" | "dryRun", import("@williamthorsen/toolbelt.terminal/candidate").Glyph>>>>;
 export type ReleaseGlyphName = keyof (typeof RELEASE_GLYPHS)['rich'];

package/dist/esm/help/prepareHelp.d.ts

@@ -1,8 +1,7 @@
 /**
- * Single source of truth for the `release-kit prepare` help text. Imported by the bin
- * dispatcher and asserted by the help drift guard test; kept free of import-time side
- * effects so both can load it.
+ * Help text for `release-kit prepare`. The module does not have any import-time side effects, so that a test can
+ * import it without running the CLI.
  */
-export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Path to config file (default: .config/release-kit.config.ts)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when no commits or no bump-worthy commits exist\n                         since the last tag. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
+export declare const prepareHelpText = "\nUsage: release-kit prepare [options]\n\nRun release preparation with automatic workspace discovery.\n\nOptions:\n  --config <path>       Config file, relative to the current directory\n                         (default: .config/release-kit.config.ts at the repo root)\n  --dry-run             Run without modifying any files\n  --bump=major|minor|patch  Set the level of every release that happens; does not trigger one\n  --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo\n                         mode it requires --only, and is rejected when a 'project' block is configured.\n  --force               Release even when the last tag is not followed by any commits,\n                         or by any bump-worthy ones. Defaults to patch when --bump is not given;\n                         use --bump=X for a different level.\n  --no-git-checks, -n   Skip the clean-working-tree check\n  --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).\n                         When a 'project' block is configured, the project release is skipped.\n  --with-release-notes  Also write per-workspace release-notes previews under <workspacePath>/docs/\n                         (docs/README.v<version>.md and docs/RELEASE_NOTES.v<version>.md).\n                         Recommended .gitignore entry: packages/*/docs/*.v*.md (or docs/*.v*.md).\n  --help, -h            Show this help message\n";
 /** Prints the prepare command's help text. */
 export declare function showPrepareHelp(): void;

package/dist/esm/help/prepareHelp.js

@@ -4,13 +4,14 @@ Usage: release-kit prepare [options]
 Run release preparation with automatic workspace discovery.
 
 Options:
-  --config <path>       Path to config file (default: .config/release-kit.config.ts)
+  --config <path>       Config file, relative to the current directory
+                         (default: .config/release-kit.config.ts at the repo root)
   --dry-run             Run without modifying any files
   --bump=major|minor|patch  Set the level of every release that happens; does not trigger one
   --set-version=X.Y.Z   Set an explicit version; bypasses the changelog-derived bump. In monorepo
                          mode it requires --only, and is rejected when a 'project' block is configured.
-  --force               Release even when no commits or no bump-worthy commits exist
-                         since the last tag. Defaults to patch when --bump is not given;
+  --force               Release even when the last tag is not followed by any commits,
+                         or by any bump-worthy ones. Defaults to patch when --bump is not given;
                          use --bump=X for a different level.
   --no-git-checks, -n   Skip the clean-working-tree check
   --only=name1,name2    Only process the named workspaces (comma-separated, monorepo only).

package/dist/esm/init/checks.d.ts

@@ -3,9 +3,9 @@ export interface CheckResult {
     ok: boolean;
     message?: string;
 }
-/** Verify the current directory is inside a git repository. */
+/** Verifies that the current directory is inside a git repository. */
 export declare function isGitRepo(): CheckResult;
-/** Verify that package.json exists in the current directory. */
+/** Verifies that package.json exists in the current directory. */
 export declare function hasPackageJson(): CheckResult;
-/** Verify that the project uses pnpm (has pnpm-lock.yaml or packageManager field). */
+/** Verifies that the project uses pnpm, signaled by pnpm-lock.yaml or a pnpm `packageManager` field. */
 export declare function usesPnpm(): CheckResult;

package/dist/esm/init/checks.js

@@ -15,7 +15,10 @@ export function hasPackageJson() {
     if (existsSync('package.json')) {
         return { ok: true };
     }
-    return { ok: false, message: 'No package.json found. Run `npm init` or `pnpm init` first.' };
+    return {
+        ok: false,
+        message: 'The current directory does not contain a package.json. Run `npm init` or `pnpm init` first.',
+    };
 }
 export function usesPnpm() {
     if (existsSync('pnpm-lock.yaml')) {

package/dist/esm/init/detectRepoType.d.ts

@@ -1,9 +1,8 @@
 /** Repo layout type. */
 export type RepoType = 'monorepo' | 'single-package';
 /**
- * Detect whether the current directory is a monorepo or a single-package repo.
+ * Detects whether the current directory is a monorepo or a single-package repo.
  *
- * Returns `'monorepo'` if `pnpm-workspace.yaml` exists or `package.json` has a `workspaces` field.
- * Otherwise returns `'single-package'`.
+ * A monorepo has `pnpm-workspace.yaml` or a `workspaces` array in `package.json`.
  */
 export declare function detectRepoType(): RepoType;

package/dist/esm/init/hasProvenance.d.ts

@@ -0,0 +1,2 @@
+/** Checks whether a publish workflow enables provenance on an uncommented line. */
+export declare function hasProvenance(workflowContent: string): boolean;

package/dist/esm/init/hasProvenance.js

@@ -0,0 +1,3 @@
+export function hasProvenance(workflowContent) {
+    return /^[^#]*provenance:\s*['"]?true['"]?/im.test(workflowContent);
+}

package/dist/esm/init/initCommand.d.ts

@@ -5,11 +5,8 @@ interface InitOptions {
     styles: StreamStyles;
     withConfig: boolean;
 }
-/**
- * Run the `release-kit init` command.
- *
- * Checks eligibility, detects repo type, scaffolds files, and prints next steps.
- * Returns the process exit code (0 for success, 1 for failure).
- */
+/** Runs the eligibility checks, stopping at the first failure, and reports whether all passed. */
+export declare function checkEligibility(styles: StreamStyles): boolean;
+/** Runs the `release-kit init` command and returns the process exit code. */
 export declare function initCommand({ dryRun, force, styles, withConfig }: InitOptions): number;
 export {};

package/dist/esm/init/initCommand.js

@@ -3,15 +3,7 @@ import { describeError } from '@williamthorsen/toolbelt.errors';
 import { hasPackageJson, isGitRepo, usesPnpm } from "./checks.js";
 import { detectRepoType } from "./detectRepoType.js";
 import { scaffoldFiles } from "./scaffold.js";
-function runRequiredCheck(label, result, styles) {
-    if (result.ok) {
-        printSuccess(label, styles.stdout);
-        return true;
-    }
-    printError(result.message ?? `${label} failed`, styles.stderr);
-    return false;
-}
-function checkEligibility(styles) {
+export function checkEligibility(styles) {
     printStep('Checking eligibility');
     if (!runRequiredCheck('Git repository detected', isGitRepo(), styles))
         return false;
@@ -66,10 +58,18 @@ export function initCommand({ dryRun, force, styles, withConfig }) {
         : '1. (Optional) Run again with --with-config to scaffold config files.';
     console.info(`
   ${configHint}
-  2. If this is a public repo, set provenance: true in .github/workflows/publish.yaml.
+  2. If this is a private repo, remove provenance: true from .github/workflows/publish.yaml.
   3. Test by running: npx @williamthorsen/release-kit prepare --dry-run
   4. Commit the generated files.
   5. Register each package as a trusted publisher on npmjs.com.
 `);
     return 0;
 }
+function runRequiredCheck(label, result, styles) {
+    if (result.ok) {
+        printSuccess(label, styles.stdout);
+        return true;
+    }
+    printError(result.message ?? `${label} failed`, styles.stderr);
+    return false;
+}

package/dist/esm/init/parseJsonRecord.d.ts

@@ -1,5 +1,2 @@
-/**
- * Parse a JSON string and return the result if it is a plain object (Record<string, unknown>).
- * Returns `undefined` if parsing fails or the result is not a plain object.
- */
+/** Parses a JSON string, returning the result if it is a plain object and `undefined` otherwise. */
 export declare function parseJsonRecord(raw: string): Record<string, unknown> | undefined;

package/dist/esm/init/scaffold.d.ts

@@ -6,6 +6,6 @@ interface ScaffoldOptions {
     overwrite: boolean;
     withConfig: boolean;
 }
-/** Scaffold release-kit files for the target repo. Returns a result for each file attempted. */
+/** Scaffolds release-kit files for the target repo, returning a result for each file attempted. */
 export declare function scaffoldFiles({ repoType, dryRun, overwrite, withConfig }: ScaffoldOptions): WriteResult[];
 export {};

package/dist/esm/init/templates.d.ts

@@ -1,18 +1,16 @@
 import type { RepoType } from './detectRepoType.js';
-/** Generate the `.config/release-kit.config.ts` starter config with TODOs for customization. */
+/** Generates the `.config/release-kit.config.ts` starter config, with commented-out options to customize. */
 export declare function releaseConfigScript(repoType: RepoType): string;
 /**
- * Generate the publish.yaml GitHub Actions entry-point workflow.
+ * Generates the publish.yaml GitHub Actions entry-point workflow.
  *
- * The `permissions` block is present for explicitness; the reusable workflow declares its own
- * permissions, so GitHub uses those rather than the caller's block.
- */
-export declare function publishWorkflow(repoType: RepoType): string;
-/**
- * Generate the create-github-release.yaml GitHub Actions caller workflow.
- *
- * Fires on tag push and delegates to the reusable workflow under `contents: write`.
+ * The caller's `permissions` block caps what the reusable workflow receives, so it must grant the `id-token: write`
+ * that OIDC publishing needs. `provenance: false` omits the provenance input, which a private repo cannot use.
  */
+export declare function publishWorkflow(repoType: RepoType, { provenance }?: {
+    provenance?: boolean;
+}): string;
+/** Generates the create-github-release.yaml GitHub Actions caller workflow. */
 export declare function createGithubReleaseWorkflow(repoType: RepoType): string;
-/** Generate the release.yaml GitHub Actions workflow. */
+/** Generates the release.yaml GitHub Actions workflow. */
 export declare function releaseWorkflow(repoType: RepoType): string;