rman-node 1.1.1

package/commands/ci.command.js

@@ -0,0 +1,35 @@
+import { applyBranchGuardOptions, applyPackageFilterOptions, assertAllowedBranch, readBranchGuardOptions, readPackageFilterOptions, } from 'rman';
+import { CiService } from '../services/ci.service.js';
+/**
+ * `rman ci` - contributed by the `rman-node` plugin rather than built into rman.
+ *
+ * A plugin's command is a `CustomCommand`, so the repository arrives through `context` instead of
+ * being captured when the command is registered - the same shape a repository's own `.rman/*.mjs`
+ * command has, and the reason both can be registered through one code path.
+ */
+export const command = {
+    command: 'ci',
+    configKeys: ['packageManager'],
+    describe: 'Deletes node_modules and lockfiles in every package, then reinstalls from scratch',
+    builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
+        .example('$0 ci', '')
+        .option('package-manager', {
+        describe: 'Package manager to install with (default: npm, or .rmanrc "packageManager")',
+        choices: PACKAGE_MANAGERS,
+    })
+        .option('progress', {
+        describe: 'Show a live progress panel while running (default: true; auto-disabled when not a TTY). ' +
+            'Unlike run/build, completion is not reported as a per-package tally - only failures are called out.',
+        type: 'boolean',
+    }),
+    handler: async ({ repository }, args) => {
+        await assertAllowedBranch(repository, readBranchGuardOptions(args));
+        await CiService.reinstall(repository, {
+            ...readPackageFilterOptions(args),
+            packageManager: args.packageManager,
+            progress: args.progress,
+            logLevel: args.logLevel,
+        });
+    },
+};
+const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'bun'];

package/commands/clean.command.d.ts

@@ -0,0 +1,6 @@
+import { type CustomCommand } from 'rman';
+/**
+ * `rman clean` - contributed by the `rman-node` plugin rather than built into rman, because what
+ * it deletes is TypeScript's output. See `CleanService.clean`.
+ */
+export declare const command: CustomCommand;

package/commands/clean.command.js

@@ -0,0 +1,32 @@
+import { applyBranchGuardOptions, applyPackageFilterOptions, applyRootOption, assertAllowedBranch, readBranchGuardOptions, readPackageFilterOptions, } from 'rman';
+import { CleanService } from '../services/clean.service.js';
+/**
+ * `rman clean` - contributed by the `rman-node` plugin rather than built into rman, because what
+ * it deletes is TypeScript's output. See `CleanService.clean`.
+ */
+export const command = {
+    command: 'clean',
+    configKeys: ['clean'],
+    describe: 'Removes compiled TypeScript output and any extra files/dirs configured via .rmanrc "clean"',
+    builder: cmd => applyRootOption(applyBranchGuardOptions(applyPackageFilterOptions(cmd)), 'Clean')
+        .example('$0 clean', '')
+        .example('$0 clean --dry-run', '# Preview what would be removed')
+        .option('progress', {
+        describe: 'Show a live progress panel (default: true; auto-disabled when not a TTY)',
+        type: 'boolean',
+    })
+        .option('dry-run', {
+        describe: 'Report what would be removed without actually removing anything',
+        type: 'boolean',
+    }),
+    handler: async ({ repository }, args) => {
+        await assertAllowedBranch(repository, readBranchGuardOptions(args));
+        await CleanService.clean(repository, {
+            ...readPackageFilterOptions(args),
+            progress: args.progress,
+            dryRun: args.dryRun,
+            root: args.root,
+            logLevel: args.logLevel,
+        });
+    },
+};

package/commands/publish.command.d.ts

@@ -0,0 +1,9 @@
+import { type CustomCommand } from 'rman';
+/**
+ * `rman publish` - contributed by the `rman-node` plugin.
+ *
+ * Question B at the package level: each target asks its *own* registry whether this version is
+ * already out there (npm via `npm view`, Docker via `docker manifest inspect`). Never whether
+ * `version` ran - it only inspects what is on disk and on the registry, so re-running is safe.
+ */
+export declare const command: CustomCommand;

