rman 1.0.8 → 1.0.10

package/README.md

@@ -91,7 +91,7 @@ worked examples of every single command, see **[docs/cli.md](docs/cli.md)**.
 | [`diff [package]`](#rman-diff-package) | Shows the git diff since a package's (or the repo's) last release tag. |
 | [`changelog`](#rman-changelog) | Generates a changelog per package from unreleased commits. |
 | [`version [bump]`](#rman-version-bump) | Bumps versions of changed packages (and their dependents). |
-| [`publish`](#rman-publish) | Publishes every package to its configured target(s) - npm and/or Docker. |
+| [`publish`](#rman-publish) | Publishes every package to its configured target(s) - npm, Docker and/or GitHub Releases. |
 | [`import <path>`](#rman-import-path) | Imports an external git repository as a new package, with history. |
 
 Options shared across several commands:
@@ -222,7 +222,7 @@ Generates a changelog per package from unreleased commits, grouped into ✨ Feat
 / 🔧 Other Changes.
 
 ```bash
-rman changelog                          # auto-detects each package's last published npm version
+rman changelog                          # auto-detects each package's own last release
 rman changelog --from a1b2c3d           # since a specific commit, for every package
 rman changelog --write                  # prepend into each package's own CHANGELOG.md
 rman changelog --write --file-path docs/CHANGELOG.md
@@ -265,8 +265,10 @@ algorithm, prerelease semantics, and `"workspace:"` dependency-range handling.
 
 ### `rman publish`
 
-Publishes every package to its configured target(s) - `npm` by default, or whatever each package's
-own `.rmanrc "publish.target"` says (`"npm"`, `"docker"`, or both).
+Publishes every package to its configured registry - `npm` by default, or whatever each package's
+own `.rmanrc "publish.target"` says (`"npm"`, `"docker"`, or both). Each target decides for itself
+whether the current version is already out there: `npm view` on the npm side, `docker manifest
+inspect` on the docker side.
 
 ```bash
 rman publish                              # show the plan, then ask for confirmation
@@ -288,6 +290,20 @@ A package opts into building/pushing a Docker image via `.rmanrc "publish.target
 a `"publish.docker"` block (`image`, `platforms`, `buildContexts`, `buildArgs`, ...) - see
 [docs/cli/publish.md#docker-publishing-publishdocker](docs/cli/publish.md#docker-publishing-publishdocker).
 
+### `rman github-release`
+
+Creates the repository's GitHub Release for the version that just shipped - one per run, named after
+the repository's own release tag, with notes covering every package that shipped under it.
+
+```bash
+rman github-release --yes
+```
+
+It is deliberately neither a `publish.target` nor opt-in: a release isn't a registry a package ships
+to, it's the repository's own record that a version shipped, and every repository wants that record.
+It needs no configuration at all - see
+[docs/cli/github-release.md](docs/cli/github-release.md).
+
 ### `rman import <path>`
 
 Imports an external git repository as a new package, preserving its **entire commit history**

package/cli.js

@@ -11,6 +11,7 @@ import * as ciCommand from './commands/ci.command.js';
 import * as cleanCommand from './commands/clean.command.js';
 import * as diffCommand from './commands/diff.command.js';
 import * as execCommand from './commands/exec.command.js';
+import * as githubReleaseCommand from './commands/github-release.command.js';
 import * as importCommand from './commands/import.command.js';
 import * as infoCommand from './commands/info.command.js';
 import * as listCommand from './commands/list.command.js';
@@ -61,6 +62,7 @@ export async function runCli(options) {
         testCommand.initCli(repository, program);
         versionCommand.initCli(repository, program);
         publishCommand.initCli(repository, program);
+        githubReleaseCommand.initCli(repository, program);
         execCommand.initCli(repository, program);
         changedCommand.initCli(repository, program);
         diffCommand.initCli(repository, program);

package/commands/changelog.command.js

@@ -7,12 +7,13 @@ export function initCli(repository, program) {
         command: 'changelog',
         describe: 'Generates a changelog per package from unreleased commits',
         builder: cmd => applyPackageFilterOptions(cmd)
-            .example('$0 changelog', "# Auto-detects each package's last published version on npm")
+            .example('$0 changelog', "# Auto-detects each package's own last release tag (or npm version)")
             .example('$0 changelog --from <hash> --write', '# Since a specific commit, written to file')
             .option('from', {
             describe: 'Generate the changelog since this commit/hash, applied the same way to every package. ' +
-                'Default (also "npm" explicitly): auto-detect per package from its published npm version, ' +
-                "falling back to not-yet-pushed commits for a package that can't be resolved this way",
+                'Default (also "npm" explicitly): auto-detect per package from its own most recent release ' +
+                'tag - same as "version"/"changed" - falling back to its published npm version (no tag yet), ' +
+                "then to its whole history for a package that's never been released at all",
             type: 'string',
         })
             .option('write', {
@@ -33,15 +34,23 @@ export function initCli(repository, program) {
             .option('include-skipped', {
             describe: 'Also generate for a package with .rmanrc "publish.skip" - excluded by default',
             type: 'boolean',
+        })
+            .option('release-version', {
+            describe: 'The version these notes are for - what the entry heading shows. Default: read back from ' +
+                "each package's own latest release tag, which is only right once that release is tagged. " +
+                'Pass it when generating notes ahead of the bump (e.g. from "changed --json" in CI), ' +
+                'otherwise the heading shows the previous release.',
+            type: 'string',
         }),
         handler: async (args) => {
             const from = args.from;
             const write = args.write;
             const logger = new Logger(args.logLevel ?? resolveRootLogLevel(repository));
             if (!from || from === 'npm') {
-                // A network round trip per package, even run concurrently, can still take a visible
-                // moment - without this, the command looks hung for that stretch instead of just busy.
-                logger.info(colors.gray('Checking published npm versions...'));
+                // Auto-detection is mostly local git work, but the npm fallback it can reach for (only
+                // when a package has no tag at all) is a network round trip per package - without this,
+                // the command looks hung for that stretch instead of just busy.
+                logger.info(colors.gray("Detecting each package's last release..."));
             }
             const options = {
                 ...readPackageFilterOptions(args),
@@ -49,6 +58,7 @@ export function initCli(repository, program) {
                 filePath: args.filePath,
                 root: args.root,
                 includeSkipped: args.includeSkipped,
+                version: args.releaseVersion,
             };
             const entries = args.write
                 ? await ChangelogService.generateToFile(repository, options)

package/commands/github-release.command.d.ts

@@ -0,0 +1,3 @@
+import type { Argv } from 'yargs';
+import type { Repository } from '../core/repository.js';
+export declare function initCli(repository: Repository, program: Argv): void;

package/commands/github-release.command.js

@@ -0,0 +1,119 @@
+import readline from 'node:readline/promises';
+import colors from 'ansi-colors';
+import { GithubReleaseService } from '../services/github-release.service.js';
+import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
+export function initCli(repository, program) {
+    program.command({
+        command: 'github-release',
+        describe: "Creates the repository's GitHub Release for the version that just shipped",
+        builder: cmd => applyBranchGuardOptions(cmd)
+            .example('$0 github-release', '# Show what would be released, then ask for confirmation')
+            .example('$0 github-release --yes', '# Create it immediately, no confirmation (CI)')
+            .example('$0 github-release --dry-run', '# Only show the plan')
+            .option('yes', {
+            alias: 'y',
+            describe: 'Skip the confirmation prompt and create the release immediately',
+            type: 'boolean',
+        })
+            .option('dry-run', {
+            describe: 'Only show the plan - never creates anything, regardless of --yes',
+            type: 'boolean',
+        })
+            .option('json', {
+            alias: 'j',
+            describe: 'Print the plan as JSON instead of text',
+            type: 'boolean',
+        })
+            .option('repository', {
+            describe: 'The "owner/repo" the release is created in - default: .rmanrc "githubRelease.repository", ' +
+                'falling back to the "origin" remote.',
+            type: 'string',
+        })
+            .option('ignore-dirty', {
+            describe: 'Release anyway when the working tree has uncommitted changes, instead of aborting',
+            type: 'boolean',
+        }),
+        handler: async (args) => {
+            await assertAllowedBranch(repository, readBranchGuardOptions(args));
+            // No package filtering: a release belongs to the repository, not to a package, so there is
+            // nothing for --scope/--ignore to narrow down.
+            const plan = await GithubReleaseService.getPlan(repository, {
+                ignoreDirty: args.ignoreDirty,
+                repository: args.repository,
+            });
+            if (args.json) {
+                console.log(JSON.stringify(plan.map(e => ({
+                    tag: e.tag,
+                    repository: e.repository,
+                    status: e.status,
+                    version: e.version,
+                    reason: e.reason,
+                })), undefined, 2));
+            }
+            else {
+                for (const e of plan) {
+                    const name = colors.cyan(e.tag ?? e.version);
+                    switch (e.status) {
+                        case 'publish':
+                            console.log(colors.green('release'), name, colors.gray(`${e.repository} - ${e.reason ?? ''}`));
+                            break;
+                        case 'up-to-date':
+                            console.log(colors.gray('up-to-date'), name, colors.gray(e.reason ?? ''));
+                            break;
+                        case 'skip':
+                            console.log(colors.cyan('skip'), name, colors.gray(e.reason ?? ''));
+                            break;
+                        case 'error':
+                            console.log(colors.red('error'), name, colors.red(e.reason ?? ''));
+                            break;
+                    }
+                }
+            }
+            const error = plan.find(e => e.status === 'error');
+            if (error) {
+                const err = new Error(error.reason ?? 'Unable to prepare the GitHub Release');
+                err.logged = true;
+                throw err;
+            }
+            if (!plan.some(e => e.status === 'publish')) {
+                if (!args.json)
+                    console.log(colors.gray('Nothing to release.'));
+                return;
+            }
+            if (args.dryRun)
+                return;
+            let proceed = !!args.yes;
+            if (!proceed) {
+                if (!process.stdout.isTTY) {
+                    console.log(colors.gray('Not a TTY - refusing to prompt. Pass --yes to release non-interactively.'));
+                    return;
+                }
+                proceed = await confirm('Create this release?');
+            }
+            if (!proceed)
+                return;
+            const applied = await GithubReleaseService.applyPlan(repository, plan);
+            const failed = applied.find(e => e.status === 'error');
+            if (failed) {
+                console.log(colors.red('failed'), colors.cyan(failed.tag ?? ''), colors.red(failed.reason ?? ''));
+                const err = new Error('"github-release" failed');
+                err.logged = true;
+                throw err;
+            }
+            for (const e of applied) {
+                if (e.status === 'publish')
+                    console.log(colors.green('released'), colors.cyan(e.tag ?? ''));
+            }
+        },
+    });
+}
+async function confirm(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(`${question} (y/N) `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}

package/commands/publish.command.js

@@ -22,6 +22,12 @@ export function initCli(repository, program) {
             .option('dry-run', {
             describe: 'Only show the plan - never publishes, regardless of --yes',
             type: 'boolean',
+        })
+            .option('json', {
+            alias: 'j',
+            describe: 'Print the plan as JSON instead of text - one entry per package and target. Combine with ' +
+                '--dry-run to ask "is there anything to publish?" without publishing (e.g. a CI release gate).',
+            type: 'boolean',
         })
             .option('target', {
             describe: 'Restrict this run to just these publish target(s) ("npm"/"docker", repeatable) - default: ' +
@@ -72,7 +78,8 @@ export function initCli(repository, program) {
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
             const targets = resolveTargets(args.target);
-            const explicitDockerTarget = !!args.target?.length && targets.has('docker');
+            const explicitTargets = !!args.target?.length;
+            const explicitDockerTarget = explicitTargets && targets.has('docker');
             const ignoreDirty = args.ignoreDirty;
             const npmOptions = {
                 ...readPackageFilterOptions(args),
@@ -87,8 +94,13 @@ export function initCli(repository, program) {
             };
             const npmPlan = targets.has('npm') ? await PublishService.getPlan(repository, npmOptions) : [];
             const dockerPlan = targets.has('docker') ? await DockerPublishService.getPlan(repository, dockerOptions) : [];
-            printPlan(npmPlan);
-            printPlan(dockerPlan, 'docker');
+            if (args.json) {
+                console.log(JSON.stringify([...npmPlan.map(e => jsonEntry(e, 'npm')), ...dockerPlan.map(e => jsonEntry(e, 'docker'))], undefined, 2));
+            }
+            else {
+                printPlan(npmPlan);
+                printPlan(dockerPlan, 'docker');
+            }
             if (explicitDockerTarget && !dockerPlan.length) {
                 const message = '--target docker was given, but no package\'s .rmanrc configures "publish.docker".';
                 console.log(colors.red(message));
@@ -108,8 +120,9 @@ export function initCli(repository, program) {
                 err.logged = true;
                 throw err;
             }
-            if (!npmPlan.some(e => e.status === 'publish') && !dockerPlan.some(e => e.status === 'publish')) {
-                console.log(colors.gray('Nothing to publish.'));
+            if (![...npmPlan, ...dockerPlan].some(e => e.status === 'publish')) {
+                if (!args.json)
+                    console.log(colors.gray('Nothing to publish.'));
                 return;
             }
             if (args.dryRun)
@@ -168,6 +181,17 @@ function resolveTargets(input) {
         return new Set(['npm', 'docker']);
     return new Set(input);
 }
+/** One `--json` row. `target` is what distinguishes otherwise-identical rows for a package that
+ *  ships to several targets at once, so a consumer can tell which one still needs publishing. */
+function jsonEntry(entry, target) {
+    return {
+        name: entry.package.name,
+        target,
+        status: entry.status,
+        version: entry.version,
+        reason: entry.reason,
+    };
+}
 function printPlan(entries, label) {
     const prefix = label ? colors.gray(`[${label}] `) : '';
     for (const e of entries) {

package/commands/version.command.js

@@ -54,7 +54,8 @@ export function initCli(repository, program) {
         })
             .option('changelog', {
             describe: "Also write each bumped package's CHANGELOG.md (same as running changelog --write " +
-                'separately) and fold it into the same commit as its version bump',
+                'separately) and fold it into the same commit as its version bump. Default: .rmanrc ' +
+                '"version.changelog", or false - --no-changelog forces it off even when that\'s true.',
             type: 'boolean',
         })
             .option('preid', {
@@ -100,10 +101,11 @@ export function initCli(repository, program) {
             }
             if (!apply)
                 return;
+            const changelog = args.changelog ?? repository.config?.version?.changelog ?? false;
             const applied = await VersionService.applyPlan(repository, plan, {
                 push: args.push,
                 message: args.message,
-                changelog: args.changelog,
+                changelog,
             });
             for (const entry of applied) {
                 if (entry.status === 'bump') {

package/constants.js

@@ -1 +1 @@
-export const version = '1.0.8';
+export const version = '1.0.10';

package/core/config.d.ts

@@ -1,102 +1,4 @@
-/**
- * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
- * `"rman"` key) - see docs/api.md#configuration-rmanrc-rmanrcyml for the full reference. Every
- * field is optional and cascades from the repository root down to each package's own directory.
- * Purely a typing aid (used by `defineConfig` below, and importable on its own for a `.rmanrc.ts`/
- * `.mts` authored config, or a plain `: RmanConfig` annotation) - never read by rman itself, which
- * only ever sees the plain JS object a JS config file exports.
- */
-export interface RmanConfig {
-    packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
-    logLevel?: 'silent' | 'error' | 'info' | 'verbose';
-    allowBranch?: string | string[];
-    ignoreBranch?: string | string[];
-    group?: boolean | string;
-    version?: RmanConfig.VersionOptions;
-    changelog?: RmanConfig.ChangelogOptions;
-    clean?: RmanConfig.CleanOptions;
-    publish?: RmanConfig.PublishOptions;
-    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). */
-    run?: Record<string, RmanConfig.RunScriptOptions>;
-    /** Keyed by the in-repo package's own name. */
-    packages?: Record<string, RmanConfig.PackageOptions>;
-}
-export declare namespace RmanConfig {
-    interface VersionOptions {
-        commitMessage?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
-    }
-    interface ChangelogOptions {
-        ignoreTypes?: string[];
-        template?: string;
-        filePath?: string;
-        tagPattern?: string;
-    }
-    interface CleanOptions {
-        include?: string | string[];
-        exclude?: string | string[];
-        skip?: boolean;
-    }
-    interface RunScriptOptions {
-        concurrency?: number;
-        topo?: boolean;
-        bail?: boolean;
-        progress?: boolean;
-        logLevel?: 'silent' | 'error' | 'info' | 'verbose';
-        changedSince?: string;
-        skip?: boolean;
-        if?: string;
-        script?: string | string[];
-        preScript?: string | string[];
-        postScript?: string | string[];
-        override?: boolean;
-    }
-    interface PackageOptions {
-        dependencies?: string[] | Record<string, string>;
-    }
-    interface PublishOptions {
-        /** Which registries `publish` should target for this package - default `['npm']` (every
-         *  existing repo keeps working unchanged). A package that only ever wants Docker images
-         *  (typically also `"private": true`, since it's not meant for npm at all) sets `['docker']`;
-         *  one that publishes both sets `['npm', 'docker']`. */
-        target?: PublishTarget | PublishTarget[];
-        docker?: DockerPublishOptions;
-        /** Excludes this package from `publish` entirely (npm and docker both), regardless of
-         *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package
-         *  released through some separate, unrelated process. `changelog` also skips it by default
-         *  (see its own `--include-skipped`) - there's little point changelogging something that's
-         *  never actually released. Independent of `version`, which never consults this at all - a
-         *  package can still be meaningfully versioned without ever being published. */
-        skip?: boolean;
-    }
-    type PublishTarget = 'npm' | 'docker';
-    /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
-     *  docker` errors clearly on a package that opts in here but leaves this out. */
-    interface DockerPublishOptions {
-        /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
-         *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
-         *  verbatim. */
-        image: string;
-        /** Relative to the package's own directory. Default `"Dockerfile"`. */
-        dockerfile?: string;
-        /** Default `["linux/amd64"]`. */
-        platforms?: string[];
-        /** Build `cwd` override, relative to the repository root - only needed when the Dockerfile's
-         *  own `COPY`/`ADD` paths expect something other than the package's own directory (rare). */
-        cwd?: string;
-        /** Named `docker buildx build --build-context <name>=<path>` entries, keyed by name - each
-         *  path is relative to the package's own directory (or absolute). */
-        buildContexts?: Record<string, string>;
-        /** `docker buildx build --build-arg <name>=<value>` entries - a value of exactly `"$NAME"`
-         *  expands to `process.env.NAME` at build time (e.g. to pass a CI secret through). */
-        buildArgs?: Record<string, string>;
-        /** A file (relative to the package's own directory) whose contents become the DockerHub repo's
-         *  full description, if present. Default `"DOCKER_README.md"`. */
-        readme?: string;
-    }
-}
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 /**
  * Identity helper for authoring a `.rmanrc.cjs`/`.mjs`/`.js` config with full type-checking and
  * autocomplete - the same `defineConfig` pattern Vite/Vitest use. Returns `config` completely

package/core/package.d.ts

@@ -1,4 +1,4 @@
-import type { RmanConfig } from './config.js';
+import type { RmanConfig } from '../interfaces/rman-config.interface.js';
 export declare class Package {
     readonly dirname: string;
     private _json;

package/index.d.ts

@@ -8,10 +8,10 @@
  * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
  * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
  */
-export type { RmanConfig } from './core/config.js';
 export { defineConfig } from './core/config.js';
 export { Package } from './core/package.js';
 export { Repository } from './core/repository.js';
+export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
 export type { DetectChangeHashOptions } from './utils/change-hash.js';
 export { detectChangeHash } from './utils/change-hash.js';

package/index.js

@@ -1,6 +1,17 @@
+/**
+ * Programmatic API - the same logic the CLI commands run, importable directly without going
+ * through yargs/argv. Each domain's logic lives in a `<Name>` namespace under `./services/*.ts`
+ * (e.g. `ChangelogService`, `CiService`, `CleanService`, `ListService`, `RunService`,
+ * `SystemInfo`, `VersionService`), re-exported here via `./services.js`. Purpose-specific functions, not one
+ * generic `run`/`get` per domain (see e.g. `SystemInfo.getSystemInfo`/`getRepositoryInfo`, kept
+ * separate since they're genuinely independent capabilities, not just steps of one operation) -
+ * CLI-only concerns (argv parsing, `--help` text, and all console/file presentation) stay in
+ * `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
+ */
 export { defineConfig } from './core/config.js';
 export { Package } from './core/package.js';
 export { Repository } from './core/repository.js';
+export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
 export { detectChangeHash } from './utils/change-hash.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';

package/interfaces/rman-config.interface.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The shape of `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` (and `package.json`'s own
+ * `"rman"` key) - see docs/api.md#configuration-rmanrc-rmanrcyml for the full reference. Every
+ * field is optional and cascades from the repository root down to each package's own directory.
+ * Purely a typing aid (used by `defineConfig` below, and importable on its own for a `.rmanrc.ts`/
+ * `.mts` authored config, or a plain `: RmanConfig` annotation) - never read by rman itself, which
+ * only ever sees the plain JS object a JS config file exports.
+ */
+export interface RmanConfig {
+    packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
+    logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+    allowBranch?: string | string[];
+    ignoreBranch?: string | string[];
+    group?: boolean | string;
+    version?: RmanConfig.VersionOptions;
+    changelog?: RmanConfig.ChangelogOptions;
+    clean?: RmanConfig.CleanOptions;
+    publish?: RmanConfig.PublishOptions;
+    githubRelease?: RmanConfig.GithubReleaseOptions;
+    /** Keyed by npm script name (e.g. `"build"`, `"lint"`, `"test"`). */
+    run?: Record<string, RmanConfig.RunScriptOptions>;
+    /** Keyed by the in-repo package's own name. */
+    packages?: Record<string, RmanConfig.PackageOptions>;
+}
+export declare namespace RmanConfig {
+    interface VersionOptions {
+        commitMessage?: string;
+        /** Default for `version --changelog` when the CLI flag isn't given - a standing "always fold
+         *  the changelog into the version-bump commit" policy, rather than something that behaves
+         *  differently on the one run someone forgets to pass `--changelog`. An explicit `--changelog`/
+         *  `--no-changelog` on the command line still wins either way. Root-level only. Default `false`. */
+        changelog?: boolean;
+        /** Tag naming the repository's own release, as opposed to the per-package/group tags
+         *  `changelog.tagPattern` names - only created when the root is on a calendar version (a repo
+         *  with more than one version line). Root-level only. Default `"release-*"`. Must **not** match
+         *  any package's own `changelog.tagPattern`, or that package's changelog boundary will resolve
+         *  to the repository release instead of its own last release. */
+        releaseTagPattern?: string;
+        script?: string | string[];
+        preScript?: string | string[];
+        postScript?: string | string[];
+    }
+    interface ChangelogOptions {
+        ignoreTypes?: string[];
+        template?: string;
+        filePath?: string;
+        tagPattern?: string;
+    }
+    interface CleanOptions {
+        include?: string | string[];
+        exclude?: string | string[];
+        skip?: boolean;
+    }
+    interface RunScriptOptions {
+        concurrency?: number;
+        topo?: boolean;
+        bail?: boolean;
+        progress?: boolean;
+        logLevel?: 'silent' | 'error' | 'info' | 'verbose';
+        changedSince?: string;
+        skip?: boolean;
+        if?: string;
+        script?: string | string[];
+        preScript?: string | string[];
+        postScript?: string | string[];
+        override?: boolean;
+    }
+    interface PackageOptions {
+        dependencies?: string[] | Record<string, string>;
+    }
+    interface PublishOptions {
+        /** Which **registry** `publish` ships this package to - default `['npm']` (every existing repo
+         *  keeps working unchanged). A package that only ever wants Docker images (typically also
+         *  `"private": true`, since it's not meant for npm at all) sets `['docker']`; both works too.
+         *  Each target answers "is this version already out there?" against its own registry, so a
+         *  package is never left without one: npm via `npm view`, docker via `docker manifest inspect`.
+         *
+         *  Note this is strictly about *package distribution*. The repository's GitHub Release is not
+         *  a target here - it isn't a place a package ships to, it's the repository's own record that
+         *  a release happened, and it is never opted into: see `githubRelease` and the
+         *  `github-release` command. */
+        target?: PublishTarget | PublishTarget[];
+        docker?: DockerPublishOptions;
+        /** Excludes this package from `publish` entirely (every target), regardless of
+         *  `target`/`"private"` - a single, explicit "never published" statement, e.g. for a package
+         *  released through some separate, unrelated process. `changelog` also skips it by default
+         *  (see its own `--include-skipped`) - there's little point changelogging something that's
+         *  never actually released. Independent of `version`, which never consults this at all - a
+         *  package can still be meaningfully versioned without ever being published. */
+        skip?: boolean;
+    }
+    type PublishTarget = 'npm' | 'docker';
+    /** Required once `"docker"` is one of this package's `publish.target`s - `publish --target
+     *  docker` errors clearly on a package that opts in here but leaves this out. */
+    interface DockerPublishOptions {
+        /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
+         *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
+         *  verbatim. */
+        image: string;
+        /** Relative to the package's own directory. Default `"Dockerfile"`. */
+        dockerfile?: string;
+        /** Default `["linux/amd64"]`. */
+        platforms?: string[];
+        /** Build `cwd` override, relative to the repository root - only needed when the Dockerfile's
+         *  own `COPY`/`ADD` paths expect something other than the package's own directory (rare). */
+        cwd?: string;
+        /** Named `docker buildx build --build-context <name>=<path>` entries, keyed by name - each
+         *  path is relative to the package's own directory (or absolute). */
+        buildContexts?: Record<string, string>;
+        /** `docker buildx build --build-arg <name>=<value>` entries - a value of exactly `"$NAME"`
+         *  expands to `process.env.NAME` at build time (e.g. to pass a CI secret through). */
+        buildArgs?: Record<string, string>;
+        /** A file (relative to the package's own directory) whose contents become the DockerHub repo's
+         *  full description, if present. Default `"DOCKER_README.md"`. */
+        readme?: string;
+    }
+    /** Entirely optional - `github-release` needs no configuration at all, since every required fact
+     *  (which tag, which repository, what the notes say) already has a sensible source. Nothing here
+     *  decides *whether* a release is cut: a release records that the repository shipped, so it is
+     *  always cut, and these are only details about how. */
+    interface GithubReleaseOptions {
+        /** Files to attach to the release, as glob patterns relative to the package's own directory
+         *  (e.g. `["dist/*.tar.gz"]`). Read from **every** package, since one release covers the whole
+         *  source tree. A release with no assets at all is still perfectly valid - it records that the
+         *  version shipped, which is all a deploy-elsewhere package needs. */
+        assets?: string[];
+        /** `owner/repo`. Default: parsed from the `origin` remote's URL. Root-level only. */
+        repository?: string;
+        /** Create the release as an unpublished draft. Default `false`. Root-level only. */
+        draft?: boolean;
+        /** Default: whether the version being released is itself a semver prerelease (`1.3.0-beta.0`).
+         *  Root-level only. */
+        prerelease?: boolean;
+    }
+}

package/interfaces/rman-config.interface.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {