@celljs/cli 3.9.0 → 4.0.0

package/src/preset/lambda/lambda-deployer.ts

@@ -0,0 +1,317 @@
+import { CellError, type DeployContext, type Deployment, type DeployPlan, type DeployResource, defineDeployer } from '@celljs/kit';
+import { CloudApi, CloudApiError, CloudCredentials, type CloudIo, CloudNames, DEFAULT_IO } from '../../deploy/cloud-api.js';
+import { CodePackage } from '../../deploy/code-package.js';
+import { RequestSigner } from '../../deploy/request-signer.js';
+import { LambdaPreset } from './lambda-preset.js';
+
+type Credentials = NonNullable<ReturnType<typeof CloudCredentials.aws>>;
+
+/** The Lambda REST API and the IAM query API, signed with SigV4. */
+export class AwsClient {
+    constructor(
+        readonly region: string,
+        protected readonly credentials: Credentials,
+        protected readonly io: CloudIo = DEFAULT_IO,
+    ) {}
+
+    async lambda<T = Record<string, any>>(method: string, path: string, body?: unknown): Promise<T> {
+        const host = `lambda.${this.region}.amazonaws.com`;
+        const text = body === undefined ? '' : JSON.stringify(body);
+        const headers = RequestSigner.sigv4(
+            { method, host, path, service: 'lambda', region: this.region, body: text, headers: text ? { 'content-type': 'application/json' } : {} },
+            this.credentials,
+            this.io.now(),
+        );
+        const response = await CloudApi.send(this.io, `https://${host}${path}`, { method, headers, body: text || undefined }, 'AWS Lambda');
+        const raw = await response.text();
+        const json = raw ? (JSON.parse(raw) as Record<string, any>) : {};
+        if (!response.ok) {
+            const type = (response.headers.get('x-amzn-errortype') ?? json.Type ?? json.__type ?? String(response.status)).split(':')[0];
+            throw new CloudApiError(response.status, type, json.message ?? json.Message ?? raw, response.headers.get('x-amzn-requestid') ?? undefined);
+        }
+        return json as T;
+    }
+
+    /** An IAM query API action; returns the XML response. IAM is global, signed in us-east-1. */
+    async iam(params: Record<string, string>): Promise<string> {
+        const host = 'iam.amazonaws.com';
+        const body = new URLSearchParams({ ...params, Version: '2010-05-08' }).toString();
+        const headers = RequestSigner.sigv4(
+            {
+                method: 'POST',
+                host,
+                path: '/',
+                service: 'iam',
+                region: 'us-east-1',
+                body,
+                headers: { 'content-type': 'application/x-www-form-urlencoded; charset=utf-8' },
+            },
+            this.credentials,
+            this.io.now(),
+        );
+        const response = await CloudApi.send(this.io, `https://${host}/`, { method: 'POST', headers, body }, 'AWS IAM');
+        const xml = await response.text();
+        if (!response.ok) {
+            throw new CloudApiError(
+                response.status,
+                AwsClient.tag(xml, 'Code') ?? String(response.status),
+                AwsClient.tag(xml, 'Message') ?? xml,
+                AwsClient.tag(xml, 'RequestId'),
+            );
+        }
+        return xml;
+    }
+
+    static tag(xml: string, name: string): string | undefined {
+        return new RegExp(`<${name}>([^<]*)</${name}>`).exec(xml)?.[1];
+    }
+}
+
+/**
+ * Deploys the output of the lambda preset: the output directory as the code of a Node.js function,
+ * a function URL without authentication and the permissions it needs, and, when `lambda.role` is
+ * not set, the execution role `cell-lambda-execution` (logs only). Credentials: AWS_ACCESS_KEY_ID /
+ * AWS_SECRET_ACCESS_KEY (/ AWS_SESSION_TOKEN), or a profile of ~/.aws/credentials.
+ */
+export class LambdaDeployment {
+    /** A zip uploaded in the request (base64 in JSON). */
+    static readonly MAX_PACKAGE = 50 * 1024 * 1024;
+    static readonly ROLE = 'cell-lambda-execution';
+    static readonly CREDENTIALS = 'AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY';
+    static readonly ASSUME_ROLE = JSON.stringify({
+        Version: '2012-10-17',
+        Statement: [{ Effect: 'Allow', Principal: { Service: 'lambda.amazonaws.com' }, Action: 'sts:AssumeRole' }],
+    });
+    static readonly BASIC_EXECUTION = 'arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole';
+
+    readonly name: string;
+    readonly region: string;
+    protected readonly credentials?: Credentials;
+
+    constructor(
+        protected readonly context: DeployContext,
+        protected readonly io: CloudIo = DEFAULT_IO,
+    ) {
+        const { options, env, root } = context;
+        this.name = CloudNames.functionName(root, options.name, 64);
+        this.region = (options.region as string | undefined) ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION ?? 'us-east-1';
+        this.credentials = CloudCredentials.aws(env);
+    }
+
+    get configuration(): Record<string, unknown> {
+        const { options } = this.context;
+        return {
+            Runtime: (options.runtime as string | undefined) ?? LambdaPreset.RUNTIMES[0],
+            Handler: LambdaPreset.HANDLER,
+            MemorySize: (options.memory as number | undefined) ?? 1024,
+            Timeout: (options.timeout as number | undefined) ?? 30,
+            Environment: { Variables: { NODE_ENV: 'production', ...((options.env as Record<string, string> | undefined) ?? {}) } },
+        };
+    }
+
+    async plan(): Promise<DeployPlan> {
+        this.checkOutput();
+        const code = CodePackage.of(this.context.outDir);
+        let fn: boolean | undefined;
+        let url: boolean | undefined;
+        if (this.credentials) {
+            const client = new AwsClient(this.region, this.credentials, this.io);
+            fn = Boolean(await this.optional(() => client.lambda('GET', `/2015-03-31/functions/${this.name}`), 'GetFunction'));
+            url = fn && Boolean(await this.optional(() => client.lambda('GET', `/2021-10-31/functions/${this.name}/url`), 'GetFunctionUrlConfig'));
+        } else {
+            this.context.warn(
+                `No AWS credentials (${LambdaDeployment.CREDENTIALS}, or ~/.aws/credentials): the plan does not say whether the function exists.`,
+            );
+        }
+        const action = (found?: boolean): DeployResource['action'] => (found === undefined ? 'deploy' : found ? 'update' : 'create');
+        const { Environment: _env, ...settings } = this.configuration;
+        return {
+            deployer: 'lambda',
+            resources: [
+                ...(this.context.options.role
+                    ? []
+                    : [
+                          {
+                              type: 'iam-role',
+                              name: LambdaDeployment.ROLE,
+                              action: 'deploy',
+                              details: { policy: 'AWSLambdaBasicExecutionRole' },
+                          } satisfies DeployResource,
+                      ]),
+                { type: 'function', name: this.name, action: action(fn), details: { region: this.region, ...settings, package: code.describe() } },
+                ...(url ? [] : [{ type: 'function-url', name: this.name, action: action(url), details: { authType: 'NONE' } } satisfies DeployResource]),
+            ],
+            details: { region: this.region, credentials: this.credentials ? 'AWS' : 'missing' },
+        };
+    }
+
+    async apply(): Promise<Deployment> {
+        this.checkOutput();
+        if (!this.credentials) {
+            throw CloudCredentials.missing('AWS', LambdaDeployment.CREDENTIALS, ', or a profile in ~/.aws/credentials (AWS_PROFILE)');
+        }
+        const client = new AwsClient(this.region, this.credentials, this.io);
+        const code = CodePackage.of(this.context.outDir);
+        code.checkSize(LambdaDeployment.MAX_PACKAGE, 'Lambda', 'Keep large packages out of the server bundle and the output directory.');
+        const path = `/2015-03-31/functions/${this.name}`;
+        if (await this.optional(() => client.lambda('GET', path), 'GetFunction')) {
+            this.context.info(`Updating function ${this.name} in ${this.region} (${code.describe()})…`);
+            await this.waitReady(client);
+            await this.step('UpdateFunctionCode', () => client.lambda('PUT', `${path}/code`, { ZipFile: code.base64 }));
+            await this.waitReady(client);
+            await this.step('UpdateFunctionConfiguration', () => client.lambda('PUT', `${path}/configuration`, this.configuration));
+        } else {
+            const role = (this.context.options.role as string | undefined) ?? (await this.executionRole(client));
+            this.context.info(`Creating function ${this.name} in ${this.region} (${code.describe()})…`);
+            await this.createFunction(client, {
+                FunctionName: this.name,
+                Role: role,
+                Code: { ZipFile: code.base64 },
+                ...this.configuration,
+                ...this.architecture,
+            });
+        }
+        await this.waitReady(client);
+        let url = (await this.optional(() => client.lambda('GET', `/2021-10-31/functions/${this.name}/url`), 'GetFunctionUrlConfig'))?.FunctionUrl as
+            | string
+            | undefined;
+        if (!url) {
+            this.context.info('Creating the function URL…');
+            url = (await this.step('CreateFunctionUrlConfig', () => client.lambda('POST', `/2021-10-31/functions/${this.name}/url`, { AuthType: 'NONE' })))
+                .FunctionUrl;
+            // Public function URLs need both permissions (since October 2025).
+            await this.permission(client, {
+                StatementId: 'cell-function-url',
+                Action: 'lambda:InvokeFunctionUrl',
+                Principal: '*',
+                FunctionUrlAuthType: 'NONE',
+            });
+            await this.permission(client, {
+                StatementId: 'cell-function-url-invoke',
+                Action: 'lambda:InvokeFunction',
+                Principal: '*',
+                InvokedViaFunctionUrl: true,
+            });
+        }
+        return { url, details: { region: this.region, function: this.name } };
+    }
+
+    protected get architecture(): Record<string, unknown> {
+        const architecture = this.context.options.architecture as string | undefined;
+        return architecture ? { Architectures: [architecture] } : {};
+    }
+
+    /** The role Lambda runs the function with: `cell-lambda-execution`, created with the basic execution policy if missing. */
+    protected async executionRole(client: AwsClient): Promise<string> {
+        try {
+            return AwsClient.tag(await client.iam({ Action: 'GetRole', RoleName: LambdaDeployment.ROLE }), 'Arn') as string;
+        } catch (error) {
+            if (!(error instanceof CloudApiError) || error.code !== 'NoSuchEntity') {
+                throw error instanceof CloudApiError
+                    ? CloudApi.failure(
+                          'IAM',
+                          'GetRole',
+                          error,
+                          'Allow the credentials iam:GetRole, iam:CreateRole and iam:AttachRolePolicy, or set lambda.role in cell.config.ts to an existing role ARN.',
+                      )
+                    : error;
+            }
+        }
+        this.context.info(`Creating IAM role ${LambdaDeployment.ROLE}…`);
+        const arn = await this.step('CreateRole', async () =>
+            AwsClient.tag(
+                await client.iam({
+                    Action: 'CreateRole',
+                    RoleName: LambdaDeployment.ROLE,
+                    AssumeRolePolicyDocument: LambdaDeployment.ASSUME_ROLE,
+                    Description: 'Created by Cell for Lambda functions',
+                }),
+                'Arn',
+            ),
+        );
+        await this.step('AttachRolePolicy', () =>
+            client.iam({ Action: 'AttachRolePolicy', RoleName: LambdaDeployment.ROLE, PolicyArn: LambdaDeployment.BASIC_EXECUTION }),
+        );
+        return arn as string;
+    }
+
+    /** A new role takes a few seconds before Lambda may assume it. */
+    protected async createFunction(client: AwsClient, body: Record<string, unknown>): Promise<void> {
+        for (let attempt = 1; ; attempt++) {
+            try {
+                await client.lambda('POST', '/2015-03-31/functions', body);
+                return;
+            } catch (error) {
+                const roleNotReady = error instanceof CloudApiError && error.code === 'InvalidParameterValueException' && /role/i.test(error.message);
+                if (!roleNotReady || attempt >= 10) {
+                    throw error instanceof CloudApiError ? CloudApi.failure('Lambda', 'CreateFunction', error) : error;
+                }
+                await this.io.sleep(3000);
+            }
+        }
+    }
+
+    protected async permission(client: AwsClient, statement: Record<string, unknown>): Promise<void> {
+        try {
+            await client.lambda('POST', `/2015-03-31/functions/${this.name}/policy`, statement);
+        } catch (error) {
+            if (!(error instanceof CloudApiError && error.code === 'ResourceConflictException')) {
+                throw error instanceof CloudApiError ? CloudApi.failure('Lambda', 'AddPermission', error) : error;
+            }
+        }
+    }
+
+    protected async waitReady(client: AwsClient): Promise<void> {
+        const config = await CloudApi.poll(
+            this.io,
+            () => this.step('GetFunctionConfiguration', () => client.lambda('GET', `/2015-03-31/functions/${this.name}/configuration`)),
+            c => c.State !== 'Pending' && c.LastUpdateStatus !== 'InProgress',
+            `function ${this.name} to become active`,
+        );
+        if (config.State === 'Failed' || config.LastUpdateStatus === 'Failed') {
+            throw new CellError({
+                code: 'CELL_DEPLOY_FAILED',
+                message: `Function ${this.name} failed: ${config.StateReason ?? config.LastUpdateStatusReason ?? 'no reason given'}`,
+                hint: 'Look at the function in the Lambda console; fix the reported problem and deploy again.',
+            });
+        }
+    }
+
+    protected async optional(call: () => Promise<Record<string, any>>, step: string): Promise<Record<string, any> | undefined> {
+        try {
+            return await call();
+        } catch (error) {
+            if (error instanceof CloudApiError && error.status === 404) {
+                return undefined;
+            }
+            throw error instanceof CloudApiError ? CloudApi.failure('Lambda', step, error) : error;
+        }
+    }
+
+    protected checkOutput(): void {
+        if (this.context.manifest.preset !== 'lambda') {
+            throw new CellError({
+                code: 'CELL_DEPLOY_OUTPUT_MISMATCH',
+                message: `${this.context.outDir} has no output of the lambda preset (built with: ${this.context.manifest.preset ?? 'no preset'}).`,
+                hint: 'Run cell deploy --preset lambda without --skip-build, or cell build --preset lambda first.',
+            });
+        }
+    }
+
+    protected async step<T>(name: string, call: () => Promise<T>): Promise<T> {
+        try {
+            return await call();
+        } catch (error) {
+            throw error instanceof CloudApiError
+                ? CloudApi.failure(name === 'CreateRole' || name === 'AttachRolePolicy' ? 'IAM' : 'Lambda', name, error)
+                : error;
+        }
+    }
+}
+
+export const lambdaDeployer = defineDeployer({
+    name: 'lambda',
+    description: 'AWS Lambda with a function URL through the AWS API (AWS_ACCESS_KEY_ID / ~/.aws/credentials)',
+    plan: context => new LambdaDeployment(context).plan(),
+    apply: context => new LambdaDeployment(context).apply(),
+});

