rman 1.0.1 → 1.0.4

package/README.md

@@ -2,14 +2,14 @@
 
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
-[![Quality Check][qc-image]][qc-url]
-[![License][license-image]][license-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
 
 **rman** is a monorepo management CLI: a self-contained alternative to reaching for Lerna,
 Changesets, and a handful of shell scripts glued together. One tool for running scripts across
 packages, computing semantic version bumps from your commit history, publishing, changelogs,
 importing external repos with history intact, and more - all driven by a single, cascading
-`.rmanrc`/`.rman.yml` config.
+`.rmanrc`/`.rmanrc.yml` config.
 
 Every command is also available as a **programmatic API** - see [docs/api.md](docs/api.md) if you
 want to call `rman`'s logic directly from a Node.js script instead of shelling out to the CLI.
@@ -243,6 +243,7 @@ rman version --changelog         # also write/fold in each bumped package's CHAN
 rman version patch --push        # commit, tag, and push in one go
 rman version patch --message "chore(release): {version}"
 rman version --ignore-dirty      # exclude dirty packages instead of aborting the whole run
+rman version patch --show        # preview what an explicit patch bump would do, without applying it
 ```
 
 Severity, when not given explicitly, is auto-detected per package/group from
@@ -298,12 +299,13 @@ covered, then run `rman ci` to install it.
 
 `rman` reads config cascaded from the repository root down to each package's own directory (the
 same way a `tsconfig.json` `extends` chain works) - a value set closer to a package overrides the
-same key set further up. Three file forms are supported per directory, merged in increasing
-precedence: `package.json`'s own `"rman"` key, `.rman.yml` (YAML), and `.rmanrc` (**JSON**, despite
-the dotfile-style name).
+same key set further up. Several file forms are supported per directory, merged in increasing
+precedence: `package.json`'s own `"rman"` key, `.rmanrc.yml` (YAML), `.rmanrc` (**JSON**, despite
+the dotfile-style name), and `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` for config that needs real
+logic (a JS module's default export).
 
 ```yaml
-# .rman.yml, at the repository root
+# .rmanrc.yml, at the repository root
 packageManager: pnpm
 logLevel: info
 allowBranch: [main, release/*]
@@ -337,10 +339,26 @@ run:
 { "group": "plugins" }
 ```
 
-See [docs/api.md#configuration-rmanrc-rmanyml](docs/api.md#configuration-rmanrc-rmanyml) for the
+See [docs/api.md#configuration-rmanrc-rmanrcyml](docs/api.md#configuration-rmanrc-rmanrcyml) for the
 full key reference (every `run.<script>.*` sub-key, `clean.*`, `changelog.*`, precedence rules,
 and which keys are root-level-only today).
 
+**Editor autocomplete:** `rman` ships a JSON Schema for `.rmanrc`/`.rmanrc.yml` at
+`rman/rmanrc.schema.json` - add `"$schema": "./node_modules/rman/rmanrc.schema.json"` to your
+`.rmanrc` (or the equivalent `# yaml-language-server: $schema=...` comment in `.rmanrc.yml`) to get
+autocomplete and validation in VS Code/WebStorm. For a `.rmanrc.cjs`/`.mjs`/`.js` config, wrap it in
+the exported `defineConfig()` helper instead for the same autocomplete via the `RmanConfig` type:
+
+```js
+// .rmanrc.mjs
+import { defineConfig } from 'rman';
+export default defineConfig({ packageManager: 'pnpm' });
+```
+
+See
+[docs/api.md#editor-support-json-schema](docs/api.md#editor-support-json-schema) for details,
+including a WebStorm setup that needs no changes to the config file itself.
+
 ## Programmatic API
 
 Every command above is a thin wrapper around an exported service function - call them directly
@@ -349,7 +367,7 @@ from your own Node.js scripts without shelling out to the `rman` binary:
 ```ts
 import { Repository, VersionService } from 'rman';
 
-const repository = Repository.create();
+const repository = await Repository.create();
 const plan = await VersionService.getPlan(repository);
 await VersionService.applyPlan(repository, plan, { changelog: true, push: true });
 ```
@@ -366,11 +384,11 @@ Full reference, with detailed examples for every service (`VersionService`, `Pub
 
 rman is available under the [MIT](LICENSE) license.
 
-[npm-image]: https://img.shields.io/npm/v/rman.svg
+[npm-image]: https://img.shields.io/npm/v/rman
 [npm-url]: https://npmjs.org/package/rman
 [downloads-image]: https://img.shields.io/npm/dm/rman.svg
 [downloads-url]: https://npmjs.org/package/rman
-[qc-image]: https://github.com/panates/rman/actions/workflows/qc.yml/badge.svg
-[qc-url]: https://github.com/panates/rman/actions/workflows/qc.yml
-[license-image]: https://img.shields.io/npm/l/rman.svg
-[license-url]: https://github.com/panates/rman/blob/main/LICENSE
+[ci-test-image]: https://github.com/panates/rman/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/rman/actions/workflows/test.yml
+[coveralls-image]: https://img.shields.io/coveralls/panates/rman/dev.svg
+[coveralls-url]: https://coveralls.io/r/panates/rman

package/cli.js

@@ -23,10 +23,10 @@ import { Repository } from './core/repository.js';
 import { LOG_LEVELS } from './utils/logger.js';
 export async function runCli(options) {
     try {
-        const repository = Repository.create(options?.cwd);
+        const repository = await Repository.create(options?.cwd);
         const _argv = options?.argv || hideBin(process.argv);
         const program = yargs(_argv)
-            .scriptName('rman2')
+            .scriptName('rman')
             .version(version)
             .alias('version', 'v')
             .usage('$0 <cmd> [options...]')

package/commands/version.command.js

@@ -11,6 +11,7 @@ export function initCli(repository, program) {
             .example('$0 version patch', '# Bump patch severity directly, applied immediately')
             .example('$0 version', "# Auto-detect severity from commits, show the plan, don't write anything")
             .example('$0 version --interactive', '# Show the plan either way, then ask for confirmation')
+            .example('$0 version patch --show', '# Preview what an explicit patch bump would do, without applying it')
             .positional('bump', {
             describe: 'A release-type keyword ("patch"/"minor"/"major") or an explicit semver version. ' +
                 'Omit to auto-detect from commits and only preview the plan.',
@@ -21,6 +22,13 @@ export function initCli(repository, program) {
             describe: 'Show the plan and ask for confirmation before applying (with or without an explicit bump)',
             type: 'boolean',
         })
+            .option('show', {
+            describe: 'Show the resulting plan for the given bump without applying it - unlike omitting bump ' +
+                'entirely, this still uses the given release-type keyword/version to compute the plan, ' +
+                'just never writes it.',
+            type: 'boolean',
+        })
+            .conflicts('show', 'interactive')
             .option('ignore-dirty', {
             describe: 'Exclude a package with uncommitted local changes instead of aborting the whole run',
             type: 'boolean',
@@ -70,6 +78,10 @@ export function initCli(repository, program) {
                 console.log(colors.gray('Nothing to version.'));
                 return;
             }
+            if (args.show) {
+                console.log(colors.gray('Preview only (--show) - nothing was written.'));
+                return;
+            }
             let apply = !!bump;
             if (args.interactive) {
                 apply = await confirm('Apply these changes?');

package/constants.js

@@ -1 +1 @@
-export const version = '1.0.1';
+export const version = '1.0.4';

package/core/config.d.ts

@@ -1,8 +1,82 @@
+/**
+ * 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;
+    /** 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>;
+    }
+}
+/**
+ * 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
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export declare function defineConfig(config: RmanConfig): RmanConfig;
 /**
  * Reads the rman configuration defined at a single directory level, merging
- * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
+ * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
  */
-export declare function readDirConfig(dirname: string): any;
+export declare function readDirConfig(dirname: string): Promise<RmanConfig>;
 /**
  * Resolves the effective config for `targetDir` by cascading from `rootDir`
  * down to `targetDir` (inclusive), the same way tsconfig's `extends` chain
@@ -10,4 +84,4 @@ export declare function readDirConfig(dirname: string): any;
  * package (or any intermediate directory) narrow or override the repository's
  * root configuration for itself and everything below it.
  */
-export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, any>): any;
+export declare function resolveConfig(rootDir: string, targetDir: string, cache?: Map<string, RmanConfig>): Promise<RmanConfig>;

package/core/config.js

@@ -1,12 +1,60 @@
 import fs from 'fs';
 import * as yaml from 'js-yaml';
+import { createRequire } from 'module';
 import path from 'path';
 import merge from 'putil-merge';
+import { pathToFileURL } from 'url';
+/**
+ * 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
+ * unchanged; this exists purely so TypeScript can infer/check against `RmanConfig`, not for any
+ * runtime behavior:
+ *
+ *   // .rmanrc.mjs
+ *   import { defineConfig } from 'rman';
+ *   export default defineConfig({ packageManager: 'pnpm' });
+ *
+ *   // .rmanrc.cjs
+ *   const { defineConfig } = require('rman');
+ *   module.exports = defineConfig({ packageManager: 'pnpm' });
+ */
+export function defineConfig(config) {
+    return config;
+}
+/** `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js`, checked in this order - a JS module whose default
+ *  export (or, lacking one, the module's own exports object) is the config. Both CommonJS (`.cjs`,
+ *  or a `.js` under a `"type": "commonjs"` package.json) and native ESM (`.mjs`, or a `.js` under
+ *  `"type": "module"`) are supported - the reason `readDirConfig`/`resolveConfig` are async at all. */
+const JS_CONFIG_FILES = ['.rmanrc.cjs', '.rmanrc.mjs', '.rmanrc.js'];
+const requireJsConfig = createRequire(import.meta.url);
+/**
+ * Loads `file`'s config object. Tries `require()` first - not just an optimization: a CommonJS
+ * module's `module.exports` is more reliably observed this way than through dynamic `import()`'s
+ * CJS-interop synthesis, which some ESM loader hooks (e.g. ts-node/swc-node-style transpilers
+ * registered via `--import`) can end up short-circuiting into an empty object. `require()` throws
+ * `ERR_REQUIRE_ESM` for a genuinely-ESM file (`.mjs`, or `.js` under `"type": "module"`) - only
+ * then does this fall back to `import()`, the one case that actually needs it. Either path can
+ * hand back an ES module namespace instead of a plain object (Node's `require(esm)` support does
+ * this too, not just `import()`), so `.default` is preferred whenever present.
+ */
+async function loadJsConfig(file) {
+    let mod;
+    try {
+        mod = requireJsConfig(file);
+    }
+    catch (e) {
+        if (e?.code !== 'ERR_REQUIRE_ESM')
+            throw e;
+        mod = await import(pathToFileURL(file).href);
+    }
+    return mod?.default ?? mod;
+}
 /**
  * Reads the rman configuration defined at a single directory level, merging
- * (in increasing precedence): `package.json#rman`, `.rman.yml`, `.rmanrc`.
+ * (in increasing precedence): `package.json#rman`, `.rmanrc.yml`, `.rmanrc`,
+ * then `.rmanrc.cjs`/`.rmanrc.mjs`/`.rmanrc.js` (whichever exist, in that order).
  */
-export function readDirConfig(dirname) {
+export async function readDirConfig(dirname) {
     const result = {};
     const pkgJsonFile = path.join(dirname, 'package.json');
     if (fs.existsSync(pkgJsonFile)) {
@@ -14,7 +62,7 @@ export function readDirConfig(dirname) {
         if (pkgJson && typeof pkgJson.rman === 'object')
             merge(result, pkgJson.rman, { deep: true });
     }
-    const ymlFile = path.join(dirname, '.rman.yml');
+    const ymlFile = path.join(dirname, '.rmanrc.yml');
     if (fs.existsSync(ymlFile)) {
         const obj = yaml.load(fs.readFileSync(ymlFile, 'utf-8'));
         if (obj && typeof obj === 'object')
@@ -26,6 +74,14 @@ export function readDirConfig(dirname) {
         if (obj && typeof obj === 'object')
             merge(result, obj, { deep: true });
     }
+    for (const jsFileName of JS_CONFIG_FILES) {
+        const jsFile = path.join(dirname, jsFileName);
+        if (fs.existsSync(jsFile)) {
+            const obj = await loadJsConfig(jsFile);
+            if (obj && typeof obj === 'object')
+                merge(result, obj, { deep: true });
+        }
+    }
     return result;
 }
 /**
@@ -35,12 +91,12 @@ export function readDirConfig(dirname) {
  * package (or any intermediate directory) narrow or override the repository's
  * root configuration for itself and everything below it.
  */
-export function resolveConfig(rootDir, targetDir, cache = new Map()) {
+export async function resolveConfig(rootDir, targetDir, cache = new Map()) {
     const result = {};
     for (const dir of dirChain(rootDir, targetDir)) {
         let local = cache.get(dir);
         if (!local) {
-            local = readDirConfig(dir);
+            local = await readDirConfig(dir);
             cache.set(dir, local);
         }
         merge(result, local, { deep: true });

package/core/package.d.ts

@@ -1,9 +1,10 @@
+import type { RmanConfig } from './config.js';
 export declare class Package {
     readonly dirname: string;
     private _json;
     dependencies: string[];
     /** Effective rman config for this package, cascaded from the repository root. */
-    config: any;
+    config: RmanConfig;
     constructor(dirname: string);
     get basename(): string;
     get name(): string;

package/core/repository.d.ts

@@ -41,11 +41,15 @@ export declare class Repository extends Package {
      * package, cascading root -> intermediate directories -> package directory,
      * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
      */
-    protected _resolveConfigs(): void;
+    protected _resolveConfigs(): Promise<void>;
     protected _updateDependencies(): void;
     static create(root?: string, options?: {
         deep?: number;
-    }): Repository;
+    }): Promise<Repository>;
+    /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
+     *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
+     *  before the dependency graph is built from it. */
+    private static _init;
     protected static _resolvePackages(dirname: string, patterns: string[]): Package[];
 }
 export declare namespace Repository {

package/core/repository.js

@@ -23,8 +23,9 @@ export class Repository extends Package {
         this.rootPackage = new Package(dirname);
         if (!monorepo)
             this.packages = [this.rootPackage];
-        this._resolveConfigs();
-        this._updateDependencies();
+        // Config resolution can load a `.rmanrc.cjs`/`.mjs`/`.js` module (dynamic `import()`, always
+        // async) - a constructor can't `await`, so `create()` finishes this instance off via `_init()`
+        // once construction itself (synchronous) completes.
     }
     /**
      * The package whose own directory contains `cwd` (the deepest match, so a package nested
@@ -90,15 +91,15 @@ export class Repository extends Package {
      * package, cascading root -> intermediate directories -> package directory,
      * so a `.rmanrc` placed anywhere along that path overrides the levels above it.
      */
-    _resolveConfigs() {
+    async _resolveConfigs() {
         const cache = new Map();
-        const rootConfig = resolveConfig(this.dirname, this.dirname, cache);
+        const rootConfig = await resolveConfig(this.dirname, this.dirname, cache);
         this.config = rootConfig;
         this.rootPackage.config = rootConfig;
         for (const pkg of this.packages) {
             if (pkg === this.rootPackage)
                 continue;
-            pkg.config = resolveConfig(this.dirname, pkg.dirname, cache);
+            pkg.config = await resolveConfig(this.dirname, pkg.dirname, cache);
         }
     }
     _updateDependencies() {
@@ -149,7 +150,7 @@ export class Repository extends Package {
             deepFindDependencies(pkg, pkg.dependencies);
         }
     }
-    static create(root, options) {
+    static async create(root, options) {
         const dirname = root || process.cwd();
         let deep = options?.deep ?? 10;
         let pkgDirname = dirname;
@@ -159,7 +160,7 @@ export class Repository extends Package {
                 const pkgJson = JSON.parse(fs.readFileSync(f, 'utf-8'));
                 if (Array.isArray(pkgJson.workspaces)) {
                     const packages = this._resolvePackages(pkgDirname, pkgJson.workspaces);
-                    return new Repository(pkgDirname, true, packages, dirname);
+                    return Repository._init(new Repository(pkgDirname, true, packages, dirname));
                 }
                 /** If we reach to the root of the project */
                 if (fs.existsSync(path.join(pkgDirname, '.git')))
@@ -167,7 +168,15 @@ export class Repository extends Package {
             }
             pkgDirname = path.resolve(pkgDirname, '..');
         }
-        return new Repository(dirname, false, [], dirname);
+        return Repository._init(new Repository(dirname, false, [], dirname));
+    }
+    /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
+     *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
+     *  before the dependency graph is built from it. */
+    static async _init(repo) {
+        await repo._resolveConfigs();
+        repo._updateDependencies();
+        return repo;
     }
     static _resolvePackages(dirname, patterns) {
         const packages = [];

package/index.d.ts

@@ -8,6 +8,8 @@
  * 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 './services.js';

package/index.js

@@ -1,13 +1,4 @@
-/**
- * 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 './services.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rman",
   "description": "Repository manager",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "author": "Panates",
   "license": "MIT",
   "dependencies": {
@@ -35,7 +35,8 @@
       "types": "./index.d.ts",
       "default": "./index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./rmanrc.schema.json": "./rmanrc.schema.json"
   },
   "bin": {
     "rman": "cli.js"

package/rmanrc.schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/panates/rman/main/schemas/rmanrc.schema.json",
+  "title": "rman configuration",
+  "description": "Schema for rman's .rmanrc (JSON) and .rmanrc.yml (YAML) config files, and the \"rman\" key in package.json. See docs/api.md#configuration-rmanrc-rmanrcyml for the full reference.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path/URL to this schema - not read by rman itself, purely for editor tooling."
+    },
+    "packageManager": {
+      "type": "string",
+      "enum": ["npm", "yarn", "pnpm", "bun"],
+      "default": "npm",
+      "description": "Package manager used by \"ci\"/\"publish\". Root-level only - an explicit --package-manager CLI flag wins over this."
+    },
+    "logLevel": {
+      "$ref": "#/definitions/logLevel",
+      "default": "info",
+      "description": "Default verbosity of the classic per-step log for run/build/test/ci/clean. Root-level only. An explicit --log-level CLI flag wins over this."
+    },
+    "allowBranch": {
+      "$ref": "#/definitions/stringOrStringArray",
+      "description": "Refuse to run a state-changing command unless the current git branch matches one of these globs. Root-level only. An explicit --allow-branch CLI flag replaces this entirely (never merges)."
+    },
+    "ignoreBranch": {
+      "$ref": "#/definitions/stringOrStringArray",
+      "description": "Refuse to run a state-changing command if the current git branch matches one of these globs. Root-level only. An explicit --ignore-branch CLI flag replaces this entirely (never merges)."
+    },
+    "group": {
+      "description": "Release-versioning group for \"version\"/\"publish\": true (default) puts the package in the implicit repo-wide group; a string joins exactly the other packages sharing that string; false makes it a solo, fully independent group. Per-package cascaded.",
+      "default": true,
+      "oneOf": [{ "type": "boolean" }, { "type": "string", "minLength": 1 }]
+    },
+    "version": {
+      "type": "object",
+      "description": "Options for the \"version\" command/VersionService.",
+      "additionalProperties": false,
+      "properties": {
+        "commitMessage": {
+          "type": "string",
+          "default": "chore(release): v{version}",
+          "description": "Commit message for every group a \"version\" run commits. \"{version}\" is substituted when every bumped package in that commit shares one version. Root-level only."
+        },
+        "script": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"version\" npm-lifecycle step, when its package.json does not define one itself."
+        },
+        "preScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"preversion\" step, when its package.json does not define one itself."
+        },
+        "postScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"postversion\" step, when its package.json does not define one itself."
+        }
+      }
+    },
+    "changelog": {
+      "type": "object",
+      "description": "Options for the \"changelog\" command/ChangelogService, and for \"version --changelog\".",
+      "additionalProperties": false,
+      "properties": {
+        "ignoreTypes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Conventional Commit types (e.g. \"chore\", \"ci\") dropped entirely from changelog output, instead of being folded into \"Other Changes\". Per-package cascaded."
+        },
+        "template": {
+          "type": "string",
+          "description": "Path (relative to the repository root) to a changelog template file - not the template text itself. Supports {{package}}/{{version}}/{{date}}/{{commits}} and {{features}}/{{fixes}}/{{other}}. Per-package cascaded."
+        },
+        "filePath": {
+          "type": "string",
+          "default": "CHANGELOG.md",
+          "description": "Where \"--write\" prepends this package's entry, relative to that package's own directory. Per-package cascaded."
+        },
+        "tagPattern": {
+          "type": "string",
+          "default": "v*",
+          "description": "Glob for this package's release tags. Include \"{name}\" for independent per-package tags (e.g. \"{name}@*\"); omit it for one shared repo-wide tag scheme. Per-package cascaded."
+        }
+      }
+    },
+    "clean": {
+      "type": "object",
+      "description": "Options for the \"clean\" command/CleanService.",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Extra glob(s) to remove, resolved relative to this package's own directory. Per-package cascaded (a package's own value replaces the root's, it does not merge)."
+        },
+        "exclude": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Glob(s) protected from \"include\" (and from the built-in TypeScript-artifact cleanup), relative to this package's own directory. Per-package cascaded."
+        },
+        "skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "Opts this package out of \"clean\" entirely. Per-package cascaded."
+        }
+      }
+    },
+    "run": {
+      "type": "object",
+      "description": "Per-script options for \"run\"/\"build\"/\"test\"/RunService, keyed by npm script name (e.g. \"build\", \"lint\", \"test\").",
+      "additionalProperties": { "$ref": "#/definitions/runScriptConfig" }
+    },
+    "packages": {
+      "type": "object",
+      "description": "Per-package overrides, keyed by the in-repo package's own name.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "dependencies": {
+            "description": "Extra in-repo \"dependencies\" not present in this package's real package.json, purely for rman's own dependency graph (topo-sort, --deps/--dependents, run's task scheduling). An array defaults each entry's range to \"*\"; an object gives an explicit name -> range map.",
+            "oneOf": [
+              { "type": "array", "items": { "type": "string" } },
+              { "type": "object", "additionalProperties": { "type": "string" } }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "logLevel": {
+      "type": "string",
+      "enum": ["silent", "error", "info", "verbose"]
+    },
+    "stringOrStringArray": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      ]
+    },
+    "runScriptConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Max packages built at once for this script. Default: CPU count."
+        },
+        "topo": {
+          "type": "boolean",
+          "default": true,
+          "description": "Respect the package dependency graph: a package waits for its dependencies and is skipped if one fails. Set false for independent scripts (lint/test) - alphabetical order, no failure skipping."
+        },
+        "bail": {
+          "type": "boolean",
+          "default": true,
+          "description": "Stop the whole batch on this package's own failure. Unusual precedence: this package-level value outranks even an explicit CLI --bail/--no-bail flag."
+        },
+        "progress": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show the live progress panel for this script (auto-disabled off a TTY)."
+        },
+        "logLevel": {
+          "$ref": "#/definitions/logLevel",
+          "description": "Verbosity of the classic per-step log for this package/script, when the live panel is off."
+        },
+        "changedSince": {
+          "type": "string",
+          "description": "Root-level fallback commit/hash for \"--changed-since\", used only when the CLI flag is not given."
+        },
+        "skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "Excludes this package (or the repository root's own pre/post hooks) from running this script entirely."
+        },
+        "if": {
+          "type": "string",
+          "description": "Conditional-execution expression: atoms \"changed\"/\"dirty\"/\"committed\" (optionally \"= <hash>\" or \"= {ENV_VAR}\"), combined with and/or/not/(...). E.g. \"changed\", \"(changed or dirty) and not committed\"."
+        },
+        "script": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own script, when its package.json does not define one for this script name."
+        },
+        "preScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"pre<script>\" hook, when its package.json does not define one."
+        },
+        "postScript": {
+          "$ref": "#/definitions/stringOrStringArray",
+          "description": "Command(s) to run as this package's own \"post<script>\" hook, when its package.json does not define one."
+        },
+        "override": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, \"script\"/\"preScript\"/\"postScript\" above replace the package's own package.json definition even when it already has one."
+        }
+      }
+    }
+  }
+}