rman 1.3.0 → 2.0.0-beta.2

package/commands/exec.command.js

@@ -1,67 +1,68 @@
-import { ExecService } from '../services/exec.service.js';
-import { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
-import { applyPackageFilterOptions, applyRootOption, readPackageFilterOptions } from '../utils/package-filter.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'exec [command..]',
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { assertAllowedBranch, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { readPackageFilterOptions } from '../utils/package-filter.js';
+import { runOptions } from '../utils/run-options.js';
+const COMMAND = 'exec [command..]';
+/**
+ * `runOptions` with three texts replaced - the override case the spread order exists for.
+ *
+ * `exec` takes the same scheduling flags as `run`, but not the same *explanations*: `run`'s mention
+ * `.rmanrc run.<script>.bail` and friends, and `exec` runs no script, so there is no such block to
+ * point at. The declarations are shared; only the sentences that would be untrue differ.
+ */
+const config = {
+    ...runOptions,
+    bail: { target: 'cli', describe: 'Stop on first failure (default: true)', type: 'boolean' },
+    topo: {
+        target: 'cli',
+        describe: 'Respect package dependency order: a package waits for its dependencies and is skipped if one ' +
+            'fails. Set false to run in every matching package independently, alphabetically. Default: true.',
+        type: 'boolean',
+    },
+    progress: {
+        target: 'cli',
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
+        type: 'boolean',
+    },
+};
+const execCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: 'Runs an arbitrary shell command in each package - unlike run, not tied to any npm script',
-        builder: cmd => applyRootOption(applyBranchGuardOptions(applyPackageFilterOptions(cmd)), 'Run')
-            .parserConfiguration({ 'populate--': true, 'unknown-options-as-args': true })
-            .example('$0 exec rm -rf dist', '# Not an npm script - runs directly in every package')
-            .example('$0 exec --scope pkg-a -- ls -la', '# "--" needed only if the command shares a flag name with exec\'s own')
-            .positional('command', {
-            describe: "The command (and its own arguments) to run in each package - its own flags don't need to be " +
-                'escaped unless one happens to share a name with one of these options below, in which case put ' +
-                '"--" first',
-            type: 'string',
-        })
-            .option('parallel', {
-            describe: 'Max packages at once: omit/true for CPU count, a number for that many, false to run serially. ' +
-                'Packages always run in dependency order unless --no-topo.',
-            coerce: (v) => {
-                if (v === undefined)
-                    return undefined;
-                if (v === 'false' || v === false)
-                    return false;
-                if (v === 'true' || v === true)
-                    return true;
-                const n = Number(v);
-                return Number.isFinite(n) ? n : true;
+        /**
+         * The two parser switches this command cannot work without: `populate--` keeps everything after
+         * `--` out of `exec`'s own options, and `unknown-options-as-args` passes the flags of the command
+         * being run through untouched.
+         */
+        parserConfiguration: { 'populate--': true, 'unknown-options-as-args': true },
+        config,
+        positionals: {
+            command: {
+                describe: "The command (and its own arguments) to run in each package - its own flags don't need to be " +
+                    'escaped unless one happens to share a name with one of these options below, in which case put ' +
+                    '"--" first',
+                type: 'string',
             },
-        })
-            .option('bail', {
-            describe: 'Stop on first failure (default: true)',
-            type: 'boolean',
-        })
-            .option('topo', {
-            describe: 'Respect package dependency order: a package waits for its dependencies and is skipped if one ' +
-                'fails. Set false to run in every matching package independently, alphabetically. Default: true.',
-            type: 'boolean',
-        })
-            .option('progress', {
-            describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
-            type: 'boolean',
-        })
-            .option('changed', {
-            alias: 'c',
-            describe: 'Only run in packages that have changed since the last publish',
-            type: 'boolean',
-        })
-            .option('changed-since', {
-            describe: 'Only run in packages that have changed since the given git commit/hash',
-            type: 'string',
-        })
-            .conflicts('changed', 'changed-since'),
+        },
+        examples: [
+            { command: '$0 exec rm -rf dist', description: '# Not an npm script - runs directly in every package' },
+            {
+                command: '$0 exec --scope pkg-a -- ls -la',
+                description: '# "--" needed only if the command shares a flag name with exec\'s own',
+            },
+        ],
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
             const afterDashDash = args['--'];
-            const tokens = afterDashDash?.length ? afterDashDash : args.command;
+            /** `command` is variadic (`[command..]`), so it arrives as a list - `ArgsOf` reads that off the
+             *  command string rather than being told. */
+            const tokens = afterDashDash?.length ? afterDashDash.map(String) : args.command;
             if (!tokens?.length) {
                 const err = new Error('No command given - e.g. "rman exec ls" or "rman exec -- eslint --bail"');
                 throw err;
             }
-            const command = tokens.join(' ');
-            await ExecService.exec(repository, command, {
+            await app.getService('exec').exec(tokens.join(' '), {
                 ...readPackageFilterOptions(args),
                 parallel: args.parallel,
                 topo: args.topo,
@@ -70,8 +71,9 @@ export function initCli(repository, program) {
                 changed: args.changed,
                 changedSince: args.changedSince,
                 logLevel: args.logLevel,
-                root: args.root,
+                fromRoot: args.fromRoot,
             });
         },
-    });
-}
+    };
+});
+export default execCommand;

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

