genbumppush 0.0.3 → 0.0.4

package/README.md

@@ -66,7 +66,7 @@ genbumppush --retry-gitlab v1.2.4                           # retry provider rel
 | `--yes`, `-y`          | Skip confirmation                                        |
 | `--help`, `-h`         | Print help                                               |
 
-Values are resolved in this order: CLI, config file, the `genbumppush` key in `package.json`, then defaults. A CLI flag such as `--no-push` overrides the config file.
+Values are resolved in this order: CLI flags, C12 config file, the `"genbumppush"` key in `package.json`, then defaults. A CLI flag such as `--no-push` overrides both config surfaces.
 
 ## Commit detection
 
@@ -84,7 +84,7 @@ chore(deps): update vite   -> excluded by default
 
 ## Configuration
 
-Create `genbumppush.config.ts`:
+Prefer a dedicated C12 file so the config stays typed, commented, and out of dependency diffs. Create `genbumppush.config.ts`:
 
 ```ts
 import { defineConfig } from 'genbumppush';
@@ -113,35 +113,83 @@ export default defineConfig({
 });
 ```
 
-The same object can live under `"genbumppush"` in `package.json`. JavaScript and TypeScript C12 files are supported; use `--config` for another location.
-
-| Key                        | Type                      | Default                        | Behavior                               |
-| -------------------------- | ------------------------- | ------------------------------ | -------------------------------------- |
-| `release`                  | release type              | detected                       | Force release type                     |
-| `preid`                    | string                    | `beta`                         | Prerelease channel                     |
-| `changelog`                | `false \| true \| string` | `CHANGELOG.md`                 | Disable, default, or custom path       |
-| `excludeDependencyCommits` | boolean                   | `true`                         | Ignore non-breaking dependency commits |
-| `files`                    | string[]                  | `['package.json']`             | Version files                          |
-| `recursive`                | boolean                   | `false`                        | Discover nested manifests              |
-| `git.remote`               | string                    | `origin`                       | Remote for checks and push             |
-| `git.push`                 | boolean                   | `true`                         | Push branch and tag                    |
-| `git.sign`                 | boolean                   | `false`                        | Sign commit and tag                    |
-| `git.requireClean`         | boolean                   | `true`                         | Reject uncommitted changes             |
-| `git.requireUpstream`      | boolean                   | `true`                         | Require upstream before pushing        |
-| `git.commitMessage`        | string                    | `chore(release): v{{version}}` | Commit template                        |
-| `git.tagName`              | string                    | `v{{version}}`                 | Tag template                           |
-| `git.tagMessage`           | string                    | `v{{version}}`                 | Annotated tag template                 |
-| `hooks.before`             | string or string[]        | unset                          | Commands before file changes           |
-| `hooks.after`              | string or string[]        | unset                          | Commands after tag/push                |
-| `github.enabled`           | boolean                   | `false`                        | Create a GitHub release after push     |
-| `github.host`              | string                    | `github.com`                   | github.com or GHES host                |
-| `github.repo`              | string                    | `GITHUB_REPOSITORY` / remote   | `owner/name`                           |
-| `github.tokenEnv`          | string                    | `GITHUB_TOKEN`                 | Token environment variable             |
-| `github.releaseName`       | string                    | tag                            | Release title template                 |
-| `gitlab.enabled`           | boolean                   | `false`                        | Create a GitLab release after push     |
+JavaScript C12 files are also supported. Use `--config <path>` to load a file at another location.
+
+### Config in `package.json`
+
+For simple setups, the same object can live under the exact top-level key `"genbumppush"` in `package.json`. Other keys are ignored.
+
+```json
+{
+  "name": "my-app",
+  "version": "1.2.3",
+  "genbumppush": {
+    "changelog": "CHANGELOG.md",
+    "files": ["package.json"],
+    "git": {
+      "remote": "origin",
+      "push": true,
+      "tagName": "v{{version}}"
+    }
+  }
+}
+```
+
+JSON has no comments and no `defineConfig` typing, so move to `genbumppush.config.ts` once the release config grows nested `github`/`gitlab` blocks or custom hooks. A config file always wins over the `package.json` key.
+
+**Never put secrets in either surface.** Tokens, host credentials, and project IDs with credentials belong in the process environment or an uncommitted `.env`. Config may only name which env var to read (for example `tokenEnv`).
+
+| Key                        | Type                      | Default                        | Behavior                                |
+| -------------------------- | ------------------------- | ------------------------------ | --------------------------------------- |
+| `release`                  | release type              | detected                       | Force release type                      |
+| `preid`                    | string                    | `beta`                         | Prerelease channel                      |
+| `changelog`                | `false \| true \| string` | `CHANGELOG.md`                 | Disable, default, or custom path        |
+| `excludeDependencyCommits` | boolean                   | `true`                         | Ignore non-breaking dependency commits  |
+| `files`                    | string[]                  | `['package.json']`             | Version files                           |
+| `recursive`                | boolean                   | `false`                        | Discover nested manifests               |
+| `git.remote`               | string                    | `origin`                       | Remote for checks and push              |
+| `git.push`                 | boolean                   | `true`                         | Push branch and tag                     |
+| `git.sign`                 | boolean                   | `false`                        | Sign commit and tag                     |
+| `git.requireClean`         | boolean                   | `true`                         | Reject uncommitted changes              |
+| `git.requireUpstream`      | boolean                   | `true`                         | Require upstream before pushing         |
+| `git.commitMessage`        | string                    | `chore(release): v{{version}}` | Commit template                         |
+| `git.tagName`              | string                    | `v{{version}}`                 | Tag template                            |
+| `git.tagMessage`           | string                    | `v{{version}}`                 | Annotated tag template                  |
+| `hooks.before`             | string or string[]        | unset                          | Commands before file changes            |
+| `hooks.after`              | string or string[]        | unset                          | Commands after tag/push                 |
+| `github.enabled`           | boolean                   | `false`                        | Create a GitHub release after push      |
+| `github.host`              | string                    | `github.com`                   | github.com or GHES host                 |
+| `github.repo`              | string                    | env / remote                   | `owner/name`                            |
+| `github.tokenEnv`          | string                    | auto                           | Exact env var name (disables fallbacks) |
+| `github.releaseName`       | string                    | tag                            | Release title template                  |
+| `gitlab.enabled`           | boolean                   | `false`                        | Create a GitLab release after push      |
 
 `{{version}}` is replaced in commit and tag templates. Hooks run through the shell in the repository directory; only use trusted configuration.
 
