rman 2.23.0 → 2.24.0

package/builtins/platforms/node/node-config.interface.d.ts

@@ -1,3 +1,4 @@
+import type { PublishFilesKeys } from '../../../core/interfaces/publish-target.js';
 import type { ConfigValue, RmanConfig, ScopedVars } from '../../../interfaces/rman-config.interface.js';
 import type { CiService } from './services/ci.service.js';
 /**
@@ -26,7 +27,7 @@ export declare namespace RmanNodeConfig {
      */
     interface NpmPublishOptions extends NpmPublishOptionsKeys, ScopedVars {
     }
-    interface NpmPublishOptionsKeys {
+    interface NpmPublishOptionsKeys extends PublishFilesKeys {
         /** 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

package/builtins/platforms/node/services/publish.service.js

@@ -17,7 +17,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { exec } from '../../../../utils/exec.js';
-import { GitHelper } from '../../../../utils/git.js';
+import { dirtyReason, filesUnder, GitHelper } from '../../../../utils/git.js';
 import { filterPackages } from '../../../../utils/package-filter.js';
 import { isCalendarVersion } from '../../../../utils/release-version.js';
 import { npmViewPackage } from '../../../publish-targets/npm/npm-view.js';
@@ -197,7 +197,7 @@ export var PublishService;
         const git = new GitHelper({ cwd: repository.dirname });
         const packages = filterPackages(repository.getPackages({ toposort: true }), options).filter(pkg => options.shipsHere?.(pkg) ?? true);
         const dirtyFiles = await git.listDirtyFiles({ absolute: true });
-        const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const isDirty = (pkg) => filesUnder(dirtyFiles, pkg.dirname).length > 0;
         /** Per package, not per run: `resolveRegistry` reads the package's own `publishConfig.registry`
          *  when `--registry` was not given, so the question is asked where the answer lives. The test
          *  seam keeps its `(name, cwd)` shape - a stub answers from a map and has no registry to
@@ -250,7 +250,7 @@ export var PublishService;
                     package: pkg,
                     version: pkg.version,
                     status: options.ignoreDirty ? 'skip' : 'error',
-                    reason: 'uncommitted local changes',
+                    reason: dirtyReason(filesUnder(dirtyFiles, pkg.dirname), repository.dirname),
                 });
             }
             else {

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

@@ -46,6 +46,9 @@ export declare class CloudflarePublishService extends Service {
     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>;
+    /** `--env <name>` when the Worker deploys to a named wrangler environment - for the deploy and for
+     *  the versions list, which would otherwise ask about a different Worker. */
+    protected envArgs(deploy: CloudflarePublishService.WorkersDeploy): string[];
     /**
      * `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
@@ -84,6 +87,10 @@ export declare namespace CloudflarePublishService {
         tag: string;
         /** Absolute path of the wrangler configuration. */
         config: string;
+        /** The wrangler environment, when one is named. */
+        env?: string;
+        /** `--var` entries. */
+        variables: Record<string, string>;
     }
     export type Deploy = PagesDeploy | WorkersDeploy;
     /** One package's outcome - a `PublishTarget.Entry` carrying where it deploys. */

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

@@ -2,7 +2,7 @@ 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 { dirtyReason, filesUnder, 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`. */
@@ -34,7 +34,7 @@ export class CloudflarePublishService extends Service {
         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 isDirty = (pkg) => filesUnder(dirtyFiles, pkg.dirname).length > 0;
         const credentials = this.credentials();
         const isDeployed = deps.isDeployed ?? ((deploy) => this.isDeployed(deploy));
         return Promise.all(packages.map(async (pkg) => {
@@ -48,7 +48,11 @@ export class CloudflarePublishService extends Service {
             }
             const located = { ...base, deploy, detail: deploy.label };
             if (isDirty(pkg)) {
-                return { ...located, status: options.ignoreDirty ? 'skip' : 'error', reason: 'uncommitted local changes' };
+                return {
+                    ...located,
+                    status: options.ignoreDirty ? 'skip' : 'error',
+                    reason: dirtyReason(filesUnder(dirtyFiles, pkg.dirname), repository.dirname),
+                };
             }
             if (!credentials) {
                 return {
@@ -91,6 +95,13 @@ export class CloudflarePublishService extends Service {
             throw new Error('"cloudflare" is a publish target but "publish.cloudflare" is not configured');
         const marker = `${pkg.name}@${pkg.version}`;
         if (cf.kind === 'pages') {
+            /** Said rather than ignored: `wrangler pages deploy` has no `--env` or `--var`, and a setting
+             *  that silently does nothing is the one a reader trusts. */
+            for (const key of ['env', 'variables']) {
+                if (cf[key] !== undefined) {
+                    throw new Error(`"publish.cloudflare.${key}" is for kind "workers" - Pages takes settings through "files"`);
+                }
+            }
             const project = cf.project;
             if (!project)
                 throw new Error('"publish.cloudflare.project" is required for kind "pages"');
@@ -108,13 +119,16 @@ export class CloudflarePublishService extends Service {
                     ? `"publish.cloudflare.config" names ${declared}, which does not exist`
                     : `kind "workers" needs a wrangler configuration - none of ${this.workerConfigFiles.join(', ')} is in the package`);
             }
+            const env = cf.env || undefined;
             return {
                 kind: 'workers',
                 pkg,
                 marker,
                 tag: `v${pkg.version}`,
                 config,
-                label: `workers ${path.relative(pkg.dirname, config)}`,
+                env,
+                variables: cf.variables ?? {},
+                label: `workers ${path.relative(pkg.dirname, config)}${env ? ` (${env})` : ''}`,
             };
         }
         throw new Error(`"publish.cloudflare.kind" must be "pages" or "workers", not ${JSON.stringify(cf.kind)}`);
@@ -154,7 +168,8 @@ export class CloudflarePublishService extends Service {
     /** 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) => {
+        const argv = ['versions', 'list', '--json', '--config', deploy.config, ...this.envArgs(deploy)];
+        await this.wrangler(deploy.pkg, argv, (line, stream) => {
             if (stream === 'stdout')
                 lines.push(line);
         });
@@ -179,7 +194,17 @@ export class CloudflarePublishService extends Service {
                 deploy.marker,
                 '--commit-dirty=true',
             ]
-            : ['deploy', '--config', deploy.config, '--tag', deploy.tag, '--message', deploy.marker];
+            : [
+                'deploy',
+                '--config',
+                deploy.config,
+                ...this.envArgs(deploy),
+                ...Object.entries(deploy.variables).flatMap(([name, value]) => ['--var', `${name}:${value}`]),
+                '--tag',
+                deploy.tag,
+                '--message',
+                deploy.marker,
+            ];
         const lines = [];
         try {
             await this.wrangler(deploy.pkg, argv, line => {
@@ -194,6 +219,11 @@ export class CloudflarePublishService extends Service {
             });
         }
     }
+    /** `--env <name>` when the Worker deploys to a named wrangler environment - for the deploy and for
+     *  the versions list, which would otherwise ask about a different Worker. */
+    envArgs(deploy) {
+        return deploy.env ? ['--env', deploy.env] : [];
+    }
     /**
      * `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

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

@@ -1,4 +1,4 @@
-import type { PublishTarget } from '../../../core/interfaces/publish-target.js';
+import type { PublishFilesKeys, 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
@@ -9,7 +9,7 @@ import type { ConfigValue, ScopedVars } from '../../../interfaces/rman-config.in
  */
 export interface CloudflarePublishOptions extends CloudflarePublishOptionsKeys, ScopedVars {
 }
-export interface CloudflarePublishOptionsKeys {
+export interface CloudflarePublishOptionsKeys extends PublishFilesKeys {
     /**
      * 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
@@ -26,6 +26,13 @@ export interface CloudflarePublishOptionsKeys {
     /** 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>;
+    /** Workers: the wrangler environment to deploy (`--env`) - one the configuration declares,
+     *  `staging` or `production`. */
+    env?: ConfigValue<string>;
+    /** Workers: variables the Worker reads from `env` at run time (`--var NAME:value`), over the
+     *  configuration's own `vars`. Not for secrets - they show in the dashboard; those are
+     *  `wrangler secret`'s. Pages takes none from the command line: a file through `files` instead. */
+    variables?: ConfigValue<Record<string, string>>;
 }
 /**
  * **Cloudflare, as a publish target** - a static site on Pages, or a Worker with its assets.

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

@@ -5,8 +5,9 @@ import { promisify } from 'node:util';
 import { Service } from '../../../core/classes/service.js';
 import { targetsOf } from '../../../core/interfaces/publish-target.js';
 import { exec } from '../../../utils/exec.js';
-import { GitHelper } from '../../../utils/git.js';
+import { dirtyReason, filesUnder, GitHelper } from '../../../utils/git.js';
 import { filterPackages } from '../../../utils/package-filter.js';
+import { isCalendarVersion } from '../../../utils/release-version.js';
 /**
  * The name this target answers to in `publish.target` and `--target`.
  *
@@ -42,7 +43,7 @@ export class DockerPublishService extends Service {
          *  where a package ships. */
         const packages = filterPackages(repository.getPackages({ toposort: true }), options).filter(pkg => targetsOf(this.app, pkg).some(t => t.name === DOCKER_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 isDirty = (pkg) => filesUnder(dirtyFiles, pkg.dirname).length > 0;
         const imageExists = deps.imageExists ?? defaultImageExists;
         const entries = new Map();
         const toCheck = [];
@@ -72,19 +73,22 @@ export class DockerPublishService extends Service {
                     image,
                     detail: image,
                     status: options.ignoreDirty ? 'skip' : 'error',
-                    reason: 'uncommitted local changes',
+                    reason: dirtyReason(filesUnder(dirtyFiles, pkg.dirname), repository.dirname),
                 });
                 continue;
             }
             toCheck.push({ pkg, image });
         }
+        /** What the plan prints beside a package is every tag it pushes, so `--dry-run` shows whether a
+         *  prerelease would move `latest`. */
+        const describe = (pkg, image) => `${image}:${imageTags(pkg).join(', ')}`;
         await Promise.all(toCheck.map(async ({ pkg, image }) => {
             const exists = await imageExists(image, pkg.version);
             entries.set(pkg.name, {
                 package: pkg,
                 version: pkg.version,
                 image,
-                detail: image,
+                detail: describe(pkg, image),
                 status: exists ? 'up-to-date' : 'publish',
                 reason: exists ? `registry already has ${image}:${pkg.version}` : 'never published',
             });
@@ -151,6 +155,40 @@ function resolveImageRef(image, namespaceOverride) {
     }
     return `${namespace}/${image}`;
 }
+/**
+ * Every tag an image of `pkg` is pushed under: its version, its floating tag, then
+ * `publish.docker.tags`, each once.
+ *
+ * The floating tag is `latest` for a release and the identifier for a prerelease - `2.0.0-beta.1`
+ * goes to `beta`, and one with no word to name it (`2.0.0-1`) to none. A calendar version is a
+ * release however its time is spelled.
+ */
+/* **Every image used to be pushed as `latest`**, a beta included, so a plain `docker pull` took
+ * whatever was pushed last - the mistake npm's `distTagFor` exists to prevent, made on the other
+ * registry. Same rule, same scheme questions. */
+function imageTags(pkg) {
+    const version = pkg.version;
+    const preview = !isCalendarVersion(version) && pkg.versionScheme.isPrerelease(version);
+    const floating = preview ? pkg.versionScheme.prereleaseId(version) : 'latest';
+    const extra = (pkg.config.publish?.docker?.tags ?? []).filter((t) => typeof t === 'string' && !!t);
+    return [...new Set([version, ...(floating ? [floating] : []), ...extra])];
+}
+/** `--secret`'s value: `"$NAME"` reads the environment, anything else is a file in the package. */
+function secretSpec(pkg, id, value) {
+    const env = /^\$([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+    if (env) {
+        if (process.env[env[1]] === undefined) {
+            throw new Error(`"publish.docker.secrets.${id}" reads ${env[1]}, which is not set`);
+        }
+        return `id=${id},env=${env[1]}`;
+    }
+    return `id=${id},src=${path.resolve(pkg.dirname, value)}`;
+}
+function asList(value) {
+    if (!value)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
 /** A value of exactly `"$NAME"` expands to `process.env.NAME` (empty string if unset) - anything
  *  else (including a value with `$` only as part of a larger string) is passed through verbatim. */
 function expandEnvValue(value) {
@@ -182,7 +220,20 @@ async function buildAndPush(repository, entry) {
     for (const [name, value] of Object.entries(docker.buildArgs ?? {})) {
         args.push('--build-arg', `${name}="${expandEnvValue(value)}"`);
     }
-    args.push('-f', `"${dockerfile}"`, '-t', `"${entry.image}:${entry.version}"`, '-t', `"${entry.image}:latest"`, '--push', '.');
+    for (const [id, value] of Object.entries(docker.secrets ?? {}))
+        args.push('--secret', `"${secretSpec(pkg, id, value)}"`);
+    for (const [name, value] of Object.entries(docker.labels ?? {}))
+        args.push('--label', `"${name}=${value}"`);
+    if (docker.target)
+        args.push('--target', `"${docker.target}"`);
+    for (const from of asList(docker.cache?.from))
+        args.push('--cache-from', `"${from}"`);
+    for (const to of asList(docker.cache?.to))
+        args.push('--cache-to', `"${to}"`);
+    args.push('-f', `"${dockerfile}"`);
+    for (const tag of imageTags(pkg))
+        args.push('-t', `"${entry.image}:${tag}"`);
+    args.push('--push', '.');
     /** **Shown as it runs and kept**, so a failure can say why. It ran with `stdio: 'inherit'`, and the
      *  one thing left to report was the exit code - measured on `panates/syncbridge`, the line that
      *  explained the failure sat forty lines above the plan's recap and the recap said

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

@@ -1,4 +1,4 @@
-import type { PublishTarget } from '../../../core/interfaces/publish-target.js';
+import type { PublishFilesKeys, PublishTarget } from '../../../core/interfaces/publish-target.js';
 import type { ConfigValue, ScopedVars } from '../../../interfaces/rman-config.interface.js';
 /**
  * **`publish.docker.*`** - this target's own config block, declared here rather than centrally.
@@ -15,7 +15,7 @@ export interface DockerPublishOptions extends DockerPublishOptionsKeys, ScopedVa
 /** Every key here is a **value**, so every one is a `ConfigValue` - this target declares no step,
  *  which is what makes the whole block uniform (see `VersionExtraKeys` for the interface where it
  *  is not). */
-export interface DockerPublishOptionsKeys {
+export interface DockerPublishOptionsKeys extends PublishFilesKeys {
     /** DockerHub image name/repository - bare (e.g. `"my-app"`) to be prefixed with
      *  `--docker-namespace`/`DOCKERHUB_NAMESPACE`, or already-namespaced (contains a `/`) to use
      *  verbatim. */
@@ -38,6 +38,26 @@ export interface DockerPublishOptionsKeys {
     /** A file (relative to the package's own directory) whose contents become the DockerHub repo's
      *  full description, if present. Default `"DOCKER_README.md"`. */
     readme?: ConfigValue<string>;
+    /**
+     * `docker buildx build --secret` entries, keyed by the secret's id: a build-time value the image's
+     * layers never record, where a `buildArgs` value is visible in its history. `"$NAME"` takes it
+     * from `process.env.NAME`; anything else is a file, relative to the package. A Dockerfile reads
+     * one with `RUN --mount=type=secret,id=<id>`.
+     */
+    secrets?: ConfigValue<Record<string, string>>;
+    /** Tags pushed besides the version's own and its floating one (`latest`, or a prerelease's
+     *  identifier) - `"${{ semver.major(pkg.version) }}"` for a major line. */
+    tags?: ConfigValue<string[]>;
+    /** `docker buildx build --target` - the stage of a multi-stage Dockerfile that becomes the image. */
+    target?: ConfigValue<string>;
+    /** `--cache-from` / `--cache-to` - where the build reads and writes its layer cache
+     *  (`type=gha` on GitHub Actions). Each a single value or a list. */
+    cache?: ConfigValue<{
+        from?: string | string[];
+        to?: string | string[];
+    }>;
+    /** `docker buildx build --label` entries - labels on the image beside the Dockerfile's own. */
+    labels?: ConfigValue<Record<string, string>>;
 }
 /**
  * **Docker, as a publish target** - the core's own, and the reason `PublishTarget` is in the core

package/commands/publish.command.js

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import readline from 'node:readline/promises';
 import colors from 'ansi-colors';
 import { shipsTo, unknownTargets } from '../core/interfaces/publish-target.js';
 import { registerCommand } from '../interfaces/rman-config.interface.js';
 import { assertAllowedBranch, branchGuardOptions, readBranchGuardOptions } from '../utils/branch-guard.js';
+import { UNCOMMITTED } from '../utils/git.js';
 import { packageFilterOptions, readPackageFilterOptions } from '../utils/package-filter.js';
+import { PublishFiles } from '../utils/publish-files.js';
 /** Hoisted for `ArgsOf` - see `version.command.ts` and `RmanConfig.ArgsOf` for why. */
 const COMMAND = 'publish';
 /**
@@ -109,6 +112,12 @@ const publishCommand = registerCommand(app => {
         ],
         handler: async (args) => {
             await assertAllowedBranch(repository, readBranchGuardOptions(args));
+            /** Before anything is planned: a run that died while one target's files were in place left
+             *  them there, and the next target - or the dirty check - must not see them. */
+            const recovered = PublishFiles.recover(repository.dirname);
+            if (recovered.length) {
+                console.error(colors.yellow(`Put back ${recovered.length} file(s) an interrupted publish had copied in (publish.<target>.files).`));
+            }
             const requested = args.target;
             /** A target built from what the others publish goes after them - see `publishesLast`. A
              *  stable sort, so registration order still decides among the rest. */
@@ -129,12 +138,27 @@ const publishCommand = registerCommand(app => {
             for (const target of selected) {
                 plans.set(target, (await target.getPlan(ctx)).filter(entry => shipsTo(entry.package, target)));
             }
+            /** A missing source fails the plan, before anything is published or copied. */
+            for (const [target, plan] of plans) {
+                for (const [i, entry] of plan.entries()) {
+                    if (entry.status !== 'publish')
+                        continue;
+                    try {
+                        filesFor(entry.package, target);
+                    }
+                    catch (e) {
+                        plan[i] = { ...entry, status: 'error', reason: e.message };
+                    }
+                }
+            }
             if (args.json) {
                 console.log(JSON.stringify(jsonPlan(plans), undefined, 2));
             }
             else {
-                for (const [target, plan] of plans)
+                for (const [target, plan] of plans) {
                     printPlan(plan, target.name);
+                    printFiles(plan, target);
+                }
             }
             /** An explicitly requested target that matched nothing is a mistake worth reporting: the run
              *  asked for something by name and silently got an empty plan back. */
@@ -147,7 +171,7 @@ const publishCommand = registerCommand(app => {
             const all = [...plans.values()].flat();
             const errors = all.filter(e => e.status === 'error');
             if (errors.length) {
-                const allDirty = errors.every(e => e.reason === 'uncommitted local changes');
+                const allDirty = errors.every(e => e.reason?.startsWith(UNCOMMITTED));
                 throw logged(allDirty
                     ? `${errors.length} package(s) have uncommitted local changes ` +
                         '(pass --ignore-dirty to exclude them instead of aborting)'
@@ -180,7 +204,15 @@ const publishCommand = registerCommand(app => {
                     waited = true;
                     await waitForPublished(ctx, publishedBy);
                 }
-                const applied = await target.applyPlan(ctx, plan);
+                const files = plan.filter(e => e.status === 'publish').flatMap(e => filesFor(e.package, target));
+                const staged = files.length ? PublishFiles.stage(repository.dirname, `[${target.name}]`, files) : undefined;
+                let applied;
+                try {
+                    applied = await target.applyPlan(ctx, plan);
+                }
+                finally {
+                    staged?.restore();
+                }
                 const done = printApplied(applied, plan, target.name);
                 outcomes.push(...done);
                 publishedBy.set(target, done.filter(o => o.entry.status === 'publish').map(o => o.entry));
@@ -257,6 +289,46 @@ function assertDeclaredTargetsExist(app, packages) {
 }
 /** One `--json` row per package *and target*: a package shipping to two registries needs two, or a
  *  consumer cannot tell which of them still has something to do. */
+/**
+ * The files `publish.<target>.files` copies into `pkg` before that target publishes it - destination
+ * and source, both relative to the package. Throws naming the first source that does not exist, or
+ * a destination outside the package.
+ */
+/* **Copied, never written from config** - the user's call: a file a platform needs (a `config.json`,
+ * an image, a font) is kept in the repository as the file it is, with a diff and a history, and the
+ * config only says where it goes. Generic over targets because it is the same need for each. */
+function filesFor(pkg, target) {
+    const block = pkg.config.publish?.[target.name];
+    const files = block && typeof block === 'object' ? block.files : undefined;
+    if (!files || typeof files !== 'object')
+        return [];
+    return Object.entries(files).map(([to, from]) => {
+        const where = `publish.${target.name}.files["${to}"]`;
+        if (typeof from !== 'string' || !from)
+            throw new Error(`${where} must name a file or directory to copy`);
+        const dest = path.resolve(pkg.dirname, to);
+        const source = path.resolve(pkg.dirname, from);
+        const relative = path.relative(pkg.dirname, dest);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new Error(`${where} must be a path inside the package`);
+        }
+        if (!fs.existsSync(source))
+            throw new Error(`${where}: ${from} does not exist`);
+        return { source, dest };
+    });
+}
+/** Under a target's plan, what each package to publish will have copied in - so `--dry-run` says
+ *  it. */
+function printFiles(plan, target) {
+    for (const entry of plan) {
+        if (entry.status !== 'publish')
+            continue;
+        for (const file of filesFor(entry.package, target)) {
+            const rel = (p) => path.relative(entry.package.dirname, p);
+            console.log(colors.gray(`  ${entry.package.name}: ${rel(file.dest)} <- ${rel(file.source)}`));
+        }
+    }
+}
 function jsonPlan(plans) {
     return [...plans].flatMap(([target, plan]) => plan.map(entry => ({
         name: entry.package.name,

package/constants.js

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

package/core/interfaces/publish-target.d.ts

@@ -1,4 +1,4 @@
-import type { RmanConfig } from '../../interfaces/rman-config.interface.js';
+import type { ConfigValue, RmanConfig } from '../../interfaces/rman-config.interface.js';
 import type { PackageFilterOptions } from '../../utils/package-filter.js';
 import type { RmanApplication } from '../application.js';
 import type { Package } from '../classes/package.js';
@@ -131,6 +131,19 @@ export declare namespace PublishTarget {
         reason?: string;
     }
 }
+/**
+ * `publish.<target>.files` - files copied into the package just before that target publishes it,
+ * and put back afterwards. Every target's block takes it; `publish` itself does the copying.
+ */
+export interface PublishFilesKeys {
+    /**
+     * Destination -> source, both relative to the package: `{ "dist/config.json":
+     * "deploy/cloudflare/config.json" }`. A source may be a file of any kind or a directory. What a
+     * destination held is moved aside and put back once the target is done, so each target sees only
+     * its own files.
+     */
+    files?: ConfigValue<Record<string, string>>;
+}
 /**
  * **A target's name, and deliberately not a union.**
  *

package/package.json

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

package/services/github-release.service.js

@@ -4,7 +4,7 @@ import fastGlob from 'fast-glob';
 import { Package } from '../core/classes/package.js';
 import { Repository } from '../core/classes/repository.js';
 import { Service } from '../core/classes/service.js';
-import { GitHelper } from '../utils/git.js';
+import { dirtyReason, GitHelper } from '../utils/git.js';
 import { expandReleaseTag, isCalendarVersion, releaseTagPattern } from '../utils/release-version.js';
 import { ChangeHashService } from './change-hash.service.js';
 /**
@@ -49,14 +49,15 @@ export class GithubReleaseService extends Service {
             ];
         }
         const tag = releaseTagFor(root);
-        if ((await git.listDirtyFiles()).length) {
+        const dirtyFiles = await git.listDirtyFiles();
+        if (dirtyFiles.length) {
             return [
                 {
                     ...base,
                     tag,
                     repository: repo,
                     status: options.ignoreDirty ? 'skip' : 'error',
-                    reason: 'uncommitted local changes',
+                    reason: dirtyReason(dirtyFiles, repository.dirname),
                 },
             ];
         }

package/services/version-plan.service.js

@@ -2,7 +2,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 { dirtyReason, filesUnder, GitHelper } from '../utils/git.js';
 import { filterPackages } from '../utils/package-filter.js';
 import { findLastReleaseVersion, formatCalendarVersion, usesCalendarVersion } from '../utils/release-version.js';
 import { groupKeyOf, ROOT_GROUP_KEY } from '../utils/version-group.js';
@@ -98,7 +98,8 @@ export class VersionPlanService {
         const git = new GitHelper({ cwd: repository.dirname });
         const packages = filterPackages(repository.getPackages(), options);
         const dirtyFiles = await git.listDirtyFiles({ absolute: true });
-        const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const isDirty = (pkg) => filesUnder(dirtyFiles, pkg.dirname).length > 0;
+        const dirtyReasonOf = (pkg) => dirtyReason(filesUnder(dirtyFiles, pkg.dirname), repository.dirname);
         const dirty = packages.filter(isDirty);
         const entries = new Map();
         /**
@@ -149,7 +150,7 @@ export class VersionPlanService {
                 group: this.groupLabel(this.resolveGroupKey(pkg)),
                 status: 'skip',
                 from: pkg.version,
-                reason: 'uncommitted local changes',
+                reason: dirtyReasonOf(pkg),
             });
         }
         const commitMessage = repository.rootPackage.config?.version?.commitMessage;
@@ -209,7 +210,7 @@ export class VersionPlanService {
                 if (!entry || unversioned.has(pkg))
                     continue;
                 entry.status = 'error';
-                entry.reason = entry.reason ? `uncommitted local changes (${entry.reason})` : 'uncommitted local changes';
+                entry.reason = entry.reason ? `${dirtyReasonOf(pkg)} (${entry.reason})` : dirtyReasonOf(pkg);
             }
         }
         return result;

package/utils/git.d.ts

@@ -150,3 +150,13 @@ export declare namespace GitHelper {
      *  show the total while the count is still zero. */
     type CommitProgress = (done: number, total: number) => void;
 }
+/** What every "you have uncommitted changes" refusal starts with - compared against by callers, so
+ *  it lives once. */
+export declare const UNCOMMITTED = "uncommitted local changes";
+/**
+ * `uncommitted local changes: a, b, c (+4 more)` - the refusal with the files that cause it,
+ * relative to `root`, at most three of them.
+ */
+export declare function dirtyReason(files: readonly string[], root: string): string;
+/** The files in `files` that sit inside `dir` - both absolute. */
+export declare function filesUnder(files: readonly string[], dir: string): string[];

package/utils/git.js

@@ -479,3 +479,24 @@ const execFileP = promisify(execFile);
 function execFileAsync(file, args, options) {
     return execFileP(file, args, { maxBuffer: GIT_MAX_BUFFER, ...options });
 }
+/** What every "you have uncommitted changes" refusal starts with - compared against by callers, so
+ *  it lives once. */
+export const UNCOMMITTED = 'uncommitted local changes';
+/**
+ * `uncommitted local changes: a, b, c (+4 more)` - the refusal with the files that cause it,
+ * relative to `root`, at most three of them.
+ */
+/* **Named, because the bare sentence cost a release.** On `panates/syncbridge` a build rewrote a
+ * Dockerfile label, `rman github-release` answered only `uncommitted local changes`, and the file was
+ * found by reading every build script in the repository - the CI log had nothing else to say. */
+export function dirtyReason(files, root) {
+    if (!files.length)
+        return UNCOMMITTED;
+    const shown = files.slice(0, 3).map(f => (path.isAbsolute(f) ? path.relative(root, f) : f));
+    const more = files.length > shown.length ? ` (+${files.length - shown.length} more)` : '';
+    return `${UNCOMMITTED}: ${shown.join(', ')}${more}`;
+}
+/** The files in `files` that sit inside `dir` - both absolute. */
+export function filesUnder(files, dir) {
+    return files.filter(f => !path.relative(dir, f).startsWith('..'));
+}

package/utils/publish-files.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Files copied into a package for one publish target, and put back afterwards - see
+ * `publish.<target>.files`.
+ *
+ * `stage` writes a journal, moves aside whatever each destination held, and copies the sources in;
+ * `restore` removes the copies and moves the originals back. A run that dies between the two leaves
+ * the journal behind, and `recover` - called before the next publish plans anything - finishes the
+ * restore, so one target's files never reach another target's publish.
+ */
+export declare class PublishFiles {
+    protected readonly dir: string;
+    protected readonly journal: PublishFiles.Journal;
+    private _done;
+    private _unhook?;
+    protected constructor(dir: string, journal: PublishFiles.Journal);
+    /**
+     * Copies `files` in, after moving aside whatever their destinations held, and returns the handle
+     * that puts everything back. `label` names the run in the journal - `[docker] my-app`.
+     */
+    static stage(repositoryDir: string, label: string, files: readonly PublishFiles.File[]): PublishFiles;
+    /**
+     * Finishes the restore a previous run left unfinished, and returns the destinations it put back -
+     * empty when there was nothing to do.
+     */
+    static recover(repositoryDir: string): string[];
+    /** Where the journal and the moved-aside originals live for this repository. */
+    static stateDir(repositoryDir: string): string;
+    /** Removes the copies, moves the originals back, drops the directories staging created, and the
+     *  journal last. Safe to call twice. */
+    restore(): void;
+    protected writeJournal(): void;
+}
+export declare namespace PublishFiles {
+    /** One copy: `source` into `dest`, both absolute. */
+    interface File {
+        source: string;
+        dest: string;
+    }
+    interface JournalEntry {
+        dest: string;
+        /** Where the destination's previous content was moved, when it had any. */
+        backup?: string;
+        /** Directories that did not exist and were created to hold `dest`, outermost first. */
+        createdDirs: string[];
+    }
+    interface Journal {
+        label: string;
+        entries: JournalEntry[];
+    }
+}

package/utils/publish-files.js

@@ -0,0 +1,148 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { onExit } from 'signal-exit';
+/**
+ * Files copied into a package for one publish target, and put back afterwards - see
+ * `publish.<target>.files`.
+ *
+ * `stage` writes a journal, moves aside whatever each destination held, and copies the sources in;
+ * `restore` removes the copies and moves the originals back. A run that dies between the two leaves
+ * the journal behind, and `recover` - called before the next publish plans anything - finishes the
+ * restore, so one target's files never reach another target's publish.
+ */
+/* **Kept in `.git/rman/publish-files`**, the user's choice and for three reasons: it is inside the
+ * repository, so the next run finds it; git never commits it, so it needs no `.gitignore`; and it
+ * survives a reboot, which `os.tmpdir()` may not - and a reboot is the case the journal exists for.
+ * A directory that is not a git repository falls back to the temporary directory.
+ *
+ * **Moved aside, not copied.** A rename on one filesystem is instant whatever the size - an image,
+ * a whole directory - and the original is untouched until it is moved back. Across filesystems it
+ * copies and removes instead.
+ *
+ * **The journal is written before anything is touched**, listing every destination and whether it
+ * held something, so a run killed at any point leaves enough to undo exactly what it did.
+ *
+ * Restoring is synchronous, so it can run from `signal-exit`'s handler on Ctrl-C or a terminated
+ * CI job - the same hook `child-tracker` uses to kill children. */
+export class PublishFiles {
+    dir;
+    journal;
+    _done = false;
+    _unhook;
+    constructor(dir, journal) {
+        this.dir = dir;
+        this.journal = journal;
+    }
+    /**
+     * Copies `files` in, after moving aside whatever their destinations held, and returns the handle
+     * that puts everything back. `label` names the run in the journal - `[docker] my-app`.
+     */
+    static stage(repositoryDir, label, files) {
+        const dir = PublishFiles.stateDir(repositoryDir);
+        fs.mkdirSync(path.join(dir, 'backup'), { recursive: true });
+        const entries = files.map((file, i) => {
+            const existed = lexists(file.dest);
+            return {
+                dest: file.dest,
+                backup: existed ? path.join(dir, 'backup', String(i)) : undefined,
+                createdDirs: missingParents(file.dest),
+            };
+        });
+        const staged = new this(dir, { label, entries });
+        staged.writeJournal();
+        staged._unhook = onExit(() => staged.restore());
+        for (const [i, entry] of entries.entries()) {
+            if (entry.backup)
+                move(entry.dest, entry.backup);
+            fs.mkdirSync(path.dirname(entry.dest), { recursive: true });
+            fs.cpSync(files[i].source, entry.dest, { recursive: true });
+        }
+        return staged;
+    }
+    /**
+     * Finishes the restore a previous run left unfinished, and returns the destinations it put back -
+     * empty when there was nothing to do.
+     */
+    static recover(repositoryDir) {
+        const dir = PublishFiles.stateDir(repositoryDir);
+        const file = path.join(dir, JOURNAL);
+        if (!fs.existsSync(file))
+            return [];
+        const journal = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        new this(dir, journal).restore();
+        return journal.entries.map(e => e.dest);
+    }
+    /** Where the journal and the moved-aside originals live for this repository. */
+    static stateDir(repositoryDir) {
+        try {
+            const gitDir = execFileSync('git', ['rev-parse', '--absolute-git-dir'], {
+                cwd: repositoryDir,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            })
+                .toString()
+                .trim();
+            return path.join(gitDir, 'rman', 'publish-files');
+        }
+        catch {
+            return path.join(os.tmpdir(), 'rman-publish-files', Buffer.from(repositoryDir).toString('base64url'));
+        }
+    }
+    /** Removes the copies, moves the originals back, drops the directories staging created, and the
+     *  journal last. Safe to call twice. */
+    restore() {
+        if (this._done)
+            return;
+        this._done = true;
+        this._unhook?.();
+        for (const entry of [...this.journal.entries].reverse()) {
+            fs.rmSync(entry.dest, { recursive: true, force: true });
+            if (entry.backup && lexists(entry.backup)) {
+                fs.mkdirSync(path.dirname(entry.dest), { recursive: true });
+                move(entry.backup, entry.dest);
+            }
+            for (const created of [...entry.createdDirs].reverse()) {
+                if (fs.existsSync(created) && !fs.readdirSync(created).length)
+                    fs.rmdirSync(created);
+            }
+        }
+        fs.rmSync(this.dir, { recursive: true, force: true });
+    }
+    writeJournal() {
+        fs.writeFileSync(path.join(this.dir, JOURNAL), JSON.stringify(this.journal, undefined, 2));
+    }
+}
+const JOURNAL = 'journal.json';
+/** Whether anything is at `p`, a broken symbolic link included. */
+function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The directories above `file` that do not exist yet, outermost first. */
+function missingParents(file) {
+    const missing = [];
+    let dir = path.dirname(file);
+    while (!fs.existsSync(dir) && dir !== path.dirname(dir)) {
+        missing.unshift(dir);
+        dir = path.dirname(dir);
+    }
+    return missing;
+}
+/** `rename`, or copy and remove where the two paths are on different filesystems. */
+function move(from, to) {
+    try {
+        fs.renameSync(from, to);
+    }
+    catch (e) {
+        if (e?.code !== 'EXDEV')
+            throw e;
+        fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true });
+        fs.rmSync(from, { recursive: true, force: true });
+    }
+}