@celljs/cli 3.8.0 → 4.0.0

package/src/preset/vercel/vercel-preset.ts

@@ -0,0 +1,111 @@
+import { cpSync, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { definePreset, type PresetOutputContext, type PresetPreviewContext, type PreviewProcess } from '@celljs/kit';
+import { PresetOptionsSchema } from '../../deploy/cloud-api.js';
+import { ServerlessScripts } from '../serverless-scripts.js';
+
+/**
+ * Vercel through the Build Output API (v3): the frontend in `static/` on Vercel's CDN, the Cell
+ * server as one Node.js function `functions/index.func` that gets every request no static file
+ * answers. The output goes to `.vercel/output`, where `vercel deploy --prebuilt` looks for it.
+ */
+export namespace VercelPreset {
+    export const OUT_DIR = '.vercel/output';
+    export const FUNCTION = 'functions/index.func';
+    export const RUNTIMES = ['nodejs22.x', 'nodejs20.x'] as const;
+
+    export const OPTIONS = PresetOptionsSchema.of({
+        project: 'string',
+        scope: 'string',
+        environment: ['production', 'preview'],
+        runtime: RUNTIMES,
+        memory: 'number',
+        maxDuration: 'number',
+        regions: 'string',
+    });
+
+    /** What `vercel build` writes into .vercel/output; a deployment would mix it with Cell's output. */
+    export const FOREIGN = ['static', 'functions', 'config.json', 'builds.json', 'diagnostics'];
+
+    export function output(context: PresetOutputContext): void {
+        const { manifest, outDir, options } = context;
+        for (const entry of FOREIGN) {
+            rmSync(join(outDir, entry), { recursive: true, force: true });
+        }
+        if (manifest.public) {
+            renameSync(join(outDir, manifest.public), join(outDir, 'static'));
+            manifest.public = 'static';
+        }
+        const routes: Record<string, unknown>[] = [
+            // Vite's hashed files never change.
+            { src: '^/assets/(.*)$', headers: { 'cache-control': 'public, max-age=31536000, immutable' }, continue: true },
+            { handle: 'filesystem' },
+        ];
+        if (manifest.server) {
+            const fn = join(outDir, FUNCTION);
+            mkdirSync(fn, { recursive: true });
+            renameSync(join(outDir, dirname(manifest.server)), join(fn, 'server'));
+            manifest.server = `${FUNCTION}/server/${manifest.server.split('/').pop()}`;
+            // The single-page fallback of serve-static, inside the function.
+            const index = join(outDir, 'static', 'index.html');
+            if (existsSync(index)) {
+                mkdirSync(join(fn, 'public'), { recursive: true });
+                cpSync(index, join(fn, 'public', 'index.html'));
+            }
+            context.write(`${FUNCTION}/vercel.mjs`, ServerlessScripts.VERCEL_FUNCTION);
+            context.write(
+                `${FUNCTION}/.vc-config.json`,
+                `${JSON.stringify(
+                    {
+                        runtime: (options.runtime as string | undefined) ?? RUNTIMES[0],
+                        handler: 'vercel.mjs',
+                        launcherType: 'Nodejs',
+                        shouldAddHelpers: false,
+                        supportsResponseStreaming: true,
+                        ...(options.memory ? { memory: options.memory } : {}),
+                        ...(options.maxDuration ? { maxDuration: options.maxDuration } : {}),
+                        ...(options.regions
+                            ? {
+                                  regions: String(options.regions)
+                                      .split(',')
+                                      .map(r => r.trim()),
+                              }
+                            : {}),
+                    },
+                    null,
+                    2,
+                )}\n`,
+            );
+            routes.push({ src: '^/(.*)$', dest: '/index' });
+        }
+        context.write('config.json', `${JSON.stringify({ version: 3, routes }, null, 2)}\n`);
+    }
+
+    /** Node.js on the function's server bundle, with the frontend from `static/`. */
+    export function preview({ outDir, manifest, port }: PresetPreviewContext): PreviewProcess {
+        return {
+            command: process.execPath.includes('bun') ? 'node' : process.execPath,
+            args: [join(outDir, manifest.server ?? `${FUNCTION}/server/index.mjs`)],
+            env: {
+                NODE_ENV: 'production',
+                CELL_BACKEND__PATHS__PUBLIC: join(outDir, 'static'),
+                ...(port === undefined ? {} : { CELL_BACKEND__SERVER__PORT: String(port) }),
+            },
+        };
+    }
+}
+
+export const vercelPreset = definePreset({
+    name: 'vercel',
+    description: 'Vercel (Build Output API): static frontend on the CDN, the server as a function',
+    entry: 'http',
+    format: 'esm',
+    outDir: VercelPreset.OUT_DIR,
+    staticHosting: true,
+    // Vercel's build machines set VERCEL=1.
+    detect: env => env.VERCEL === '1',
+    options: VercelPreset.OPTIONS,
+    output: context => VercelPreset.output(context),
+    preview: context => VercelPreset.preview(context),
+    deployer: 'vercel',
+});

package/src/test/fixture-project.ts

@@ -0,0 +1,50 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * A throw-away project on disk for tests. It lives under this package's `.fixtures/` directory so
+ * that the repository's node_modules (and therefore @celljs/core) are resolvable from it.
+ */
+export class FixtureProject {
+    /** Created eagerly: Bun's resolver caches a missing directory, which would break later lookups from it. */
+    static readonly BASE = FixtureProject.createBase();
+
+    protected static createBase(): string {
+        const base = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '.fixtures');
+        mkdirSync(base, { recursive: true });
+        return base;
+    }
+
+    readonly root: string;
+
+    constructor(name: string) {
+        this.root = join(FixtureProject.BASE, `${name}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+        mkdirSync(this.root, { recursive: true });
+    }
+
+    file(path: string, content: string | object): this {
+        const file = join(this.root, path);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, typeof content === 'string' ? content : `${JSON.stringify(content, null, 2)}\n`);
+        return this;
+    }
+
+    /** Adds a package under `node_modules` (or nested under `under`). */
+    dependency(name: string, pkg: Record<string, unknown> = {}, files: Record<string, string> = {}, under = ''): this {
+        const dir = join(under, 'node_modules', name);
+        this.file(join(dir, 'package.json'), { name, version: '1.0.0', ...pkg });
+        for (const [path, content] of Object.entries(files)) {
+            this.file(join(dir, path), content);
+        }
+        return this;
+    }
+
+    path(...parts: string[]): string {
+        return join(this.root, ...parts);
+    }
+
+    dispose(): void {
+        rmSync(this.root, { recursive: true, force: true });
+    }
+}

package/src/testing/create-test-app.ts

@@ -0,0 +1,73 @@
+import { type TestApp as BaseTestApp, TestApp as ViteTestApp } from '@celljs/vite';
+
+export type { TestApp, TestContainer } from '@celljs/vite';
+
+import { Toolchain } from '../toolchain/toolchain.js';
+
+export interface CreateTestAppOptions {
+    /** Project root. Default: the current directory. */
+    root?: string;
+    /** Modes after `test`, which is always on (cell.test.yml). */
+    mode?: string[];
+    /** Preset whose entry runs the backend. Default as for `cell build`. */
+    preset?: string;
+    /** Environment for `${env.*}` and `CELL_*__` overrides of the frontend. Default: `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+
+/** A test application that also closes the toolchain it was created with. */
+class ToolchainTestApp extends ViteTestApp {
+    constructor(
+        options: ConstructorParameters<typeof ViteTestApp>[0],
+        protected readonly toolchain: Toolchain,
+    ) {
+        super(options);
+    }
+
+    override async close(): Promise<void> {
+        await super.close();
+        await this.toolchain.close();
+    }
+}
+
+/**
+ * The application of the project in the test process (docs/design/agent-first.md R11): cell.config.ts,
+ * toolchain modules and the preset's entry apply as for `cell dev`, in the `test` mode, without a
+ * port. Requests go through `app.fetch(path, init)`, which returns a standard `Response`.
+ *
+ * ```ts
+ * import { createTestApp } from '@celljs/cli';
+ *
+ * const app = await createTestApp();
+ * expect(await (await app.fetch('/users')).json()).toEqual([]);
+ * await app.close();
+ * ```
+ */
+export async function createTestApp(options: CreateTestAppOptions = {}): Promise<BaseTestApp> {
+    const toolchain = await Toolchain.create({
+        root: options.root,
+        command: 'test',
+        flags: { mode: options.mode, preset: options.preset },
+        env: options.env,
+        runHooks: false,
+        logger: { info: () => undefined, warn: message => process.stderr.write(`warning: ${message}\n`) },
+    });
+    const { config } = toolchain;
+    const app = new ToolchainTestApp(
+        {
+            ...toolchain.projectOptions(),
+            mode: config.mode,
+            env: options.env,
+            vite: config.vite,
+            plugins: toolchain.modules.vitePlugins(),
+            outDir: config.build.outDir,
+        },
+        toolchain,
+    );
+    try {
+        return await app.start();
+    } catch (error) {
+        await toolchain.close();
+        throw error;
+    }
+}

package/src/toolchain/toolchain.ts

@@ -0,0 +1,121 @@
+import { resolve } from 'node:path';
+import type { CellError, Preset } from '@celljs/kit';
+import { type CellBuilderOptions, ComponentCollector, type ProjectLoaderOptions } from '@celljs/vite';
+import { type CellCommand, type ConfigFlags, ConfigResolver, type ResolvedConfig } from '../config/config-resolver.js';
+import { EventBus } from '../events/event-bus.js';
+import { HookRunner } from '../events/hook-runner.js';
+import { ModuleHost } from '../modules/module-host.js';
+import { BUILTIN_PRESETS } from '../preset/builtin-presets.js';
+import { PresetRegistry } from '../preset/preset-registry.js';
+
+export interface ToolchainOptions {
+    root?: string;
+    command: CellCommand;
+    flags?: ConfigFlags;
+    env?: NodeJS.ProcessEnv;
+    /** Send hook output to stderr (`--json`). */
+    quiet?: boolean;
+    /** Run the project's `hooks` commands; read-only commands such as `cell info` turn this off. Default `true`. */
+    runHooks?: boolean;
+    /** Messages of modules. Default: stderr. */
+    logger?: { info(message: string): void; warn(message: string): void };
+    /** Report failing notification handlers here instead of failing (`cell dev`). */
+    onNotifyError?: (error: CellError) => void;
+}
+
+/**
+ * The toolchain of one command run: resolved configuration, toolchain modules, the preset and the
+ * event bus with the project's hooks. Startup order follows docs/design/modules.md §3.3: read
+ * cell.config.ts → find components → run module factories → resolve the preset → modules:done →
+ * config:resolved.
+ */
+export class Toolchain {
+    protected constructor(
+        readonly config: ResolvedConfig,
+        readonly preset: Preset,
+        readonly events: EventBus,
+        readonly presets: PresetRegistry,
+        readonly modules: ModuleHost,
+    ) {}
+
+    static async create(options: ToolchainOptions): Promise<Toolchain> {
+        const presets = new PresetRegistry();
+        for (const preset of BUILTIN_PRESETS) {
+            presets.register(preset);
+        }
+        const config = await new ConfigResolver({ ...options, detectors: presets.detectors }).resolve();
+        const events = new EventBus(options.onNotifyError);
+        const disabled = new Set(config.modules.flatMap(spec => (spec.kind === 'disabled' ? [spec.name] : [])));
+        const components = new ComponentCollector(config.root, disabled).collect();
+        const logger = options.logger ?? { info: (m: string) => process.stderr.write(`${m}\n`), warn: (m: string) => process.stderr.write(`warning: ${m}\n`) };
+        const modules = new ModuleHost({
+            config,
+            events,
+            presets,
+            logger,
+            components: components.map(({ name, version, dir, root }) => ({ name, version, dir, root })),
+        });
+        await modules.load(ModuleHost.sources(config, components));
+        Toolchain.detectModulePreset(config, presets, options.env ?? process.env);
+        const preset = presets.resolve(config.preset.name, config.preset.source === 'config' ? config.file : undefined);
+        // The options of every preset are accepted, so switching presets does not break cell.config.ts.
+        for (const { name, options: schema } of presets.all) {
+            if (schema) {
+                modules.claimOption(name, `the ${name} preset`, schema);
+            }
+        }
+        if (preset.outDir && config.build.outDir === ConfigResolver.DEFAULT_OUT_DIR) {
+            config.build.outDir = preset.outDir;
+        }
+        await modules.checkOptions();
+        if (options.runHooks ?? true) {
+            const outDir = resolve(config.root, config.build.outDir);
+            new HookRunner({ root: config.root, preset: preset.name, mode: config.mode, outDir, quiet: options.quiet, env: options.env }).register(
+                events,
+                config.hooks,
+            );
+        }
+        const toolchain = new Toolchain(config, preset, events, presets, modules);
+        await events.emit('modules:done', { modules: modules.loaded.map(m => m.name) });
+        await events.emit('config:resolved', { config, preset });
+        return toolchain;
+    }
+
+    /** Presets added by modules take part in CI detection like the built-in ones. */
+    protected static detectModulePreset(config: ResolvedConfig, presets: PresetRegistry, env: NodeJS.ProcessEnv): void {
+        if (config.preset.source !== 'default' || !config.ci) {
+            return;
+        }
+        const detected = presets.detectors.find(detector => detector.detect(env));
+        if (detected) {
+            config.preset = { name: detected.name, source: 'ci' };
+        }
+    }
+
+    /** What decides the component graph, with what modules added (DI modules, entries). */
+    projectOptions(): ProjectLoaderOptions {
+        return { ...ConfigResolver.toProjectOptions(this.config, this.preset), ...this.moduleProjectOptions() };
+    }
+
+    /** Options of the build: the configuration, the preset and the modules' plugins. */
+    builderOptions(): CellBuilderOptions {
+        return { ...ConfigResolver.toBuilderOptions(this.config, this.preset), ...this.moduleProjectOptions(), plugins: this.modules.vitePlugins() };
+    }
+
+    protected moduleProjectOptions(): Pick<ProjectLoaderOptions, 'extraModules' | 'entry'> {
+        const entry = this.modules.entries;
+        return {
+            ...(this.modules.extraModules.length > 0 ? { extraModules: this.modules.extraModules } : {}),
+            ...(Object.keys(entry).length > 0 ? { entry } : {}),
+        };
+    }
+
+    /** The options of a preset: its field of cell.config.ts, `{}` when absent. */
+    presetOptions(name = this.preset.name): Record<string, unknown> {
+        return this.config.options[name] ?? {};
+    }
+
+    async close(reason: 'exit' | 'restart' = 'exit'): Promise<void> {
+        await this.events.emit('close', { reason });
+    }
+}

package/src/utils/json-util.ts

@@ -0,0 +1,67 @@
+export namespace JsonUtil {
+    /**
+     * Parses JSON with comments and trailing commas (JSONC, as in wrangler.jsonc and tsconfig.json).
+     * Comments become spaces, so positions in error messages still match the text.
+     */
+    export function parseJsonc(text: string): unknown {
+        return JSON.parse(withoutTrailingCommas(withoutComments(text)));
+    }
+
+    export function withoutComments(text: string): string {
+        let result = '';
+        let i = 0;
+        while (i < text.length) {
+            const char = text[i];
+            if (char === '"') {
+                const end = stringEnd(text, i);
+                result += text.slice(i, end);
+                i = end;
+            } else if (char === '/' && text[i + 1] === '/') {
+                const end = text.indexOf('\n', i);
+                const stop = end === -1 ? text.length : end;
+                result += ' '.repeat(stop - i);
+                i = stop;
+            } else if (char === '/' && text[i + 1] === '*') {
+                const end = text.indexOf('*/', i + 2);
+                const stop = end === -1 ? text.length : end + 2;
+                result += text.slice(i, stop).replace(/[^\n]/g, ' ');
+                i = stop;
+            } else {
+                result += char;
+                i++;
+            }
+        }
+        return result;
+    }
+
+    /** Drops a comma that is followed only by whitespace and a closing bracket. */
+    export function withoutTrailingCommas(text: string): string {
+        let result = '';
+        let i = 0;
+        while (i < text.length) {
+            const char = text[i];
+            if (char === '"') {
+                const end = stringEnd(text, i);
+                result += text.slice(i, end);
+                i = end;
+                continue;
+            }
+            if (char === ',' && /^\s*[}\]]/.test(text.slice(i + 1))) {
+                result += ' ';
+            } else {
+                result += char;
+            }
+            i++;
+        }
+        return result;
+    }
+
+    /** Index just after the string literal that starts at `start` (or the end of the text). */
+    function stringEnd(text: string, start: number): number {
+        let i = start + 1;
+        while (i < text.length && text[i] !== '"') {
+            i += text[i] === '\\' ? 2 : 1;
+        }
+        return Math.min(i + 1, text.length);
+    }
+}

package/src/utils/text-util.ts

@@ -0,0 +1,68 @@
+export interface SourcePosition {
+    line: number;
+    column: number;
+}
+
+export namespace TextUtil {
+    /** Edit distance between two strings (insertions, deletions and substitutions). */
+    export function distance(a: string, b: string): number {
+        let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+        for (let i = 1; i <= a.length; i++) {
+            const current = [i];
+            for (let j = 1; j <= b.length; j++) {
+                current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+            }
+            previous = current;
+        }
+        return previous[b.length];
+    }
+
+    /** The candidate closest to `word`, if it is a likely typo (at most `max` edits away). */
+    export function closest(word: string, candidates: readonly string[], max = 2): string | undefined {
+        let best: string | undefined;
+        let bestDistance = max + 1;
+        for (const candidate of candidates) {
+            const d = distance(word, candidate);
+            if (d < bestDistance) {
+                best = candidate;
+                bestDistance = d;
+            }
+        }
+        return best;
+    }
+
+    /** Line and column of the first occurrence of `text` in `source`. */
+    export function find(source: string, text: string): SourcePosition | undefined {
+        const offset = source.indexOf(text);
+        return offset < 0 ? undefined : position(source, offset);
+    }
+
+    export function position(source: string, offset: number): SourcePosition {
+        const before = source.slice(0, offset).split('\n');
+        return { line: before.length, column: before[before.length - 1].length + 1 };
+    }
+
+    /**
+     * Where the property at `path` is written in an object-literal source file, found by searching each
+     * key after the previous one. Good enough to point a reader at the line; undefined when not found.
+     */
+    export function locate(source: string, path: readonly (string | number)[]): SourcePosition | undefined {
+        let offset = 0;
+        let found = false;
+        for (const key of path) {
+            if (typeof key === 'number') {
+                continue;
+            }
+            const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const pattern = new RegExp(`(^|[\\s{,])(['"\`]?)${escaped}\\2\\s*:`, 'mg');
+            pattern.lastIndex = offset;
+            const match = pattern.exec(source);
+            if (!match) {
+                break;
+            }
+            offset = match.index + match[1].length;
+            found = true;
+        }
+        return found ? position(source, offset) : undefined;
+    }
+}

package/templates/backend/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+A [Cell](https://github.com/cellbang/cell) backend.
+
+```bash
+npm install
+npx cell dev        # http://127.0.0.1:3000, reloads on save
+bun test            # tests with createTestApp()
+npx cell check      # types, configuration and DI bindings
+npx cell build      # .cell/output; npx cell preview runs it
+```
+
+Coding agents: see AGENTS.md; `npx cell mcp` is configured in .mcp.json.

package/templates/backend/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+.cell
+.vercel
+*.log
+.env

package/templates/backend/cell.yml

@@ -0,0 +1,3 @@
+backend:
+  cell:
+    greeting: Hello from {{name}}

package/templates/backend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "cell dev",
+    "build": "cell build",
+    "preview": "cell preview",
+    "check": "cell check",
+    "test": "bun test ./test"
+  },
+  "dependencies": {
+    "@celljs/core": "^{{cellVersion}}",
+    "@celljs/express-adapter": "^{{cellVersion}}",
+    "@celljs/mvc": "^{{cellVersion}}"
+  },
+  "devDependencies": {
+    "@celljs/cli": "^{{cellVersion}}",
+    "@types/bun": "^1.3.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.0"
+  }
+}