+## Environment variables and `.env`
+
+Config never stores secrets — not in `genbumppush.config.ts`, not in `"genbumppush"` inside `package.json`. Those files are committed; tokens must not be. Provider credentials are read from the process environment. On every run, genbumppush loads `.env` from the working directory (same behavior as changelogen). Values already set in the real environment win over `.env`.
+
+Preferred names use the `GENBUMPPUSH_` prefix. Legacy provider variables still work as fallbacks:
+
+| Purpose           | Preferred                       | Fallbacks                                               |
+| ----------------- | ------------------------------- | ------------------------------------------------------- |
+| GitHub token      | `GENBUMPPUSH_GITHUB_TOKEN`      | `GITHUB_TOKEN`, `GH_TOKEN`, `CHANGELOGEN_TOKENS_GITHUB` |
+| GitHub host       | `GENBUMPPUSH_GITHUB_HOST`       | `GITHUB_API_URL`                                        |
+| GitHub repository | `GENBUMPPUSH_GITHUB_REPOSITORY` | `GITHUB_REPOSITORY`                                     |
+| GitLab token      | `GENBUMPPUSH_GITLAB_TOKEN`      | `GITLAB_TOKEN`                                          |
+| GitLab host       | `GENBUMPPUSH_GITLAB_HOST`       | `GITLAB_HOST`                                           |
+| GitLab project    | `GENBUMPPUSH_GITLAB_PROJECT`    | `GITLAB_PROJECT`                                        |
+
+When `tokenEnv` is set in config, only that exact variable name is read; the fallback chain is skipped. Leave `tokenEnv` unset to use the preferred/fallback chain above.
+
+```bash
+# .env (do not commit)
+GENBUMPPUSH_GITHUB_TOKEN=ghp_...
+```
+
+`.env` is optional. Add it to `.gitignore`. CI should inject the same variables through the job environment instead of a file.
+
 ## Version-file adapters
 
 Every configured file is validated before writes begin. Structured files must agree with the root version; mismatches fail without partial updates.
@@ -216,8 +264,8 @@ export default defineConfig({
   github: {
     enabled: true,
     // host: 'github.com', // or a GHES host
-    // repo: 'group/project', // or GITHUB_REPOSITORY / package.json repository
-    tokenEnv: 'GITHUB_TOKEN', // also honors GH_TOKEN and CHANGELOGEN_TOKENS_GITHUB
+    // repo: 'group/project', // or GENBUMPPUSH_GITHUB_REPOSITORY / GITHUB_REPOSITORY / package.json
+    // omit tokenEnv to use GENBUMPPUSH_GITHUB_TOKEN, then GITHUB_TOKEN / GH_TOKEN / CHANGELOGEN_TOKENS_GITHUB
     releaseName: 'v{{version}}',
   },
 });
