@celljs/cli 3.9.0 → 4.0.0

package/src/config/config-explainer.ts

@@ -0,0 +1,158 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { CellError, type ProjectModel, type Target } from '@celljs/kit';
+import { EnvOverrides, TOOLING_KEYS } from '@celljs/vite';
+import yaml from 'js-yaml';
+import { TextUtil } from '../utils/text-util.js';
+
+/** A configuration file that sets the key, in merge order (the last one wins). */
+export interface ConfigLayer {
+    /** Relative to the project root. */
+    file: string;
+    component: string;
+    /** `shared`: top level of the file; `frontend` / `backend`: the target's section. */
+    section: 'shared' | Target;
+    value: unknown;
+}
+
+/** The result of `cell config get`. */
+export interface ConfigValue {
+    key: string;
+    target: Target;
+    value: unknown;
+    /** Files that set the key or a part of it, in merge order (the last wins): shared parts of all files, then the target sections. */
+    layers: ConfigLayer[];
+    /** `CELL_<TARGET>__*` variables that set the key or a part of it. */
+    env: { variable: string; path: string }[];
+    /** Backend values keep `${...}` expressions; the server evaluates them at startup. */
+    expressions: boolean;
+}
+
+/**
+ * Looks up one key of the merged application configuration of a target and says where it came
+ * from: which cell*.yml files set it (shared or target section) and which environment variables.
+ */
+export class ConfigExplainer {
+    constructor(
+        protected readonly model: ProjectModel,
+        protected readonly env: Record<string, string | undefined>,
+    ) {}
+
+    /** `cell.server.port`, `items[0].name` and `items.0.name` all work. */
+    static parseKey(key: string): string[] {
+        const parts = key
+            .replace(/\[(\d+)\]/g, '.$1')
+            .split('.')
+            .filter(part => part !== '');
+        if (parts.length === 0) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `Invalid configuration key '${key}'.`,
+                hint: 'Pass a dotted key, e.g. cell.server.port.',
+            });
+        }
+        return parts;
+    }
+
+    defaultTarget(): Target {
+        return this.model.backend ? 'backend' : 'frontend';
+    }
+
+    explain(key: string, target: Target = this.defaultTarget()): ConfigValue {
+        const model = this.model[target];
+        if (!model) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `The project has no ${target} target.`,
+                hint: `Its targets: ${this.model.targets.join(', ')}.`,
+            });
+        }
+        const path = ConfigExplainer.parseKey(key);
+        const config = structuredClone(model.config);
+        // The frontend model has its variables applied already; the server applies the backend ones at startup.
+        const report = target === 'backend' ? new EnvOverrides(this.model.root, this.env).apply('backend', config) : model.envOverrides;
+        const found = ConfigExplainer.lookup(config, path);
+        if (!found.found) {
+            throw this.notFound(key, path, config, target);
+        }
+        const env = report.applied
+            .filter(({ path: set }) => ConfigExplainer.overlaps(ConfigExplainer.parseKey(set), path))
+            .map(({ variable, path: set }) => ({ variable, path: set }));
+        return {
+            key: path.join('.'),
+            target,
+            value: found.value,
+            layers: this.layers(path, target),
+            env,
+            expressions: target === 'backend' && JSON.stringify(found.value ?? null).includes('${'),
+        };
+    }
+
+    /** Shared layers of every file first, then the target sections: how ConfigLoader.forTarget merges. */
+    protected layers(path: string[], target: Target): ConfigLayer[] {
+        const shared: ConfigLayer[] = [];
+        const sections: ConfigLayer[] = [];
+        for (const component of this.model.components) {
+            for (const file of component.configFiles) {
+                const doc = (yaml.load(readFileSync(file, 'utf8')) ?? {}) as Record<string, unknown>;
+                const layer = (section: 'shared' | Target, value: unknown): ConfigLayer => ({
+                    file: relative(this.model.root, file) || file,
+                    component: component.name,
+                    section,
+                    value,
+                });
+                const inShared = TOOLING_KEYS.includes(path[0]) ? { found: false } : ConfigExplainer.lookup(doc, path);
+                if (inShared.found) {
+                    shared.push(layer('shared', inShared.value));
+                }
+                const inSection = ConfigExplainer.lookup(doc[target], path);
+                if (inSection.found) {
+                    sections.push(layer(target, inSection.value));
+                }
+            }
+        }
+        return [...shared, ...sections];
+    }
+
+    protected notFound(key: string, path: string[], config: Record<string, unknown>, target: Target): CellError {
+        let parent: unknown = config;
+        let depth = 0;
+        for (; depth < path.length - 1; depth++) {
+            const next = ConfigExplainer.lookup(parent, [path[depth]]);
+            if (!next.found || typeof next.value !== 'object' || next.value === null) {
+                break;
+            }
+            parent = next.value;
+        }
+        const keys = typeof parent === 'object' && parent !== null ? Object.keys(parent) : [];
+        const missing = path[depth];
+        const suggestion = TextUtil.closest(missing, keys);
+        const where = depth === 0 ? 'the top level' : path.slice(0, depth).join('.');
+        return new CellError({
+            code: 'CELL_CONFIG_KEY_NOT_FOUND',
+            message: `No key '${key}' in the ${target} configuration: '${missing}' is not under ${where}.`,
+            hint: suggestion
+                ? `Did you mean '${[...path.slice(0, depth), suggestion].join('.')}'?`
+                : keys.length > 0
+                  ? `Keys under ${where}: ${keys.slice(0, 20).join(', ')}${keys.length > 20 ? ', ...' : ''}.`
+                  : 'Set it in cell.yml, or run cell info --json --app-config for the whole configuration.',
+        });
+    }
+
+    static lookup(root: unknown, path: string[]): { found: boolean; value?: unknown } {
+        let value = root;
+        for (const part of path) {
+            if (typeof value !== 'object' || value === null || !Object.hasOwn(value, part)) {
+                return { found: false };
+            }
+            value = (value as Record<string, unknown>)[part];
+        }
+        return { found: true, value };
+    }
+
+    /** One path is a prefix of the other: the variable sets the key, a part of it, or an object around it. */
+    protected static overlaps(a: string[], b: string[]): boolean {
+        const n = Math.min(a.length, b.length);
+        return a.slice(0, n).every((part, i) => part.toLowerCase() === b[i].toLowerCase());
+    }
+}

