rman 2.22.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

@@ -0,0 +1,107 @@
+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>;
+    /** `--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
+     * 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;
+        /** 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. */
+    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,243 @@
+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 { 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`. */
+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) => 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) => {
+            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: dirtyReason(filesUnder(dirtyFiles, pkg.dirname), repository.dirname),
+                };
+            }
+            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') {
+            /** 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"');
+            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`);
+            }
+            const env = cf.env || undefined;
+            return {
+                kind: 'workers',
+                pkg,
+                marker,
+                tag: `v${pkg.version}`,
+                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)}`);
+    }
+    /** 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 = [];
+        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);
+        });
+        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,
+                ...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 => {
+                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,
+            });
+        }
+    }
+    /** `--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
+     * 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,45 @@
+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
+ * `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 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
+     * 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>;
+    /** 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.
+ *
+ * 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/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.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/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.22.0';
+export const version = '2.24.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/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.22.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 });
+    }
+}