@@ -234,14 +282,12 @@ export default defineConfig({
     enabled: true,
     host: 'https://gitlab.com',
     project: 'group/project',
-    tokenEnv: 'GITLAB_TOKEN',
     releaseName: 'v{{version}}',
   },
 });
 ```
 
-`GITLAB_HOST` and `GITLAB_PROJECT` may be used as environment fallbacks. The token
-must be available as the configured `tokenEnv` (default `GITLAB_TOKEN`). GitLab receives
+Without `tokenEnv`, GitLab tokens resolve from `GENBUMPPUSH_GITLAB_TOKEN`, then `GITLAB_TOKEN`. `GENBUMPPUSH_GITLAB_HOST` / `GITLAB_HOST` and `GENBUMPPUSH_GITLAB_PROJECT` / `GITLAB_PROJECT` cover host and project fallbacks. GitLab receives
 the matching `CHANGELOG.md` section as the release description. If `git.push` is false,
 the provider is rejected because GitLab cannot create a release for an unpublished tag.
 
@@ -320,6 +366,10 @@ vp pack
 
 The test suite covers CLI parsing, C12 configuration, SemVer edges, JSON/npm/Cargo adapters, recursive workspaces, dry runs, rollback, hooks, tag collisions, detached HEAD, upstream checks, and a real atomic push to a temporary bare Git remote.
 
+### Agent skill
+
+This repository ships a project skill at `skills/genbumppush/`. Agents working in this checkout can load it for configuration recipes, CLI and error recovery, CI patterns, and library development notes. New conversations that open this worktree pick it up automatically; it is not published on npm.
+
 ## License
 
 MIT

package/dist/bin.mjs

@@ -1,7 +1,21 @@
 #!/usr/bin/env node
-import { n as ReleaseError, t as runRelease } from "./release-CVQ5WSKG.mjs";
+import { n as ReleaseError, t as runRelease } from "./release-gwyqzR0C.mjs";
 import { resolve } from "node:path";
 //#region src/types.ts
+/**
+* Every release type genbumppush can apply.
+*
+* The first seven values match Semantic Versioning. The `pre*` variants
+* enter a prerelease channel (`beta` by default); `prerelease` continues
+* an existing one.
+*
+* @example
+* ```ts
+* import type { ReleaseType } from 'genbumppush';
+*
+* const forced: ReleaseType = 'minor';
+* ```
+*/
 const RELEASE_TYPES = [
 	"major",
 	"premajor",

package/dist/index.d.mts

@@ -1,81 +1,519 @@
 //#region src/types.d.ts
+/**
+ * Every release type genbumppush can apply.
+ *
+ * The first seven values match Semantic Versioning. The `pre*` variants
+ * enter a prerelease channel (`beta` by default); `prerelease` continues
+ * an existing one.
+ *
+ * @example
+ * ```ts
+ * import type { ReleaseType } from 'genbumppush';
+ *
+ * const forced: ReleaseType = 'minor';
+ * ```
+ */
 declare const RELEASE_TYPES: readonly ["major", "premajor", "minor", "preminor", "patch", "prepatch", "prerelease"];
+/** One of {@link RELEASE_TYPES}. */
 type ReleaseType = (typeof RELEASE_TYPES)[number];
+/**
+ * How genbumppush talks to Git: remote name, commit/tag templates,
+ * and the safety checks run before anything is written.
+ */
 type GitOptions = {
+  /** Remote used for tag collision checks and `git push`. Default: `'origin'`. */
   remote?: string;
+  /**
+   * Push the release commit and tag together with `git push --atomic`.
+   * Set to `false` for a local-only rehearsal.
+   * @defaultValue true
+   */
   push?: boolean;
+  /**
+   * Sign the release commit (`git commit -S`) and annotated tag (`git tag -s`).
+   * @defaultValue false
+   */
   sign?: boolean;
+  /**
+   * Refuse to release when the worktree has uncommitted changes.
+   * @defaultValue true
+   */
   requireClean?: boolean;
+  /**
+   * Require the current branch to have an upstream before pushing.
+   * Ignored when {@link GitOptions.push} is `false`.
+   * @defaultValue true
+   */
   requireUpstream?: boolean;
+  /**
+   * Release commit subject. `{{version}}` is replaced with the new version
+   * (without a leading `v` unless the template adds one).
+   * @defaultValue `'chore(release): v{{version}}'`
+   * @example `'release: v{{version}}'`
+   */
   commitMessage?: string;
+  /**
+   * Tag name template. `{{version}}` is replaced with the new version.
+   * @defaultValue `'v{{version}}'`
+   */
   tagName?: string;
+  /**
+   * Annotated tag message template. `{{version}}` is replaced with the new version.
+   * @defaultValue `'v{{version}}'`
+   */
   tagMessage?: string;
 };
+/**
+ * Shell commands run around the release.
+ *
+ * Commands run in the repository root with a shell. Use them for gates you
+ * want on every release (checks, tests), not for storing secrets.
+ */
 type HookOptions = {
+  /**
+   * Runs after validation and before version files or the changelog change.
+   * A failing hook aborts the release with nothing written.
+   * @example
+   * ```ts
+   * hooks: {
+   *   before: ['npm run check', 'npm test'],
+   * }
+   * ```
+   */
   before?: string | string[];
+  /**
+   * Runs after the commit, tag, and optional provider release succeed.
+   * @example
+   * ```ts
+   * hooks: {
+   *   after: 'echo "Shipped {{version}}"',
+   * }
+   * ```
+   */
   after?: string | string[];
 };
+/**
+ * Optional GitLab release creation after a successful Git push.
+ *
+ * Credentials come from the environment (`GENBUMPPUSH_GITLAB_TOKEN` or
+ * `GITLAB_TOKEN`). Never put the token itself in this object.
+ */
 type GitLabOptions = {
+  /**
+   * Create a GitLab release for the new tag.
+   * Requires {@link GitOptions.push} to stay enabled and a token in the environment.
+   * @defaultValue false
+   */
   enabled?: boolean;
+  /**
+   * GitLab base URL, including protocol when not on gitlab.com.
+   * @defaultValue `'https://gitlab.com'`
+   * @example `'https://gitlab.example.com'`
+   */
   host?: string;
+  /**
+   * Project path or numeric ID, as used by the GitLab API.
+   * Falls back to `GENBUMPPUSH_GITLAB_PROJECT` or `GITLAB_PROJECT`.
+   * @example `'group/subgroup/project'`
+   */
   project?: string;
+  /**
+   * Exact environment variable name to read the token from.
+   * When set, the usual fallback chain is skipped.
+   * @example `'CI_JOB_TOKEN'`
+   */
   tokenEnv?: string;
+  /**
+   * Release title template. `{{version}}` is replaced with the new version.
+   * @defaultValue the tag name (for example `v1.2.3`)
+   */
   releaseName?: string;
 };
+/**
+ * Optional GitHub (or GitHub Enterprise Server) release after a successful Git push.
+ *
+ * Credentials come from the environment (`GENBUMPPUSH_GITHUB_TOKEN`,
+ * `GITHUB_TOKEN`, or `GH_TOKEN`). Never put the token itself in this object.
+ */
 type GitHubOptions = {
+  /**
+   * Create a GitHub release for the new tag.
+   * Requires {@link GitOptions.push} to stay enabled and a token in the environment.
+   * @defaultValue false
+   */
   enabled?: boolean;
+  /**
+   * GitHub host. `github.com` uses the public API; any other host is treated
+   * as GitHub Enterprise Server (`https://<host>/api/v3`).
+   * @defaultValue `'github.com'`
+   */
   host?: string;
+  /**
+   * Repository as `owner/name`. Usually inferred from the Git remote.
+   * Override when inference is wrong or unavailable.
+   * @example `'xcvzmoon/genbumppush'`
+   */
   repo?: string;
+  /**
+   * Exact environment variable name to read the token from.
+   * When set, the usual fallback chain is skipped.
+   */
   tokenEnv?: string;
+  /**
+   * Release title template. `{{version}}` is replaced with the new version.
+   * @defaultValue the tag name (for example `v1.2.3`)
+   */
   releaseName?: string;
 };
