@celljs/cli 3.9.0 → 4.0.0

package/src/cli/dev-command.ts

@@ -0,0 +1,232 @@
+import { type FSWatcher, watch } from 'node:fs';
+import { relative } from 'node:path';
+import { CellError } from '@celljs/kit';
+import { CellDevServer } from '@celljs/vite';
+import type { Logger } from 'vite';
+import { ConfigResolver } from '../config/config-resolver.js';
+import { DevActivity } from '../mcp/dev-activity.js';
+import { DevMcpEndpoint } from '../mcp/dev-mcp-endpoint.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { BuildCommand } from './build-command.js';
+import { Command, type CommandContext, type ParsedValues } from './command.js';
+import type { Reporter } from './reporter.js';
+
+type Outcome = { kind: 'restart'; files: string[] } | { kind: 'exit' };
+
+/**
+ * `cell dev`: frontend and backend on one port with the `development` mode. The frontend has
+ * Vite's HMR, the backend reloads when one of its files changes, and a change of cell*.yml,
+ * package.json or cell.config.* restarts everything with a new toolchain. Runs until SIGINT/SIGTERM.
+ */
+export class DevCommand extends Command {
+    readonly name = 'dev';
+    readonly description = 'Run the application for development: one port, frontend HMR, backend reload';
+    override readonly options = {
+        preset: BuildCommand.OPTIONS.preset,
+        mode: BuildCommand.OPTIONS.mode,
+        port: { type: 'string', short: 'p' },
+        host: { type: 'string' },
+    } as const;
+    override readonly usage = [
+        '--preset <name>      preset whose entry runs the backend (default: node)',
+        '-m, --mode <mode>    extra mode, reads cell.<mode>.yml (repeatable); development is always on',
+        '-p, --port <port>    port (default: cell.server.port, else 3000)',
+        '--host <host>        interface to listen on (default: cell.server.host, else 127.0.0.1)',
+    ];
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const port = DevCommand.port(values);
+        const restore = reporter.json ? DevCommand.consoleToStderr() : undefined;
+        const activity = new DevActivity();
+        const stopCapture = activity.captureConsole();
+        let current: CellDevServer | undefined;
+        const { CellCli } = await import('./cell-cli.js');
+        const mcp = new DevMcpEndpoint(() => current, activity, CellCli.version);
+        let first = true;
+        let address: { host: string; port: number } | undefined;
+        try {
+            for (;;) {
+                const started = performance.now();
+                let toolchain: Toolchain;
+                let server: CellDevServer;
+                let settle!: (outcome: Outcome) => void;
+                const outcome = new Promise<Outcome>(resolve => {
+                    settle = resolve;
+                });
+                try {
+                    toolchain = await Toolchain.create({
+                        root: values.root as string | undefined,
+                        command: 'dev',
+                        flags: { preset: values.preset as string | undefined, mode: values.mode as string[] | undefined },
+                        env,
+                        quiet: reporter.json,
+                        logger: reporter,
+                        // A failing module handler is reported; development goes on (docs/design/modules.md §3.4).
+                        onNotifyError: error => reporter.info(error.format()),
+                    });
+                    const { config, preset, events } = toolchain;
+                    server = await new CellDevServer({
+                        ...toolchain.projectOptions(),
+                        plugins: toolchain.modules.vitePlugins(),
+                        devHandlers: [{ path: DevMcpEndpoint.PATH, handler: mcp.handler }, ...(toolchain.modules.devHandlerList as never[])],
+                        watchFiles: toolchain.modules.watchFileList,
+                        env,
+                        preset: preset.name,
+                        format: ConfigResolver.format(config, preset),
+                        outDir: config.build.outDir,
+                        vite: config.vite,
+                        // A restart keeps the address the first start got.
+                        port: address?.port ?? port,
+                        host: address?.host ?? (values.host as string | undefined),
+                        logLevel: reporter.json ? 'warn' : 'info',
+                        logger: reporter.json ? DevCommand.stderrLogger(reporter) : undefined,
+                        onRestart: files => settle({ kind: 'restart', files }),
+                        onRequest: record => activity.recordRequest(record),
+                        onReload: (files, error) => {
+                            if (error) {
+                                activity.recordError(error, files);
+                                reporter.info(error.format());
+                            } else {
+                                reporter.info(`Reloaded the backend (${files.map(file => relative(config.root, file)).join(', ')})`);
+                            }
+                            void events.emit('dev:reload', { files, error: error?.toJSON() }).catch(e => reporter.info(DevCommand.format(e)));
+                        },
+                    }).start();
+                } catch (error) {
+                    if (first) {
+                        throw error;
+                    }
+                    // A broken cell.config.ts or cell.yml: report it and try again on the next change.
+                    reporter.info(DevCommand.format(error));
+                    const next = await DevCommand.waitForConfigChange(values.root as string | undefined);
+                    if (next.kind === 'exit') {
+                        return 0;
+                    }
+                    continue;
+                }
+                const { config, preset, events } = toolchain;
+                current = server;
+                address = server.address;
+                const stopOnSignal = DevCommand.onSignal(() => settle({ kind: 'exit' }));
+                await events.emit('dev:ready', { url: server.url, port: address.port });
+                if (server.error) {
+                    activity.recordError(server.error);
+                    reporter.info(server.error.format());
+                }
+                const mcpUrl = `${server.url}${DevMcpEndpoint.PATH}`;
+                const durationMs = Math.round(performance.now() - started);
+                if (first) {
+                    reporter.result(
+                        'dev',
+                        {
+                            root: config.root,
+                            url: server.url,
+                            port: address.port,
+                            preset: preset.name,
+                            mode: config.mode,
+                            targets: server.project.targets,
+                            mcp: mcpUrl,
+                            durationMs,
+                            ...(server.error ? { backendError: server.error.toJSON() } : {}),
+                        },
+                        `Ready at ${server.url} (${server.project.targets.join(' + ')}, mode ${config.mode.join(', ')}) in ${durationMs}ms\n  MCP endpoint for agents: ${mcpUrl}`,
+                    );
+                    first = false;
+                } else {
+                    reporter.info(`Restarted at ${server.url} in ${durationMs}ms`);
+                }
+                const result = await outcome;
+                stopOnSignal();
+                current = undefined;
+                await server.close();
+                await toolchain.close(result.kind);
+                if (result.kind === 'exit') {
+                    return 0;
+                }
+                reporter.info(`${result.files.map(file => relative(config.root, file)).join(', ')} changed, restarting…`);
+            }
+        } finally {
+            stopCapture();
+            restore?.();
+        }
+    }
+
+    static port(values: ParsedValues): number | undefined {
+        const port = values.port as string | undefined;
+        if (port !== undefined && !/^\d+$/.test(port)) {
+            throw new CellError({ code: 'CELL_ARGUMENT_INVALID', message: `Invalid --port '${port}'.`, hint: 'Pass a port number, e.g. --port 3000.' });
+        }
+        return port === undefined ? undefined : Number(port);
+    }
+
+    /** Resolves once on SIGINT or SIGTERM; returns the function that stops listening. */
+    protected static onSignal(handler: () => void): () => void {
+        process.once('SIGINT', handler);
+        process.once('SIGTERM', handler);
+        return () => {
+            process.off('SIGINT', handler);
+            process.off('SIGTERM', handler);
+        };
+    }
+
+    protected static waitForConfigChange(root = process.cwd()): Promise<Outcome> {
+        return new Promise(resolve => {
+            let watcher: FSWatcher | undefined;
+            const done = (outcome: Outcome) => {
+                watcher?.close();
+                stop();
+                resolve(outcome);
+            };
+            const stop = DevCommand.onSignal(() => done({ kind: 'exit' }));
+            watcher = watch(root, (_event, file) => {
+                if (file && CellDevServer.CONFIG_FILE.test(file)) {
+                    done({ kind: 'restart', files: [file] });
+                }
+            });
+        });
+    }
+
+    /** `--json`: stdout carries only the result line, so the application's console output goes to stderr. */
+    protected static consoleToStderr(): () => void {
+        const { log, info, debug, error } = console;
+        // The stderr function of now: a later wrapper of console.error must not see these twice.
+        console.log = console.info = console.debug = (...args: unknown[]) => error.apply(console, args);
+        return () => {
+            Object.assign(console, { log, info, debug });
+        };
+    }
+
+    static format(error: unknown): string {
+        return (
+            CellError.is(error)
+                ? error
+                : new CellError({
+                      code: 'CELL_INTERNAL_ERROR',
+                      message: String((error as Error)?.message ?? error),
+                      hint: 'Rerun with CELL_DEBUG=1 and report it.',
+                  })
+        ).format();
+    }
+
+    protected static stderrLogger(reporter: Reporter): Logger {
+        const warned = new Set<string>();
+        const logger: Logger = {
+            hasWarned: false,
+            info: message => reporter.info(message),
+            warn: message => {
+                logger.hasWarned = true;
+                reporter.info(message);
+            },
+            warnOnce: message => {
+                if (!warned.has(message)) {
+                    warned.add(message);
+                    logger.warn(message);
+                }
+            },
+            error: message => reporter.info(message),
+            clearScreen: () => {},
+            hasErrorLogged: () => false,
+        };
+        return logger;
+    }
+}

