rman 2.22.0 → 2.23.0

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

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

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

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

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

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

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

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

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

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

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

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

package/commands/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/constants.js

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

package/core/application.js

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

package/package.json

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