rman 1.3.0 → 2.0.0-beta.2

package/commands/list.command.d.ts

@@ -1,3 +1,163 @@
-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';
+/** `[options...]` is yargs-meaningless - its variadic marker is two dots, and this command declares
+ *  no positional for it. Left as it is rather than fixed in passing: dropping it makes
+ *  `rman list foo` start failing, which is a behaviour change and belongs in its own commit. */
+declare const COMMAND: "list [options...]";
+declare const config: {
+    short: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    parseable: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    toposort: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    graph: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+        /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+         *  it cannot be combined with end up in one place. */
+        conflicts: string[];
+    };
+    json: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changed: {
+        target: "cli";
+        alias: string;
+        describe: string;
+        type: "boolean";
+    };
+    changedSince: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+        conflicts: string;
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+declare const listCommand: (app: import("../index.js").RmanApplication) => {
+    command: "list [options...]";
+    aliases: string[];
+    describe: string;
+    config: {
+        short: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        parseable: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        toposort: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        graph: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+            /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+             *  it cannot be combined with end up in one place. */
+            conflicts: string[];
+        };
+        json: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        changed: {
+            target: "cli";
+            alias: string;
+            describe: string;
+            type: "boolean";
+        };
+        changedSince: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+            conflicts: string;
+        };
+        scope: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        ignore: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        platform: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        deps: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dependents: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default listCommand;

package/commands/list.command.js

@@ -1,7 +1,91 @@
 import colors from 'ansi-colors';
 import EasyTable from 'easy-table';