package/src/cli/docs-command.ts

@@ -0,0 +1,53 @@
+import { CellError } from '@celljs/kit';
+import { DocsIndex } from '../docs/docs-index.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { Command, type CommandContext } from './command.js';
+
+/**
+ * `cell docs <query>`: searches the README.md and docs/ of the installed components and the docs
+ * of toolchain modules, the versions this project uses. Read-only; prints the best sections.
+ */
+export class DocsCommand extends Command {
+    readonly name = 'docs';
+    readonly description = 'Search the docs of the installed components and modules';
+    override readonly arguments = '<query...>';
+    override readonly options = { limit: { type: 'string' } } as const;
+    override readonly usage = ['--limit <n>          number of sections (default: 5)'];
+
+    async run({ values, positionals, reporter, env }: CommandContext): Promise<number> {
+        const query = positionals.join(' ').trim();
+        if (!query) {
+            throw new CellError({ code: 'CELL_ARGUMENT_INVALID', message: 'cell docs needs a query.', hint: 'For example: cell docs transactional' });
+        }
+        const limit = DocsCommand.limit(values.limit as string | undefined);
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'docs',
+            env,
+            quiet: reporter.json,
+            runHooks: false,
+            logger: reporter,
+        });
+        await toolchain.close();
+        const index = new DocsIndex(toolchain.config.root, DocsIndex.sourcesOf(toolchain.modules.components, toolchain.modules.docs));
+        const results = index.search(query, limit);
+        reporter.result(
+            'docs',
+            { query, files: index.files, results },
+            results.length === 0
+                ? `No section of ${index.files} doc file${index.files === 1 ? '' : 's'} matches '${query}'.`
+                : results.map(hit => `── ${hit.file}:${hit.line} (${hit.source})\n${hit.text}`).join('\n\n'),
+        );
+        return 0;
+    }
+
+    static limit(value: string | undefined): number {
+        if (value === undefined) {
+            return 5;
+        }
+        if (!/^\d+$/.test(value) || Number(value) < 1) {
+            throw new CellError({ code: 'CELL_ARGUMENT_INVALID', message: `Invalid --limit '${value}'.`, hint: 'Pass a positive number, e.g. --limit 5.' });
+        }
+        return Number(value);
+    }
+}

