@celljs/cli 3.9.0 → 4.0.0

package/src/cli/build-command.ts

@@ -0,0 +1,189 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { CellError, type OutputManifest, type ProjectModel } from '@celljs/kit';
+import { CellBuilder, type CellBuilderOptions } from '@celljs/vite';
+import { ExecutableCompiler } from '../build/executable-compiler.js';
+import { type ConfigFlags, ConfigResolver } from '../config/config-resolver.js';
+import type { CompileTarget } from '../config/types.js';
+import { ProjectInspector } from '../info/project-inspector.js';
+import { PresetOutput } from '../preset/preset-output.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { Command, type CommandContext, type ParsedValues } from './command.js';
+import type { Reporter } from './reporter.js';
+
+export interface BuildResult {
+    options: CellBuilderOptions;
+    model: ProjectModel;
+    /** Absolute output directory. */
+    outDir: string;
+    manifest: OutputManifest;
+}
+
+/** `cell build`: build every target into the output directory, as the preset prescribes. */
+export class BuildCommand extends Command {
+    readonly name = 'build';
+    readonly description = 'Build the application into .cell/output';
+    /** Options that decide what is built; `cell info` accepts the same ones. */
+    static readonly OPTIONS = {
+        preset: { type: 'string' },
+        mode: { type: 'string', short: 'm', multiple: true },
+        format: { type: 'string' },
+        single: { type: 'boolean' },
+        compile: { type: 'string' },
+        'compile-target': { type: 'string' },
+        sourcemap: { type: 'boolean' },
+        'out-dir': { type: 'string' },
+    } as const;
+    static readonly USAGE = [
+        '--preset <name>      shape of the output: node (default), cloudflare, cli',
+        '-m, --mode <mode>    extra mode, reads cell.<mode>.yml (repeatable)',
+        '--format <esm|cjs>   server bundle format',
+        '--single             embed the frontend in server/index.mjs: one file runs the whole app',
+        '--compile [tool]     one executable .cell/output/app: bun (default), node or deno',
+        '--compile-target <t> cross-compile with bun or deno, e.g. bun-linux-x64',
+        '--sourcemap          emit source maps',
+        '--out-dir <dir>      output directory (default: .cell/output)',
+    ];
+    override readonly options = BuildCommand.OPTIONS;
+    override readonly usage = BuildCommand.USAGE;
+
+    static flags(values: ParsedValues): ConfigFlags {
+        const format = values.format as string | undefined;
+        if (format !== undefined && format !== 'esm' && format !== 'cjs') {
+            throw new CellError({ code: 'CELL_ARGUMENT_INVALID', message: `Invalid --format '${format}'.`, hint: 'Use --format esm or --format cjs.' });
+        }
+        const compile = values.compile as string | undefined;
+        if (compile !== undefined && !['bun', 'node', 'deno'].includes(compile)) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `Invalid --compile '${compile}'.`,
+                hint: 'Use --compile, --compile bun, --compile node or --compile deno.',
+            });
+        }
+        return {
+            preset: values.preset as string | undefined,
+            mode: values.mode as string[] | undefined,
+            format,
+            single: values.single as boolean | undefined,
+            compile: compile as CompileTarget | undefined,
+            sourcemap: values.sourcemap as boolean | undefined,
+            outDir: values['out-dir'] as string | undefined,
+        };
+    }
+
+    /** Files of modules (`cell.addOutputFile`), relative to the output directory, which they must not leave. */
+    static writeFiles(outDir: string, files: Record<string, string | Uint8Array>): void {
+        for (const [path, content] of Object.entries(files)) {
+            const file = resolve(outDir, path);
+            if (!file.startsWith(outDir + sep)) {
+                throw new CellError({
+                    code: 'CELL_MODULE_ERROR',
+                    message: `Output file '${path}' is outside the output directory.`,
+                    hint: 'Pass a path relative to the output directory to cell.addOutputFile().',
+                });
+            }
+            mkdirSync(dirname(file), { recursive: true });
+            writeFileSync(file, content);
+        }
+    }
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const started = performance.now();
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'build',
+            flags: BuildCommand.flags(values),
+            env,
+            quiet: reporter.json,
+            logger: reporter,
+        });
+        const { config, preset } = toolchain;
+        const compileTarget = values['compile-target'] as string | undefined;
+        if (compileTarget !== undefined && !config.build.compile) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: '--compile-target needs --compile.',
+                hint: 'Use --compile bun --compile-target bun-linux-x64, for example.',
+            });
+        }
+        const { options, model, manifest } = await BuildCommand.build(toolchain, reporter, env, compileTarget);
+        await toolchain.close();
+        const outDir = relative(process.cwd(), `${config.root}/${options.outDir}`) || '.';
+        const durationMs = Math.round(performance.now() - started);
+        reporter.result(
+            'build',
+            {
+                root: config.root,
+                preset: preset.name,
+                format: options.format,
+                mode: config.mode,
+                targets: model.targets,
+                outDir: options.outDir,
+                entry: model.backend?.entry,
+                ...(manifest.single ? { single: true } : {}),
+                ...(manifest.executable ? { executable: manifest.executable } : {}),
+                durationMs,
+            },
+            manifest.executable
+                ? `Built ${model.targets.join(' + ')} → ${join(outDir, manifest.executable.file)} in ${durationMs}ms`
+                : `Built ${model.targets.join(' + ')}${manifest.single ? ' (single file)' : ''} → ${outDir} in ${durationMs}ms`,
+        );
+        return 0;
+    }
+
+    /** Builds every target and writes the files of the preset and of modules: `cell build`, and `cell deploy` before it deploys. */
+    static async build(toolchain: Toolchain, reporter: Reporter, env: NodeJS.ProcessEnv, compileTarget?: string): Promise<BuildResult> {
+        const { config, preset, events } = toolchain;
+        const options = toolchain.builderOptions();
+        const cancelled = await events.gate('build:before', { config, preset });
+        if (cancelled) {
+            throw new CellError({
+                code: 'CELL_BUILD_CANCELLED',
+                message: `The build was cancelled: ${cancelled.reason}.`,
+                hint: 'Fix the reported hook or module, then build again.',
+            });
+        }
+        reporter.info(`Building with the ${preset.name} preset (${options.format}, mode ${config.mode.join(', ')})…`);
+        const model = await new CellBuilder({ ...options, env, logLevel: 'warn' }).build();
+        if (model.backend && preset.entry && !model.backend.entryComponent && !options.entry?.backend) {
+            reporter.warn(ProjectInspector.missingEntryWarning(preset));
+        }
+        // Backend variables matter where the server runs, not here; `cell info` checks them.
+        for (const problem of model.frontend?.envOverrides.problems ?? []) {
+            reporter.warn(ProjectInspector.envProblemWarning('frontend', problem));
+        }
+        const outDir = resolve(config.root, options.outDir ?? ConfigResolver.DEFAULT_OUT_DIR);
+        let manifest = await PresetOutput.write(preset, {
+            root: config.root,
+            outDir,
+            project: model,
+            env,
+            options: toolchain.presetOptions(),
+            warn: message => reporter.warn(message),
+        });
+        if (config.build.single && !manifest.single) {
+            reporter.warn(
+                '--single embeds the frontend in the server bundle, but the project does not build both a frontend and a backend: the output is as without it.',
+            );
+        }
+        if (config.build.compile) {
+            manifest = new ExecutableCompiler({
+                outDir,
+                manifest,
+                compiler: config.build.compile,
+                target: compileTarget,
+                env,
+                info: m => reporter.info(m),
+            }).compile();
+            writeFileSync(join(outDir, PresetOutput.MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+        } else if (manifest.single && existsSync(join(outDir, 'server', 'node_modules'))) {
+            reporter.warn('server/node_modules (packages kept outside the bundle) must stay next to server/index.* for the single file to run.');
+        }
+        const files: Record<string, string | Uint8Array> = Object.fromEntries([...toolchain.modules.outputFiles].map(([path, { value }]) => [path, value]));
+        // build:done handlers may add, change or remove files before they are written.
+        const done = await events.emit('build:done', { config, preset, project: model, outDir: options.outDir, files });
+        BuildCommand.writeFiles(outDir, done.files);
+        await events.emit('output:done', { config, preset, outDir: done.outDir });
+        return { options, model, outDir, manifest };
+    }
+}

package/src/cli/cell-cli.ts

@@ -0,0 +1,174 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { CellError } from '@celljs/kit';
+import { TextUtil } from '../utils/text-util.js';
+import { AgentCommand } from './agent-command.js';
+import { BuildCommand } from './build-command.js';
+import { CheckCommand } from './check-command.js';
+import type { Command, ParseArgsOptions, ParsedValues } from './command.js';
+import { ConfigCommand } from './config-command.js';
+import { DeployCommand } from './deploy-command.js';
+import { DevCommand } from './dev-command.js';
+import { DocsCommand } from './docs-command.js';
+import { InfoCommand } from './info-command.js';
+import { InitCommand } from './init-command.js';
+import { McpCommand } from './mcp-command.js';
+import { PreviewCommand } from './preview-command.js';
+import { Reporter, type Writable } from './reporter.js';
+
+export interface CellCliOptions {
+    stdout?: Writable;
+    stderr?: Writable;
+    env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The `cell` command line. Never prompts; every command accepts `--json`; failures print a
+ * CellError and exit with 1, invalid usage with 2 (docs/design/agent-first.md R5, R6, R9).
+ */
+export class CellCli {
+    static readonly COMMON_OPTIONS: ParseArgsOptions = {
+        root: { type: 'string' },
+        json: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    };
+    static readonly COMPILE_TARGETS = ['bun', 'node', 'deno'];
+
+    protected readonly commands: Command[] = [
+        new InitCommand(() => CellCli.version),
+        new DevCommand(),
+        new BuildCommand(),
+        new PreviewCommand(),
+        new DeployCommand(),
+        new InfoCommand(),
+        new CheckCommand(),
+        new ConfigCommand(),
+        new DocsCommand(),
+        new McpCommand(argv => this.capture(argv)),
+        new AgentCommand(() => CellCli.version),
+    ];
+
+    constructor(protected readonly options: CellCliOptions = {}) {}
+
+    static get version(): string {
+        return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+    }
+
+    async run(argv: string[]): Promise<number> {
+        const json = argv.includes('--json');
+        const reporter = new Reporter(json, this.options.stdout, this.options.stderr);
+        const [name, ...rest] = argv;
+        if (name === undefined || name === '--help' || name === '-h' || name === 'help') {
+            this.write(this.help());
+            return 0;
+        }
+        if (name === '--version' || name === '-v') {
+            this.write(CellCli.version);
+            return 0;
+        }
+        const command = this.commands.find(c => c.name === name);
+        try {
+            if (!command) {
+                const suggestion = TextUtil.closest(
+                    name,
+                    this.commands.map(c => c.name),
+                );
+                throw new CellError({
+                    code: 'CELL_ARGUMENT_INVALID',
+                    message: `Unknown command '${name}'.`,
+                    hint: suggestion
+                        ? `Did you mean 'cell ${suggestion}'?`
+                        : `Run 'cell --help' for the commands: ${this.commands.map(c => c.name).join(', ')}.`,
+                });
+            }
+            const { values, positionals } = this.parse(command, rest);
+            if (values.help) {
+                this.write(this.commandHelp(command));
+                return 0;
+            }
+            return await command.run({ values, positionals, reporter, env: this.options.env ?? process.env });
+        } catch (error) {
+            const cellError = Reporter.toCellError(error);
+            if (cellError.code === 'CELL_INTERNAL_ERROR' && (this.options.env ?? process.env).CELL_DEBUG) {
+                (this.options.stderr ?? process.stderr).write(`${(error as Error).stack}\n`);
+            }
+            reporter.error(command?.name, cellError);
+            return cellError.code === 'CELL_ARGUMENT_INVALID' ? 2 : 1;
+        }
+    }
+
+    protected parse(command: Command, args: string[]): { values: ParsedValues; positionals: string[] } {
+        const options = { ...CellCli.COMMON_OPTIONS, ...command.options };
+        try {
+            const { values, positionals } = parseArgs({ args: this.normalizeCompile(args), options, allowPositionals: command.arguments !== '', strict: true });
+            return { values: values as ParsedValues, positionals };
+        } catch (error) {
+            const message = (error as Error).message.split('\n')[0];
+            const unknown = /Unknown option '(-{1,2}[^']+)'/.exec(message)?.[1];
+            const known = Object.keys(options).map(o => `--${o}`);
+            const suggestion = unknown && TextUtil.closest(unknown, known);
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message,
+                hint: suggestion ? `Did you mean '${suggestion}'?` : `Run 'cell ${command.name} --help' for the options.`,
+                cause: error,
+            });
+        }
+    }
+
+    /** `--compile` takes an optional target: a bare `--compile` means bun. */
+    protected normalizeCompile(args: string[]): string[] {
+        return args.flatMap((arg, i) => {
+            if (arg !== '--compile') {
+                return [arg];
+            }
+            const next = args[i + 1];
+            return next && CellCli.COMPILE_TARGETS.includes(next) ? [arg] : ['--compile=bun'];
+        });
+    }
+
+    protected help(): string {
+        const width = Math.max(...this.commands.map(c => c.name.length)) + 2;
+        return [
+            `cell ${CellCli.version}`,
+            '',
+            'Usage: cell <command> [options]',
+            '',
+            'Commands:',
+            ...this.commands.map(c => `  ${c.name.padEnd(width)}${c.description}`),
+            '',
+            'Common options:',
+            '  --root <dir>         project root (default: current directory)',
+            '  --json               print one JSON result on stdout',
+            '  -h, --help           show help',
+        ].join('\n');
+    }
+
+    protected commandHelp(command: Command): string {
+        return [
+            `Usage: cell ${command.name}${command.arguments ? ` ${command.arguments}` : ''} [options]`,
+            '',
+            command.description,
+            '',
+            'Options:',
+            ...command.usage.map(line => `  ${line}`),
+            '  --root <dir>         project root',
+            '  --json               print one JSON result on stdout',
+        ].join('\n');
+    }
+
+    /** Runs a command in this process with its stdout captured (`cell mcp`); stderr stays. */
+    protected async capture(argv: string[]): Promise<{ code: number; stdout: string }> {
+        let stdout = '';
+        const code = await new CellCli({
+            stdout: { write: chunk => (stdout += chunk) },
+            stderr: this.options.stderr ?? process.stderr,
+            env: this.options.env,
+        }).run(argv);
+        return { code, stdout };
+    }
+
+    protected write(text: string): void {
+        (this.options.stdout ?? process.stdout).write(`${text}\n`);
+    }
+}