-import { ListService } from '../services/list.service.js';
-import { applyPackageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+/** `[options...]` is yargs-meaningless - its variadic marker is two dots, and this command declares
+ *  no positional for it. Left as it is rather than fixed in passing: dropping it makes
+ *  `rman list foo` start failing, which is a behaviour change and belongs in its own commit. */
+const COMMAND = 'list [options...]';
+const config = {
+    ...packageFilterOptions,
+    short: { target: 'cli', alias: 's', describe: 'Do not show extended information', type: 'boolean' },
+    parseable: { target: 'cli', alias: 'p', describe: 'Show parseable output', type: 'boolean' },
+    toposort: {
+        target: 'cli',
+        alias: 't',
+        describe: 'Sort packages in topological order (dependencies before dependents) instead of lexical by directory',
+        type: 'boolean',
+    },
+    graph: {
+        target: 'cli',
+        alias: 'g',
+        describe: 'Show dependency graph as a JSON-formatted adjacency list',
+        type: 'boolean',
+        /** Declared on the option instead of as separate `.conflicts()` calls - what a flag is and what
+         *  it cannot be combined with end up in one place. */
+        conflicts: ['parseable', 'json'],
+    },
+    json: { target: 'cli', alias: 'j', describe: 'Show output in JSON format', type: 'boolean' },
+    changed: {
+        target: 'cli',
+        alias: 'c',
+        describe: 'Only list packages that have changed since the last publish (dirty or committed but not yet published)',
+        type: 'boolean',
+    },
+    changedSince: {
+        target: 'cli',
+        cliName: 'changed-since',
+        describe: 'Only list packages that have changed since the given git commit/hash',
+        type: 'string',
+        conflicts: 'changed',
+    },
+};
+const listCommand = registerCommand(app => {
+    return {
+        command: COMMAND,
+        aliases: ['ls'],
+        describe: 'Lists packages in repository',
+        config,
+        examples: [
+            { command: '$0 list', description: '# List all packages' },
+            { command: '$0 list --json', description: '# List all packages in JSON format' },
+        ],
+        handler: async (args) => {
+            /**
+             * **Only the table asks for the root**, and that is why the option exists rather than the
+             * service always including it. The table draws a tree, which needs the row its members are
+             * nested under; the other four forms are the inventory a script parses, and the inventory is
+             * the workspace members - which is also what the count line reports.
+             */
+            const table = !args.graph && !args.json && !args.parseable && !args.short;
+            const items = await app.getService('list').getPackages({
+                ...readPackageFilterOptions(args),
+                toposort: args.toposort,
+                changed: args.changed,
+                changedSince: args.changedSince,
+                includeRoot: table,
+            });
+            if (args.graph)
+                printGraph(items);
+            else if (args.json)
+                console.log(JSON.stringify(items, undefined, 2));
+            else if (args.parseable)
+                printParseable(items);
+            else if (args.short)
+                for (const it of items)
+                    console.log(it.name);
+            /**
+             * **Whether a root row was added is asked here, not inferred from the rows.** `isRoot` is
+             * true of the one package in a *single-package* repository too - it genuinely is the root -
+             * so counting rows that are not the root reported `0 Package(s) found` there (measured). The
+             * condition is the same one the service applies, and it is one line.
+             */
+            else
+                printTable(items, table && app.repository.monorepo);
+        },
+    };
+});
+export default listCommand;
 function statusLabel(status) {
     switch (status) {
         case 'dirty':
@@ -14,11 +98,31 @@ function statusLabel(status) {
             return '';
     }
 }
-function printTable(items) {
+/**
+ * **The tree, as a table**: the root first, then each package indented by how far below it sits.
+ *
+ * Indentation rather than box-drawing characters, which was the cheaper answer to the same
+ * question and stays legible when the output is pasted somewhere without a monospace font, copied
+ * into a `--scope` argument, or read by eye for the one name someone is looking for. The nesting is
+ * `Item.depth`, a fact about the package - so `--toposort` reorders the rows and leaves each one's
+ * indentation telling the truth about where it lives.
+ *
+ * **`Platform` is a column because a package's technology is now a per-package answer.** A polyglot
+ * repository is the whole point of the walk finding nested packages of another platform, and until
+ * this column existed `rman list` was the one place that showed every package and could not say
+ * which technology each belonged to. Blank rather than a word when none claimed it: `Package.provider`
+ * is an empty string there, and inventing `unknown` would read as a technology's name.
+ *
+ * **The count is the members**, root excluded, which is what `repository.packages` means and what
+ * every other form of this command reports.
+ */
+function printTable(items, withRoot) {
     const table = new EasyTable();
     for (const it of items) {
-        table.cell('Package', colors.yellowBright(it.name));
+        const indent = '  '.repeat(it.depth);
+        table.cell('Package', indent + (it.isRoot ? colors.whiteBright(it.selector) : colors.yellowBright(it.selector)));
         table.cell('Version', colors.yellow(it.version));
+        table.cell('Platform', it.platform ? colors.cyan(it.platform) : '');
         table.cell('Private', it.private ? colors.magentaBright('yes') : '');
         table.cell('Changed', statusLabel(it.status));
         table.cell('Path', it.location);
@@ -26,7 +130,7 @@ function printTable(items) {
     }
     console.log(table.toString().trim());
     console.log('');
-    console.log(colors.gray(`${items.length} Package(s) found`));
+    console.log(colors.gray(`${items.length - (withRoot ? 1 : 0)} Package(s) found`));
 }
 function printParseable(items) {
     for (const it of items) {
@@ -45,69 +149,3 @@ function printGraph(items) {
         graph[it.name] = it.dependencies;
     console.log(JSON.stringify(graph, undefined, 2));
 }
-export function initCli(repository, program) {
-    program.command({
-        command: 'list [options...]',
-        aliases: ['ls'],
-        describe: 'Lists packages in repository',
-        builder: cmd => applyPackageFilterOptions(cmd)
-            .example('$0 list', '# List all packages')
-            .example('$0 list --json', '# List all packages in JSON format')
-            .conflicts('graph', ['parseable', 'json'])
-            .conflicts('short', ['parseable', 'json'])
-            .conflicts('changed', 'changed-since')
-            .option('short', {
-            alias: 's',
-            describe: 'Do not show extended information',
-            type: 'boolean',
-        })
-            .option('parseable', {
-            alias: 'p',
-            describe: 'Show parseable output',
-            type: 'boolean',
-        })
-            .option('toposort', {
-            alias: 't',
-            describe: 'Sort packages in topological order (dependencies before dependents) instead of lexical by directory',
-            type: 'boolean',
-        })
-            .option('graph', {
-            alias: 'g',
-            describe: 'Show dependency graph as a JSON-formatted adjacency list',
-            type: 'boolean',
-        })
-            .option('json', {
-            alias: 'j',
-            describe: 'Show output in JSON format',
-            type: 'boolean',
-        })
-            .option('changed', {
-            alias: 'c',
-            describe: 'Only list packages that have changed since the last publish (dirty or committed but not yet published)',
-            type: 'boolean',
-        })
-            .option('changed-since', {
-            describe: 'Only list packages that have changed since the given git commit/hash',
-            type: 'string',
-        }),
-        handler: async (args) => {
-            const items = await ListService.getPackages(repository, {
-                ...readPackageFilterOptions(args),
-                toposort: args.toposort,
-                changed: args.changed,
-                changedSince: args.changedSince,
-            });
-            if (args.graph)
-                printGraph(items);
-            else if (args.json)
-                console.log(JSON.stringify(items, undefined, 2));
-            else if (args.parseable)
-                printParseable(items);
-            else if (args.short)
-                for (const it of items)
-                    console.log(it.name);
-            else
-                printTable(items);
-        },
-    });
-}

package/commands/publish.command.d.ts

@@ -0,0 +1,231 @@
+import type { RmanApplication } from '../core/application.js';
+import { type RmanConfig } from '../interfaces/rman-config.interface.js';
+import type { DockerPublishOptions } from '../targets/docker.target.js';
+/** Hoisted for `ArgsOf` - see `version.command.ts` and `RmanConfig.ArgsOf` for why. */
+declare const COMMAND: "publish";
+/**
+ * **The options that belong to publishing, rather than to any one registry.**
+ *
+ * Everything npm-shaped that used to sit beside them - `--access`, `--tag`, `--otp`, `--registry`,
+ * `--userconfig`, `--contents`, `--package-manager` - is declared by the `npm` target now, and
+ * `--docker-namespace` by the `docker` one. They are merged in at build time (see below), so
+ * `rman publish --help` lists exactly the flags the targets this repository actually has.
+ */
+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";
+    };
+    /**
+     * `target: 'both'` because it is genuinely both: `--target docker` for one run, `publish.target`
+     * in a `.rmanrc` for a package's standing answer. Its `choices` cannot be written here - which
+     * targets exist is whatever the repository's plugins contribute - so they are filled in from the
+     * registry where the command is built.
+     */
+    target: {
+        target: "both";
+        describe: string;
+        type: "array";
+    };
+    skip: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
+    allowBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    ignoreBranch: {
+        target: "cli";
+        cliName: string;
+        describe: string;
+        type: "string";
+    };
+    scope: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    ignore: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    platform: {
+        target: "cli";
+        describe: string;
+        type: "string";
+    };
+    deps: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+    dependents: {
+        target: "cli";
+        describe: string;
+        type: "boolean";
+    };
+};
+/**
+ * The rest of `publish.*`: **one block per target, contributed by the target**.
+ *
+ * `PublishTargetConfigs` is an empty interface on purpose - an extension point rather than a list.
+ * `docker` below is the core's own target declaring its block; `rman-node` adds `directory` from
+ * its own package the same way. Neither could be written here: which targets exist is whatever the
+ * repository's plugins contribute.
+ *
+ * **It had to be a slot, not two declarations of `publish`.** A key that arrives from two places is
+ * `Interface 'RmanConfig' cannot simultaneously extend types ... Named property 'publish' of types
+ * ... are not identical` (measured) - so `publish` is contributed once, here, and everything under
+ * it merges into this one interface first.
+ */
+export interface PublishExtraKeys extends PublishTargetConfigs {
+}
+/** Where a target declares its own `publish.<target>` config block. Augmented, never edited. */
+export interface PublishTargetConfigs {
+    /** Required once `"docker"` is one of a package's `publish.target`s - `publish --target docker`
+     *  errors clearly on a package that opts in here but leaves this out. */
+    docker?: DockerPublishOptions;
+}
+type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
+/**
+ * `rman publish` - the repository's half of question B: which packages' current version is not out
+ * there yet, and pushing the ones that are not.
+ *
+ * **This was `rman-node`'s command until the targets became contributions**, and that had the
+ * ownership backwards. Everything here is about a repository - which packages are candidates, what
+ * order to push them in (dependencies first), the plan/confirm/apply shape, `--dry-run`, the JSON a
+ * CI gate reads - and none of it is npm's. What *is* npm's is one answer to "is this version on the
+ * registry, and how do I push it", which is `PublishTarget`. The measured consequence of the old
+ * arrangement: `publish --target docker` in a repository with no JavaScript in it required
+ * installing a Node plugin to reach a Docker push the core had implemented all along.
+ *
+ * Never looks at whether `version` ran - it inspects what is on disk and on each registry, so it
+ * behaves the same right after a bump or days later, and re-running is safe.
+ */
+declare const publishCommand: (app: RmanApplication) => {
+    command: "publish";
+    describe: string;
+    /** `group` is not read here, but `allowBranch`/`ignoreBranch` are - through the shared
+     *  branch-guard group, which only exposes them as flags. */
+    configKeys: string[];
+    config: {
+        /** Filled in from the registry: `--target` can only offer what this repository installed. */
+        target: {
+            choices: string[];
+            target: "both";
+            describe: string;
+            type: "array";
+        };
+        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";
+        };
+        skip: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
+        allowBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        ignoreBranch: {
+            target: "cli";
+            cliName: string;
+            describe: string;
+            type: "string";
+        };
+        scope: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        ignore: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        platform: {
+            target: "cli";
+            describe: string;
+            type: "string";
+        };
+        deps: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+        dependents: {
+            target: "cli";
+            describe: string;
+            type: "boolean";
+        };
+    };
+    examples: {
+        command: string;
+        description: string;
+    }[];
+    handler: (args: Args) => Promise<void>;
+};
+export default publishCommand;
+/**
+ * `publish`'s own keys on `RmanConfig`: `target` and `skip` derived from the `config` block, plus
+ * every target's own block through `PublishExtraKeys`.
+ *
+ * So a target contributes its config type as well as its flags now - `publish.docker.*` is declared
+ * by the core's docker target and `publish.npm.directory` by `rman-node`'s npm one, each from its own
+ * package, and neither can collide with the other or with what the command derives.
+ */
+declare module '../interfaces/rman-config.interface.js' {
+    namespace RmanConfig {
+        interface CommandConfigs extends RmanConfig.CommandContribution<ReturnType<typeof publishCommand>, PublishExtraKeys> {
+        }
+    }
+}