@@ -1,3 +1,154 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "github-release";
+declare const config: {
+    yes: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    dryRun: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "boolean";
+    };
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    ignoreDirty: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "boolean";
+    };
+    repository: {
+        target: "both";
+        describe: string;
+        type: "string";
+    };
+    /** Config-only: details of the release, with no reason to be a flag. `target: 'config'` is what
+     *  says so, and it is the whole point of the field - a key can exist in `.rmanrc` without
+     *  existing on the command line. */
+    draft: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
+    prerelease: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
+    assets: {
+        target: "config";
+        describe: string;
+        /** `type: 'string'` plus `array: true`, not `type: 'array'`: the latter loses the element type
+         *  and the contribution would read `unknown[]`. This is what keeps `assets` a `string[]` and is
+         *  why the key needs no `Extra`. */
+        type: "string";
+        array: true;
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const githubReleaseCommand: (app: import("../index.js").RmanApplication) => {
+    command: "github-release";
+    /** `githubRelease`, not `github-release`: a config key is camelCase and a command name is
+     *  hyphenated, and this is the one command out of the whole set where the two differ. */
+    configKey: "githubRelease";
+    describe: string;
+    /** Read, not owned - the release tag's pattern is `version`'s key. */
+    configKeys: string[];
+    config: {
+        yes: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        dryRun: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "boolean";
+        };
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        ignoreDirty: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "boolean";
+        };
+        repository: {
+            target: "both";
+            describe: string;
+            type: "string";
+        };
+        /** Config-only: details of the release, with no reason to be a flag. `target: 'config'` is what
+         *  says so, and it is the whole point of the field - a key can exist in `.rmanrc` without
+         *  existing on the command line. */
+        draft: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
+        prerelease: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
+        assets: {
+            target: "config";
+            describe: string;
+            /** `type: 'string'` plus `array: true`, not `type: 'array'`: the latter loses the element type
+             *  and the contribution would read `unknown[]`. This is what keeps `assets` a `string[]` and is
+             *  why the key needs no `Extra`. */
+            type: "string";
+            array: true;
+        };
+        allowBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        ignoreBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default githubReleaseCommand;
+declare module '../interfaces/rman-config.interface.js' {
+    namespace RmanConfig {
+        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof githubReleaseCommand>> {
+        }
+    }
+}

package/commands/github-release.command.js

@@ -1,44 +1,73 @@
 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',
-        configKeys: ['githubRelease', 'version.releaseTagPattern'],
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
+const COMMAND = 'github-release';
+const config = {
+    ...branchGuardOptions,
+    yes: {
+        target: 'cli',
+        alias: 'y',
+        describe: 'Skip the confirmation prompt and create the release immediately',
+        type: 'boolean',
+    },
+    dryRun: {
+        target: 'cli',
+        cliName: 'dry-run',
+        describe: 'Only show the plan - never creates anything, regardless of --yes',
+        type: 'boolean',
+    },
+    json: { target: 'cli', alias: 'j', describe: 'Print the plan as JSON instead of text', type: 'boolean' },
+    ignoreDirty: {
+        target: 'cli',
+        cliName: 'ignore-dirty',
+        describe: 'Release anyway when the working tree has uncommitted changes, instead of aborting',
+        type: 'boolean',
+    },
+    repository: {
+        target: 'both',
+        describe: 'The "owner/repo" the release is created in - default: .rmanrc "githubRelease.repository", ' +
+            'falling back to the "origin" remote.',
+        type: 'string',
+    },
+    /** Config-only: details of the release, with no reason to be a flag. `target: 'config'` is what
+     *  says so, and it is the whole point of the field - a key can exist in `.rmanrc` without
+     *  existing on the command line. */
+    draft: { target: 'config', describe: 'Create the release as a draft', type: 'boolean' },
+    prerelease: { target: 'config', describe: 'Mark the release as a prerelease', type: 'boolean' },
+    assets: {
+        target: 'config',
+        describe: "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.',
+        /** `type: 'string'` plus `array: true`, not `type: 'array'`: the latter loses the element type
+         *  and the contribution would read `unknown[]`. This is what keeps `assets` a `string[]` and is
+         *  why the key needs no `Extra`. */
+        type: 'string',
+        array: true,
+    },
+};
+const githubReleaseCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
+        /** `githubRelease`, not `github-release`: a config key is camelCase and a command name is
+         *  hyphenated, and this is the one command out of the whole set where the two differ. */
+        configKey: 'githubRelease',
         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',
-        }),
+        /** Read, not owned - the release tag's pattern is `version`'s key. */
+        configKeys: ['version.releaseTagPattern'],
+        config,
+        examples: [
+            { command: '$0 github-release', description: '# Show what would be released, then ask for confirmation' },
+            { command: '$0 github-release --yes', description: '# Create it immediately, no confirmation (CI)' },
+            { command: '$0 github-release --dry-run', description: '# Only show the plan' },
+        ],
         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, {
+            const plan = await app.getService('githubRelease').getPlan({
                 ignoreDirty: args.ignoreDirty,
                 repository: args.repository,
             });
@@ -93,7 +122,7 @@ export function initCli(repository, program) {
             }
             if (!proceed)
                 return;
-            const applied = await GithubReleaseService.applyPlan(repository, plan);
+            const applied = await app.getService('githubRelease').applyPlan(plan);
             const failed = applied.find(e => e.status === 'error');
             if (failed) {
                 console.log(colors.red('failed'), colors.cyan(failed.tag ?? ''), colors.red(failed.reason ?? ''));
@@ -106,8 +135,9 @@ export function initCli(repository, program) {
                     console.log(colors.green('released'), colors.cyan(e.tag ?? ''));
             }
         },
-    });
-}
+    };
+});
+export default githubReleaseCommand;
 async function confirm(question) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {

package/commands/import.command.d.ts

@@ -1,3 +1,36 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
-export declare function initCli(repository: Repository, program: Argv): void;
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "import <path>";
+declare const config: {
+    dest: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const importCommand: (app: import("../index.js").RmanApplication) => {
+    command: "import <path>";
+    describe: string;
+    config: {
+        dest: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+    };
+    positionals: {
+        path: {
+            describe: string;
+            type: "string";
+        };
+    };
+    examples: ({
+        command: string;
+        description?: undefined;
+    } | {
+        command: string;
+        description: string;
+    })[];
+    handler: (args: Args) => Promise<void>;
+};
+export default importCommand;

package/commands/import.command.js

@@ -1,27 +1,35 @@
 import path from 'node:path';
 import colors from 'ansi-colors';
-import { ImportService } from '../services/import.service.js';
-export function initCli(repository, program) {
-    program.command({
-        command: 'import <path>',
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+const COMMAND = 'import <path>';
+const config = {
+    dest: {
+        target: 'cli',
+        describe: 'Subdirectory the new package is placed under (default: "packages")',
+        type: 'string',
+    },
+};
+const importCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
         describe: 'Imports an external git repository as a new package, preserving its full commit history',
-        builder: cmd => cmd
-            .example('$0 import ../my-old-repo', '')
-            .example('$0 import ../my-old-repo --dest libs', '# Under libs/ instead of packages/')
-            .positional('path', {
-            describe: 'Path to a local clone of the repository to import (not a URL - clone it first)',
-            type: 'string',
-        })
-            .option('dest', {
-            describe: 'Subdirectory the new package is placed under (default: "packages")',
-            type: 'string',
-        }),
+        config,
+        positionals: {
+            path: {
+                describe: 'Path to a local clone of the repository to import (not a URL - clone it first)',
+                type: 'string',
+            },
+        },
+        examples: [
+            { command: '$0 import ../my-old-repo' },
+            { command: '$0 import ../my-old-repo --dest libs', description: '# Under libs/ instead of packages/' },
+        ],
         handler: async (args) => {
-            const result = await ImportService.importRepo(repository, args.path, {
-                dest: args.dest,
-            });
+            const result = await app.getService('import').importRepo(args.path, { dest: args.dest });
             console.log(colors.green('imported'), colors.cyan(result.name), '->', path.relative(repository.dirname, result.targetDir), colors.gray(`(${result.commitCount} commit(s))`));
             console.log(colors.gray('Add it to your workspaces glob if it is not already covered, then reinstall ("ci").'));
         },
-    });
-}
+    };
+});
+export default importCommand;

package/commands/info.command.d.ts

@@ -1,12 +1,40 @@
-import type { Argv } from 'yargs';
-import type { Repository } from '../core/repository.js';
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+declare const COMMAND: "info";
+declare const config: {
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+/** Reports; declares no config key of its own. */
+declare const infoCommand: (app: import("../index.js").RmanApplication) => {
+    command: "info";
+    describe: string;
+    config: {
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default infoCommand;
 /**
  * `rman info` - environment and repository, and back in the core because most of what it reports
  * (OS, CPU, shell, git, the repository's own shape) is true of any repository.
  *
- * The Node half is not here at all: installing `rman-node` augments `SystemInfo` and the package
- * manager, `npmPackages` and this plugin's own version start appearing. Without it nothing
- * npm-shaped is asked for or printed, which is the right answer for a repository in any other
- * language.
+ * The Node half is not written here: registering the `node` built-in augments `SystemInfo` in
+ * place, and the package manager and `npmPackages` start appearing. A repository that never names
+ * it - or that detection reads as something else - asks for and prints nothing npm-shaped, which is
+ * the right answer in any other language. **Bundled is not the same as on**: the built-in ships
+ * inside rman, and this is one of the places that difference is visible.
  */
-export declare function initCli(repository: Repository, program: Argv): void;

package/commands/info.command.js

@@ -1,6 +1,37 @@
 import colors from 'ansi-colors';
 import semver from 'semver';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { SystemInfo } from '../services/system-info.js';
+const COMMAND = 'info';
+const config = {
+    json: { target: 'cli', alias: 'j', describe: 'Print output as JSON', type: 'boolean' },
+};
+/** Reports; declares no config key of its own. */
+const infoCommand = registerCommand(app => {
+    const repository = app.repository;
+    return {
+        command: COMMAND,
+        describe: 'Prints local environment and repository information',
+        config,
+        examples: [
+            { command: '$0 info', description: '# Prints information' },
+            { command: '$0 info --json', description: '# Prints information in JSON format' },
+        ],
+        handler: async (args) => {
+            /** Only the repository - which package manager to report, if any, is a question the core
+             *  cannot ask. `rman-node`'s augmentation reads `.rmanrc "packageManager"` off this. */
+            const systemInfo = await SystemInfo.getSystemInfo({ repository });
+            const repositoryInfo = SystemInfo.getRepositoryInfo(repository);
+            if (args.json) {
+                console.log(JSON.stringify({ ...systemInfo, repository: repositoryInfo }, undefined, 2));
+                return;
+            }
+            printSystemInfo(systemInfo);
+            printRepositoryInfo(repositoryInfo);
+        },
+    };
+});
+export default infoCommand;
 function printSystemInfo(systemInfo) {
     const maxName = Object.keys(systemInfo).reduce((l, p) => Object.keys(systemInfo[p]).reduce((i, x) => Math.max(i, x.length), l), 0);
     for (const [categoryName, category] of Object.entries(systemInfo)) {
@@ -39,34 +70,9 @@ function printRepositoryInfo(info) {
  * `rman info` - environment and repository, and back in the core because most of what it reports
  * (OS, CPU, shell, git, the repository's own shape) is true of any repository.
  *
- * The Node half is not here at all: installing `rman-node` augments `SystemInfo` and the package
- * manager, `npmPackages` and this plugin's own version start appearing. Without it nothing
- * npm-shaped is asked for or printed, which is the right answer for a repository in any other
- * language.
+ * The Node half is not written here: registering the `node` built-in augments `SystemInfo` in
+ * place, and the package manager and `npmPackages` start appearing. A repository that never names
+ * it - or that detection reads as something else - asks for and prints nothing npm-shaped, which is
+ * the right answer in any other language. **Bundled is not the same as on**: the built-in ships
+ * inside rman, and this is one of the places that difference is visible.
  */
-export function initCli(repository, program) {
-    program.command({
-        command: 'info',
-        describe: 'Prints local environment and repository information',
-        builder: cmd => cmd
-            .example('$0 info', '# Prints information')
-            .example('$0 info --json', '# Prints information in JSON format')
-            .option('json', {
-            alias: 'j',
-            describe: 'Print output as JSON',
-            type: 'boolean',
-        }),
-        handler: async (args) => {
-            /** Only the repository - which package manager to report, if any, is a question the core
-             *  cannot ask. `rman-node`'s augmentation reads `.rmanrc "packageManager"` off this. */
-            const systemInfo = await SystemInfo.getSystemInfo({ repository });
-            const repositoryInfo = SystemInfo.getRepositoryInfo(repository);
-            if (args.json) {
-                console.log(JSON.stringify({ ...systemInfo, repository: repositoryInfo }, undefined, 2));
-                return;
-            }
-            printSystemInfo(systemInfo);
-            printRepositoryInfo(repositoryInfo);
-        },
-    });
-}