+/**
+ * Full genbumppush configuration.
+ *
+ * Every field is optional. Missing values fall back to the built-in defaults
+ * documented on each property. Prefer {@link defineConfig} in a config file
+ * so your editor can check the shape.
+ *
+ * @example Minimal config in `genbumppush.config.ts`
+ * ```ts
+ * import { defineConfig } from 'genbumppush';
+ *
+ * export default defineConfig({
+ *   files: ['package.json', 'package-lock.json'],
+ *   git: { tagName: 'v{{version}}' },
+ * });
+ * ```
+ *
+ * @example Same object under `"genbumppush"` in `package.json`
+ * ```json
+ * {
+ *   "genbumppush": {
+ *     "changelog": false,
+ *     "git": { "push": false }
+ *   }
+ * }
+ * ```
+ */
 type GenBumpPushConfig = {
+  /**
+   * Force a release type instead of detecting it from Conventional Commits.
+   * Leave unset for automatic detection.
+   * @example `'patch'`
+   */
   release?: ReleaseType;
+  /**
+   * Prerelease identifier used by `premajor`, `preminor`, `prepatch`,
+   * and `prerelease`.
+   * @defaultValue `'beta'`
+   * @example `'rc'` produces `1.2.4-rc.0` from `1.2.3`
+   */
   preid?: string;
+  /**
+   * Files whose version strings are updated for the release.
+   * Each path is relative to the repository root and must stay inside it.
+   * @defaultValue `['package.json']`
+   * @example
+   * ```ts
+   * files: [
+   *   'package.json',
+   *   'src-tauri/tauri.conf.json',
+   *   'src-tauri/Cargo.toml',
+   * ]
+   * ```
+   */
   files?: string[];
+  /**
+   * Also update every nested `package.json` under the repository.
+   * Meant for fixed-version monorepos that share one version number.
+   * @defaultValue false
+   */
   recursive?: boolean;
+  /**
+   * Changelog behavior:
+   * - `false` — do not write a changelog
+   * - `true` — write `CHANGELOG.md`
+   * - `string` — write that path
+   * @defaultValue `'CHANGELOG.md'`
+   * @example `'docs/RELEASES.md'`
+   */
   changelog?: boolean | string;
+  /**
+   * Ignore non-breaking `chore(deps): …` commits when detecting the next
+   * version and building the changelog.
+   * @defaultValue true
+   */
   excludeDependencyCommits?: boolean;
+  /** Git commit, tag, and push behavior. See {@link GitOptions}. */
   git?: GitOptions;
+  /** Optional GitLab release after push. See {@link GitLabOptions}. */
   gitlab?: GitLabOptions;
+  /** Optional GitHub release after push. See {@link GitHubOptions}. */
   github?: GitHubOptions;
+  /** Shell commands run before and after the release. See {@link HookOptions}. */
   hooks?: HookOptions;
 };
+/**
+ * Parsed CLI arguments for {@link runRelease}.
+ *
+ * You usually receive this from the binary rather than building it by hand.
+ * When embedding genbumppush, the minimum object is `{ cwd, dryRun: false, yes: true }`
+ * (plus `help: false` if you want a complete {@link CliOptions}).
+ *
+ * @example Non-interactive patch release in another directory
+ * ```ts
+ * import { runRelease } from 'genbumppush';
+ *
+ * await runRelease({
+ *   cwd: '/path/to/repo',
+ *   dryRun: false,
+ *   yes: true,
+ *   help: false,
+ *   release: 'patch',
+ * });
+ * ```
+ */
 type CliOptions = {
+  /** Absolute path to the Git repository to release. Defaults to `process.cwd()` in the CLI. */
   cwd: string;
+  /** Explicit C12 config file path. Overrides discovery and the `package.json` key. */
   configFile?: string;
+  /** Retry only GitLab release creation for a tag that already exists on the remote. */
   gitlabRetryTag?: string;
+  /** Retry only GitHub release creation for a tag that already exists on the remote. */
   githubRetryTag?: string;
+  /** Force a release type; otherwise it is detected from commits (or config). */
   release?: ReleaseType;
+  /** Prerelease identifier; overrides the value from config when set. */
   preid?: string;
+  /** Preview the release without changing files, Git, or remotes. */
   dryRun: boolean;
+  /** `false` keeps the commit and tag local. Unset means “use config”. */
   push?: boolean;
+  /** Skip the interactive `Create a … release?` confirmation. */
   yes: boolean;
+  /** Print CLI help and exit without running a release. */
   help: boolean;
 };
+/**
+ * What {@link runRelease} did (or would do, for a dry run).
+ *
+ * When there are no releasable commits, `releaseType`, `newVersion`, and
+ * `tag` stay `undefined` and `pushed` is `false`. That is a successful no-op.
+ *
+ * @example Inspect a dry run
+ * ```ts
+ * import { runRelease } from 'genbumppush';
+ *
+ * const result = await runRelease({ cwd: process.cwd(), dryRun: true, yes: true, help: false });
+ * if (result.releaseType === undefined) {
+ *   console.log('Nothing to release');
+ * } else {
+ *   console.log(`${result.currentVersion} → ${result.newVersion} as ${result.tag}`);
+ * }
+ * ```
+ */
 type ReleaseResult = {
+  /** Version before this run (from the root `package.json`). */
   currentVersion: string;
+  /** Version after the bump. Absent on dry-run skips and “no releasable commits”. */
   newVersion?: string;
+  /** Release type that was applied (or planned, for a dry run). */
   releaseType?: ReleaseType;
+  /** Tag name created or planned, after `{{version}}` substitution. */
   tag?: string;
+  /** `true` only when the branch and tag were pushed to the remote. */
   pushed: boolean;
+  /** `true` when the run was a dry run and nothing was written. */
   dryRun: boolean;
+  /** Number of Conventional Commits that fed the release decision. */
   commitCount: number;
+  /** `true` when a GitLab release was created after the Git push. */
   gitlabReleaseCreated?: boolean;
+  /** `true` when a GitHub release was created after the Git push. */
   githubReleaseCreated?: boolean;
 };
 //#endregion
 //#region src/config.d.ts
+/**
+ * Identity helper that types a release config for your editor.
+ *
+ * It does not change the object at runtime — it only enables autocomplete
+ * and catches typos inside `defineConfig({ … })`.
+ *
+ * @typeParam Config - Config object shape; defaults to {@link GenBumpPushConfig}.
+ * @returns The same object you passed in.
+ *
+ * @example `genbumppush.config.ts`
+ * ```ts
+ * import { defineConfig } from 'genbumppush';
+ *
+ * export default defineConfig({
+ *   preid: 'beta',
+ *   files: ['package.json'],
+ *   git: {
+ *     commitMessage: 'chore(release): v{{version}}',
+ *   },
+ *   hooks: {
+ *     before: ['npm run check', 'npm test'],
+ *   },
+ * });
+ * ```
+ */
 export declare const defineConfig: import("c12").DefineConfig<GenBumpPushConfig, import("c12").ConfigLayerMeta>;
+/**
+ * Load the effective release config for a repository.
+ *
+ * Resolution order (later wins):
+ * 1. {@link defaults}
+ * 2. `"genbumppush"` key in that directory’s `package.json`
+ * 3. C12 config file (`genbumppush.config.ts` / `.js`, or `configFile` when given)
+ * 4. `overrides` you pass here (CLI flags in the binary go through this)
+ *
+ * Also loads `.env` from `cwd` into `process.env` without overwriting
+ * variables that are already set. Secrets still belong in the environment —
+ * not in config files.
+ *
+ * @param cwd - Repository root to load config from.
+ * @param configFile - Optional explicit path to a C12 config file.
+ * @param overrides - Highest-priority values (for example CLI flags).
+ * @returns The fully merged config object.
+ * @throws May reject if the config file throws or cannot be loaded.
+ *
+ * @example Read what a repo already configured
+ * ```ts
+ * import { loadReleaseConfig } from 'genbumppush';
+ *
+ * const config = await loadReleaseConfig(process.cwd());
+ * console.log(config.git?.remote ?? 'origin');
+ * ```
+ *
+ * @example Force a dry-run-style push disable from a script
+ * ```ts
+ * import { loadReleaseConfig } from 'genbumppush';
+ *
+ * const config = await loadReleaseConfig(process.cwd(), undefined, {
+ *   git: { push: false },
+ * });
+ * // config.git.push === false even if the file enabled push
+ * ```
+ */
 export declare function loadReleaseConfig(cwd: string, configFile?: string, overrides?: GenBumpPushConfig): Promise<GenBumpPushConfig>;
 //#endregion
 //#region src/error.d.ts
+/**
+ * Error thrown by genbumppush for expected release failures.
+ *
+ * Unlike a generic `Error`, every {@link ReleaseError} carries a stable
+ * {@link ReleaseError.code} so scripts and the CLI can branch on the reason
+ * (`DIRTY_WORKTREE`, `TAG_EXISTS`, `CANCELLED`, …) without parsing messages.
+ *
+ * @example Branch on the failure reason
+ * ```ts
+ * import { runRelease, ReleaseError } from 'genbumppush';
+ *
+ * try {
+ *   await runRelease({ cwd: process.cwd(), dryRun: false, yes: true, help: false });
+ * } catch (error) {
+ *   if (error instanceof ReleaseError && error.code === 'CANCELLED') {
+ *     process.exit(0);
+ *   }
+ *   throw error;
+ * }
+ * ```
+ *
+ * @example Print code and message the same way the CLI does
+ * ```ts
+ * if (error instanceof ReleaseError) {
+ *   console.error(`[${error.code}] ${error.message}`);
+ * }
+ * ```
+ */
 export declare class ReleaseError extends Error {
+  /** Machine-readable reason, for example `'DIRTY_WORKTREE'` or `'TAG_EXISTS'`. */
   readonly code: string;
+  /**
+   * @param code - Stable machine-readable reason.
+   * @param message - Human-readable explanation shown to the user.
+   * @param options - Optional `cause` when wrapping an underlying error.
+   */
   constructor(code: string, message: string, options?: ErrorOptions);
 }
 //#endregion
 //#region src/release.d.ts
