@celljs/cli 3.9.0 → 4.0.0

package/src/index.ts

@@ -0,0 +1,57 @@
+export * from './agent/agent-guide.js';
+export * from './build/executable-compiler.js';
+export * from './check/project-checker.js';
+export * from './cli/agent-command.js';
+export * from './cli/build-command.js';
+export * from './cli/cell-cli.js';
+export * from './cli/check-command.js';
+export * from './cli/command.js';
+export * from './cli/config-command.js';
+export * from './cli/deploy-command.js';
+export * from './cli/dev-command.js';
+export * from './cli/docs-command.js';
+export * from './cli/info-command.js';
+export * from './cli/init-command.js';
+export * from './cli/mcp-command.js';
+export * from './cli/preview-command.js';
+export * from './cli/reporter.js';
+export * from './config/config-explainer.js';
+export * from './config/config-file-loader.js';
+export * from './config/config-resolver.js';
+export * from './config/config-validator.js';
+export * from './config/define-config.js';
+export * from './config/types.js';
+export * from './deploy/cloud-api.js';
+export * from './deploy/code-package.js';
+export * from './deploy/deployer-registry.js';
+export * from './deploy/request-signer.js';
+export * from './deploy/zip-writer.js';
+export * from './docs/docs-index.js';
+export * from './events/event-bus.js';
+export * from './events/hook-runner.js';
+export * from './info/project-inspector.js';
+export * from './init/project-initializer.js';
+export * from './mcp/dev-activity.js';
+export * from './mcp/dev-mcp-endpoint.js';
+export * from './mcp/mcp-server.js';
+export * from './mcp/project-mcp-tools.js';
+export * from './preset/builtin-presets.js';
+export * from './preset/cloudflare/cloudflare-deployer.js';
+export * from './preset/cloudflare/cloudflare-preset.js';
+export * from './preset/cloudflare/wrangler.js';
+export * from './preset/cloudflare/wrangler-config.js';
+export * from './preset/fc/fc-deployer.js';
+export * from './preset/fc/fc-preset.js';
+export * from './preset/lambda/lambda-deployer.js';
+export * from './preset/lambda/lambda-preset.js';
+export * from './preset/preset-output.js';
+export * from './preset/preset-registry.js';
+export * from './preset/scf/scf-deployer.js';
+export * from './preset/scf/scf-preset.js';
+export * from './preset/serverless-scripts.js';
+export * from './preset/vercel/vercel-deployer.js';
+export * from './preset/vercel/vercel-preset.js';
+export * from './testing/create-test-app.js';
+export * from './toolchain/toolchain.js';
+export * from './utils/json-util.js';
+export * from './utils/text-util.js';

package/src/info/project-inspector.ts