package/src/preset/lambda/lambda-preset.ts

@@ -0,0 +1,45 @@
+import { definePreset, type PresetOutputContext } from '@celljs/kit';
+import { PresetOptionsSchema } from '../../deploy/cloud-api.js';
+import { ServerlessScripts } from '../serverless-scripts.js';
+
+/**
+ * AWS Lambda (Node.js runtime) behind a function URL: `server/lambda.mjs` starts the Cell server
+ * during the init phase and turns each HTTP event into a request to it.
+ */
+export namespace LambdaPreset {
+    export const HANDLER_FILE = 'server/lambda.mjs';
+    export const HANDLER = 'server/lambda.handler';
+    export const RUNTIMES = ['nodejs22.x', 'nodejs20.x'] as const;
+
+    export const OPTIONS = PresetOptionsSchema.of({
+        name: 'string',
+        region: 'string',
+        runtime: RUNTIMES,
+        architecture: ['x86_64', 'arm64'],
+        memory: 'number',
+        timeout: 'number',
+        role: 'string',
+        env: 'env',
+    });
+
+    export function output(context: PresetOutputContext): void {
+        if (!context.manifest.server) {
+            context.warn('The lambda preset deploys a server, but the project builds no backend.');
+            return;
+        }
+        if (context.manifest.server !== 'server/index.mjs') {
+            context.warn(`The lambda handler imports server/index.mjs, but the server bundle is ${context.manifest.server}.`);
+        }
+        context.write(HANDLER_FILE, ServerlessScripts.LAMBDA_HANDLER);
+    }
+}
+
+export const lambdaPreset = definePreset({
+    name: 'lambda',
+    description: 'AWS Lambda with a function URL',
+    entry: 'http',
+    format: 'esm',
+    options: LambdaPreset.OPTIONS,
+    output: context => LambdaPreset.output(context),
+    deployer: 'lambda',
+});