package/commands/publish.command.js

@@ -0,0 +1,228 @@
+import readline from 'node:readline/promises';
+import colors from 'ansi-colors';
+import { applyBranchGuardOptions, applyPackageFilterOptions, assertAllowedBranch, DockerPublishService, readBranchGuardOptions, readPackageFilterOptions, } from 'rman';
+import { CiService } from '../services/ci.service.js';
+import { PublishService } from '../services/publish.service.js';
+/**
+ * `rman publish` - contributed by the `rman-node` plugin.
+ *
+ * Question B at the package level: each target asks its *own* registry whether this version is
+ * already out there (npm via `npm view`, Docker via `docker manifest inspect`). Never whether
+ * `version` ran - it only inspects what is on disk and on the registry, so re-running is safe.
+ */
+export const command = {
+    command: 'publish',
+    configKeys: ['publish'],
+    describe: 'Publishes every package to its configured target(s) (npm by default, or .rmanrc "publish.target")',
+    builder: cmd => applyBranchGuardOptions(applyPackageFilterOptions(cmd))
+        .example('$0 publish', '# Show the plan, then ask for confirmation')
+        .example('$0 publish --yes', '# Publish immediately, no confirmation')
+        .example('$0 publish --dry-run', '# Only show the plan, never publish')
+        .example('$0 publish --target docker', '# Only the packages configured for the "docker" target')
+        .option('yes', {
+        alias: 'y',
+        describe: 'Skip the confirmation prompt and publish immediately',
+        type: 'boolean',
+    })
+        .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: ' +
+            'every target each package itself is configured for (.rmanrc "publish.target", "npm" when unset). ' +
+            'A package that opts into "docker" but has no "publish.docker" config errors clearly instead of ' +
+            'being silently skipped.',
+        type: 'array',
+        choices: ['npm', 'docker'],
+    })
+        .option('ignore-dirty', {
+        describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
+        type: 'boolean',
+    })
+        .option('package-manager', {
+        describe: 'Package manager to publish with (default: npm, or .rmanrc "packageManager")',
+        choices: PACKAGE_MANAGERS,
+    })
+        .option('access', {
+        describe: 'npm publish --access <public|restricted> - required by the registry for a new scoped package',
+        choices: ['public', 'restricted'],
+    })
+        .option('tag', {
+        describe: 'npm publish --tag <tag> - the dist-tag this version is published under (default "latest")',
+        type: 'string',
+    })
+        .option('otp', {
+        describe: 'npm publish --otp <otp> - a 2FA one-time password, for registries that require it',
+        type: 'string',
+    })
+        .option('registry', {
+        describe: 'Registry to check against and publish to (default: whatever .npmrc already configures)',
+        type: 'string',
+    })
+        .option('userconfig', {
+        describe: 'Path to a custom .npmrc to use for both the registry check and the actual publish',
+        type: 'string',
+    })
+        .option('contents', {
+        describe: "Subdirectory to publish from, relative to each package's own directory - only consulted when a " +
+            'package has no "publishConfig.directory" of its own (that always wins when present)',
+        type: 'string',
+    })
+        .option('docker-namespace', {
+        describe: 'Prefixed onto a bare (no "/") "publish.docker.image" - default: the DOCKERHUB_NAMESPACE ' +
+            'environment variable.',
+        type: 'string',
+    }),
+    handler: async ({ repository }, args) => {
+        await assertAllowedBranch(repository, readBranchGuardOptions(args));
+        const targets = resolveTargets(args.target);
+        const explicitTargets = !!args.target?.length;
+        const explicitDockerTarget = explicitTargets && targets.has('docker');
+        const ignoreDirty = args.ignoreDirty;
+        const npmOptions = {
+            ...readPackageFilterOptions(args),
+            ignoreDirty,
+            registry: args.registry,
+            userconfig: args.userconfig,
+        };
+        const dockerOptions = {
+            ...readPackageFilterOptions(args),
+            ignoreDirty,
+            namespace: args.dockerNamespace,
+        };
+        const npmPlan = targets.has('npm') ? await PublishService.getPlan(repository, npmOptions) : [];
+        const dockerPlan = targets.has('docker') ? await DockerPublishService.getPlan(repository, dockerOptions) : [];
+        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));
+            const err = new Error(message);
+            err.logged = true;
+            throw err;
+        }
+        const errors = [...npmPlan, ...dockerPlan].filter(e => e.status === 'error');
+        if (errors.length) {
+            const allDirty = errors.every(e => e.reason === 'uncommitted local changes');
+            const message = allDirty
+                ? `${errors.length} package(s) have uncommitted local changes ` +
+                    '(pass --ignore-dirty to exclude them instead of aborting)'
+                : `${errors.length} package(s) failed to prepare for publish - see the errors above`;
+            console.log(colors.red(message));
+            const err = new Error(message);
+            err.logged = true;
+            throw err;
+        }
+        if (![...npmPlan, ...dockerPlan].some(e => e.status === 'publish')) {
+            if (!args.json)
+                console.log(colors.gray('Nothing to publish.'));
+            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 publish non-interactively.'));
+                return;
+            }
+            proceed = await confirm('Publish these packages?');
+        }
+        if (!proceed)
+            return;
+        const appliedNpm = targets.has('npm')
+            ? await PublishService.applyPlan(repository, npmPlan, {
+                ...npmOptions,
+                packageManager: args.packageManager,
+                access: args.access,
+                tag: args.tag,
+                otp: args.otp,
+                contents: args.contents,
+            })
+            : [];
+        const appliedDocker = targets.has('docker') ? await DockerPublishService.applyPlan(repository, dockerPlan) : [];
+        let failed = false;
+        for (const entry of appliedNpm) {
+            if (entry.status === 'publish') {
+                console.log(colors.green('published'), colors.cyan(entry.package.name), entry.version);
+            }
+            else if (entry.status === 'error' && npmPlan.find(e => e.package === entry.package)?.status === 'publish') {
+                failed = true;
+                console.log(colors.red('failed'), colors.cyan(entry.package.name), colors.red(entry.reason ?? ''));
+            }
+        }
+        for (const entry of appliedDocker) {
+            if (entry.status === 'publish') {
+                console.log(colors.green('published'), colors.gray('[docker]'), colors.cyan(entry.package.name), entry.image);
+            }
+            else if (entry.status === 'error' && dockerPlan.find(e => e.package === entry.package)?.status === 'publish') {
+                failed = true;
+                console.log(colors.red('failed'), colors.gray('[docker]'), colors.cyan(entry.package.name), colors.red(entry.reason ?? ''));
+            }
+        }
+        if (failed) {
+            const err = new Error('"publish" failed');
+            err.logged = true;
+            throw err;
+        }
+    },
+};
+function resolveTargets(input) {
+    if (!input?.length)
+        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) {
+        const name = prefix + colors.cyan(e.package.name);
+        switch (e.status) {
+            case 'publish':
+                console.log(colors.green('publish'), name, e.version, colors.gray(e.reason ?? ''));
+                break;
+            case 'up-to-date':
+                console.log(colors.gray('up-to-date'), name, e.version);
+                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;
+        }
+    }
+}
+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();
+    }
+}
+const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'bun'];

