@celljs/cli 3.8.0 → 4.0.0

package/src/modules/module-host.ts

@@ -0,0 +1,489 @@
+import { execFile } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type {
+    CellAPI,
+    CellComponent,
+    CellEventName,
+    CellLogger,
+    CheckDefinition,
+    DevHandler,
+    McpToolDefinition,
+    Preset,
+    StandardSchema,
+    Target,
+    VitePluginLike,
+} from '@celljs/kit';
+import { CellError } from '@celljs/kit';
+import type { ExtraModule } from '@celljs/vite';
+import type { Plugin } from 'vite';
+import type { ResolvedConfig } from '../config/config-resolver.js';
+import type { EventBus } from '../events/event-bus.js';
+import type { PresetRegistry } from '../preset/preset-registry.js';
+import { TextUtil } from '../utils/text-util.js';
+
+/** Where a toolchain module comes from. */
+export interface ModuleSource {
+    /** Package name of the component, the package, or the path of a local module relative to the root. */
+    name: string;
+    kind: 'component' | 'package' | 'local';
+    /** Absolute file of the module. */
+    file: string;
+}
+
+/** What one module registered; `cell info` lists it (docs/design/modules.md §3.5). */
+export interface ModuleRegistrations {
+    name: string;
+    kind: ModuleSource['kind'];
+    file: string;
+    options: string[];
+    /** What `updateConfig` added, e.g. `build.external: sharp`, `vite.resolve`. */
+    config: string[];
+    vitePlugins: { name: string; env?: 'client' | 'server' }[];
+    runtimeModules: { target: Target; path: string; static: boolean }[];
+    virtualModules: string[];
+    entries: Partial<Record<Target, string>>;
+    devHandlers: string[];
+    watchFiles: string[];
+    presets: string[];
+    outputFiles: string[];
+    checks: string[];
+    mcpTools: string[];
+    docs: string[];
+    events: string[];
+}
+
+export interface ModuleHostOptions {
+    config: ResolvedConfig;
+    events: EventBus;
+    presets: PresetRegistry;
+    components: CellComponent[];
+    logger: { info(message: string): void; warn(message: string): void };
+}
+
+interface Registered<T> {
+    source: string;
+    value: T;
+}
+
+/**
+ * Loads toolchain modules and keeps what they register (docs/design/modules.md §3). Modules load in a
+ * fixed order: components in dependency order, then the `modules` entries of cell.config.ts. A
+ * factory only registers; anything it registers is listed by `cell info`.
+ */
+export class ModuleHost {
+    readonly loaded: ModuleRegistrations[] = [];
+    readonly checks: Registered<CheckDefinition>[] = [];
+    readonly mcpTools: Registered<McpToolDefinition>[] = [];
+    readonly docs: Registered<string>[] = [];
+    readonly outputFiles = new Map<string, Registered<string | Uint8Array>>();
+    protected readonly plugins: Registered<{ plugin: VitePluginLike; env?: 'client' | 'server' }>[] = [];
+    protected readonly virtualModules = new Map<string, Registered<string | (() => string)>>();
+    protected readonly runtimeModules: ExtraModule[] = [];
+    protected readonly devHandlers: Registered<{ path: string; handler: DevHandler }>[] = [];
+    protected readonly watchFiles: string[] = [];
+    protected readonly schemas = new Map<string, Registered<StandardSchema>>();
+    protected readonly claimed = new Map<string, string>();
+    protected readonly bus = new Map<string, ((payload: unknown) => unknown)[]>();
+    readonly entries: Partial<Record<Target, string>> = {};
+
+    constructor(protected readonly options: ModuleHostOptions) {}
+
+    /** Components of the project, in dependency order (the project last). */
+    get components(): readonly CellComponent[] {
+        return this.options.components;
+    }
+
+    /** Modules of the components (`cell.toolchain`) and of cell.config.ts, in load order. */
+    static sources(config: ResolvedConfig, components: (CellComponent & { toolchain?: string })[]): ModuleSource[] {
+        const off = new Set(config.modules.flatMap(spec => (spec.kind === 'filter' && !spec.toolchain ? [spec.name] : [])));
+        const sources: ModuleSource[] = [];
+        for (const component of components) {
+            if (component.toolchain && !off.has(component.name)) {
+                sources.push({ name: component.name, kind: 'component', file: ModuleHost.file(join(component.dir, component.toolchain), component.name) });
+            }
+        }
+        const require = createRequire(join(config.root, 'package.json'));
+        for (const spec of config.modules) {
+            if (spec.kind === 'local') {
+                sources.push({
+                    name: spec.path.startsWith(config.root) ? spec.path.slice(config.root.length + 1) : spec.path,
+                    kind: 'local',
+                    file: ModuleHost.file(spec.path, spec.path),
+                });
+            } else if (spec.kind === 'package' && !sources.some(s => s.name === spec.name)) {
+                sources.push({ name: spec.name, kind: 'package', file: ModuleHost.resolvePackage(require, spec.name, config.file) });
+            }
+        }
+        return sources;
+    }
+
+    protected static file(path: string, name: string): string {
+        for (const candidate of [
+            path,
+            ...['.js', '.mjs', '.cjs', '.ts', '.mts'].map(ext => path + ext),
+            ...['index.js', 'index.mjs', 'index.ts'].map(f => join(path, f)),
+        ]) {
+            if (existsSync(candidate) && statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        throw new CellError({
+            code: 'CELL_LOCAL_MODULE_NOT_FOUND',
+            message: `The toolchain module of ${name} is missing: ${path}.`,
+            file: path,
+            hint: 'Build the package, or fix the `cell.toolchain` field of its package.json / the path in `modules`.',
+        });
+    }
+
+    protected static resolvePackage(require: NodeJS.Require, name: string, file?: string): string {
+        try {
+            const manifest = require.resolve(`${name}/package.json`);
+            const pkg = require(manifest) as { cell?: { toolchain?: string } };
+            if (pkg.cell?.toolchain) {
+                return ModuleHost.file(join(manifest, '..', pkg.cell.toolchain), name);
+            }
+            return require.resolve(name);
+        } catch (cause) {
+            if (CellError.is(cause)) {
+                throw cause;
+            }
+            throw new CellError({
+                code: 'CELL_COMPONENT_NOT_FOUND',
+                message: `The toolchain module ${name} is not installed.`,
+                file,
+                hint: `Install it (npm install -D ${name}), or remove it from \`modules\` in cell.config.ts.`,
+                cause,
+            });
+        }
+    }
+
+    async load(sources: ModuleSource[]): Promise<void> {
+        for (const source of sources) {
+            const factory = await this.import(source);
+            const record = this.record(source);
+            const api = this.api(source, record);
+            try {
+                await factory(api.cell);
+            } catch (error) {
+                throw CellError.is(error)
+                    ? error
+                    : new CellError({
+                          code: 'CELL_MODULE_ERROR',
+                          message: `The toolchain module ${source.name} failed: ${(error as Error)?.message ?? String(error)}`,
+                          file: source.file,
+                          hint: `Fix the factory of ${source.name}, or turn it off with { source: '${source.name}', toolchain: false } in modules.`,
+                          cause: error,
+                      });
+            } finally {
+                api.close();
+            }
+            this.loaded.push(record);
+        }
+    }
+
+    /** The field `key` of cell.config.ts belongs to `source` (a preset of the CLI), unless a module reads it already. */
+    claimOption(key: string, source: string, schema?: StandardSchema): void {
+        if (this.claimed.has(key)) {
+            return;
+        }
+        this.claimed.set(key, source);
+        if (schema) {
+            this.schemas.set(key, { source, value: schema });
+        }
+    }
+
+    /** After `modules:done`: every option field of cell.config.ts must belong to a module, and match its schema. */
+    async checkOptions(): Promise<void> {
+        for (const [key, value] of Object.entries(this.options.config.options)) {
+            if (!this.claimed.has(key)) {
+                const suggestion = TextUtil.closest(key, [...this.claimed.keys()]);
+                throw new CellError({
+                    code: 'CELL_CONFIG_UNKNOWN_OPTION',
+                    message: `No toolchain module reads the '${key}' field of cell.config.ts.${this.claimed.size > 0 ? ` Module options: ${[...this.claimed.keys()].join(', ')}.` : ''}`,
+                    file: this.options.config.file,
+                    hint: suggestion ? `Did you mean '${suggestion}'?` : 'Remove the field, or add the module that reads it to `modules`.',
+                });
+            }
+            const schema = this.schemas.get(key);
+            if (schema) {
+                await this.validate(key, value, schema);
+            }
+        }
+    }
+
+    protected async validate(key: string, value: unknown, { source, value: schema }: Registered<StandardSchema>): Promise<void> {
+        const result = (await schema['~standard'].validate(value)) as { issues?: ReadonlyArray<{ message: string; path?: ReadonlyArray<unknown> }> };
+        const issue = result.issues?.[0];
+        if (issue) {
+            const path = [key, ...(issue.path ?? []).map(p => String(typeof p === 'object' && p !== null ? (p as { key: unknown }).key : p))].join('.');
+            throw new CellError({
+                code: 'CELL_CONFIG_INVALID',
+                message: `${path}: ${issue.message}`,
+                file: this.options.config.file,
+                hint: `Fix the '${key}' options in cell.config.ts; they are defined by ${source}.`,
+            });
+        }
+    }
+
+    /** Vite plugins of the modules: their own, and one serving the virtual modules. */
+    vitePlugins(): Plugin[] {
+        const plugins = this.plugins.map(
+            ({ value: { plugin, env } }) =>
+                (env ? { ...plugin, applyToEnvironment: (environment: { name: string }) => environment.name === env } : plugin) as Plugin,
+        );
+        if (this.virtualModules.size > 0) {
+            const modules = this.virtualModules;
+            plugins.push({
+                name: 'cell:virtual-modules',
+                resolveId: id => (modules.has(id) ? `\0${id}` : null),
+                load: id => {
+                    const code = id.startsWith('\0') ? modules.get(id.slice(1))?.value : undefined;
+                    return code === undefined ? null : typeof code === 'function' ? code() : code;
+                },
+            });
+        }
+        return plugins;
+    }
+
+    get extraModules(): ExtraModule[] {
+        return [...this.runtimeModules];
+    }
+
+    get devHandlerList(): { path: string; handler: DevHandler }[] {
+        return this.devHandlers.map(h => h.value);
+    }
+
+    get watchFileList(): string[] {
+        return [...this.watchFiles];
+    }
+
+    protected async import(source: ModuleSource): Promise<(cell: CellAPI) => unknown> {
+        let exported: unknown;
+        try {
+            if (source.kind === 'local' && /\.[cm]?ts$/.test(source.file)) {
+                // TypeScript of the project: Vite's runner transpiles it (docs/design/modules.md §3).
+                const { runnerImport } = await import('vite');
+                exported = (await runnerImport<{ default?: unknown }>(source.file, { configFile: false, logLevel: 'error' })).module.default;
+            } else {
+                const module = (await import(pathToFileURL(source.file).href)) as { default?: unknown };
+                exported = module.default;
+            }
+        } catch (cause) {
+            throw new CellError({
+                code: 'CELL_MODULE_ERROR',
+                message: `Cannot load the toolchain module ${source.name}: ${(cause as Error)?.message ?? String(cause)}`,
+                file: source.file,
+                hint: 'Fix the module file; it must load without the project being built.',
+                cause,
+            });
+        }
+        // A CommonJS module compiled from `export default` has the factory one level down.
+        const factory = typeof exported === 'function' ? exported : (exported as { default?: unknown } | undefined)?.default;
+        if (typeof factory !== 'function') {
+            throw new CellError({
+                code: 'CELL_MODULE_INVALID',
+                message: `The toolchain module ${source.name} does not export a factory function by default.`,
+                file: source.file,
+                hint: 'Write `export default function (cell) { ... }` or `export default defineCellModule({ name }, cell => { ... })`.',
+            });
+        }
+        return factory as (cell: CellAPI) => unknown;
+    }
+
+    /** Deep merge of plain objects; `over` wins, arrays are replaced. */
+    static merge(under: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown> {
+        const result: Record<string, unknown> = { ...under };
+        for (const [key, value] of Object.entries(over)) {
+            const base = result[key];
+            const plain = (v: unknown): v is Record<string, unknown> =>
+                typeof v === 'object' && v !== null && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+            result[key] = plain(base) && plain(value) ? ModuleHost.merge(base, value) : value;
+        }
+        return result;
+    }
+
+    protected record(source: ModuleSource): ModuleRegistrations {
+        return {
+            name: source.name,
+            kind: source.kind,
+            file: source.file,
+            options: [],
+            config: [],
+            vitePlugins: [],
+            runtimeModules: [],
+            virtualModules: [],
+            entries: {},
+            devHandlers: [],
+            watchFiles: [],
+            presets: [],
+            outputFiles: [],
+            checks: [],
+            mcpTools: [],
+            docs: [],
+            events: [],
+        };
+    }
+
+    /** The `cell` object of one module. `close()` ends the factory: options can no longer be read. */
+    protected api(source: ModuleSource, record: ModuleRegistrations): { cell: CellAPI; close(): void } {
+        const { config, events, presets, components } = this.options;
+        let open = true;
+        const name = source.name;
+        const claim = (key: string) => {
+            const owner = this.claimed.get(key);
+            if (owner && owner !== name) {
+                throw new CellError({
+                    code: 'CELL_MODULE_ERROR',
+                    message: `${name} reads the '${key}' options, which ${owner} already reads.`,
+                    file: source.file,
+                    hint: 'Each option field belongs to one module; use another key.',
+                });
+            }
+            this.claimed.set(key, name);
+            if (!record.options.includes(key)) {
+                record.options.push(key);
+            }
+        };
+        const prefix = `[${name}] `;
+        const logger: CellLogger = {
+            info: message => this.options.logger.info(prefix + message),
+            success: message => this.options.logger.info(prefix + message),
+            warn: message => this.options.logger.warn(prefix + message),
+            error: message => this.options.logger.warn(prefix + message),
+        };
+        const require = createRequire(join(config.root, 'package.json'));
+        const cell: CellAPI = {
+            command: config.command,
+            mode: [...config.mode],
+            dev: config.dev,
+            ci: config.ci,
+            root: config.root,
+            preset: config.preset.source === 'default' ? undefined : config.preset.name,
+            components,
+            logger,
+            options: <T extends object>(key: string, defaults?: T): T => {
+                if (!open) {
+                    throw new CellError({
+                        code: 'CELL_MODULE_ERROR',
+                        message: `${name} read its options after its factory returned.`,
+                        file: source.file,
+                        hint: 'Call cell.options() synchronously in the factory and keep the result.',
+                    });
+                }
+                claim(key);
+                return { ...(defaults ?? {}), ...(config.options[key] ?? {}) } as T;
+            },
+            updateConfig: partial => {
+                if (!open) {
+                    throw new CellError({
+                        code: 'CELL_MODULE_ERROR',
+                        message: `${name} changed the configuration after its factory returned.`,
+                        file: source.file,
+                        hint: 'Call cell.updateConfig() in the factory.',
+                    });
+                }
+                const external = partial.build?.external ?? [];
+                config.build.external = [...new Set([...config.build.external, ...external])];
+                if (partial.vite) {
+                    config.vite = ModuleHost.merge(partial.vite, config.vite as Record<string, unknown>);
+                }
+                record.config.push(...external.map(e => `build.external: ${e}`), ...Object.keys(partial.vite ?? {}).map(k => `vite.${k}`));
+            },
+            addConfigSchema: (key, schema) => {
+                claim(key);
+                this.schemas.set(key, { source: name, value: schema });
+            },
+            addVitePlugin: (plugin, options) => {
+                this.plugins.push({ source: name, value: { plugin, env: options?.env } });
+                record.vitePlugins.push({ name: plugin.name, ...(options?.env ? { env: options.env } : {}) });
+            },
+            addRuntimeModule: (path, options) => {
+                const specifier = path.startsWith('.') ? resolvePath(config.root, path) : path;
+                this.runtimeModules.push({ target: options.target, specifier, static: options.static ?? false, component: name });
+                record.runtimeModules.push({ target: options.target, path: specifier, static: options.static ?? false });
+            },
+            addVirtualModule: (id, code) => {
+                this.virtualModules.set(id, { source: name, value: code });
+                record.virtualModules.push(id);
+            },
+            setEntry: (target, path) => {
+                const entry = path.startsWith('.') ? resolvePath(config.root, path) : path;
+                this.entries[target] = entry;
+                record.entries[target] = entry;
+            },
+            addDevHandler: (path, handler) => {
+                this.devHandlers.push({ source: name, value: { path, handler } });
+                record.devHandlers.push(path);
+            },
+            addWatchFile: path => {
+                const file = resolvePath(config.root, path);
+                this.watchFiles.push(file);
+                record.watchFiles.push(file);
+            },
+            addPreset: (preset: Preset) => {
+                presets.register(preset);
+                record.presets.push(preset.name);
+            },
+            addOutputFile: (path, content) => {
+                this.outputFiles.set(path, { source: name, value: content });
+                record.outputFiles.push(path);
+            },
+            addCheck: check => {
+                this.checks.push({ source: name, value: check });
+                record.checks.push(check.name);
+            },
+            addMcpTool: tool => {
+                this.mcpTools.push({ source: name, value: tool });
+                record.mcpTools.push(tool.name);
+            },
+            addDocs: dir => {
+                const path = resolvePath(source.file, '..', dir);
+                this.docs.push({ source: name, value: path });
+                record.docs.push(path);
+            },
+            on: (event: CellEventName, handler) => {
+                if (!record.events.includes(event)) {
+                    record.events.push(event);
+                }
+                return events.on(event, handler, name);
+            },
+            events: {
+                on: (event, handler) => {
+                    this.bus.set(event, [...(this.bus.get(event) ?? []), handler]);
+                    return () =>
+                        this.bus.set(
+                            event,
+                            (this.bus.get(event) ?? []).filter(h => h !== handler),
+                        );
+                },
+                emit: async (event, payload) => {
+                    for (const handler of [...(this.bus.get(event) ?? [])]) {
+                        await handler(payload);
+                    }
+                },
+            },
+            exec: (command, args = [], options = {}) =>
+                new Promise(resolve => {
+                    execFile(
+                        command,
+                        args,
+                        { cwd: options.cwd ?? config.root, signal: options.signal, timeout: options.timeout, maxBuffer: 64 * 1024 * 1024 },
+                        (error, stdout, stderr) => {
+                            const code = error ? (typeof (error as { code?: unknown }).code === 'number' ? (error as { code: number }).code : 1) : 0;
+                            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+                        },
+                    );
+                }),
+            resolve: specifier => require.resolve(specifier),
+        };
+        return {
+            cell,
+            close: () => {
+                open = false;
+            },
+        };
+    }
+}

package/src/preset/builtin-presets.ts

@@ -0,0 +1,26 @@
+import { definePreset } from '@celljs/kit';
+import { cloudflarePreset } from './cloudflare/cloudflare-preset.js';
+import { fcPreset } from './fc/fc-preset.js';
+import { lambdaPreset } from './lambda/lambda-preset.js';
+import { scfPreset } from './scf/scf-preset.js';
+import { vercelPreset } from './vercel/vercel-preset.js';
+
+/** A Node.js HTTP server: `node server/index.mjs` listens on `cell.server.port` (override with `CELL_BACKEND__SERVER__PORT`). */
+export const nodePreset = definePreset({
+    name: 'node',
+    description: 'Node.js HTTP server',
+    entry: 'http',
+    format: 'esm',
+});
+
+/**
+ * A Node.js command-line application: `node server/index.mjs` starts the application without a server;
+ * its components do the work (an `ApplicationLifecycle` reads arguments, opens a terminal UI, ...).
+ */
+export const cliPreset = definePreset({
+    name: 'cli',
+    description: 'Node.js command-line application (no server)',
+    format: 'esm',
+});
+
+export const BUILTIN_PRESETS = [nodePreset, cloudflarePreset, cliPreset, fcPreset, scfPreset, lambdaPreset, vercelPreset];

package/src/preset/cloudflare/cloudflare-deployer.ts

@@ -0,0 +1,126 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { CellError, type DeployContext, type Deployment, type DeployPlan, type DeployResource, defineDeployer } from '@celljs/kit';
+import { Wrangler } from './wrangler.js';
+import { WranglerConfig, type WranglerJson } from './wrangler-config.js';
+
+/**
+ * Deploys the output of the cloudflare preset with Wrangler. `plan` runs `wrangler deploy --dry-run`,
+ * which bundles the worker and checks the configuration without uploading; `apply` runs `wrangler deploy`.
+ */
+export class CloudflareDeployment {
+    static readonly AUTH_HINT =
+        'Set CLOUDFLARE_API_TOKEN (a token with the "Edit Cloudflare Workers" template; also CLOUDFLARE_ACCOUNT_ID if it can access several accounts), or run `npx wrangler login` once.';
+
+    static readonly SUBDOMAIN_HINT =
+        'Register the workers.dev subdomain of the account once (open Workers & Pages in the Cloudflare dashboard, the link in the message), or deploy to your own domain with `routes` in wrangler.jsonc.';
+
+    protected readonly wrangler: Wrangler;
+    protected readonly file: string;
+
+    constructor(protected readonly context: DeployContext) {
+        this.wrangler = new Wrangler(context.root, context.env);
+        this.file = join(context.outDir, WranglerConfig.OUTPUT_FILE);
+    }
+
+    async plan(): Promise<DeployPlan> {
+        const config = this.readConfig();
+        const outdir = mkdtempSync(join(tmpdir(), 'cell-wrangler-'));
+        this.context.info('Checking the worker with wrangler deploy --dry-run…');
+        try {
+            const result = await this.wrangler.run(['deploy', '--dry-run', '--config', this.file, '--outdir', outdir], this.relay);
+            if (result.code !== 0) {
+                throw this.failure('CELL_DEPLOY_PLAN_FAILED', 'wrangler deploy --dry-run', result.output);
+            }
+            return {
+                deployer: 'cloudflare',
+                resources: this.resources(config, result.output),
+                details: {
+                    config: relative(this.context.root, this.file),
+                    wrangler: result.source === 'project' ? 'project' : Wrangler.PACKAGE,
+                    credentials: this.context.env.CLOUDFLARE_API_TOKEN ? 'CLOUDFLARE_API_TOKEN' : 'wrangler login',
+                },
+            };
+        } finally {
+            rmSync(outdir, { recursive: true, force: true });
+        }
+    }
+
+    async apply(_plan: DeployPlan): Promise<Deployment> {
+        this.readConfig();
+        const result = await this.wrangler.run(['deploy', '--config', this.file], this.relay);
+        if (result.code !== 0) {
+            throw this.failure('CELL_DEPLOY_FAILED', 'wrangler deploy', result.output);
+        }
+        const url = CloudflareDeployment.urlOf(result.output);
+        const version = /Current Version ID:\s*(\S+)/.exec(result.output)?.[1];
+        return { url, details: version ? { versionId: version } : undefined };
+    }
+
+    /** Where the worker answers: its first custom domain, else its workers.dev address (as Wrangler lists them after deploying). */
+    static urlOf(output: string): string | undefined {
+        const domain = /^\s+(\S+) \(custom domain\)\s*$/m.exec(output)?.[1];
+        return domain ? `https://${domain}` : /https:\/\/\S+\.workers\.dev\b/.exec(output)?.[0];
+    }
+
+    protected readonly relay = (chunk: string, stream: 'stdout' | 'stderr') => this.context.relay(chunk, stream);
+
+    protected readConfig(): WranglerJson {
+        if (this.context.manifest.preset !== 'cloudflare' || !existsSync(this.file)) {
+            throw new CellError({
+                code: 'CELL_DEPLOY_OUTPUT_MISMATCH',
+                message: `${this.context.outDir} has no output of the cloudflare preset (built with: ${this.context.manifest.preset ?? 'no preset'}).`,
+                file: join(this.context.outDir, 'manifest.json'),
+                hint: 'Run `cell deploy --preset cloudflare` without --skip-build, or `cell build --preset cloudflare` first.',
+            });
+        }
+        return JSON.parse(readFileSync(this.file, 'utf8')) as WranglerJson;
+    }
+
+    /** The worker and its assets, with the sizes Wrangler reported in the dry run. */
+    protected resources(config: WranglerJson, output: string): DeployResource[] {
+        const name = String(config.name);
+        const upload = /Total Upload:\s*(.+)/.exec(output)?.[1]?.trim();
+        const files = /Read (\d+) files? from the assets directory/.exec(output)?.[1];
+        const resources: DeployResource[] = [];
+        if (config.main) {
+            resources.push({
+                type: 'worker',
+                name,
+                action: 'deploy',
+                details: {
+                    main: config.main,
+                    compatibilityDate: config.compatibility_date,
+                    compatibilityFlags: config.compatibility_flags,
+                    ...(upload ? { upload } : {}),
+                },
+            });
+        }
+        const directory = (config.assets as { directory?: string } | undefined)?.directory;
+        if (directory) {
+            resources.push({ type: 'assets', name, action: 'deploy', details: { directory, ...(files ? { files: Number(files) } : {}) } });
+        }
+        return resources;
+    }
+
+    protected failure(code: string, step: string, output: string): CellError {
+        return new CellError({
+            code,
+            message: `${step} failed: ${Wrangler.errorOf(output)}`,
+            file: this.file,
+            hint: Wrangler.isSubdomainError(output)
+                ? CloudflareDeployment.SUBDOMAIN_HINT
+                : Wrangler.isAuthError(output)
+                  ? CloudflareDeployment.AUTH_HINT
+                  : 'Fix the reported problem (Wrangler printed the details above), then run cell deploy again.',
+        });
+    }
+}
+
+export const cloudflareDeployer = defineDeployer({
+    name: 'cloudflare',
+    description: "Cloudflare Workers through Wrangler (the project's, or wrangler@4 installed on first use)",
+    plan: context => new CloudflareDeployment(context).plan(),
+    apply: (context, plan) => new CloudflareDeployment(context).apply(plan),
+});