package/src/config/config-file-loader.ts

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+import { CellError } from '@celljs/kit';
+import { ConfigValidator } from './config-validator.js';
+import type { CellConfig } from './types.js';
+
+export interface LoadedConfigFile {
+    file: string;
+    config: CellConfig;
+    /** The config file and the local files it imports; a change to any of them means reloading. */
+    dependencies: string[];
+}
+
+interface LoadError extends Error {
+    loc?: { file?: string; line?: number; column?: number };
+    errors?: LoadError[];
+}
+
+/**
+ * Finds and loads cell.config.{ts,mts,cts,js,mjs,cjs} with Vite's config loader (TypeScript needs no
+ * pre-compilation; packages it imports are loaded by Node), then validates the default export.
+ */
+export class ConfigFileLoader {
+    static readonly FILE_NAMES = ['cell.config.ts', 'cell.config.mts', 'cell.config.cts', 'cell.config.js', 'cell.config.mjs', 'cell.config.cjs'];
+
+    constructor(protected readonly root: string) {}
+
+    /** The project's config file, or undefined when it has none. Two of them is an error: only one is read. */
+    find(): string | undefined {
+        const files = ConfigFileLoader.FILE_NAMES.map(name => join(this.root, name)).filter(existsSync);
+        if (files.length > 1) {
+            throw new CellError({
+                code: 'CELL_CONFIG_AMBIGUOUS',
+                message: `Found ${files.length} config files: ${files.map(f => f.slice(this.root.length + 1)).join(', ')}.`,
+                file: files[1],
+                hint: 'Keep one cell.config file and delete the others.',
+            });
+        }
+        return files[0];
+    }
+
+    async load(): Promise<LoadedConfigFile | undefined> {
+        const file = this.find();
+        if (!file) {
+            return undefined;
+        }
+        const { loadConfigFromFile } = await import('vite');
+        let loaded: Awaited<ReturnType<typeof loadConfigFromFile>>;
+        try {
+            loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, file, this.root, 'silent');
+        } catch (cause) {
+            throw this.loadError(file, cause);
+        }
+        const config = new ConfigValidator(file, readFileSync(file, 'utf8')).validate(loaded?.config);
+        return { file, config, dependencies: (loaded?.dependencies ?? [file]).map(dep => resolve(this.root, dep)) };
+    }
+
+    protected loadError(file: string, cause: unknown): CellError {
+        const error = cause as LoadError;
+        const first = error.errors?.[0] ?? error;
+        const message = stripVTControlCharacters(String(first?.message ?? cause))
+            .split('\n')
+            .map(line => line.trim())
+            .find(line => line && !/^Build failed/.test(line));
+        return new CellError({
+            code: 'CELL_CONFIG_LOAD',
+            message: `Cannot load ${file}: ${message}`,
+            file: first?.loc?.file ?? file,
+            line: first?.loc?.line,
+            column: first?.loc?.column,
+            hint: 'Fix the reported error in the config file, or install the packages it imports.',
+            cause,
+        });
+    }
+}