package/src/cli/check-command.ts

@@ -0,0 +1,74 @@
+import { relative } from 'node:path';
+import type { CheckIssue } from '@celljs/kit';
+import { ProjectChecker } from '../check/project-checker.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { BuildCommand } from './build-command.js';
+import { Command, type CommandContext } from './command.js';
+
+/**
+ * `cell check`: configuration, types, decorator settings, DI bindings and module checks in one run.
+ * Exits with 1 when an error-level issue is found; `--json` lists every issue with a stable code.
+ */
+export class CheckCommand extends Command {
+    readonly name = 'check';
+    readonly description = 'Check configuration, types, decorators and DI bindings';
+    override readonly options = {
+        preset: BuildCommand.OPTIONS.preset,
+        mode: BuildCommand.OPTIONS.mode,
+        skip: { type: 'string', multiple: true },
+    } as const;
+    override readonly usage = [
+        '--preset <name>      preset whose entry the backend uses (default: node)',
+        '-m, --mode <mode>    extra mode, reads cell.<mode>.yml (repeatable)',
+        '--skip <check>       skip a check: config, types, decorators, di or a module check (repeatable)',
+    ];
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const started = performance.now();
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'check',
+            flags: { preset: values.preset as string | undefined, mode: values.mode as string[] | undefined },
+            env,
+            quiet: reporter.json,
+            runHooks: false,
+            logger: reporter,
+        });
+        const reports = await new ProjectChecker(toolchain, { env, skip: values.skip as string[] | undefined }).run();
+        await toolchain.close();
+        const issues = reports.flatMap(report => report.issues.map(issue => ({ check: report.name, ...issue })));
+        const errors = issues.filter(issue => issue.level === 'error').length;
+        const warnings = issues.filter(issue => issue.level === 'warning').length;
+        const durationMs = Math.round(performance.now() - started);
+        const root = toolchain.config.root;
+        reporter.result(
+            'check',
+            {
+                root,
+                passed: errors === 0,
+                // `warnings` of the result are those of the command itself; the findings are in `issues`.
+                summary: { errors, warnings, info: issues.length - errors - warnings },
+                issues,
+                checks: reports.map(({ issues: found, ...report }) => ({ ...report, issues: found.length })),
+                durationMs,
+            },
+            [
+                ...issues.filter(issue => issue.level !== 'info').map(issue => CheckCommand.formatIssue(issue, root)),
+                ...reports.filter(report => report.skipped).map(report => `skipped ${report.name}: ${report.skipped}`),
+                `${errors === 0 ? 'Passed' : 'Failed'}: ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} (${reports
+                    .filter(r => !r.skipped)
+                    .map(r => r.name)
+                    .join(', ')}) in ${durationMs}ms`,
+            ].join('\n'),
+        );
+        return errors === 0 ? 0 : 1;
+    }
+
+    /** `src/a.ts:3:5 error TS2322 message`, like compilers print. */
+    static formatIssue(issue: CheckIssue & { check: string }, root: string): string {
+        const where = issue.file
+            ? `${relative(root, issue.file) || issue.file}${issue.line ? `:${issue.line}${issue.column ? `:${issue.column}` : ''}` : ''} `
+            : '';
+        return `${where}${issue.level} ${issue.code} ${issue.message}${issue.hint ? `\n  fix: ${issue.hint}` : ''}`;
+    }
+}