@@ -0,0 +1,352 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, isAbsolute, join, relative } from 'node:path';
+import type { CheckIssue, ComponentInfo, EnvOverrideReport, Preset, ProjectModel, ServerRuntime, Target, TargetModel } from '@celljs/kit';
+import { type OutputManifest, ProjectLoader, type ProjectLoaderOptions } from '@celljs/vite';
+import { ConfigResolver, type ModuleSpec, type ResolvedConfig, type ValueSource } from '../config/config-resolver.js';
+import type { CompileTarget } from '../config/types.js';
+import type { ModuleRegistrations } from '../modules/module-host.js';
+import { TextUtil } from '../utils/text-util.js';
+
+/** A component as `cell info` reports it. Paths are relative to the project root; empty declarations are left out. */
+export interface ComponentSummary {
+    name: string;
+    version: string;
+    dir: string;
+    /** Present (and `true`) for the project itself. */
+    root?: true;
+    configFiles: string[];
+    targets?: Target[];
+    entries?: Record<string, string>;
+    toolchain?: string;
+    optionalDependencies?: string[];
+}
+
+export interface TargetSummary {
+    entry: string;
+    /** Component whose `entries` provided the entry. */
+    entryComponent?: string;
+    /** DI modules in load order; files of the project are relative to its root. */
+    staticModules: string[];
+    modules: string[];
+    /** Merged application configuration, only with `--app-config`. Backend values keep `${...}`. */
+    config?: Record<string, unknown>;
+    /**
+     * `CELL_FRONTEND__*` / `CELL_BACKEND__*` variables of the current environment and the keys they set;
+     * present when there are any. Frontend ones are applied by `cell build`, backend ones by the server
+     * at startup. Values are left out.
+     */
+    envOverrides?: EnvOverrideReport;
+}
+
+export interface OutputSummary {
+    /** Output directory, relative to the project root. */
+    dir: string;
+    built: boolean;
+    preset?: string;
+    format?: 'esm' | 'cjs';
+    targets?: Target[];
+    server?: string;
+    public?: string;
+}
+
+/** The result of `cell info` (docs/design/architecture.md §8): what the next `cell build` with the same flags would use. */
+export interface ProjectInfo {
+    root: string;
+    name: string;
+    version: string;
+    cellVersion: string;
+    /** cell.config file, relative to the root. */
+    configFile?: string;
+    preset: {
+        name: string;
+        source: ValueSource;
+        description?: string;
+        entry?: string;
+        format?: 'esm' | 'cjs';
+        runtime?: ServerRuntime;
+        /** Deployer of `cell deploy`; none means the output is run by hand. */
+        deployer?: string;
+        available: string[];
+    };
+    mode: string[];
+    targets: Target[];
+    /** Why each target is built: `cell.config.ts`, `default` (the backend) or the components that declare it. */
+    targetSources: Partial<Record<Target, string[]>>;
+    build: { format: 'esm' | 'cjs'; outDir: string; external: string[]; sourcemap: boolean; single: boolean; compile: false | CompileTarget };
+    components: ComponentSummary[];
+    frontend?: TargetSummary;
+    backend?: TargetSummary;
+    /** Project hooks by event. `cell info` lists them and never runs them. */
+    hooks: Record<string, string>;
+    /** The `modules` entries of cell.config.ts. */
+    modules: ModuleSpec[];
+    /** Keys of toolchain module options in cell.config.ts. */
+    moduleOptions: string[];
+    /** Toolchain modules in load order and what each registered (docs/design/modules.md §3.5); `file` is relative to the root. */
+    toolchainModules: ModuleRegistrations[];
+    output: OutputSummary;
+}
+
+export interface InspectOptions {
+    /** Include the merged application configuration of each target. */
+    appConfig?: boolean;
+    cellVersion?: string;
+    /** Environment for frontend expressions and `CELL_*__` overrides. Default: `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+
+/**
+ * Describes a project from its resolved toolchain configuration and the project model. Reads
+ * package.json, cell*.yml and manifest.json only: no project code runs and nothing is built, so it
+ * returns quickly and is safe to call from agents and editors (docs/design/agent-first.md R2).
+ */
+export class ProjectInspector {
+    static readonly COMMAND_MODES = ['production', 'development'];
+    static readonly MODE_FILE = /^cell\.([\w-]+)\.yml$/;
+
+    /** What `cell info` warns about, with stable codes for `cell check`. */
+    readonly issues: CheckIssue[] = [];
+
+    get warnings(): string[] {
+        return this.issues.map(issue => issue.message);
+    }
+
+    protected warn(code: string, message: string, file?: string): void {
+        this.issues.push({ level: 'warning', code, message, ...(file ? { file } : {}) });
+    }
+
+    constructor(
+        protected readonly config: ResolvedConfig,
+        protected readonly preset: Preset,
+        protected readonly presets: string[],
+        /** What toolchain modules contributed: project options (DI modules, entries) and their registrations. */
+        protected readonly contributions: { projectOptions?: ProjectLoaderOptions; modules?: ModuleRegistrations[] } = {},
+    ) {}
+
+    inspect(options: InspectOptions = {}): ProjectInfo {
+        const { config, preset } = this;
+        const projectOptions = this.contributions.projectOptions ?? ConfigResolver.toProjectOptions(config, preset);
+        const model = new ProjectLoader({ ...projectOptions, env: options.env }).load();
+        const project = model.components[model.components.length - 1];
+        const info: ProjectInfo = {
+            root: config.root,
+            name: project.name,
+            version: project.version,
+            cellVersion: options.cellVersion ?? '',
+            ...(config.file ? { configFile: this.relative(config.file) } : {}),
+            preset: {
+                name: preset.name,
+                source: config.preset.source,
+                ...(preset.description ? { description: preset.description } : {}),
+                ...(preset.entry ? { entry: preset.entry } : {}),
+                ...(preset.format ? { format: preset.format } : {}),
+                ...(preset.runtime ? { runtime: preset.runtime } : {}),
+                ...(preset.deployer ? { deployer: preset.deployer } : {}),
+                available: this.presets,
+            },
+            mode: config.mode,
+            targets: model.targets,
+            targetSources: this.targetSources(model),
+            build: {
+                format: ConfigResolver.format(config, preset),
+                outDir: config.build.outDir,
+                external: config.build.external,
+                sourcemap: config.build.sourcemap,
+                single: config.build.single,
+                compile: config.build.compile,
+            },
+            components: model.components.map(c => this.component(c)),
+            hooks: { ...config.hooks } as Record<string, string>,
+            modules: config.modules.map(spec => (spec.kind === 'local' ? { ...spec, path: this.relative(spec.path) } : spec)),
+            moduleOptions: Object.keys(config.options),
+            toolchainModules: (this.contributions.modules ?? []).map(m => ({ ...m, file: this.relative(m.file) })),
+            output: this.output(),
+        };
+        for (const target of model.targets) {
+            info[target] = this.target(model[target] as TargetModel, options.appConfig ?? false);
+        }
+        this.check(model);
+        return info;
+    }
+
+    /** The human form of {@link ProjectInfo}: a short summary; `--json` has the details. */
+    static format(info: ProjectInfo): string {
+        const rows: [string, string][] = [
+            ['config', info.configFile ?? 'none (defaults)'],
+            ['preset', `${info.preset.name} (${info.preset.source})${info.preset.description ? `: ${info.preset.description}` : ''}, ${info.build.format}`],
+            ['mode', info.mode.join(', ')],
+            ['targets', info.targets.map(t => `${t} (${info.targetSources[t]?.join(', ')})`).join(', ')],
+        ];
+        for (const target of info.targets) {
+            const summary = info[target] as TargetSummary;
+            const count = summary.staticModules.length + summary.modules.length;
+            const entry = target === 'backend' && !summary.entryComponent ? `${summary.entry} (default entry)` : summary.entry;
+            rows.push([target, `${entry}, ${count} DI module${count === 1 ? '' : 's'}`]);
+        }
+        const overrides = info.targets.flatMap(target => (info[target] as TargetSummary).envOverrides?.applied ?? []);
+        if (overrides.length > 0) {
+            rows.push(['env', overrides.map(({ variable, path }) => `${variable} → ${path}`).join(', ')]);
+        }
+        const hooks = Object.entries(info.hooks);
+        rows.push(['hooks', hooks.length > 0 ? hooks.map(([event, command]) => `${event} → ${command}`).join('; ') : 'none']);
+        if (info.modules.length > 0) {
+            rows.push(['modules', info.modules.map(spec => ProjectInspector.formatModule(spec)).join(', ')]);
+        }
+        if (info.toolchainModules.length > 0) {
+            rows.push(['toolchain', info.toolchainModules.map(m => ProjectInspector.formatToolchainModule(m)).join(', ')]);
+        }
+        const { output } = info;
+        rows.push([
+            'output',
+            output.built
+                ? `${output.dir} (built: ${output.preset ?? 'no preset'}, ${output.format}, ${output.targets?.join(' + ')})`
+                : `${output.dir} (not built)`,
+        ]);
+        rows.push(['components', String(info.components.length)]);
+        const width = Math.max(...rows.map(([label]) => label.length)) + 2;
+        return [
+            `${info.name} ${info.version}  ${info.root}`,
+            ...rows.map(([label, value]) => `  ${label.padEnd(width)}${value}`),
+            ...info.components.map(c => `    ${c.name} ${c.version}${c.root ? ' (project)' : ''}`),
+            '',
+            'Details: cell info --json (add --app-config for the merged cell.yml)',
+        ].join('\n');
+    }
+
+    static missingEntryWarning(preset: Preset): string {
+        return `No component provides the '${preset.entry}' entry of the ${preset.name} preset, so the backend starts the application without a server. Add @celljs/express-adapter to dependencies for an HTTP server, or use the cli preset for a command-line application.`;
+    }
+
+    static envProblemWarning(target: Target, problem: { variable: string; message: string }): string {
+        return `${problem.variable} is ignored${target === 'backend' ? ' by the server' : ''}: ${problem.message}`;
+    }
+
+    /** `@x/ui (2 vite plugins, 1 check)`: what a module registered, counted. */
+    static formatToolchainModule(module: ModuleRegistrations): string {
+        const counts: [number, string, string][] = [
+            [module.vitePlugins.length, 'vite plugin', 'vite plugins'],
+            [module.runtimeModules.length, 'DI module', 'DI modules'],
+            [module.virtualModules.length, 'virtual module', 'virtual modules'],
+            [Object.keys(module.entries).length, 'entry', 'entries'],
+            [module.devHandlers.length, 'dev handler', 'dev handlers'],
+            [module.presets.length, 'preset', 'presets'],
+            [module.outputFiles.length, 'output file', 'output files'],
+            [module.checks.length, 'check', 'checks'],
+            [module.mcpTools.length, 'MCP tool', 'MCP tools'],
+            [module.docs.length, 'docs dir', 'docs dirs'],
+            [module.events.length, 'event', 'events'],
+        ];
+        const parts = counts.filter(([n]) => n > 0).map(([n, one, many]) => `${n} ${n === 1 ? one : many}`);
+        return parts.length > 0 ? `${module.name} (${parts.join(', ')})` : module.name;
+    }
+
+    static formatModule(spec: ModuleSpec): string {
+        switch (spec.kind) {
+            case 'local':
+                return spec.path;
+            case 'package':
+                return spec.name;
+            case 'disabled':
+                return `!${spec.name}`;
+            case 'filter':
+                return `${spec.name} (${[spec.runtime ? '' : 'runtime: false', spec.toolchain ? '' : 'toolchain: false'].filter(Boolean).join(', ')})`;
+        }
+    }
+
+    protected targetSources(model: ProjectModel): Partial<Record<Target, string[]>> {
+        const sources: Partial<Record<Target, string[]>> = {};
+        for (const target of model.targets) {
+            if (this.config.targets) {
+                sources[target] = [this.config.file ? basename(this.config.file) : 'cell.config.ts'];
+                continue;
+            }
+            const declaring = model.components.filter(c => c.targets.includes(target)).map(c => c.name);
+            sources[target] = target === 'backend' ? ['default', ...declaring] : declaring;
+        }
+        return sources;
+    }
+
+    protected component(component: ComponentInfo): ComponentSummary {
+        const { name, version, dir, root, configFiles, targets, entries, toolchain, optionalDependencies } = component;
+        return {
+            name,
+            version,
+            dir: this.relative(dir) || '.',
+            ...(root ? { root: true as const } : {}),
+            configFiles: configFiles.map(file => this.relative(file)),
+            ...(targets.length > 0 ? { targets } : {}),
+            ...(Object.keys(entries).length > 0 ? { entries } : {}),
+            ...(toolchain ? { toolchain } : {}),
+            ...(optionalDependencies.length > 0 ? { optionalDependencies } : {}),
+        };
+    }
+
+    protected target(model: TargetModel, appConfig: boolean): TargetSummary {
+        const specifier = (s: string) => (isAbsolute(s) ? this.relative(s) : s);
+        return {
+            entry: specifier(model.entry),
+            ...(model.entryComponent ? { entryComponent: model.entryComponent } : {}),
+            staticModules: model.staticModules.map(m => specifier(m.specifier)),
+            modules: model.modules.map(m => specifier(m.specifier)),
+            ...(appConfig ? { config: model.config } : {}),
+            ...(model.envOverrides.applied.length + model.envOverrides.problems.length > 0 ? { envOverrides: model.envOverrides } : {}),
+        };
+    }
+
+    protected output(): OutputSummary {
+        const dir = this.config.build.outDir;
+        const file = join(this.config.root, dir, 'manifest.json');
+        if (!existsSync(file)) {
+            return { dir, built: false };
+        }
+        try {
+            const { preset, format, targets, server, public: publicDir } = JSON.parse(readFileSync(file, 'utf8')) as OutputManifest;
+            return { dir, built: true, preset, format, targets, server, public: publicDir };
+        } catch {
+            this.warn('CELL_OUTPUT_UNREADABLE', `${this.relative(file)} cannot be read; run \`cell build\` to write it again.`, file);
+            return { dir, built: false };
+        }
+    }
+
+    /** Settings that `cell build` would accept but that change nothing or fail: say so before the build does. */
+    protected check(model: ProjectModel): void {
+        if (model.backend && !model.backend.entryComponent && this.preset.entry) {
+            this.warn('CELL_ENTRY_MISSING', ProjectInspector.missingEntryWarning(this.preset), join(this.config.root, 'package.json'));
+        }
+        const available = this.availableModes(model);
+        for (const mode of this.config.mode) {
+            if (!ProjectInspector.COMMAND_MODES.includes(mode) && !available.includes(mode)) {
+                const suggestion = TextUtil.closest(mode, available);
+                this.warn(
+                    'CELL_MODE_UNKNOWN',
+                    `Mode '${mode}' changes nothing: neither the project nor its components have cell.${mode}.yml.${suggestion ? ` Did you mean '${suggestion}'?` : ''}`,
+                );
+            }
+        }
+        for (const target of model.targets) {
+            const { applied, problems } = (model[target] as TargetModel).envOverrides;
+            for (const problem of problems) {
+                this.warn('CELL_ENV_OVERRIDE_IGNORED', ProjectInspector.envProblemWarning(target, problem));
+            }
+            for (const { variable, path, shadows } of applied) {
+                if (shadows) {
+                    const explicit = variable.replace(/^(CELL_[A-Z]+__)/, '$1CELL__');
+                    this.warn(
+                        'CELL_ENV_OVERRIDE_SHADOWS',
+                        `${variable} sets ${path}, not ${shadows}: the top-level key comes first. Use ${explicit} for ${shadows}.`,
+                    );
+                }
+            }
+        }
+    }
+
+    /** Modes with a `cell.<mode>.yml` in the project or any of its components, active or not. */
+    protected availableModes(model: ProjectModel): string[] {
+        const modes = model.components.flatMap(c => readdirSync(c.dir).flatMap(file => ProjectInspector.MODE_FILE.exec(file)?.[1] ?? []));
+        return [...new Set(modes)];
+    }
+
+    protected relative(path: string): string {
+        return relative(this.config.root, path);
+    }
+}

package/src/init/project-initializer.ts

@@ -0,0 +1,111 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CellError } from '@celljs/kit';
+import { AgentGuide } from '../agent/agent-guide.js';
+import { TextUtil } from '../utils/text-util.js';
+
+export interface TemplateInfo {
+    name: string;
+    description: string;
+}
+
+export interface InitResult {
+    template: string;
+    name: string;
+    /** Absolute project directory. */
+    dir: string;
+    /** Files created, relative to the project directory. */
+    files: string[];
+    /** Commands to run next, from the current directory. */
+    next: string[];
+}
+
+/**
+ * `cell init`: copies a template of @celljs/cli into a new directory, with the project name and the
+ * Cell version filled in, and adds what coding agents need: AGENTS.md, the cell skill, a CLAUDE.md
+ * that includes AGENTS.md and an MCP configuration for `cell mcp` (docs/design/agent-first.md §3).
+ */
+export class ProjectInitializer {
+    static readonly TEMPLATES = fileURLToPath(new URL('../../templates', import.meta.url));
+    /** Files whose names npm would drop or rename when publishing. */
+    static readonly RENAMED: Record<string, string> = { _gitignore: '.gitignore' };
+    static readonly MCP_CONFIG = { mcpServers: { cell: { command: 'npx', args: ['cell', 'mcp'] } } };
+
+    constructor(protected readonly version: string) {}
+
+    static templates(): TemplateInfo[] {
+        return readdirSync(ProjectInitializer.TEMPLATES)
+            .filter(name => existsSync(join(ProjectInitializer.TEMPLATES, name, 'template.json')))
+            .sort()
+            .map(name => ({ name, description: JSON.parse(readFileSync(join(ProjectInitializer.TEMPLATES, name, 'template.json'), 'utf8')).description }));
+    }
+
+    /** npm package names are lowercase, without spaces, at most 214 characters. */
+    static packageName(dir: string): string {
+        return basename(dir)
+            .toLowerCase()
+            .replace(/[^a-z0-9._~-]+/g, '-')
+            .replace(/^[._-]+|-+$/g, '');
+    }
+
+    init(template: string, dir: string, options: { name?: string; force?: boolean; cwd?: string } = {}): InitResult {
+        const templates = ProjectInitializer.templates();
+        if (!templates.some(t => t.name === template)) {
+            const suggestion = TextUtil.closest(
+                template,
+                templates.map(t => t.name),
+            );
+            throw new CellError({
+                code: 'CELL_TEMPLATE_NOT_FOUND',
+                message: `Unknown template '${template}'.`,
+                hint: suggestion ? `Did you mean '${suggestion}'?` : `Templates: ${templates.map(t => t.name).join(', ')}.`,
+            });
+        }
+        const target = resolve(options.cwd ?? process.cwd(), dir);
+        const name = options.name ?? ProjectInitializer.packageName(target);
+        if (!/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name) || name.length > 214) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `'${name}' is not a valid package name.`,
+                hint: 'Pass --name with lowercase letters, digits, - and . (e.g. --name my-app).',
+            });
+        }
+        if (existsSync(target) && (!statSync(target).isDirectory() || readdirSync(target).length > 0) && !options.force) {
+            throw new CellError({
+                code: 'CELL_INIT_NOT_EMPTY',
+                message: `${target} exists and is not empty.`,
+                hint: 'Choose a new directory, or pass --force to write the template files into it (files with the same names are replaced).',
+            });
+        }
+        mkdirSync(target, { recursive: true });
+        const source = join(ProjectInitializer.TEMPLATES, template);
+        cpSync(source, target, { recursive: true, filter: file => basename(file) !== 'template.json' });
+        const files: string[] = [];
+        for (const file of ProjectInitializer.walk(source).filter(f => basename(f) !== 'template.json')) {
+            const rel = relative(source, file);
+            const renamed = join(target, ...rel.split(/[\\/]/).map(part => ProjectInitializer.RENAMED[part] ?? part));
+            if (renamed !== join(target, rel)) {
+                renameSync(join(target, rel), renamed);
+            }
+            writeFileSync(renamed, readFileSync(renamed, 'utf8').replaceAll('{{name}}', name).replaceAll('{{cellVersion}}', this.version));
+            files.push(relative(target, renamed));
+        }
+        files.push(...new AgentGuide(target, this.version).sync([]).files);
+        writeFileSync(join(target, 'CLAUDE.md'), '@AGENTS.md\n');
+        writeFileSync(join(target, '.mcp.json'), `${JSON.stringify(ProjectInitializer.MCP_CONFIG, null, 2)}\n`);
+        files.push('CLAUDE.md', '.mcp.json');
+        const cd = relative(options.cwd ?? process.cwd(), target) || '.';
+        return {
+            template,
+            name,
+            dir: target,
+            files: files.map(f => f.split('\\').join('/')).sort(),
+            next: [...(cd === '.' ? [] : [`cd ${cd}`]), 'npm install', 'npx cell agent sync', 'npx cell dev'],
+        };
+    }
+
+    protected static walk(dir: string): string[] {
+        return (readdirSync(dir, { recursive: true }) as string[]).map(name => join(dir, name)).filter(file => statSync(file).isFile());
+    }
+}