+/**
+ * Run a full release (or a dry run / provider retry) for one repository.
+ *
+ * Typical flow:
+ * 1. Load config and `.env`
+ * 2. Verify the worktree is a clean Git repo on a branch
+ * 3. Detect (or force) a release type from Conventional Commits
+ * 4. Confirm, run `before` hooks, update version files and the changelog
+ * 5. Commit, tag, and atomically push branch + tag
+ * 6. Optionally create a GitHub/GitLab release, then run `after` hooks
+ *
+ * Version-file or commit failures restore files and the index. A failed tag
+ * or network push can leave the release commit locally so you can inspect
+ * and retry — see the returned {@link ReleaseResult} and any thrown
+ * {@link ReleaseError}.
+ *
+ * Prefer the `genbumppush` CLI for day-to-day use. Call this directly when
+ * embedding releases in a Node script or CI job that already builds
+ * {@link CliOptions}.
+ *
+ * @param options - Parsed CLI options. `cwd`, `dryRun`, `yes`, and `help` are required;
+ *   the rest override config when set.
+ * @returns A summary of what happened. Never mutates when `dryRun` is `true`.
+ * @throws {@link ReleaseError} for expected failures (dirty worktree, existing tag,
+ *   cancelled confirmation, Git/provider errors). Unexpected errors may also throw.
+ *
+ * @example Dry run in the current directory
+ * ```ts
+ * import { runRelease } from 'genbumppush';
+ *
+ * const result = await runRelease({
+ *   cwd: process.cwd(),
+ *   dryRun: true,
+ *   yes: true,
+ *   help: false,
+ * });
+ *
+ * console.log(result);
+ * // {
+ * //   currentVersion: '1.2.3',
+ * //   newVersion: '1.3.0',
+ * //   releaseType: 'minor',
+ * //   tag: 'v1.3.0',
+ * //   pushed: false,
+ * //   dryRun: true,
+ * //   commitCount: 4
+ * // }
+ * ```
+ *
+ * @example Non-interactive patch release that stays local
+ * ```ts
+ * import { runRelease } from 'genbumppush';
+ *
+ * await runRelease({
+ *   cwd: process.cwd(),
+ *   dryRun: false,
+ *   yes: true,
+ *   help: false,
+ *   release: 'patch',
+ *   push: false,
+ * });
+ * ```
+ *
+ * @example Retry only the GitLab release after Git already succeeded
+ * ```ts
+ * import { runRelease } from 'genbumppush';
+ *
+ * await runRelease({
+ *   cwd: process.cwd(),
+ *   dryRun: false,
+ *   yes: true,
+ *   help: false,
+ *   gitlabRetryTag: 'v1.3.0',
+ * });
+ * ```
+ */
 export declare function runRelease(options: CliOptions): Promise<ReleaseResult>;
 //#endregion
 export type { CliOptions, GenBumpPushConfig, GitHubOptions, GitLabOptions, GitOptions, HookOptions, ReleaseResult, ReleaseType };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { i as loadReleaseConfig, n as ReleaseError, r as defineConfig, t as runRelease } from "./release-CVQ5WSKG.mjs";
+import { i as loadReleaseConfig, n as ReleaseError, r as defineConfig, t as runRelease } from "./release-gwyqzR0C.mjs";
 export { ReleaseError, defineConfig, loadReleaseConfig, runRelease };

package/dist/{release-CVQ5WSKG.mjs → release-gwyqzR0C.mjs}