package/src/cli/info-command.ts

@@ -0,0 +1,40 @@
+import { ProjectInspector } from '../info/project-inspector.js';
+import { Toolchain } from '../toolchain/toolchain.js';
+import { BuildCommand } from './build-command.js';
+import { CellCli } from './cell-cli.js';
+import { Command, type CommandContext } from './command.js';
+
+/**
+ * `cell info`: what `cell build` with the same flags would use: preset and where it came from, modes,
+ * targets, components, DI modules, hooks and the state of the output. Read-only: hooks are listed,
+ * never run, and nothing is built.
+ */
+export class InfoCommand extends Command {
+    readonly name = 'info';
+    readonly description = 'Describe the project: preset, modes, targets, components, hooks, output';
+    override readonly options = { ...BuildCommand.OPTIONS, 'app-config': { type: 'boolean' } } as const;
+    override readonly usage = [...BuildCommand.USAGE, '--app-config         include the merged cell.yml of each target'];
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const toolchain = await Toolchain.create({
+            root: values.root as string | undefined,
+            command: 'info',
+            flags: BuildCommand.flags(values),
+            env,
+            quiet: reporter.json,
+            runHooks: false,
+            logger: reporter,
+        });
+        const inspector = new ProjectInspector(toolchain.config, toolchain.preset, toolchain.presets.names, {
+            projectOptions: toolchain.projectOptions(),
+            modules: toolchain.modules.loaded,
+        });
+        const info = inspector.inspect({ appConfig: values['app-config'] === true, cellVersion: CellCli.version, env });
+        await toolchain.close();
+        for (const warning of inspector.warnings) {
+            reporter.warn(warning);
+        }
+        reporter.result('info', { ...info }, ProjectInspector.format(info));
+        return 0;
+    }
+}

package/src/cli/init-command.ts

@@ -0,0 +1,53 @@
+import { CellError } from '@celljs/kit';
+import { ProjectInitializer } from '../init/project-initializer.js';
+import { Command, type CommandContext } from './command.js';
+
+/** `cell init <template> [dir]`: a new project from a template. Never prompts; without arguments it lists the templates. */
+export class InitCommand extends Command {
+    readonly name = 'init';
+    readonly description = 'Create a project from a template (cell init to list them)';
+    override readonly arguments = '[template] [dir]';
+    override readonly options = { name: { type: 'string' }, force: { type: 'boolean' } } as const;
+    override readonly usage = [
+        '--name <name>        package name (default: the directory name)',
+        '--force              write into a directory that is not empty',
+    ];
+
+    constructor(protected readonly version: () => string) {
+        super();
+    }
+
+    async run({ values, positionals, reporter }: CommandContext): Promise<number> {
+        const [template, dir, ...rest] = positionals;
+        if (rest.length > 0) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: 'cell init takes a template and a directory.',
+                hint: 'For example: cell init backend my-app',
+            });
+        }
+        if (!template) {
+            const templates = ProjectInitializer.templates();
+            const width = Math.max(...templates.map(t => t.name.length)) + 2;
+            reporter.result(
+                'init',
+                { templates },
+                ['Templates:', ...templates.map(t => `  ${t.name.padEnd(width)}${t.description}`), '', 'Create a project: cell init <template> <dir>'].join(
+                    '\n',
+                ),
+            );
+            return 0;
+        }
+        const result = new ProjectInitializer(this.version()).init(template, dir ?? template, {
+            name: values.name as string | undefined,
+            force: values.force === true,
+            cwd: values.root ? String(values.root) : undefined,
+        });
+        reporter.result(
+            'init',
+            { ...result },
+            [`Created ${result.name} from the ${template} template in ${result.dir}`, '', 'Next:', ...result.next.map(c => `  ${c}`)].join('\n'),
+        );
+        return 0;
+    }
+}

package/src/cli/main.ts

@@ -0,0 +1,3 @@
+import { CellCli } from './cell-cli.js';
+
+process.exitCode = await new CellCli().run(process.argv.slice(2));

package/src/cli/mcp-command.ts

@@ -0,0 +1,98 @@
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { Readable } from 'node:stream';
+import { McpServer } from '../mcp/mcp-server.js';
+import { type CellRunner, ProjectMcpTools } from '../mcp/project-mcp-tools.js';
+import { Command, type CommandContext } from './command.js';
+import type { Writable } from './reporter.js';
+
+export interface McpIo {
+    input: Readable;
+    /** Where protocol messages go; nothing else is written to it. */
+    output: Writable;
+    /** Logs of the server and of the commands it runs. */
+    log: Writable;
+    /** Undoes what the IO changed when the server stops. */
+    restore?(): void;
+}
+
+/**
+ * `cell mcp`: an MCP server on stdio (newline-delimited JSON-RPC) with the project tools of
+ * docs/design/agent-first.md R8 and those of toolchain modules. Runs until stdin closes. stdout
+ * carries protocol messages only: console output of anything else goes to stderr.
+ */
+export class McpCommand extends Command {
+    readonly name = 'mcp';
+    readonly description = 'Serve the project tools to coding agents over MCP (stdio)';
+
+    constructor(
+        protected readonly runner: CellRunner,
+        protected readonly io?: McpIo,
+    ) {
+        super();
+    }
+
+    async run({ values, env }: CommandContext): Promise<number> {
+        const root = resolve((values.root as string | undefined) ?? process.cwd());
+        const io = this.io ?? McpCommand.processIo();
+        const log = (message: string): void => {
+            io.log.write(`${message}\n`);
+        };
+        const tools = new ProjectMcpTools(root, this.runner, env, log);
+        const { CellCli } = await import('./cell-cli.js');
+        const server = new McpServer({
+            name: 'cell',
+            version: CellCli.version,
+            instructions: [
+                `Tools for the Cell project at ${root}.`,
+                'Start with info (the project model); run check after changing code or configuration; config_get tells where a configuration value comes from; docs_search finds docs of the installed component versions.',
+                'While cell dev runs, the running application has its own MCP endpoint at <dev url>/_cell/mcp (errors, routes, DI bindings, logs).',
+            ].join(' '),
+            tools: () => tools.tools(),
+        });
+        const pending = new Set<Promise<void>>();
+        const lines = createInterface({ input: io.input, crlfDelay: Number.POSITIVE_INFINITY });
+        try {
+            for await (const line of lines) {
+                if (!line.trim()) {
+                    continue;
+                }
+                const task = server
+                    .handleText(line)
+                    .then(response => {
+                        if (response !== undefined) {
+                            io.output.write(`${response}\n`);
+                        }
+                    })
+                    .catch(error => log(`cell mcp: ${(error as Error)?.stack ?? error}`))
+                    .finally(() => pending.delete(task));
+                pending.add(task);
+            }
+            await Promise.all(pending);
+        } finally {
+            await tools.close();
+            io.restore?.();
+        }
+        return 0;
+    }
+
+    /**
+     * stdin/stdout of the process, with stdout kept for protocol messages: `process.stdout.write` and
+     * `console.log`/`info`/`debug` of modules, hooks and Vite go to stderr while the server runs.
+     */
+    static processIo(): McpIo & { restore(): void } {
+        const write = process.stdout.write.bind(process.stdout);
+        const { log, info, debug } = console;
+        process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;
+        console.log = console.info = console.debug = (...args: unknown[]) => console.error(...args);
+        return {
+            input: process.stdin,
+            output: { write: (chunk: string) => write(chunk) },
+            log: process.stderr,
+            restore: () => {
+                process.stdout.write = write as typeof process.stdout.write;
+                Object.assign(console, { log, info, debug });
+            },
+        };
+    }
+}

package/src/cli/preview-command.ts

@@ -0,0 +1,98 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CellError, type OutputManifest, type Preset } from '@celljs/kit';
+import { ConfigResolver } from '../config/config-resolver.js';
+import { BUILTIN_PRESETS } from '../preset/builtin-presets.js';
+import { PresetOutput } from '../preset/preset-output.js';
+import { PresetRegistry } from '../preset/preset-registry.js';
+import { Command, type CommandContext } from './command.js';
+
+/** `cell preview`: run the built output as described by `manifest.json`, without rebuilding. */
+export class PreviewCommand extends Command {
+    readonly name = 'preview';
+    readonly description = 'Run the built application from .cell/output';
+    override readonly options = {
+        port: { type: 'string', short: 'p' },
+        'out-dir': { type: 'string' },
+    } as const;
+    override readonly usage = [
+        '-p, --port <port>    port to listen on (default: cell.server.port; 8787 for cloudflare)',
+        '--out-dir <dir>      output directory (default: .cell/output)',
+    ];
+
+    async run({ values, reporter, env }: CommandContext): Promise<number> {
+        const root = realpathSync(resolve((values.root as string | undefined) ?? process.cwd()));
+        const outDir = resolve(root, (values['out-dir'] as string | undefined) ?? ConfigResolver.DEFAULT_OUT_DIR);
+        const manifest = PresetOutput.read(outDir);
+        const port = values.port as string | undefined;
+        if (port !== undefined && !/^\d+$/.test(port)) {
+            throw new CellError({ code: 'CELL_ARGUMENT_INVALID', message: `Invalid --port '${port}'.`, hint: 'Pass a port number, e.g. --port 3000.' });
+        }
+        const stdio = ['inherit', reporter.json ? 2 : 'inherit', 'inherit'] as const;
+        const preset = this.preset(manifest);
+        if (preset?.preview) {
+            const preview = await preset.preview({ root, outDir, manifest, port: port ? Number(port) : undefined, env });
+            const command = [preview.command, ...preview.args];
+            const child = spawn(preview.command, preview.args, { cwd: preview.cwd ?? root, env: { ...env, ...preview.env }, stdio: [...stdio] });
+            reporter.result(
+                'preview',
+                { command, pid: child.pid, port: port ? Number(port) : undefined, preset: manifest.preset },
+                `Running ${command.join(' ')}`,
+            );
+            return this.wait(child);
+        }
+        if (manifest.executable) {
+            const app = join(outDir, manifest.executable.file);
+            const child = spawn(app, [], {
+                cwd: root,
+                env: { ...env, NODE_ENV: env.NODE_ENV ?? 'production', ...(port ? { CELL_BACKEND__SERVER__PORT: port } : {}) },
+                stdio: [...stdio],
+            });
+            reporter.result('preview', { executable: app, pid: child.pid, port: port ? Number(port) : undefined, preset: manifest.preset }, `Running ${app}`);
+            return this.wait(child);
+        }
+        if (!manifest.server) {
+            throw new CellError({
+                code: 'CELL_PREVIEW_NO_SERVER',
+                message: `The output in ${outDir} has no server (targets: ${manifest.targets.join(', ')}).`,
+                file: join(outDir, PresetOutput.MANIFEST),
+                hint: 'Serve the public directory with any static file server, or build a backend target.',
+            });
+        }
+        const server = join(outDir, manifest.server);
+        const child = spawn(process.execPath.includes('bun') ? 'node' : process.execPath, [server], {
+            cwd: root,
+            env: { ...env, NODE_ENV: env.NODE_ENV ?? 'production', ...(port ? { CELL_BACKEND__SERVER__PORT: port } : {}) },
+            stdio: [...stdio],
+        });
+        reporter.result('preview', { server, pid: child.pid, port: port ? Number(port) : undefined, preset: manifest.preset }, `Running ${server}`);
+        return this.wait(child);
+    }
+
+    /** The built-in preset that built the output, if any; presets of toolchain modules preview with Node.js. */
+    protected preset(manifest: OutputManifest): Preset | undefined {
+        const presets = new PresetRegistry();
+        for (const preset of BUILTIN_PRESETS) {
+            presets.register(preset);
+        }
+        return manifest.preset && presets.names.includes(manifest.preset) ? presets.resolve(manifest.preset) : undefined;
+    }
+
+    /** Forwards Ctrl+C and termination to the server and exits with its code. */
+    protected wait(child: ChildProcess): Promise<number> {
+        const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
+        const onInt = forward('SIGINT');
+        const onTerm = forward('SIGTERM');
+        process.on('SIGINT', onInt);
+        process.on('SIGTERM', onTerm);
+        return new Promise((resolvePromise, reject) => {
+            child.on('error', reject);
+            child.on('exit', (code, signal) => {
+                process.off('SIGINT', onInt);
+                process.off('SIGTERM', onTerm);
+                resolvePromise(code ?? (signal === 'SIGINT' || signal === 'SIGTERM' ? 0 : 1));
+            });
+        });
+    }
+}

package/src/cli/reporter.ts

@@ -0,0 +1,67 @@
+import { CellError } from '@celljs/kit';
+
+export interface Writable {
+    write(chunk: string): unknown;
+}
+
+/**
+ * Prints command results. Human output is short text; with `--json` stdout carries exactly one JSON
+ * document with `schemaVersion` (docs/design/agent-first.md R6), and everything else goes to stderr.
+ */
+export class Reporter {
+    static readonly SCHEMA_VERSION = 1;
+
+    readonly warnings: string[] = [];
+
+    constructor(
+        readonly json: boolean,
+        protected readonly stdout: Writable = process.stdout,
+        protected readonly stderr: Writable = process.stderr,
+    ) {}
+
+    /** Progress and incidental messages: never on stdout in JSON mode. */
+    info(message: string): void {
+        (this.json ? this.stderr : this.stdout).write(`${message}\n`);
+    }
+
+    warn(message: string): void {
+        this.warnings.push(message);
+        this.stderr.write(`warning: ${message}\n`);
+    }
+
+    /** Output of a child process: `stderr` stays stderr, `stdout` moves to stderr in JSON mode. */
+    relay(chunk: string, stream: 'stdout' | 'stderr'): void {
+        (this.json || stream === 'stderr' ? this.stderr : this.stdout).write(chunk);
+    }
+
+    result(command: string, data: Record<string, unknown>, human: string): void {
+        if (this.json) {
+            this.stdout.write(`${JSON.stringify({ schemaVersion: Reporter.SCHEMA_VERSION, command, ok: true, ...data, warnings: this.warnings })}\n`);
+        } else {
+            this.stdout.write(`${human}\n`);
+        }
+    }
+
+    error(command: string | undefined, error: CellError): void {
+        if (this.json) {
+            this.stdout.write(
+                `${JSON.stringify({ schemaVersion: Reporter.SCHEMA_VERSION, command, ok: false, error: error.toJSON(), warnings: this.warnings })}\n`,
+            );
+        } else {
+            this.stderr.write(`${error.format()}\n`);
+        }
+    }
+
+    /** Anything that is not a CellError is a bug in Cell or a module: say so instead of dumping a stack. */
+    static toCellError(error: unknown): CellError {
+        if (CellError.is(error)) {
+            return error;
+        }
+        return new CellError({
+            code: 'CELL_INTERNAL_ERROR',
+            message: (error as Error)?.message ?? String(error),
+            hint: 'This is a bug in Cell or one of its modules; rerun with CELL_DEBUG=1 for the stack trace and report it.',
+            cause: error,
+        });
+    }
+}