package/index.d.ts

@@ -0,0 +1,31 @@
+import './augmentation/rman.augmentation.js';
+export { augmentManifest, DEPENDENCY_KEYS, packageJsonManifest } from './augmentation/manifest.augmentation.js';
+export { augmentRun, packageJsonSteps } from './augmentation/run.augmentation.js';
+export { augmentSystemInfo } from './augmentation/system-info.augmentation.js';
+export { augmentWorkspace, npmWorkspace } from './augmentation/workspace.augmentation.js';
+export type { NodeConfigKeys, RmanNodeConfig } from './interfaces/rman-config.interface.js';
+export { defineConfig } from './interfaces/rman-config.interface.js';
+export { CiService } from './services/ci.service.js';
+export { CleanService } from './services/clean.service.js';
+export { PublishService } from './services/publish.service.js';
+export { augmentVersionPlan, nodeVersionPlanner, NodeVersionPlanService } from './services/version-plan.service.js';
+export { augmentBinPath, npmBinPaths } from './utils/npm-run-path.js';
+export type { ParsedWorkspaceRange } from './utils/workspace-range.js';
+export { parseWorkspaceRange, resolveWorkspaceRange } from './utils/workspace-range.js';
+/** The version this package reports. Rewritten into `build/index.js` by `support/postbuild.cjs`. */
+export declare const version = "1";
+/** Everything this package contributes to rman, as one plugin. Exported by name as well, for code
+ *  registering it directly instead of through a config. */
+export declare const nodePlugin: import("rman").RmanPlugin;
+/**
+ * **An `.rmanrc` config, not a plugin** - which is what a package naming itself in `plugins` should
+ * hand over. A package exposing exactly one plugin was the shape of the plugin it happens to
+ * contain today: adding a second, or anything else a config can say, would have changed what every
+ * repository importing it receives. As a config it is the same kind of thing as the file that names
+ * it, and `plugins` accepts an object entry precisely so this works.
+ *
+ * Only `plugins` is read out of it by `loadPlugins` - a config's other keys reach a repository
+ * through `extends`, the key that means "merge this underneath mine".
+ */
+declare const _default: import("./interfaces/rman-config.interface.js").RmanNodeConfig;
+export default _default;