package/templates/{file-service/src → backend/src/node}/home-controller.ts

@@ -1,11 +1,14 @@
+import { Value } from '@celljs/core';
 import { Controller, Get, Text } from '@celljs/mvc/lib/node';
 
 @Controller()
 export class HomeController {
-    
+    @Value('cell.greeting')
+    protected readonly greeting: string;
+
     @Get()
     @Text()
     home(): string {
-        return 'Welcome to Cell';
+        return this.greeting;
     }
 }

package/templates/{file-service/src → backend/src/node}/module.ts

@@ -1,5 +1,4 @@
 import './home-controller';
-import './file-controller';
 import { autoBind } from '@celljs/core';
 
 export default autoBind();

package/templates/backend/template.json

@@ -0,0 +1,3 @@
+{
+  "description": "REST API on Express with a test"
+}

package/templates/backend/test/app.spec.ts

@@ -0,0 +1,19 @@
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import { join } from 'node:path';
+import { createTestApp, type TestApp } from '@celljs/cli';
+
+describe('{{name}}', () => {
+    let app: TestApp;
+
+    beforeAll(async () => {
+        app = await createTestApp({ root: join(__dirname, '..') });
+    }, 60000);
+
+    afterAll(() => app?.close());
+
+    it('GET /', async () => {
+        const res = await app.fetch('/');
+        expect(res.status).toBe(200);
+        expect(await res.text()).toBe('Hello from {{name}}');
+    });
+});

package/templates/backend/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": [
+      "ES2022"
+    ],
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": false,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": [
+      "node",
+      "bun"
+    ]
+  },
+  "include": [
+    "src",
+    "test"
+  ]
+}

package/templates/fullstack/README.md

@@ -0,0 +1,13 @@
+# {{name}}
+
+A [Cell](https://github.com/cellbang/cell) application: React frontend and backend on one port, calling the backend over RPC.
+
+```bash
+npm install
+npx cell dev        # http://127.0.0.1:3000, reloads on save
+bun test            # tests with createTestApp()
+npx cell check      # types, configuration and DI bindings
+npx cell build      # .cell/output; npx cell preview runs it
+```
+
+Coding agents: see AGENTS.md; `npx cell mcp` is configured in .mcp.json.

package/templates/fullstack/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+.cell
+.vercel
+*.log
+.env

package/templates/fullstack/cell.yml

@@ -0,0 +1,6 @@
+frontend:
+  cell:
+    name: {{name}}
+backend:
+  cell:
+    greeting: Hello from {{name}}