rman 2.21.1 → 2.23.0

package/builtins/publish-targets/cloudflare/cloudflare-publish.service.d.ts

@@ -0,0 +1,100 @@
+import type { Package } from '../../../core/classes/package.js';
+import { Service } from '../../../core/classes/service.js';
+import { type PublishTarget } from '../../../core/interfaces/publish-target.js';
+import { type PackageFilterOptions } from '../../../utils/package-filter.js';
+/** The name this target answers to in `publish.target` and `--target`. */
+export declare const CLOUDFLARE_TARGET = "cloudflare";
+/**
+ * Deploys packages to Cloudflare Pages or Workers through `wrangler`, once per version.
+ *
+ * **Question B, like every target**: is *this version* already deployed? Each deploy is labelled
+ * with the version - a Pages deployment's commit message is `<name>@<version>`, a Worker version's
+ * tag is `v<version>` - and the plan reads those labels back, so a release run twice deploys once.
+ */
+export declare class CloudflarePublishService extends Service {
+    /** The wrangler configuration a Worker package is looked for in, in order. */
+    protected readonly workerConfigFiles: readonly string[];
+    /**
+     * What `publish --target cloudflare` would do. Only packages naming `"cloudflare"` in their own
+     * `publish.target` are candidates. A candidate whose config is incomplete, whose working tree is
+     * dirty (unless `ignoreDirty`), or that runs without `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID`
+     * is an `'error'`; otherwise it is `'up-to-date'` when its version is already deployed and
+     * `'publish'` when it is not.
+     */
+    getPlan(options?: CloudflarePublishService.Options, deps?: CloudflarePublishService.Deps): Promise<CloudflarePublishService.Entry[]>;
+    /**
+     * Deploys every `'publish'` entry with `wrangler`, one package after another. A failure is that
+     * package's alone and is reported on its entry.
+     */
+    applyPlan(plan: CloudflarePublishService.Entry[]): Promise<CloudflarePublishService.Entry[]>;
+    /** Where and how `pkg` deploys, from its `publish.cloudflare` - or a thrown reason it cannot. */
+    protected resolveDeploy(pkg: Package): CloudflarePublishService.Deploy;
+    /** The API token and account id wrangler reads, or `undefined` when either is missing. */
+    protected credentials(): {
+        token: string;
+        accountId: string;
+    } | undefined;
+    /**
+     * Whether this version is already deployed. A check that cannot be answered - the network, an
+     * expired token - reads as "not deployed", the catch-everything shape every target's registry
+     * check has: deploying a version again is harmless, failing the run over a question is not.
+     */
+    protected isDeployed(deploy: CloudflarePublishService.Deploy): Promise<boolean>;
+    /** A Pages deployment of the project whose commit message is this version's marker. */
+    protected pagesHas(deploy: CloudflarePublishService.PagesDeploy): Promise<boolean>;
+    /** A version of the Worker tagged with this version - among the ten most recent wrangler lists. */
+    protected workerHas(deploy: CloudflarePublishService.WorkersDeploy): Promise<boolean>;
+    /** Runs the deploy, its output shown on stderr as it comes and kept for the reason if it fails. */
+    protected deploy(deploy: CloudflarePublishService.Deploy): Promise<void>;
+    /**
+     * `wrangler`, from the package's own or the repository's `node_modules` when it is installed there,
+     * and through `npx` when it is not - so a package that never added it as a dependency still
+     * deploys.
+     */
+    protected wrangler(pkg: Package, argv: string[], onLine: (line: string, stream: 'stdout' | 'stderr') => void): Promise<void>;
+}
+export declare namespace CloudflarePublishService {
+    /** Injectable "is this version deployed" check, so a spec needs neither network nor wrangler. */
+    export interface Deps {
+        isDeployed?: (deploy: Deploy) => Promise<boolean>;
+    }
+    export interface Options extends PackageFilterOptions {
+        /** A package with uncommitted local changes is excluded (`'skip'`) instead of aborting the
+         *  plan (`'error'`) - the same option every target takes. */
+        ignoreDirty?: boolean;
+    }
+    interface DeployBase {
+        pkg: Package;
+        /** `<name>@<version>` - the Pages commit message and the Worker version's message, and what
+         *  the plan looks for on a Pages project. */
+        marker: string;
+        /** What the plan prints beside the package. */
+        label: string;
+    }
+    export interface PagesDeploy extends DeployBase {
+        kind: 'pages';
+        project: string;
+        branch: string;
+        /** Absolute. */
+        directory: string;
+    }
+    export interface WorkersDeploy extends DeployBase {
+        kind: 'workers';
+        /** `v<version>` - the Worker version's tag, which the plan looks for. */
+        tag: string;
+        /** Absolute path of the wrangler configuration. */
+        config: string;
+    }
+    export type Deploy = PagesDeploy | WorkersDeploy;
+    /** One package's outcome - a `PublishTarget.Entry` carrying where it deploys. */
+    export interface Entry extends PublishTarget.Entry {
+        /** Unset only on an `'error'` entry whose config could not be read. */
+        deploy?: Deploy;
+    }
+    export {};
+}
+declare module '../../../core/classes/service.js' {
+    interface ServiceMap {
+        cloudflarePublish: CloudflarePublishService;
+    }
+}