package/src/mcp/dev-activity.ts

@@ -0,0 +1,71 @@
+import { format } from 'node:util';
+import type { CellError } from '@celljs/kit';
+import type { DevRequestRecord } from '@celljs/vite';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface DevLogRecord {
+    time: string;
+    level: LogLevel;
+    message: string;
+}
+
+export interface DevErrorRecord {
+    time: string;
+    /** Files whose change led to the failed reload; empty for a start. */
+    files: string[];
+    error: ReturnType<CellError['toJSON']>;
+}
+
+/**
+ * What happened in `cell dev`, for the dev MCP endpoint: backend requests, start errors and console
+ * output, each kept to the last few hundred entries. Lives across restarts of the dev server.
+ */
+export class DevActivity {
+    static readonly MAX_REQUESTS = 200;
+    static readonly MAX_ERRORS = 20;
+    static readonly MAX_LOGS = 1000;
+    static readonly LEVELS: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+    readonly requests: DevRequestRecord[] = [];
+    readonly errors: DevErrorRecord[] = [];
+    readonly logs: DevLogRecord[] = [];
+
+    recordRequest(record: DevRequestRecord): void {
+        DevActivity.push(this.requests, record, DevActivity.MAX_REQUESTS);
+    }
+
+    recordError(error: CellError, files: string[] = []): void {
+        DevActivity.push(this.errors, { time: new Date().toISOString(), files, error: error.toJSON() }, DevActivity.MAX_ERRORS);
+    }
+
+    recordLog(level: LogLevel, message: string): void {
+        DevActivity.push(this.logs, { time: new Date().toISOString(), level, message }, DevActivity.MAX_LOGS);
+    }
+
+    /** Copies console output into {@link logs}, still printing it; returns the function that stops. */
+    captureConsole(): () => void {
+        const original = { debug: console.debug, log: console.log, info: console.info, warn: console.warn, error: console.error };
+        const wrap =
+            (level: LogLevel, print: (...args: unknown[]) => void) =>
+            (...args: unknown[]) => {
+                this.recordLog(level, format(...args));
+                print.apply(console, args);
+            };
+        console.debug = wrap('debug', original.debug);
+        console.log = wrap('info', original.log);
+        console.info = wrap('info', original.info);
+        console.warn = wrap('warn', original.warn);
+        console.error = wrap('error', original.error);
+        return () => {
+            Object.assign(console, original);
+        };
+    }
+
+    protected static push<T>(list: T[], item: T, max: number): void {
+        list.push(item);
+        if (list.length > max) {
+            list.splice(0, list.length - max);
+        }
+    }
+}