package/src/config/config-resolver.ts

@@ -0,0 +1,300 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CellError, type HookableEventName, type Preset, type Target } from '@celljs/kit';
+import type { CellBuilderOptions, ProjectLoaderOptions } from '@celljs/vite';
+import type { UserConfig } from 'vite';
+import { TextUtil } from '../utils/text-util.js';
+import { ConfigFileLoader, type LoadedConfigFile } from './config-file-loader.js';
+import { ConfigValidator } from './config-validator.js';
+import type { BuildOptions, CellConfig, CompileTarget } from './types.js';
+
+export type CellCommand = 'dev' | 'build' | 'preview' | 'deploy' | 'info' | 'check' | 'config' | 'docs' | 'mcp' | 'test';
+
+/** Command-line flags; each wins over the same setting in cell.config.ts. */
+export interface ConfigFlags {
+    preset?: string;
+    /** `-m`, in order; appended after the mode of the command (`development` or `production`). */
+    mode?: string[];
+    format?: 'esm' | 'cjs';
+    single?: boolean;
+    compile?: boolean | CompileTarget;
+    sourcemap?: boolean;
+    outDir?: string;
+}
+
+/** A preset that recognises the CI platform it runs on, e.g. Vercel from `VERCEL=1`. */
+export interface PresetDetector {
+    name: string;
+    detect(env: NodeJS.ProcessEnv): boolean;
+}
+
+export interface ConfigResolverOptions {
+    root?: string;
+    command: CellCommand;
+    flags?: ConfigFlags;
+    env?: NodeJS.ProcessEnv;
+    /** Tried in order when running in CI and no preset is chosen explicitly. */
+    detectors?: PresetDetector[];
+}
+
+/** Where a resolved value came from, reported by `cell info`. */
+export type ValueSource = 'flag' | 'config' | 'env' | 'ci' | 'default';
+
+export type ModuleSpec =
+    | { kind: 'local'; path: string }
+    | { kind: 'package'; name: string }
+    | { kind: 'disabled'; name: string }
+    | { kind: 'filter'; name: string; runtime: boolean; toolchain: boolean };
+
+export interface ResolvedBuildOptions {
+    /** Undefined until a preset chooses; `esm` when none does. */
+    format?: 'esm' | 'cjs';
+    single: boolean;
+    compile: false | CompileTarget;
+    external: string[];
+    sourcemap: boolean;
+    outDir: string;
+}
+
+/** The toolchain configuration of one command run: cell.config.ts, flags and environment combined. */
+export interface ResolvedConfig {
+    root: string;
+    /** The cell.config file, if the project has one. */
+    file?: string;
+    /** Files whose change requires reloading the configuration. */
+    dependencies: string[];
+    command: CellCommand;
+    dev: boolean;
+    ci: boolean;
+    mode: string[];
+    preset: { name: string; source: ValueSource };
+    /** Explicit targets from cell.config.ts; undefined means "what the components declare". */
+    targets?: Target[];
+    build: ResolvedBuildOptions;
+    modules: ModuleSpec[];
+    vite: UserConfig;
+    hooks: Partial<Record<HookableEventName, string>>;
+    /** Options of toolchain modules, by key. */
+    options: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Resolves the toolchain configuration. Precedence: flags → cell.config.ts → environment → CI
+ * detection → defaults (docs/design/architecture.md §4, §7).
+ */
+export class ConfigResolver {
+    static readonly DEFAULT_PRESET = 'node';
+    static readonly DEFAULT_OUT_DIR = '.cell/output';
+    static readonly MODE_NAME = /^[\w-]+$/;
+    static readonly LOCAL_MODULE_EXTENSIONS = ['', '.ts', '.mts', '.js', '.mjs'];
+
+    protected readonly env: NodeJS.ProcessEnv;
+    protected readonly flags: ConfigFlags;
+
+    constructor(protected readonly options: ConfigResolverOptions) {
+        this.env = options.env ?? process.env;
+        this.flags = options.flags ?? {};
+    }
+
+    async resolve(): Promise<ResolvedConfig> {
+        const root = this.findRoot();
+        return this.create(root, await new ConfigFileLoader(root).load());
+    }
+
+    /** Options of {@link CellBuilder} for this configuration and the preset it chose. */
+    static toBuilderOptions(resolved: ResolvedConfig, preset?: Preset): CellBuilderOptions {
+        const { build } = resolved;
+        const format = ConfigResolver.format(resolved, preset);
+        if ((preset?.staticHosting || preset?.runtime === 'workerd') && (build.single || build.compile)) {
+            throw new CellError({
+                code: 'CELL_CONFIG_CONFLICT',
+                message: `The ${preset.name} preset deploys the frontend as static assets of the platform; ${build.compile ? '--compile' : '--single'} does not apply.`,
+                file: resolved.file,
+                hint: 'Remove --single / --compile and build.single / build.compile from cell.config.ts, or use the node preset.',
+            });
+        }
+        if (preset?.runtime === 'workerd' && format !== 'esm') {
+            throw new CellError({
+                code: 'CELL_CONFIG_CONFLICT',
+                message: `The ${preset.name} preset runs on Cloudflare Workers, which load ES modules only, but the format is ${format}.`,
+                file: resolved.file,
+                hint: 'Remove --format cjs and build.format from cell.config.ts.',
+            });
+        }
+        return {
+            ...ConfigResolver.toProjectOptions(resolved, preset),
+            preset: preset?.name,
+            runtime: preset?.runtime,
+            format,
+            outDir: build.outDir,
+            external: build.external,
+            sourcemap: build.sourcemap,
+            // An executable serves the frontend too: it is built from the single-file bundle.
+            single: build.single || build.compile !== false,
+            vite: resolved.vite,
+        };
+    }
+
+    /** Options of {@link ProjectLoader}: what decides the component graph, without the build-only settings. */
+    static toProjectOptions(resolved: ResolvedConfig, preset?: Preset): ProjectLoaderOptions {
+        const names = (keep: (spec: ModuleSpec) => boolean) => resolved.modules.filter(keep).map(spec => (spec as { name: string }).name);
+        return {
+            root: resolved.root,
+            mode: resolved.mode,
+            targets: resolved.targets,
+            entryName: preset?.entry,
+            disabled: names(spec => spec.kind === 'disabled'),
+            runtimeDisabled: names(spec => spec.kind === 'filter' && !spec.runtime),
+        };
+    }
+
+    /** Server bundle format: the project's choice, else the preset's, else `esm`. */
+    static format(resolved: ResolvedConfig, preset?: Preset): 'esm' | 'cjs' {
+        return resolved.build.format ?? preset?.format ?? 'esm';
+    }
+
+    protected create(root: string, loaded?: LoadedConfigFile): ResolvedConfig {
+        const config: CellConfig = loaded?.config ?? {};
+        const { preset, targets, modules, build, vite, hooks, ...options } = config;
+        const dev = this.options.command === 'dev';
+        return {
+            root,
+            file: loaded?.file,
+            dependencies: loaded?.dependencies ?? [],
+            command: this.options.command,
+            dev,
+            ci: this.isCI(),
+            mode: this.mode(dev),
+            preset: this.preset(preset),
+            targets,
+            build: this.build(build ?? {}, loaded?.file),
+            modules: this.modules(modules ?? [], loaded?.file),
+            vite: vite ?? {},
+            hooks: hooks ?? {},
+            options: options as Record<string, Record<string, unknown>>,
+        };
+    }
+
+    protected findRoot(): string {
+        const root = resolve(this.options.root ?? process.cwd());
+        if (!existsSync(join(root, 'package.json'))) {
+            throw new CellError({
+                code: 'CELL_PROJECT_NOT_FOUND',
+                message: `No package.json in ${root}.`,
+                file: join(root, 'package.json'),
+                hint: 'Run the command in the project root, or pass --root.',
+            });
+        }
+        return realpathSync(root);
+    }
+
+    protected isCI(): boolean {
+        const ci = this.env.CI;
+        return ci !== undefined && ci !== '' && ci !== '0' && ci !== 'false';
+    }
+
+    protected mode(dev: boolean): string[] {
+        const flags = this.flags.mode ?? [];
+        const invalid = flags.find(mode => !ConfigResolver.MODE_NAME.test(mode));
+        if (invalid !== undefined) {
+            throw new CellError({
+                code: 'CELL_ARGUMENT_INVALID',
+                message: `Invalid mode '${invalid}'.`,
+                hint: 'A mode names the file cell.<mode>.yml: use letters, digits, - and _ only.',
+            });
+        }
+        const base = this.options.command === 'test' ? 'test' : dev ? 'development' : 'production';
+        return [...new Set([base, ...flags])];
+    }
+
+    protected preset(configured?: string): ResolvedConfig['preset'] {
+        if (this.flags.preset) {
+            return { name: this.flags.preset, source: 'flag' };
+        }
+        if (configured) {
+            return { name: configured, source: 'config' };
+        }
+        if (this.env.CELL_PRESET) {
+            return { name: this.env.CELL_PRESET, source: 'env' };
+        }
+        const detected = this.isCI() ? this.options.detectors?.find(detector => detector.detect(this.env)) : undefined;
+        return detected ? { name: detected.name, source: 'ci' } : { name: ConfigResolver.DEFAULT_PRESET, source: 'default' };
+    }
+
+    protected build(build: BuildOptions, file?: string): ResolvedBuildOptions {
+        const compileOption = this.flags.compile ?? build.compile ?? false;
+        const compile = compileOption === true ? 'bun' : compileOption;
+        let format = this.flags.format ?? build.format;
+        if (compile === 'node') {
+            if (format === 'esm') {
+                throw new CellError({
+                    code: 'CELL_CONFIG_CONFLICT',
+                    message: 'A Node.js executable (compile: node) needs a CommonJS bundle, but the format is esm.',
+                    file,
+                    hint: "Remove the format setting (node executables use cjs), or compile with 'bun'.",
+                });
+            }
+            format = 'cjs';
+        }
+        return {
+            format,
+            single: this.flags.single ?? build.single ?? false,
+            compile,
+            external: build.external ?? [],
+            sourcemap: this.flags.sourcemap ?? build.sourcemap ?? false,
+            outDir: this.flags.outDir ?? build.outDir ?? ConfigResolver.DEFAULT_OUT_DIR,
+        };
+    }
+
+    /** Normalises `modules`; a package may appear once, whatever the form of the entry. */
+    protected modules(entries: NonNullable<CellConfig['modules']>, file?: string): ModuleSpec[] {
+        const source = file ? readFileSync(file, 'utf8') : '';
+        const seen = new Map<string, string>();
+        return entries.map(entry => {
+            const text = typeof entry === 'string' ? entry : entry.source;
+            const spec = this.moduleSpec(entry, file, source);
+            const identity = spec.kind === 'local' ? spec.path : spec.name;
+            if (seen.has(identity)) {
+                const position = TextUtil.find(source, text);
+                throw new CellError({
+                    code: 'CELL_CONFIG_INVALID',
+                    message: `modules lists ${identity} twice ('${seen.get(identity)}' and '${text}').`,
+                    file,
+                    line: position?.line,
+                    column: position?.column,
+                    hint: 'Keep one entry per package or path.',
+                });
+            }
+            seen.set(identity, text);
+            return spec;
+        });
+    }
+
+    protected moduleSpec(entry: NonNullable<CellConfig['modules']>[number], file: string | undefined, source: string): ModuleSpec {
+        if (typeof entry !== 'string') {
+            return { kind: 'filter', name: entry.source, runtime: entry.runtime ?? true, toolchain: entry.toolchain ?? true };
+        }
+        if (entry.startsWith('!')) {
+            return { kind: 'disabled', name: entry.slice(1) };
+        }
+        if (!ConfigValidator.isLocalPath(entry)) {
+            return { kind: 'package', name: entry };
+        }
+        const base = resolve(file ? dirname(file) : this.findRoot(), entry);
+        for (const suffix of ConfigResolver.LOCAL_MODULE_EXTENSIONS) {
+            const path = base + suffix;
+            if (existsSync(path) && (statSync(path).isFile() || existsSync(join(path, 'package.json')))) {
+                return { kind: 'local', path };
+            }
+        }
+        const position = TextUtil.find(source, entry);
+        throw new CellError({
+            code: 'CELL_LOCAL_MODULE_NOT_FOUND',
+            message: `Local module ${entry} not found (looked for ${base}{${ConfigResolver.LOCAL_MODULE_EXTENSIONS.filter(Boolean).join(',')}}).`,
+            file,
+            line: position?.line,
+            column: position?.column,
+            hint: 'Fix the path (relative to cell.config.ts); a directory needs a package.json.',
+        });
+    }
+}