package/src/preset/preset-output.ts

@@ -0,0 +1,55 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CellError, type OutputManifest, type Preset, type ProjectModel } from '@celljs/kit';
+
+export interface PresetOutputOptions {
+    root: string;
+    /** Absolute output directory. */
+    outDir: string;
+    project: ProjectModel;
+    env: NodeJS.ProcessEnv;
+    /** The preset's field of cell.config.ts. */
+    options?: Record<string, unknown>;
+    warn(message: string): void;
+}
+
+/** Reads and writes `manifest.json` of an output, and lets the preset add its files around the bundles. */
+export namespace PresetOutput {
+    export const MANIFEST = 'manifest.json';
+
+    export function read(outDir: string): OutputManifest {
+        const file = join(outDir, MANIFEST);
+        if (!existsSync(file)) {
+            throw new CellError({ code: 'CELL_OUTPUT_NOT_FOUND', message: `No build output in ${outDir}.`, file, hint: 'Run `cell build` first.' });
+        }
+        return JSON.parse(readFileSync(file, 'utf8')) as OutputManifest;
+    }
+
+    /** Runs `preset.output` on a fresh build; files it writes are listed in `manifest.files`. */
+    export async function write(preset: Preset, options: PresetOutputOptions): Promise<OutputManifest> {
+        const manifest = read(options.outDir);
+        if (!preset.output) {
+            return manifest;
+        }
+        const files = new Set(manifest.files ?? []);
+        await preset.output({
+            ...options,
+            options: options.options ?? {},
+            manifest,
+            write: (path, content, mode) => {
+                const file = join(options.outDir, path);
+                mkdirSync(dirname(file), { recursive: true });
+                writeFileSync(file, content);
+                if (mode !== undefined) {
+                    chmodSync(file, mode);
+                }
+                files.add(path.replace(/\\/g, '/'));
+            },
+        });
+        if (files.size > 0) {
+            manifest.files = [...files].sort();
+        }
+        writeFileSync(join(options.outDir, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+        return manifest;
+    }
+}

package/src/preset/preset-registry.ts

@@ -0,0 +1,65 @@
+import { CellError, type Preset } from '@celljs/kit';
+import type { PresetDetector } from '../config/config-resolver.js';
+import { TextUtil } from '../utils/text-util.js';
+
+/** Presets by name. Built-in ones are registered first; toolchain modules may add more. */
+export class PresetRegistry {
+    protected readonly presets = new Map<string, Preset>();
+
+    register(preset: Preset): this {
+        if (this.presets.has(preset.name)) {
+            throw new CellError({
+                code: 'CELL_PRESET_DUPLICATE',
+                message: `Preset '${preset.name}' is registered twice.`,
+                hint: 'Give the preset another name, or extend the existing one with `extends`.',
+            });
+        }
+        this.presets.set(preset.name, preset);
+        return this;
+    }
+
+    get names(): string[] {
+        return [...this.presets.keys()];
+    }
+
+    /** Every registered preset, as registered (without its `extends` chain). */
+    get all(): Preset[] {
+        return [...this.presets.values()];
+    }
+
+    /** Presets that recognise a CI platform, for {@link ConfigResolver}. */
+    get detectors(): PresetDetector[] {
+        return [...this.presets.values()].flatMap(({ name, detect }) => (detect ? [{ name, detect }] : []));
+    }
+
+    /** The preset with the fields of its `extends` chain filled in. */
+    resolve(name: string, file?: string): Preset {
+        const chain: Preset[] = [];
+        for (let current: string | undefined = name; current !== undefined; current = chain[chain.length - 1].extends) {
+            const preset = this.presets.get(current);
+            if (!preset) {
+                throw this.notFound(current, file);
+            }
+            if (chain.includes(preset)) {
+                throw new CellError({
+                    code: 'CELL_PRESET_CYCLE',
+                    message: `Preset '${name}' extends itself: ${[...chain.map(p => p.name), current].join(' → ')}.`,
+                    hint: 'Remove the cycle from the `extends` fields.',
+                });
+            }
+            chain.push(preset);
+        }
+        const { detect: _detect, extends: _extends, ...merged } = Object.assign({}, ...chain.reverse()) as Preset;
+        return { ...merged, name };
+    }
+
+    protected notFound(name: string, file?: string): CellError {
+        const suggestion = TextUtil.closest(name, this.names);
+        return new CellError({
+            code: 'CELL_PRESET_NOT_FOUND',
+            message: `Unknown preset '${name}'. Available: ${this.names.join(', ')}.`,
+            file,
+            hint: suggestion ? `Did you mean '${suggestion}'?` : 'Use one of the available presets, or add the module that provides it.',
+        });
+    }
+}