package/index.js

@@ -0,0 +1,100 @@
+import './augmentation/rman.augmentation.js';
+import { definePlugin } from 'rman';
+import { augmentManifest, packageJsonManifest } from './augmentation/manifest.augmentation.js';
+import { augmentRun, packageJsonSteps } from './augmentation/run.augmentation.js';
+import { augmentSystemInfo } from './augmentation/system-info.augmentation.js';
+import { augmentWorkspace, npmWorkspace } from './augmentation/workspace.augmentation.js';
+import * as ciCommand from './commands/ci.command.js';
+import * as cleanCommand from './commands/clean.command.js';
+import * as publishCommand from './commands/publish.command.js';
+import { defineConfig } from './interfaces/rman-config.interface.js';
+import { augmentVersionPlan, nodeVersionPlanner } from './services/version-plan.service.js';
+import { augmentBinPath, npmBinPaths } from './utils/npm-run-path.js';
+export { augmentManifest, DEPENDENCY_KEYS, packageJsonManifest } from './augmentation/manifest.augmentation.js';
+export { augmentRun, packageJsonSteps } from './augmentation/run.augmentation.js';
+export { augmentSystemInfo } from './augmentation/system-info.augmentation.js';
+export { augmentWorkspace, npmWorkspace } from './augmentation/workspace.augmentation.js';
+export { defineConfig } from './interfaces/rman-config.interface.js';
+export { CiService } from './services/ci.service.js';
+export { CleanService } from './services/clean.service.js';
+export { PublishService } from './services/publish.service.js';
+export { augmentVersionPlan, nodeVersionPlanner, NodeVersionPlanService } from './services/version-plan.service.js';
+export { augmentBinPath, npmBinPaths } from './utils/npm-run-path.js';
+export { parseWorkspaceRange, resolveWorkspaceRange } from './utils/workspace-range.js';
+/** The version this package reports. Rewritten into `build/index.js` by `support/postbuild.cjs`. */
+export const version = '1.1.1';
+/**
+ * Node.js support for rman, as a plugin:
+ *
+ * ```yaml
+ * # .rmanrc.yml
+ * plugins: ['rman-node']
+ * ```
+ *
+ * rman's core is about repositories - packages, versions, changelogs, releases, branches. These
+ * three commands are about *npm*, which is a different thing that happens to be true of most
+ * repositories rman has been used on so far:
+ *
+ * - **`publish`** asks an npm registry whether a version is already out there, and pushes it -
+ *   including the manifest it generates in a build directory, the `"workspace:"` ranges it
+ *   resolves, and the `devDependencies` it strips.
+ * - **`ci`** deletes `node_modules` and a lockfile, and reinstalls with npm/yarn/pnpm/bun.
+ * - **`clean`** deletes TypeScript's output - a compiled `.js`/`.js.map`/`.d.ts` beside its `.ts`
+ *   source, a `*.tsbuildinfo`, skipping `node_modules` while it looks. Every one of those is a
+ *   TypeScript fact, so a core `clean` was a command that only looked general: nothing in it would
+ *   fire for a Cargo or Go repository, which have `cargo clean` and `go clean` of their own. The
+ *   `clean.include`/`clean.exclude` globs came along because splitting them off would leave two
+ *   commands with one name.
+ *
+ * `.rmanrc "packageManager"` is **this package's** config key, declared in `NodeConfigKeys` and
+ * merged into `RmanConfig` by declaration - `ci`/`publish` read it to decide which one to shell out
+ * to, and the `SystemInfo` augmentation reads it to decide which version to report. It was core
+ * "because `info` reads it", and that stopped being true when `SystemInfo`'s npm half moved here:
+ * measured, nothing in the core read it at all, only the declaration was left behind.
+ *
+ * **Docker stayed in the core**, where it belongs - any language's project can publish an image.
+ * What is still wrong is that this command *drives* it: `publish --target docker` in a repository
+ * that is not a Node one would have to install this plugin to reach it. Fixing that means making a
+ * publish target something a plugin contributes to a core `publish`, which is the next step rather
+ * than this one.
+ */
+/** Applied as the plugin module loads - before any command runs, since `loadPlugins` imports this
+ *  during CLI startup. Augmentations go here rather than inside a command so that `rman info`,
+ *  which is a *core* command, is affected too. */
+augmentManifest();
+augmentSystemInfo();
+augmentRun();
+augmentWorkspace();
+augmentVersionPlan();
+augmentBinPath();
+/** Everything this package contributes to rman, as one plugin. Exported by name as well, for code
+ *  registering it directly instead of through a config. */
+export const nodePlugin = definePlugin({
+    name: 'rman-node',
+    commands: [publishCommand.command, ciCommand.command, cleanCommand.command],
+    /** Declared as well as registered by `augmentRun()` above - `addStepSource` is idempotent per
+     *  source, and a plugin loaded through `plugins` should not need an import side effect to work. */
+    runSteps: packageJsonSteps,
+    /** What finds the packages at all - see `Repository.create` for why this has to be declared
+     *  rather than only registered by an import. */
+    workspace: npmWorkspace,
+    /** What a package's name and version even are - read before anything else. */
+    manifest: packageJsonManifest,
+    /** What `version`/`changed` compute a release with. `VersionPlanService` is abstract, so without
+     *  this the two commands have nothing to ask - see `NodeVersionPlanService`. */
+    versionPlanner: nodeVersionPlanner,
+    /** `node_modules/.bin` on PATH for every `exec`/`runBin`, so a repository's pinned `eslint`/`tsc`
+     *  is the one that runs. */
+    binPaths: npmBinPaths,
+});
+/**
+ * **An `.rmanrc` config, not a plugin** - which is what a package naming itself in `plugins` should
+ * hand over. A package exposing exactly one plugin was the shape of the plugin it happens to
+ * contain today: adding a second, or anything else a config can say, would have changed what every
+ * repository importing it receives. As a config it is the same kind of thing as the file that names
+ * it, and `plugins` accepts an object entry precisely so this works.
+ *
+ * Only `plugins` is read out of it by `loadPlugins` - a config's other keys reach a repository
+ * through `extends`, the key that means "merge this underneath mine".
+ */
+export default defineConfig({ plugins: [nodePlugin] });

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