@@ -1,4 +1,4 @@
-import { createDefineConfig, loadConfig } from "c12";
+import { createDefineConfig, loadConfig, setupDotenv } from "c12";
 import { determineSemverChange, generateMarkDown, getGitDiff, loadChangelogConfig, parseCommits, resolveRepoConfig } from "changelogen";
 import { existsSync, readFileSync } from "node:fs";
 import { readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
@@ -6,7 +6,38 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:pat
 import { createInterface } from "node:readline/promises";
 import { execFileSync, spawnSync } from "node:child_process";
 //#region src/config.ts
+/**
+* Identity helper that types a release config for your editor.
+*
+* It does not change the object at runtime — it only enables autocomplete
+* and catches typos inside `defineConfig({ … })`.
+*
+* @typeParam Config - Config object shape; defaults to {@link GenBumpPushConfig}.
+* @returns The same object you passed in.
+*
+* @example `genbumppush.config.ts`
+* ```ts
+* import { defineConfig } from 'genbumppush';
+*
+* export default defineConfig({
+*   preid: 'beta',
+*   files: ['package.json'],
+*   git: {
+*     commitMessage: 'chore(release): v{{version}}',
+*   },
+*   hooks: {
+*     before: ['npm run check', 'npm test'],
+*   },
+* });
+* ```
+*/
 const defineConfig = createDefineConfig();
+/**
+* Built-in defaults used when neither the CLI, a config file, nor
+* `package.json` sets a field.
+*
+* Useful if you want to document or assert what an empty config resolves to.
+*/
 const defaults = {
 	changelog: "CHANGELOG.md",
 	excludeDependencyCommits: true,
@@ -22,7 +53,45 @@ const defaults = {
 		tagMessage: "v{{version}}"
 	}
 };
+/**
+* Load the effective release config for a repository.
+*
+* Resolution order (later wins):
+* 1. {@link defaults}
+* 2. `"genbumppush"` key in that directory’s `package.json`
+* 3. C12 config file (`genbumppush.config.ts` / `.js`, or `configFile` when given)
+* 4. `overrides` you pass here (CLI flags in the binary go through this)
+*
+* Also loads `.env` from `cwd` into `process.env` without overwriting
+* variables that are already set. Secrets still belong in the environment —
+* not in config files.
+*
+* @param cwd - Repository root to load config from.
+* @param configFile - Optional explicit path to a C12 config file.
+* @param overrides - Highest-priority values (for example CLI flags).
+* @returns The fully merged config object.
+* @throws May reject if the config file throws or cannot be loaded.
+*
+* @example Read what a repo already configured
+* ```ts
+* import { loadReleaseConfig } from 'genbumppush';
+*
+* const config = await loadReleaseConfig(process.cwd());
+* console.log(config.git?.remote ?? 'origin');
+* ```
+*
+* @example Force a dry-run-style push disable from a script
+* ```ts
+* import { loadReleaseConfig } from 'genbumppush';
+*
+* const config = await loadReleaseConfig(process.cwd(), undefined, {
+*   git: { push: false },
+* });
+* // config.git.push === false even if the file enabled push
+* ```
+*/
 async function loadReleaseConfig(cwd, configFile, overrides) {
+	await setupDotenv({ cwd });
 	return (await loadConfig({
 		name: "genbumppush",
 		cwd,
@@ -36,8 +105,42 @@ async function loadReleaseConfig(cwd, configFile, overrides) {
 }
 //#endregion
 //#region src/error.ts
+/**
+* Error thrown by genbumppush for expected release failures.
+*
+* Unlike a generic `Error`, every {@link ReleaseError} carries a stable
+* {@link ReleaseError.code} so scripts and the CLI can branch on the reason
+* (`DIRTY_WORKTREE`, `TAG_EXISTS`, `CANCELLED`, …) without parsing messages.
+*
+* @example Branch on the failure reason
+* ```ts
+* import { runRelease, ReleaseError } from 'genbumppush';
+*
+* try {
+*   await runRelease({ cwd: process.cwd(), dryRun: false, yes: true, help: false });
+* } catch (error) {
+*   if (error instanceof ReleaseError && error.code === 'CANCELLED') {
+*     process.exit(0);
+*   }
+*   throw error;
+* }
+* ```
+*
+* @example Print code and message the same way the CLI does
+* ```ts
+* if (error instanceof ReleaseError) {
+*   console.error(`[${error.code}] ${error.message}`);
+* }
+* ```
+*/
 var ReleaseError = class extends Error {
+	/** Machine-readable reason, for example `'DIRTY_WORKTREE'` or `'TAG_EXISTS'`. */
 	code;
+	/**
+	* @param code - Stable machine-readable reason.
+	* @param message - Human-readable explanation shown to the user.
+	* @param options - Optional `cause` when wrapping an underlying error.
+	*/
 	constructor(code, message, options) {
 		super(message, options);
 		this.name = "ReleaseError";
@@ -101,6 +204,26 @@ function runHook(command, cwd) {
 	}).status !== 0) throw new ReleaseError("HOOK_FAILED", `Hook failed: ${command}`);
 }
 //#endregion
+//#region src/env.ts
+const ENV = {
+	GITHUB_TOKEN: "GENBUMPPUSH_GITHUB_TOKEN",
+	GITHUB_HOST: "GENBUMPPUSH_GITHUB_HOST",
+	GITHUB_REPOSITORY: "GENBUMPPUSH_GITHUB_REPOSITORY",
+	GITLAB_TOKEN: "GENBUMPPUSH_GITLAB_TOKEN",
+	GITLAB_HOST: "GENBUMPPUSH_GITLAB_HOST",
+	GITLAB_PROJECT: "GENBUMPPUSH_GITLAB_PROJECT"
+};
+function readEnv(name) {
+	const value = process.env[name];
+	return value !== void 0 && value.length > 0 ? value : void 0;
+}
+function readEnvFirst(...names) {
+	for (const name of names) {
+		const value = readEnv(name);
+		if (value !== void 0) return value;
+	}
+}
+//#endregion
 //#region src/github.ts
 function normalizeHost(host) {
 	return host.replace(/^https?:\/\//, "").replace(/\/$/, "");
@@ -113,23 +236,22 @@ function apiBase(host) {
 function encodeRepoPath(repo) {
 	return repo.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
+const GITHUB_TOKEN_FALLBACKS = [
+	ENV.GITHUB_TOKEN,
+	"GITHUB_TOKEN",
+	"GH_TOKEN",
+	"CHANGELOGEN_TOKENS_GITHUB"
+];
+function githubTokenEnvLabel(tokenEnv) {
+	return tokenEnv ?? `${ENV.GITHUB_TOKEN} (or GITHUB_TOKEN, GH_TOKEN, CHANGELOGEN_TOKENS_GITHUB)`;
+}
 function resolveGitHubToken(tokenEnv) {
-	if (tokenEnv !== void 0) {
-		const token = process.env[tokenEnv];
-		return token !== void 0 && token.length > 0 ? token : void 0;
-	}
-	for (const name of [
-		"GITHUB_TOKEN",
-		"GH_TOKEN",
-		"CHANGELOGEN_TOKENS_GITHUB"
-	]) {
-		const token = process.env[name];
-		if (token !== void 0 && token.length > 0) return token;
-	}
+	if (tokenEnv !== void 0) return readEnv(tokenEnv);
+	return readEnvFirst(...GITHUB_TOKEN_FALLBACKS);
 }
 async function resolveGitHubRepo(cwd, source) {
-	const host = normalizeHost(source.host ?? process.env.GITHUB_API_URL ?? "github.com");
-	const explicit = source.repo ?? process.env.GITHUB_REPOSITORY;
+	const host = normalizeHost(source.host ?? readEnv(ENV.GITHUB_HOST) ?? readEnv("GITHUB_API_URL") ?? "github.com");
+	const explicit = source.repo ?? readEnvFirst(ENV.GITHUB_REPOSITORY, "GITHUB_REPOSITORY");
 	if (explicit !== void 0 && explicit.length > 0) return {
 		host,
 		repo: explicit
@@ -139,7 +261,7 @@ async function resolveGitHubRepo(cwd, source) {
 		host: normalizeHost(resolved.domain ?? host),
 		repo: resolved.repo
 	};
-	throw new ReleaseError("GITHUB_RELEASE_FAILED", "Set github.repo or GITHUB_REPOSITORY to create a GitHub release.");
+	throw new ReleaseError("GITHUB_RELEASE_FAILED", `Set github.repo or ${ENV.GITHUB_REPOSITORY} (or GITHUB_REPOSITORY) to create a GitHub release.`);
 }
 async function githubFetch(options, path, init) {
 	const url = `${apiBase(options.host)}/repos/${encodeRepoPath(options.repo)}${path}`;
@@ -201,6 +323,20 @@ async function createGitHubRelease(options) {
 }
 //#endregion
 //#region src/gitlab.ts
+const GITLAB_TOKEN_FALLBACKS = [ENV.GITLAB_TOKEN, "GITLAB_TOKEN"];
+function gitLabTokenEnvLabel(tokenEnv) {
+	return tokenEnv ?? `${ENV.GITLAB_TOKEN} (or GITLAB_TOKEN)`;
+}
+function resolveGitLabToken(tokenEnv) {
+	if (tokenEnv !== void 0) return readEnv(tokenEnv);
+	return readEnvFirst(...GITLAB_TOKEN_FALLBACKS);
+}
+function resolveGitLabHost(host) {
+	return host ?? readEnv(ENV.GITLAB_HOST) ?? readEnv("GITLAB_HOST") ?? "https://gitlab.com";
+}
+function resolveGitLabProject(project) {
+	return project ?? readEnvFirst(ENV.GITLAB_PROJECT, "GITLAB_PROJECT");
+}
 function releaseNotes(changelog, tag) {
 	const lines = changelog.split("\n");
 	const heading = `## ${tag}`;
@@ -620,13 +756,12 @@ function isString(value) {
 }
 function gitLabContext(config) {
 	if (config?.enabled !== true) throw new ReleaseError("GITLAB_RELEASE_FAILED", "Enable gitlab before creating a release.");
-	const tokenEnv = config.tokenEnv ?? "GITLAB_TOKEN";
-	const token = process.env[tokenEnv];
-	const project = config.project ?? process.env.GITLAB_PROJECT;
-	if (token === void 0 || token.length === 0) throw new ReleaseError("GITLAB_RELEASE_FAILED", `Set ${tokenEnv} to create a GitLab release.`);
-	if (project === void 0 || project.length === 0) throw new ReleaseError("GITLAB_RELEASE_FAILED", "Set gitlab.project or GITLAB_PROJECT to create a GitLab release.");
+	const token = resolveGitLabToken(config.tokenEnv);
+	const project = resolveGitLabProject(config.project);
+	if (token === void 0) throw new ReleaseError("GITLAB_RELEASE_FAILED", `Set ${gitLabTokenEnvLabel(config.tokenEnv)} to create a GitLab release.`);
+	if (project === void 0) throw new ReleaseError("GITLAB_RELEASE_FAILED", "Set gitlab.project or GENBUMPPUSH_GITLAB_PROJECT (or GITLAB_PROJECT) to create a GitLab release.");
 	const context = {
-		host: config.host ?? process.env.GITLAB_HOST ?? "https://gitlab.com",
+		host: resolveGitLabHost(config.host),
 		project,
 		token
 	};
@@ -636,7 +771,7 @@ function gitLabContext(config) {
 function resolveGitHubContext(config, cwd) {
 	if (config?.enabled !== true) throw new ReleaseError("GITHUB_RELEASE_FAILED", "Enable github before creating a release.");
 	const token = resolveGitHubToken(config.tokenEnv);
-	if (token === void 0) throw new ReleaseError("GITHUB_RELEASE_FAILED", `Set ${config.tokenEnv ?? "GITHUB_TOKEN"} to create a GitHub release.`);
+	if (token === void 0) throw new ReleaseError("GITHUB_RELEASE_FAILED", `Set ${githubTokenEnvLabel(config.tokenEnv)} to create a GitHub release.`);
 	return resolveGitHubRepo(cwd, {
 		host: config.host,
 		repo: config.repo
@@ -714,6 +849,82 @@ function packageVersion(cwd) {
 	if (!isObject(data) || !("version" in data) || !isString(data.version)) throw new ReleaseError("INVALID_PACKAGE", "package.json must contain a version string.");
 	return data.version;
 }
+/**
+* Run a full release (or a dry run / provider retry) for one repository.
+*
+* Typical flow:
+* 1. Load config and `.env`
+* 2. Verify the worktree is a clean Git repo on a branch
+* 3. Detect (or force) a release type from Conventional Commits
+* 4. Confirm, run `before` hooks, update version files and the changelog
+* 5. Commit, tag, and atomically push branch + tag
+* 6. Optionally create a GitHub/GitLab release, then run `after` hooks
+*
+* Version-file or commit failures restore files and the index. A failed tag
+* or network push can leave the release commit locally so you can inspect
+* and retry — see the returned {@link ReleaseResult} and any thrown
+* {@link ReleaseError}.
+*
+* Prefer the `genbumppush` CLI for day-to-day use. Call this directly when
+* embedding releases in a Node script or CI job that already builds
+* {@link CliOptions}.
+*
+* @param options - Parsed CLI options. `cwd`, `dryRun`, `yes`, and `help` are required;
+*   the rest override config when set.
+* @returns A summary of what happened. Never mutates when `dryRun` is `true`.
+* @throws {@link ReleaseError} for expected failures (dirty worktree, existing tag,
+*   cancelled confirmation, Git/provider errors). Unexpected errors may also throw.
+*
+* @example Dry run in the current directory
+* ```ts
+* import { runRelease } from 'genbumppush';
+*
+* const result = await runRelease({
+*   cwd: process.cwd(),
+*   dryRun: true,
+*   yes: true,
+*   help: false,
+* });
+*
+* console.log(result);
+* // {
+* //   currentVersion: '1.2.3',
+* //   newVersion: '1.3.0',
+* //   releaseType: 'minor',
+* //   tag: 'v1.3.0',
+* //   pushed: false,
+* //   dryRun: true,
+* //   commitCount: 4
+* // }
+* ```
+*
+* @example Non-interactive patch release that stays local
+* ```ts
+* import { runRelease } from 'genbumppush';
+*
+* await runRelease({
+*   cwd: process.cwd(),
+*   dryRun: false,
+*   yes: true,
+*   help: false,
+*   release: 'patch',
+*   push: false,
+* });
+* ```
+*
+* @example Retry only the GitLab release after Git already succeeded
+* ```ts
+* import { runRelease } from 'genbumppush';
+*
+* await runRelease({
+*   cwd: process.cwd(),
+*   dryRun: false,
+*   yes: true,
+*   help: false,
+*   gitlabRetryTag: 'v1.3.0',
+* });
+* ```
+*/
 async function runRelease(options) {
 	const overrides = {};
 	if (options.release !== void 0) overrides.release = options.release;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genbumppush",
   "description": "Generate changelog, bump version, then push",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",