package/builtins/publish-targets/cloudflare/cloudflare-publish.service.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Service } from '../../../core/classes/service.js';
+import { targetsOf } from '../../../core/interfaces/publish-target.js';
+import { GitHelper } from '../../../utils/git.js';
+import { filterPackages } from '../../../utils/package-filter.js';
+import { runBin } from '../../../utils/run-bin.js';
+/** The name this target answers to in `publish.target` and `--target`. */
+export const CLOUDFLARE_TARGET = 'cloudflare';
+/**
+ * Deploys packages to Cloudflare Pages or Workers through `wrangler`, once per version.
+ *
+ * **Question B, like every target**: is *this version* already deployed? Each deploy is labelled
+ * with the version - a Pages deployment's commit message is `<name>@<version>`, a Worker version's
+ * tag is `v<version>` - and the plan reads those labels back, so a release run twice deploys once.
+ */
+/* **Pages is asked through Cloudflare's API, Workers through wrangler**, and the asymmetry is
+ * wrangler's. `wrangler versions list --json` returns a version's annotations, `workers/tag`
+ * among them; `wrangler pages deployment list --json` returns id, branch, a short commit hash, url
+ * and status, and drops the commit message - measured in wrangler 4.81's own source. The API has
+ * it (`deployment_trigger.metadata.commit_message`), with the same token wrangler uses. */
+export class CloudflarePublishService extends Service {
+    /** The wrangler configuration a Worker package is looked for in, in order. */
+    workerConfigFiles = ['wrangler.jsonc', 'wrangler.json', 'wrangler.toml'];
+    /**
+     * What `publish --target cloudflare` would do. Only packages naming `"cloudflare"` in their own
+     * `publish.target` are candidates. A candidate whose config is incomplete, whose working tree is
+     * dirty (unless `ignoreDirty`), or that runs without `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID`
+     * is an `'error'`; otherwise it is `'up-to-date'` when its version is already deployed and
+     * `'publish'` when it is not.
+     */
+    async getPlan(options = {}, deps = {}) {
+        const repository = this.repository;
+        const git = new GitHelper({ cwd: repository.dirname });
+        const packages = filterPackages(repository.getPackages({ toposort: true }), options).filter(pkg => targetsOf(this.app, pkg).some(t => t.name === CLOUDFLARE_TARGET) && !pkg.config.publish?.skip);
+        const dirtyFiles = await git.listDirtyFiles({ absolute: true });
+        const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const credentials = this.credentials();
+        const isDeployed = deps.isDeployed ?? ((deploy) => this.isDeployed(deploy));
+        return Promise.all(packages.map(async (pkg) => {
+            const base = { package: pkg, version: pkg.version };
+            let deploy;
+            try {
+                deploy = this.resolveDeploy(pkg);
+            }
+            catch (e) {
+                return { ...base, status: 'error', reason: e.message };
+            }
+            const located = { ...base, deploy, detail: deploy.label };
+            if (isDirty(pkg)) {
+                return { ...located, status: options.ignoreDirty ? 'skip' : 'error', reason: 'uncommitted local changes' };
+            }
+            if (!credentials) {
+                return {
+                    ...located,
+                    status: 'error',
+                    reason: 'CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID must be set to check and deploy',
+                };
+            }
+            const deployed = await isDeployed(deploy);
+            return deployed
+                ? { ...located, status: 'up-to-date', reason: `${deploy.marker} is already deployed` }
+                : { ...located, status: 'publish', reason: 'not deployed yet' };
+        }));
+    }
+    /**
+     * Deploys every `'publish'` entry with `wrangler`, one package after another. A failure is that
+     * package's alone and is reported on its entry.
+     */
+    async applyPlan(plan) {
+        const result = [];
+        for (const entry of plan) {
+            if (entry.status !== 'publish' || !entry.deploy) {
+                result.push(entry);
+                continue;
+            }
+            try {
+                await this.deploy(entry.deploy);
+                result.push(entry);
+            }
+            catch (e) {
+                result.push({ ...entry, status: 'error', reason: e.message });
+            }
+        }
+        return result;
+    }
+    /** Where and how `pkg` deploys, from its `publish.cloudflare` - or a thrown reason it cannot. */
+    resolveDeploy(pkg) {
+        const cf = pkg.config.publish?.cloudflare;
+        if (!cf)
+            throw new Error('"cloudflare" is a publish target but "publish.cloudflare" is not configured');
+        const marker = `${pkg.name}@${pkg.version}`;
+        if (cf.kind === 'pages') {
+            const project = cf.project;
+            if (!project)
+                throw new Error('"publish.cloudflare.project" is required for kind "pages"');
+            const branch = cf.branch || 'main';
+            const directory = path.resolve(pkg.dirname, cf.directory || 'dist');
+            return { kind: 'pages', pkg, marker, project, branch, directory, label: `pages ${project} (${branch})` };
+        }
+        if (cf.kind === 'workers') {
+            const declared = cf.config;
+            const config = declared
+                ? path.resolve(pkg.dirname, declared)
+                : this.workerConfigFiles.map(f => path.join(pkg.dirname, f)).find(f => fs.existsSync(f));
+            if (!config || !fs.existsSync(config)) {
+                throw new Error(declared
+                    ? `"publish.cloudflare.config" names ${declared}, which does not exist`
+                    : `kind "workers" needs a wrangler configuration - none of ${this.workerConfigFiles.join(', ')} is in the package`);
+            }
+            return {
+                kind: 'workers',
+                pkg,
+                marker,
+                tag: `v${pkg.version}`,
+                config,
+                label: `workers ${path.relative(pkg.dirname, config)}`,
+            };
+        }
+        throw new Error(`"publish.cloudflare.kind" must be "pages" or "workers", not ${JSON.stringify(cf.kind)}`);
+    }
+    /** The API token and account id wrangler reads, or `undefined` when either is missing. */
+    credentials() {
+        const token = process.env.CLOUDFLARE_API_TOKEN;
+        const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+        return token && accountId ? { token, accountId } : undefined;
+    }
+    /**
+     * Whether this version is already deployed. A check that cannot be answered - the network, an
+     * expired token - reads as "not deployed", the catch-everything shape every target's registry
+     * check has: deploying a version again is harmless, failing the run over a question is not.
+     */
+    async isDeployed(deploy) {
+        try {
+            if (deploy.kind === 'pages')
+                return await this.pagesHas(deploy);
+            return await this.workerHas(deploy);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A Pages deployment of the project whose commit message is this version's marker. */
+    async pagesHas(deploy) {
+        const { token, accountId } = this.credentials();
+        const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/pages/projects/` +
+            `${encodeURIComponent(deploy.project)}/deployments`;
+        const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+        if (!res.ok)
+            return false;
+        const body = (await res.json());
+        return (body.result ?? []).some(d => d.deployment_trigger?.metadata?.commit_message === deploy.marker);
+    }
+    /** A version of the Worker tagged with this version - among the ten most recent wrangler lists. */
+    async workerHas(deploy) {
+        const lines = [];
+        await this.wrangler(deploy.pkg, ['versions', 'list', '--json', '--config', deploy.config], (line, stream) => {
+            if (stream === 'stdout')
+                lines.push(line);
+        });
+        const versions = JSON.parse(lines.join('\n'));
+        return versions.some(v => v.annotations?.['workers/tag'] === deploy.tag);
+    }
+    /** Runs the deploy, its output shown on stderr as it comes and kept for the reason if it fails. */
+    async deploy(deploy) {
+        if (deploy.kind === 'pages' && !fs.existsSync(deploy.directory)) {
+            throw new Error(`${path.relative(deploy.pkg.dirname, deploy.directory)} does not exist - build the package first`);
+        }
+        const argv = deploy.kind === 'pages'
+            ? [
+                'pages',
+                'deploy',
+                deploy.directory,
+                '--project-name',
+                deploy.project,
+                '--branch',
+                deploy.branch,
+                '--commit-message',
+                deploy.marker,
+                '--commit-dirty=true',
+            ]
+            : ['deploy', '--config', deploy.config, '--tag', deploy.tag, '--message', deploy.marker];
+        const lines = [];
+        try {
+            await this.wrangler(deploy.pkg, argv, line => {
+                lines.push(line);
+                process.stderr.write(line + '\n');
+            });
+        }
+        catch (e) {
+            const tail = lines.filter(l => /error|✘/i.test(l)).slice(-4);
+            throw new Error(e.message + (tail.length ? ':\n' + tail.map(l => `    ${l.trim()}`).join('\n') : ''), {
+                cause: e,
+            });
+        }
+    }
+    /**
+     * `wrangler`, from the package's own or the repository's `node_modules` when it is installed there,
+     * and through `npx` when it is not - so a package that never added it as a dependency still
+     * deploys.
+     */
+    async wrangler(pkg, argv, onLine) {
+        const options = { cwd: pkg.dirname, app: this.app, logLevel: 'silent', onLine };
+        try {
+            await runBin('wrangler', argv, options);
+        }
+        catch (e) {
+            if (!/was not found/.test(e?.message ?? ''))
+                throw e;
+            await runBin('npx', ['--yes', 'wrangler', ...argv], options);
+        }
+    }
+}

package/builtins/publish-targets/cloudflare/cloudflare.target.d.ts

@@ -0,0 +1,38 @@
+import type { PublishTarget } from '../../../core/interfaces/publish-target.js';
+import type { ConfigValue, ScopedVars } from '../../../interfaces/rman-config.interface.js';
+/**
+ * **`publish.cloudflare.*`** - this target's own config block, declared beside it and reaching
+ * `RmanConfig` through the `PublishTargetConfigs` slot `publish.command.ts` exports, as
+ * `publish.docker.*` does.
+ *
+ * Required once `"cloudflare"` is one of a package's `publish.target`s.
+ */
+export interface CloudflarePublishOptions extends CloudflarePublishOptionsKeys, ScopedVars {
+}
+export interface CloudflarePublishOptionsKeys {
+    /**
+     * What the package deploys as: `"pages"` - a directory of static files uploaded to a Pages
+     * project (`wrangler pages deploy`) - or `"workers"` - a Worker, static assets included, as its
+     * own wrangler configuration describes it (`wrangler deploy`).
+     */
+    kind: ConfigValue<'pages' | 'workers'>;
+    /** Pages: the project to deploy to. Required for `"pages"`. */
+    project?: ConfigValue<string>;
+    /** Pages: the branch the deployment is made for - the project's production branch puts it live.
+     *  Default `"main"`. */
+    branch?: ConfigValue<string>;
+    /** Pages: the directory to upload, relative to the package. Default `"dist"`. */
+    directory?: ConfigValue<string>;
+    /** Workers: the wrangler configuration file, relative to the package. Default: the first of
+     *  `wrangler.jsonc`, `wrangler.json`, `wrangler.toml` in the package. */
+    config?: ConfigValue<string>;
+}
+/**
+ * **Cloudflare, as a publish target** - a static site on Pages, or a Worker with its assets.
+ *
+ * Opt-in like `docker`, so no `claims`: a package deploys here only by naming `"cloudflare"` in
+ * its own `publish.target`. What that buys over a workflow running `wrangler` on its own is what
+ * every target gets from `publish`: `publish.skip`, `--dry-run` and `--json`, and a deploy that
+ * happens once per version rather than once per merge.
+ */
+export declare const cloudflarePublishTarget: PublishTarget;

package/builtins/publish-targets/cloudflare/cloudflare.target.js

@@ -0,0 +1,23 @@
+import { CLOUDFLARE_TARGET } from './cloudflare-publish.service.js';
+/**
+ * **Cloudflare, as a publish target** - a static site on Pages, or a Worker with its assets.
+ *
+ * Opt-in like `docker`, so no `claims`: a package deploys here only by naming `"cloudflare"` in
+ * its own `publish.target`. What that buys over a workflow running `wrangler` on its own is what
+ * every target gets from `publish`: `publish.skip`, `--dry-run` and `--json`, and a deploy that
+ * happens once per version rather than once per merge.
+ */
+/* **Last, with `docker`.** A site's build installs from the registries the other targets publish
+ * to, so it waits for what they published - the same reason `docker` runs last. */
+export const cloudflarePublishTarget = {
+    name: CLOUDFLARE_TARGET,
+    describe: 'Deploy to Cloudflare Pages or Workers (wrangler)',
+    publishesLast: true,
+    getPlan(ctx) {
+        return ctx.app.getService('cloudflarePublish').getPlan(ctx.options);
+    },
+    applyPlan(ctx, plan) {
+        /** The entries are this target's own - `getPlan` produced them. */
+        return ctx.app.getService('cloudflarePublish').applyPlan(plan);
+    },
+};

package/builtins/publish-targets/cloudflare/index.d.ts

@@ -0,0 +1,2 @@
+export * from './cloudflare.target.js';
+export * from './cloudflare-publish.service.js';

package/builtins/publish-targets/cloudflare/index.js

@@ -0,0 +1,2 @@
+export * from './cloudflare.target.js';
+export * from './cloudflare-publish.service.js';

package/commands/list.command.js

@@ -1,6 +1,7 @@
 import colors from 'ansi-colors';
 import EasyTable from 'easy-table';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
+import { fitTable } from '../utils/fit-table.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
 import { isNamedGroupKey, isSoloGroupKey, ROOT_GROUP_KEY } from '../utils/version-group.js';
 /** `[options...]` is yargs-meaningless - its variadic marker is two dots, and this command declares
@@ -185,7 +186,7 @@ function printTable(items, withRoot) {
         table.cell('Path', it.location);
         table.newRow();
     }
-    console.log(table.toString().trim());
+    console.log(fitTable(table.toString().trim(), process.stdout.isTTY ? process.stdout.columns : undefined));
     console.log('');
     console.log(colors.gray(`${items.length - (withRoot ? 1 : 0)} Package(s) found`));
 }

package/commands/publish.command.d.ts

@@ -1,3 +1,4 @@
+import type { CloudflarePublishOptions } from '../builtins/publish-targets/cloudflare/cloudflare.target.js';
 import type { DockerPublishOptions } from '../builtins/publish-targets/docker/docker.target.js';
 import type { RmanApplication } from '../core/application.js';
 import { type RmanConfig } from '../interfaces/rman-config.interface.js';
@@ -110,6 +111,9 @@ 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;
+    /** Required once `"cloudflare"` is one of a package's `publish.target`s - `kind` says Pages or
+     *  Workers. */
+    cloudflare?: CloudflarePublishOptions;
 }
 type Args = RmanConfig.ArgsOf<typeof config, typeof COMMAND>;
 /**

package/commands/version.command.d.ts

@@ -70,6 +70,11 @@ declare const config: {
      * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
      * states once, not things a single run overrides.
      */
+    skip: {
+        target: "config";
+        describe: string;
+        type: "boolean";
+    };
     commitMessage: {
         target: "config";
         describe: string;
@@ -271,6 +276,11 @@ declare const versionCommand: (app: import("../index.js").RmanApplication) => {
          * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
          * states once, not things a single run overrides.
          */
+        skip: {
+            target: "config";
+            describe: string;
+            type: "boolean";
+        };
         commitMessage: {
             target: "config";
             describe: string;

package/commands/version.command.js

@@ -4,6 +4,7 @@ import EasyTable from 'easy-table';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { VersionPlanService } from '../services/version-plan.service.js';
 import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { fitTable } from '../utils/fit-table.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
 import { isNamedGroupKey, isSoloGroupKey, ROOT_GROUP_KEY } from '../utils/version-group.js';
 /**
@@ -93,6 +94,13 @@ const config = {
      * `--message` is `commitMessage`'s flag and is declared above; the rest are settings a repository
      * states once, not things a single run overrides.
      */
+    skip: {
+        target: 'config',
+        describe: 'Whether this package takes a version at all. Unset, a package kept out of publishing ' +
+            '(publish.skip, or private) is left out; true leaves out one that publishes, false versions ' +
+            'one that does not.',
+        type: 'boolean',
+    },
     commitMessage: {
         target: 'config',
         describe: 'The commit message for each group this run commits - "{version}" is substituted when a ' +
@@ -304,7 +312,7 @@ function printPlan(entries) {
         for (const e of members)
             printPlanRow(table, e);
     }
-    console.log(table.toString().trim());
+    console.log(fitTable(table.toString().trim(), process.stdout.isTTY ? process.stdout.columns : undefined));
 }
 /**
  * The plan, split into the blocks a delimiter is drawn between: the **repository root** first, then

package/constants.js

@@ -1 +1 @@
-export const version = '2.21.1';
+export const version = '2.23.0';

package/core/application.js

@@ -1,3 +1,4 @@
+import { CloudflarePublishService, cloudflarePublishTarget } from '../builtins/publish-targets/cloudflare/index.js';
 import { DockerPublishService, dockerPublishTarget } from '../builtins/publish-targets/docker/index.js';
 import { ChangelogService } from '../services/changelog.service.js';
 import { ConfigService } from '../services/config-service.js';
@@ -93,6 +94,7 @@ export class RmanApplication {
         // Register core services.
         this.setService('config', a => new ConfigService(a));
         this.setService('changelog', a => new ChangelogService(a));
+        this.setService('cloudflarePublish', a => new CloudflarePublishService(a));
         this.setService('dockerPublish', a => new DockerPublishService(a));
         this.setService('githubRelease', a => new GithubReleaseService(a));
         this.setService('exec', a => new ExecService(a));
@@ -102,6 +104,7 @@ export class RmanApplication {
         this.setService('version', a => new VersionService(a));
         // Register core targets.
         this.publishTargets.add(dockerPublishTarget);
+        this.publishTargets.add(cloudflarePublishTarget);
     }
     /** Which platform claims a directory - the first whose manifest provider recognizes it, because
      *  before a package is read there is nothing else to go on. `basePlatform` when none does, so the

package/package.json

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

package/services/version-plan.service.d.ts

@@ -71,6 +71,12 @@ export declare abstract class VersionPlanService {
      * disagree about which commits are unreleased.
      */
     getPlan(repository: Repository, options?: VersionPlanService.Options): Promise<VersionPlanService.Entry[]>;
+    /**
+     * Why `pkg` takes no version at all, or `undefined` when it does: `.rmanrc "version.skip"` when
+     * it says so, and otherwise whether it has been kept out of publishing - `publish.skip`, or every
+     * target that ships it leaving it out (npm's `private`).
+     */
+    protected notVersionedReason(pkg: Package): string | undefined;
     /**
      * The commit a package's changes are measured **since** - its last release boundary, or
      * `undefined` for a package that has never been released (the caller then reads the whole

package/services/version-plan.service.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { RmanApplication } from '../core/application.js';
 import { assertOneScheme, semverScheme, VersionScheme } from '../core/classes/version-scheme.js';
+import { skipReasonFor, targetsOf } from '../core/interfaces/publish-target.js';
 import { GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { findLastReleaseVersion, formatCalendarVersion, usesCalendarVersion } from '../utils/release-version.js';
@@ -121,8 +122,27 @@ export class VersionPlanService {
          * `usesCalendarVersion`'s "one line" case, and the root reported `0.0.5 -> 2.1.6` on the
          * *semver* path instead of the calendar version it takes with four.
          */
-        const eligible = options.ignoreDirty ? packages.filter(pkg => !dirty.includes(pkg)) : packages;
-        for (const pkg of options.ignoreDirty ? dirty : []) {
+        /** Not versioned at all - see `notVersionedReason`. Out before `eligible`, for the reason a
+         *  skipped dirty package is: a number its group's other members get cannot come from it. */
+        const unversioned = new Map();
+        for (const pkg of packages) {
+            const reason = this.notVersionedReason(pkg);
+            if (reason)
+                unversioned.set(pkg, reason);
+        }
+        for (const [pkg, reason] of unversioned) {
+            entries.set(pkg.name, {
+                package: pkg,
+                groupKey: this.resolveGroupKey(pkg),
+                group: this.groupLabel(this.resolveGroupKey(pkg)),
+                status: 'skip',
+                from: pkg.version,
+                reason,
+            });
+        }
+        const versioned = packages.filter(pkg => !unversioned.has(pkg));
+        const eligible = options.ignoreDirty ? versioned.filter(pkg => !dirty.includes(pkg)) : versioned;
+        for (const pkg of options.ignoreDirty ? dirty.filter(d => !unversioned.has(d)) : []) {
             entries.set(pkg.name, {
                 package: pkg,
                 groupKey: this.resolveGroupKey(pkg),
@@ -185,7 +205,8 @@ export class VersionPlanService {
         if (!options.ignoreDirty) {
             for (const pkg of dirty) {
                 const entry = entries.get(pkg.name);
-                if (!entry)
+                /** A package that is not versioned has nothing to protect from a dirty tree. */
+                if (!entry || unversioned.has(pkg))
                     continue;
                 entry.status = 'error';
                 entry.reason = entry.reason ? `uncommitted local changes (${entry.reason})` : 'uncommitted local changes';
@@ -193,6 +214,46 @@ export class VersionPlanService {
         }
         return result;
     }
+    /**
+     * Why `pkg` takes no version at all, or `undefined` when it does: `.rmanrc "version.skip"` when
+     * it says so, and otherwise whether it has been kept out of publishing - `publish.skip`, or every
+     * target that ships it leaving it out (npm's `private`).
+     */
+    /* **A version nothing publishes is a number nobody can install**, and that is the user's reason
+     * for reversing the old rule that `version` never reads `publish.skip`. Measured on
+     * `panates/syncbridge`: fourteen packages kept out of publishing were still bumped, tagged and
+     * written into changelogs on every release - tags with nothing on the registry behind them, and a
+     * version line that had jumped by the time publishing was switched back on.
+     *
+     * `version.skip` decides first, both ways: `true` holds back a package that does publish, `false`
+     * versions one that does not - an application deployed by other means, whose number still
+     * matters. A monorepo's root never reaches here; its version is the repository's release
+     * identity, decided by `buildRootEntry`.
+     *
+     * **A package no target ships to is still versioned**, deliberately. Tried the other way first,
+     * and it stopped versioning every package of a repository that has no publish target at all - one
+     * that versions with rman and publishes by other means, or a technology rman has no target for -
+     * which is most of the core's own spec fixtures. Only a package kept out *on purpose* is left
+     * out. */
+    notVersionedReason(pkg) {
+        const declared = pkg.config.version?.skip;
+        if (declared === true)
+            return 'excluded via .rmanrc "version.skip"';
+        if (declared === false)
+            return undefined;
+        if (pkg.config.publish?.skip)
+            return 'not published - .rmanrc "publish.skip"';
+        const app = pkg.repository?.app;
+        if (!app)
+            return undefined;
+        const targets = targetsOf(app, pkg);
+        if (!targets.length)
+            return undefined;
+        const reasons = targets.map(target => skipReasonFor(pkg, target));
+        if (reasons.every(Boolean))
+            return `not published - ${reasons[0]}`;
+        return undefined;
+    }
     /**
      * **Which planner answers for one package: its own technology's.**
      *
@@ -468,7 +529,9 @@ export class VersionPlanService {
             const source = worklist.shift();
             for (const pkg of packages) {
                 const entry = entries.get(pkg.name);
-                if (entry.status === 'bump' || entry.groupKey === source.groupKey)
+                /** A skipped package stays skipped: it is out of the release on purpose (not published, or
+                 *  dirty under `--ignore-dirty`), and a dependency moving does not change that. */
+                if (entry.status === 'bump' || entry.status === 'skip' || entry.groupKey === source.groupKey)
                     continue;
                 if (!pkg.dependencies.includes(source.package))
                     continue;

package/utils/fit-table.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A rendered `easy-table` fitted to a terminal `columns` wide: a row wider than that has its **last
+ * column** continued on further lines, each starting at that column, and a delimiter line is cut at
+ * the edge. Anything that already fits is left exactly as it was.
+ *
+ * `columns` is `undefined` when the output is not a terminal, and then nothing changes - a file or a
+ * pipe has no edge to wrap at, and a reader of one wants each row on one line.
+ */
+export declare function fitTable(text: string, columns: number | undefined): string;

package/utils/fit-table.js

@@ -0,0 +1,92 @@
+/**
+ * A rendered `easy-table` fitted to a terminal `columns` wide: a row wider than that has its **last
+ * column** continued on further lines, each starting at that column, and a delimiter line is cut at
+ * the edge. Anything that already fits is left exactly as it was.
+ *
+ * `columns` is `undefined` when the output is not a terminal, and then nothing changes - a file or a
+ * pipe has no edge to wrap at, and a reader of one wants each row on one line.
+ */
+/* **The terminal wrapping it is what this replaces**, and what that did to a table: measured on
+ * `panates/syncbridge`, `rman version`'s root row carries a 70-character reason, so the row and the
+ * delimiter under the header - as wide as the widest cell - both ran past the edge and continued at
+ * column 0, breaking the table into lines the eye could not follow.
+ *
+ * **Only the last column moves**, because it is the free-text one in every table rman prints
+ * (`Reason`, `Path`) - the columns before it are short, fixed values whose alignment is the point.
+ * Where it starts is read off the first delimiter line easy-table draws, the one place the column
+ * boundaries are spelled out without colour codes in the way.
+ *
+ * A row whose last column would get fewer than `MIN_WIDTH` characters is left alone: wrapping into a
+ * sliver is worse than the terminal's own wrap. */
+export function fitTable(text, columns) {
+    if (!columns)
+        return text;
+    const lines = text.split('\n');
+    const delimiter = lines.find(line => /^[\s-]*-[\s-]*$/.test(line));
+    if (!delimiter)
+        return text;
+    const start = delimiter.search(/-+\s*$/);
+    const width = columns - start;
+    /** Every cell is padded to its column, the last one included, so a row of short text is still as
+     *  wide as the widest - past the edge, those spaces wrapped into a blank line under each row.
+     *  Trimmed and cut even where the last column is too narrow to wrap into. */
+    const trimmed = lines.map(line => (/^[\s-]+$/.test(line) ? line.slice(0, columns) : line.trimEnd()));
+    if (start <= 0 || width < MIN_WIDTH)
+        return trimmed.join('\n');
+    return trimmed
+        .flatMap(line => {
+        if (visibleLength(line) <= columns)
+            return [line];
+        const at = rawIndexOf(line, start);
+        const head = line.slice(0, at);
+        const tail = line.slice(at);
+        /** A cell painted as a whole (`colors.gray(reason)`) keeps its colour on every line. */
+        // eslint-disable-next-line no-control-regex
+        const paint = /^(?:\x1b\[[0-9;]*m)+/.exec(tail)?.[0] ?? '';
+        const chunks = wrapWords(stripAnsi(tail), width);
+        const pad = ' '.repeat(start);
+        return chunks.map((chunk, i) => (i ? pad : head) + (paint ? `${paint}${chunk}\x1b[0m` : chunk));
+    })
+        .join('\n');
+}
+const MIN_WIDTH = 20;
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+function stripAnsi(text) {
+    return text.replace(ANSI, '');
+}
+function visibleLength(text) {
+    return stripAnsi(text).length;
+}
+/** The index in `line` of its `visible`-th visible character, colour codes skipped. */
+function rawIndexOf(line, visible) {
+    let seen = 0;
+    let i = 0;
+    while (i < line.length && seen < visible) {
+        if (line[i] === '\x1b') {
+            const end = line.indexOf('m', i);
+            i = end < 0 ? line.length : end + 1;
+            continue;
+        }
+        seen++;
+        i++;
+    }
+    /** Colour codes sitting right at the boundary belong to the cell after it. */
+    return i;
+}
+/** `text` cut at spaces into lines of at most `width` - a word longer than that on a line of its own. */
+function wrapWords(text, width) {
+    const lines = [];
+    let current = '';
+    for (const word of text.trim().split(/\s+/)) {
+        if (current && current.length + 1 + word.length > width) {
+            lines.push(current);
+            current = word;
+        }
+        else
+            current = current ? `${current} ${word}` : word;
+    }
+    if (current)
+        lines.push(current);
+    return lines;
+}