package/src/cli/command.ts

@@ -0,0 +1,29 @@
+import type { ParseArgsConfig } from 'node:util';
+
+export type ParseArgsOptions = NonNullable<ParseArgsConfig['options']>;
+
+import type { Reporter } from './reporter.js';
+
+export type ParsedValues = Record<string, string | boolean | string[] | undefined>;
+
+export interface CommandContext {
+    values: ParsedValues;
+    positionals: string[];
+    reporter: Reporter;
+    env: NodeJS.ProcessEnv;
+}
+
+/** One `cell <name>` command. Options are parsed with node:util `parseArgs`. */
+export abstract class Command {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    /** Options of this command in addition to the common ones (`--root`, `--json`, `--help`). */
+    readonly options: ParseArgsOptions = {};
+    /** One line per option for `--help`. */
+    readonly usage: string[] = [];
+    /** Positional arguments for `--help`, e.g. `get <key>`; commands without them reject positionals. */
+    readonly arguments: string = '';
+
+    /** Returns the process exit code. */
+    abstract run(context: CommandContext): Promise<number>;
+}

package/src/cli/config-command.ts

@@ -0,0 +1,73 @@
+import { CellError, type Target } from '@celljs/kit';
+import { ProjectLoader } from '@celljs/vite';
+import { ConfigExplainer, type ConfigValue } from '../config/config-explainer.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { BuildCommand } from './build-command.js';
+import { Command, type CommandContext } from './command.js';
+
+/**
+ * `cell config get <key>`: one value of the merged application configuration (cell*.yml of every
+ * component and the active modes, then `CELL_<TARGET>__*` variables), with the files and variables
+ * that set it. Read-only, like `cell info`.
+ */
+export class ConfigCommand extends Command {
+    readonly name = 'config';
+    readonly description = 'Show a configuration value and where it comes from';
+    override readonly arguments = 'get <key>';
+    override readonly options = {
+        mode: BuildCommand.OPTIONS.mode,
+        target: { type: 'string' },
+        why: { type: 'boolean' },
+    } as const;
+    override readonly usage = [
+        '-m, --mode <mode>    extra mode, reads cell.<mode>.yml (repeatable)',
+        '--target <target>    backend or frontend (default: backend, else frontend)',
+        '--why                list the files and variables that set the value',
+    ];
+
+    async run({ values, positionals, reporter, env }: CommandContext): Promise<number> {
+        const [action, key, ...rest] = positionals;
+        if (action !== 'get' || key === undefined || rest.length > 0) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: action === 'get' ? 'cell config get takes one key.' : `Unknown config action '${action ?? ''}'.`,
+                hint: 'Use cell config get <key>, e.g. cell config get cell.server.port.',
+            });
+        }
+        const target = values.target as string | undefined;
+        if (target !== undefined && target !== 'backend' && target !== 'frontend') {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `Invalid --target '${target}'.`,
+                hint: 'Use --target backend or --target frontend.',
+            });
+        }
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'config',
+            flags: { mode: values.mode as string[] | undefined },
+            env,
+            quiet: reporter.json,
+            runHooks: false,
+            logger: reporter,
+        });
+        await toolchain.close();
+        const model = new ProjectLoader({ ...toolchain.projectOptions(), env }).load();
+        const result = new ConfigExplainer(model, env).explain(key, target as Target | undefined);
+        reporter.result('config', { ...result }, ConfigCommand.format(result, values.why === true));
+        return 0;
+    }
+
+    static format(result: ConfigValue, why: boolean): string {
+        const value = typeof result.value === 'string' ? result.value : JSON.stringify(result.value, null, 2);
+        if (!why) {
+            return value;
+        }
+        return [
+            `${result.key} (${result.target}) = ${value}`,
+            ...result.layers.map(layer => `  ${layer.file}${layer.section === 'shared' ? '' : ` [${layer.section}]`}: ${JSON.stringify(layer.value)}`),
+            ...result.env.map(({ variable, path }) => `  ${variable} → ${path}`),
+            ...(result.expressions ? ['  ${...} is evaluated by the server at startup'] : []),
+        ].join('\n');
+    }
+}