@@ -0,0 +1,80 @@
+import type { RmanConfig, WithAppend } from 'rman';
+import type { CiService } from '../services/ci.service.js';
+/**
+ * The `.rmanrc` keys that only mean something because the repository is a Node one.
+ *
+ * Declared here rather than in rman's core for the reason the commands themselves are: `clean`
+ * describes TypeScript's output, and `publish.directory` a `package.json` generated at publish
+ * time. A Cargo or Go repository has neither, and a core interface offering them was a core
+ * interface claiming to know npm.
+ *
+ * **Two surfaces, and they are not alternatives:**
+ *
+ * - the `declare module 'rman'` block in [`../augmentation/rman.augmentation.ts`] merges these into
+ *   `RmanConfigKeys`, so `pkg.config.clean` stays typed wherever it is read - `CleanService`
+ *   included - with no casts. It lives there because one such block per package is the limit;
+ * - `RmanNodeConfig` is the name a *config author* annotates with, which is what makes the import
+ *   carrying that augmentation explicit instead of a side effect someone has to remember.
+ */
+export interface NodeConfigKeys {
+    /**
+     * Which package manager `ci`/`publish` shell out to, and whose version `info` reports under
+     * `Binaries`. Root level only. Default `npm`.
+     *
+     * It used to be a core key, on the grounds that `info` read it - and that stopped being true the
+     * moment `SystemInfo`'s npm half moved here: measured, **nothing in rman's core reads it at
+     * all**, only the declaration was left behind. The value set was npm's tooling the whole time.
+     */
+    packageManager?: CiService.PackageManager;
+    /** Extra files and directories `clean` removes, beyond TypeScript's own output - globs relative
+     *  to each package's own directory. Per-package cascaded; a package declaring its own `clean`
+     *  block replaces the root's entirely for itself, rather than combining with it. */
+    clean?: RmanNodeConfig.CleanOptions;
+}
+export declare namespace RmanNodeConfig {
+    interface CleanOptions extends CleanOptionsKeys, WithAppend<CleanOptionsKeys> {
+    }
+    interface CleanOptionsKeys {
+        include?: string | string[];
+        exclude?: string | string[];
+        /** Excludes this package from `clean` entirely. */
+        skip?: boolean;
+    }
+    /** Added to the core's `publish` block - the npm-only half of it. `target`, `skip` and `docker`
+     *  stay in the core: the first two are read by `list` and by every target's own plan, and Docker
+     *  publishing is not a Node concern at all. */
+    interface PublishOptions {
+        /** Where this package's publishable output lives, relative to its own directory (e.g.
+         *  `"build"`). Per-package cascaded, so a root `"[*]"` block can say it once for the whole
+         *  repository instead of repeating `publishConfig.directory` in every `package.json` - which
+         *  still wins when a package declares it, being the more specific statement.
+         *
+         *  Publishing from such a directory means the manifest there is **generated by `publish`**,
+         *  from the package's own - see `PublishService`. There is nothing to configure about it. */
+        directory?: string;
+    }
+}
+/**
+ * `.rmanrc` for a repository using this plugin: rman's own keys plus the ones above.
+ *
+ * ```js
+ * // .rmanrc.mjs
+ * import { defineConfig } from 'rman-node';
+ *
+ * export default defineConfig({
+ *   plugins: ['rman-node'],
+ *   '[ws:*]': { clean: { include: 'build' }, publish: { directory: 'build' } },
+ * });
+ * ```
+ *
+ * `.mjs`, not `.ts`: rman loads `.rmanrc.cjs`/`.mjs`/`.js` and no TypeScript form, so the type
+ * reaches a config file through the editor rather than through a compiler. The JSON and YAML forms
+ * carry no type at all - since the JSON Schema was removed, they are unchecked.
+ */
+export interface RmanNodeConfig extends RmanConfig {
+}
+/**
+ * Identity helper for authoring a `.rmanrc.mjs`/`.cjs`/`.js` config with this plugin's keys checked
+ * - rman's own `defineConfig` with a narrower parameter, nothing more. Returns `config` unchanged.
+ */
+export declare function defineConfig(config: RmanNodeConfig): RmanNodeConfig;