package/src/cli/deploy-command.ts

@@ -0,0 +1,122 @@
+import { relative, resolve } from 'node:path';
+import { CellError, type Deployment, type DeployPlan, type OutputManifest } from '@celljs/kit';
+import { ConfigResolver } from '../config/config-resolver.js';
+import { DeployerRegistry } from '../deploy/deployer-registry.js';
+import { PresetOutput } from '../preset/preset-output.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { BuildCommand } from './build-command.js';
+import { Command, type CommandContext } from './command.js';
+
+/**
+ * `cell deploy`: build with the preset, then publish the output with the preset's deployer. The
+ * deployer plans first; `--dry-run` prints the plan and changes nothing (docs/design/agent-first.md R9).
+ */
+export class DeployCommand extends Command {
+    readonly name = 'deploy';
+    readonly description = 'Build and deploy the application (--dry-run to only plan)';
+    override readonly options = {
+        preset: BuildCommand.OPTIONS.preset,
+        mode: BuildCommand.OPTIONS.mode,
+        sourcemap: BuildCommand.OPTIONS.sourcemap,
+        'out-dir': BuildCommand.OPTIONS['out-dir'],
+        'dry-run': { type: 'boolean' },
+        'skip-build': { type: 'boolean' },
+    } as const;
+    override readonly usage = [
+        '--preset <name>      platform: cloudflare, fc, scf, lambda or vercel',
+        '-m, --mode <mode>    extra mode, reads cell.<mode>.yml (repeatable)',
+        '--dry-run            build and plan only; nothing is deployed',
+        '--skip-build         deploy the existing output in --out-dir',
+        '--sourcemap          emit source maps',
+        '--out-dir <dir>      output directory (default: .cell/output)',
+    ];
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const started = performance.now();
+        const dryRun = values['dry-run'] === true;
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'deploy',
+            flags: BuildCommand.flags(values),
+            env,
+            quiet: reporter.json,
+            logger: reporter,
+        });
+        const { config, events } = toolchain;
+        const outDir = resolve(config.root, config.build.outDir);
+        const existing = values['skip-build'] ? this.existingOutput(toolchain, outDir) : undefined;
+        // Checked before building: a preset without a deployer fails fast.
+        const preset = existing ? toolchain.presets.resolve(existing.preset ?? ConfigResolver.DEFAULT_PRESET) : toolchain.preset;
+        if (!preset.deployer) {
+            throw new CellError({
+                code: 'CELL_DEPLOY_UNSUPPORTED',
+                message: `The ${preset.name} preset has no deployer; its output in ${relative(process.cwd(), outDir) || '.'} runs wherever you start it.`,
+                file: config.preset.source === 'config' ? config.file : undefined,
+                hint: `Deploy with a preset that has a deployer: --preset ${DeployCommand.deployable(toolchain).join(', --preset ')}.`,
+            });
+        }
+        const deployer = DeployerRegistry.builtin().get(preset.deployer);
+        const manifest = existing ?? (await BuildCommand.build(toolchain, reporter, env)).manifest;
+        const context = {
+            root: config.root,
+            outDir,
+            manifest,
+            env,
+            options: toolchain.presetOptions(preset.name),
+            info: (message: string) => reporter.info(message),
+            warn: (message: string) => reporter.warn(message),
+            relay: (chunk: string, stream: 'stdout' | 'stderr') => reporter.relay(chunk, stream),
+        };
+        const cancelled = await events.gate('deploy:before', { config, preset, manifest, dryRun });
+        if (cancelled) {
+            throw new CellError({
+                code: 'CELL_DEPLOY_CANCELLED',
+                message: `The deployment was cancelled: ${cancelled.reason}.`,
+                hint: 'Fix the reported hook or module, then deploy again.',
+            });
+        }
+        const { plan } = await events.emit('deploy:plan', { config, preset, plan: await deployer.plan(context) });
+        let deployment: Deployment | undefined;
+        if (!dryRun) {
+            reporter.info(`Deploying with ${deployer.name}…`);
+            deployment = await deployer.apply(context, plan);
+            await events.emit('deploy:done', { config, preset, plan, deployment });
+        }
+        await toolchain.close();
+        const durationMs = Math.round(performance.now() - started);
+        reporter.result(
+            'deploy',
+            { root: config.root, preset: preset.name, deployer: deployer.name, dryRun, plan, ...(deployment ? { deployment } : {}), durationMs },
+            DeployCommand.describe(plan, deployment),
+        );
+        return 0;
+    }
+
+    /** `--skip-build`: the output must exist and come from the preset this run chose. */
+    protected existingOutput(toolchain: Toolchain, outDir: string): OutputManifest {
+        const manifest = PresetOutput.read(outDir);
+        const chosen = toolchain.config.preset;
+        if (chosen.source !== 'default' && manifest.preset !== chosen.name) {
+            throw new CellError({
+                code: 'CELL_DEPLOY_OUTPUT_MISMATCH',
+                message: `The output in ${outDir} was built with the ${manifest.preset ?? 'unknown'} preset, not ${chosen.name}.`,
+                file: toolchain.config.file,
+                hint: `Run cell deploy without --skip-build, or cell build --preset ${chosen.name} first.`,
+            });
+        }
+        return manifest;
+    }
+
+    /** Presets that have a deployer, for hints. */
+    static deployable(toolchain: Toolchain): string[] {
+        return toolchain.presets.names.filter(name => toolchain.presets.resolve(name).deployer);
+    }
+
+    static describe(plan: DeployPlan, deployment?: Deployment): string {
+        const lines = plan.resources.map(r => `  ${r.action} ${r.type} ${r.name}${r.details ? ` ${JSON.stringify(r.details)}` : ''}`);
+        if (!deployment) {
+            return [`Plan (${plan.deployer}):`, ...lines, 'Nothing was deployed (--dry-run).'].join('\n');
+        }
+        return [`Deployed (${plan.deployer}):`, ...lines, ...(deployment.url ? [`URL: ${deployment.url}`] : [])].join('\n');
+    }
+}