package/interfaces/rman-config.interface.js

@@ -0,0 +1,7 @@
+/**
+ * Identity helper for authoring a `.rmanrc.mjs`/`.cjs`/`.js` config with this plugin's keys checked
+ * - rman's own `defineConfig` with a narrower parameter, nothing more. Returns `config` unchanged.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "rman-node",
+  "description": "Node.js support for rman - the commands and conventions that only mean something in a Node repository",
+  "version": "1.1.1",
+  "author": "Panates",
+  "license": "MIT",
+  "dependencies": {
+    "@netlify/parse-npm-script": "^0.1.2",
+    "ansi-colors": "^4.1.3",
+    "envinfo": "^7.21.0",
+    "fast-glob": "^3.3.3",
+    "semver": "^7.8.5",
+    "yargs": "^18.1.0"
+  },
+  "peerDependencies": {
+    "rman": "^1.1.1"
+  },
+  "type": "module",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.0"
+  },
+  "contributors": [
+    "Eray Hanoglu <e.hanoglu@panates.com>",
+    "Ilker Gurelli <i.gurelli@panates.com>",
+    "Onur Tokel <o.tokel@panates.com>",
+    "Bircan Yuruk <b.yuruk@panates.com>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panates/rman.git",
+    "directory": "./packages/node"
+  },
+  "keywords": [
+    "rman",
+    "node",
+    "nodejs",
+    "npm",
+    "monorepo",
+    "repository",
+    "release"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/services/ci.service.d.ts

@@ -0,0 +1,38 @@
+import { type LogLevel, type PackageFilterOptions, type Repository } from 'rman';
+export declare namespace CiService {
+    type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+    interface Options extends PackageFilterOptions {
+        packageManager?: PackageManager;
+        /** Show the live progress panel while running. Default true, same as `run`/`build`; auto-disabled
+         *  when stdout isn't a TTY. Doesn't affect what's printed once done - see `run`. */
+        progress?: boolean;
+        /** Verbosity of the classic per-step log (only applies when the live panel is off). Falls back to
+         *  the root's `.rmanrc logLevel`, then 'info' - see `resolveRootLogLevel`. */
+        logLevel?: LogLevel;
+    }
+    /** `.rmanrc packageManager` (root only) picks the package manager used for the final install;
+     *  explicit CLI value wins over it. Defaults to 'npm'. */
+    function resolvePackageManager(repository: Repository, cliValue?: PackageManager): PackageManager;
+    /** Deletes `node_modules` and any known lockfile directly under `dirname`. Returns the names
+     *  that actually existed (and were removed), so the caller can log only those. */
+    function wipe(dirname: string): Promise<string[]>;
+    /**
+     * `ci`: a from-scratch, reproducible install for CI pipelines. For every package (root
+     * included), deletes `node_modules` and any lockfile - or, if the package defines its own
+     * `"ci"` script, runs that instead. Once every package is clean, installs once at the root
+     * with the configured package manager (`npm`/`yarn`/`pnpm`/`bun`).
+     *
+     * Uses the same live progress panel as `run`/`build` (see `../utils/progress-panel.ts`) while it
+     * runs, falling back to a plain rmdir/clean/run/install log line per step when the panel is off.
+     *
+     * Unlike `run`/`build`, it does *not* end with a per-package success tally: `ci`'s packages don't
+     * have independently meaningful outcomes the way a build or test run does - wiping a package is
+     * trivial and the one step that can genuinely fail, the install, is a single operation for the
+     * whole repository. Counting "N succeeded" across packages would just be noise, so only actual
+     * failures get called out (by name, with whatever output they produced), followed by one plain
+     * completed/failed line.
+     */
+    function reinstall(repository: Repository, options?: Options): Promise<void>;
+}
+declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "bun"];
+export {};