# Cell 4.8.0

> Every page of https://cell.cellbang.com in one file. Error codes: https://cell.cellbang.com/errors/

<!-- https://cell.cellbang.com/guide (README.md) -->

# Introduction

Cell is a **serverless-first**, **component-based**, **platform-independent** application framework for TypeScript. You write plain classes with dependency injection; Cell turns them into a full-stack application, bundles the backend into a single file, and ships the same code to a Node.js server, a container, a single executable, Cloudflare Workers, AWS Lambda, Alibaba Cloud Function Compute, Tencent Cloud SCF or Vercel.

**Cell 4** rebuilds the toolchain on Vite 8 and treats coding agents as first-class users: every command speaks JSON, every error carries a code and a fix, and every project ships with an `AGENTS.md` and an MCP server.

## Why Cell

- **One codebase, every runtime**: Pick a preset at build time: `node`, `cli`, `cloudflare`, `fc`, `scf`, `lambda`, `vercel`. No platform SDK in your code, no rewrite when you move.
- **Single-file output**: The backend is one dependency-inlined `index.mjs`. Add `--single` to embed the frontend as well, or `--compile` for a standalone executable (Bun, Deno or Node.js SEA).
- **Agent-first toolchain**: `--json` on every command, structured `CellError` codes with hints, `cell check` for types and DI wiring, version-matched docs, and MCP tools for both the project and the running dev server.
- **Enterprise-grade architecture**: Dependency injection and AOP (`@Component`, `@Autowired`, `@Value`, `@Aspect`), MVC, RPC, declarative transactions, security, JWT and OAuth2.
- **Full stack in one process**: Backend MVC plus React, served on one port in development with frontend HMR and backend hot reload.
- **AI native**: Provider-neutral chat models, prompts and streaming; agents and [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) coding agent sessions whose tools are your own services.
- **Zero configuration**: Sensible defaults everywhere. Override only what you need in `cell.yml`, `cell.config.ts` or `CELL_*` environment variables.
- **Minimal footprint**: The toolchain depends on little more than Vite; cloud deployers sign their own requests instead of pulling in vendor SDKs.

## Quick Start

Developing and building need Node.js `^20.19.0 || >=22.12.0` (Vite 8). The built application runs on Node.js 18 or later, Bun 1.2 or later and Deno 2: CI starts the builds of the examples with each of them.

```bash
npx @celljs/cli init backend my-app     # or: fullstack (React + backend over RPC)
cd my-app
npm install
npx cell dev                            # http://127.0.0.1:3000, hot reload on save
```

A complete backend is a configuration file and a class:

```yaml
# cell.yml
app:
  greeting: Hello from my-app
```

```typescript
// src/node/home-controller.ts
import { Value } from '@celljs/core';
import { Controller, Get, Text } from '@celljs/mvc/lib/node';

@Controller()
export class HomeController {
    @Value('app.greeting')
    protected readonly greeting: string;

    @Get()
    @Text()
    home(): string {
        return this.greeting;
    }
}
```

Test it in-process, without opening a port:

```typescript
import { createTestApp } from '@celljs/cli';

const app = await createTestApp({ root: process.cwd() });
const res = await app.fetch('/');          // 200 "Hello from my-app"
await app.close();
```

The everyday commands:

| Command | What it does |
| --- | --- |
| `cell dev` | One port for frontend and backend; HMR for the UI, hot reload for the server, automatic restart on config changes |
| `cell build` | Production build into `.cell/output` (`--single`, `--compile`, `--preset <name>`) |
| `cell preview` | Run the build output exactly as the target platform would |
| `cell deploy` | Build and publish with the preset's deployer; `--dry-run` prints the plan |
| `cell check` | Configuration, TypeScript types, decorator settings and DI bindings in one pass |
| `cell info` | Everything Cell resolved: preset, modes, components, DI modules, hooks, output state |
| `cell config get <key> --why` | The merged value of a setting and every file or variable that set it |

## Deploy Anywhere

Your code stays the same; the preset decides the shape of the output and how it is deployed.

| Preset | Output | Deploy |
| --- | --- | --- |
| `node` (default) | Node.js HTTP server, one `index.mjs` | Anywhere Node.js runs: VM, container, PaaS |
| `cli` | Command-line program on Cell DI | Distribute as a file or an executable |
| `cloudflare` | Worker + static assets + `wrangler.json` | `cell deploy --preset cloudflare` |
| `fc` | Alibaba Cloud Function Compute (custom runtime) | `cell deploy --preset fc` |
| `scf` | Tencent Cloud SCF web function | `cell deploy --preset scf` |
| `lambda` | AWS Lambda (Function URL / API Gateway) | `cell deploy --preset lambda` |
| `vercel` | Vercel Build Output API (`.vercel/output`) | `cell deploy --preset vercel` |

```bash
cell build --single                      # the whole full-stack app in one file: node index.mjs
cell build --compile                     # a standalone executable, no Node.js required on the host
cell deploy --preset cloudflare --dry-run
```

## Built for Coding Agents

Cell assumes the next developer on your project may be an AI agent, and makes the framework something an agent can use correctly on the first try ([design principles](https://github.com/cellbang/cell/blob/main/docs/design/agent-first.md)).

- **Machine-readable everything**: `--json` on every command returns exactly one JSON result; errors are `CellError`s with a stable `code`, a location and a `hint`.
- **Context, not guesswork**: `cell init` writes `AGENTS.md`, a Cell skill and `.mcp.json`; `cell agent sync` keeps them matched to the installed versions; `cell docs <query>` searches the docs shipped with your exact dependencies.
- **MCP built in**: `cell mcp` exposes `info`, `check`, `config_get`, `docs_search`, `build` and `deploy_plan`; `cell dev` serves `/_cell/mcp` with routes, DI bindings, resolved config, recent requests, logs and errors of the running app.
- **Fast feedback**: `cell check` catches type errors, missing decorator settings and broken DI bindings before anything runs; `createTestApp()` gives in-process integration tests.

```jsonc
// .mcp.json (Claude Code, Cursor, CodeBuddy, ...)
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }
```

## AI Native

```typescript
import { Component, Autowired } from '@celljs/core';
import { ChatModel, ProxyChatModel, PromptTemplate } from '@celljs/ai-core';

@Component()
export class Assistant {
    @Autowired(ProxyChatModel)
    protected chatModel: ChatModel;

    @Autowired(PromptTemplate)
    protected promptTemplate: PromptTemplate;

    async ask(question: string): Promise<string> {
        const prompt = await this.promptTemplate.create('Answer briefly: {question}', {
            variables: { question },
            // pi:<provider>/<model id>, routed by ProxyChatModel to @celljs/ai-pi
            chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' }
        });
        const response = await this.chatModel.call(prompt);
        return response.result.output.content;
    }
}
```

- **Models**: `@celljs/ai-pi` connects 20+ providers (Anthropic, OpenAI, Google, DeepSeek, Ollama and other OpenAI-compatible endpoints) behind the `@celljs/ai-core` `ChatModel` API (`pi:<provider>/<model>`).
- **Agents**: `@celljs/ai-agent` builds tool-using agents whose tools are ordinary Cell components; events stream over SSE.
- **Coding agents**: `@celljs/ai-coding-agent` hosts pi coding agent sessions inside your application, managed by DI.
- **Terminal UIs**: `@celljs/tui` turns an agent into an interactive command-line chat (see [`examples/tui-app`](https://github.com/cellbang/cell/tree/main/examples/tui-app)).

## More Examples

<details>
<summary><strong>Dependency injection</strong></summary>

```typescript
import { Component, Autowired, Value } from '@celljs/core';

@Component()
export class A {}

@Component()
export class B {
    @Autowired()
    protected a: A;                  // class injection
}

@Component()
export class C {
    @Value('foo')                    // configuration injection: 'obj.xxx', 'arr[1]', ...
    protected foo: string;
}
```

</details>

<details>
<summary><strong>Database access with declarative transactions</strong></summary>

```typescript
import { Controller, Get, Param, Delete, Put, Post, Body } from '@celljs/mvc/lib/node';
import { Transactional, OrmContext } from '@celljs/typeorm/lib/node';
import { User } from './entity';

@Controller('users')
export class UserController {

    @Get()
    @Transactional({ readOnly: true })
    list(): Promise<User[]> {
        return OrmContext.getRepository(User).find();
    }

    @Get(':id')
    @Transactional({ readOnly: true })
    get(@Param('id') id: number): Promise<User | null> {
        return OrmContext.getRepository(User).findOneBy({ id });
    }

    @Post()
    @Transactional()
    create(@Body() user: User): Promise<User> {
        return OrmContext.getRepository(User).save(user);
    }

    @Put()
    @Transactional()
    async modify(@Body() user: User): Promise<void> {
        await OrmContext.getRepository(User).update(user.id, user);
    }

    @Delete(':id')
    @Transactional()
    async remove(@Param('id') id: number): Promise<void> {
        await OrmContext.getRepository(User).delete(id);
    }
}
```

</details>

<details>
<summary><strong>RPC between frontend, backend and services</strong></summary>

```typescript
// Shared contract
export const UserService = 'UserService';
export interface UserService {
    hello(name: string): Promise<string>;
}

// Provider
import { Rpc } from '@celljs/rpc';

@Rpc(UserService)
export class UserServiceImpl implements UserService {
    async hello(name: string): Promise<string> {
        return `Hello, ${name}`;
    }
}

// Consumer: a typed remote proxy is injected
import { Component } from '@celljs/core';
import { Autorpc } from '@celljs/rpc';

@Component()
export class Greeter {
    @Autorpc(UserService)
    protected userService: UserService;
}
```

</details>

Runnable applications live in [`examples/`](https://github.com/cellbang/cell/tree/main/examples): `backend-app`, `sample-app` (React), `security-app`, `jwt-app`, `grpc-app`, `schedule`, `prisma-app`, `docker-app`, `standalone-app`, `mycli`, `tui-app`, `coding-agent-app` and `openapi-app`.

## Ecosystem

All packages are published under the [`@celljs`](https://www.npmjs.com/org/celljs) scope as dual CommonJS / ES module builds.

| Area | Packages |
| --- | --- |
| Core ([`packages/`](https://github.com/cellbang/cell/tree/main/packages)) | `core`, `logger`, `web`, `mvc`, `http`, `express-adapter`, `serve-static`, `rpc`, `typeorm`, `cache`, `retry`, `schedule`, `cqrs`, `grpc`, `security`, `jwt`, `oauth2-core`, `oauth2-client`, `oauth2-jose`, `validation`, `openapi`, `wechat-pay`, `alipay`, `stripe` |
| Cloud ([`cloud-packages/`](https://github.com/cellbang/cell/tree/main/cloud-packages)) | `cloud`, `faas-adapter`, `lambda-adapter`, `fc-adapter`, `scf-adapter`, `vercel-adapter`, `oss`, `cos` |
| AI ([`ai-packages/`](https://github.com/cellbang/cell/tree/main/ai-packages)) | `ai-core`, `ai-pi`, `ai-agent`, `ai-coding-agent` |
| UI ([`ui-packages/`](https://github.com/cellbang/cell/tree/main/ui-packages)) | `react`, `widget`, `tui` |
| Toolchain ([`dev-packages/`](https://github.com/cellbang/cell/tree/main/dev-packages)) | `cli`, `vite`, `kit` |
| Ta ([`apps/ta`](https://github.com/cellbang/cell/tree/main/apps/ta), [`ta-packages/`](https://github.com/cellbang/cell/tree/main/ta-packages)) | [Ta](https://cell.cellbang.com/ta), a coding agent built on Cell and pi (`npm i -g @celljs/ta`): the `ta` command, `ta serve` with its web client, desktop and mobile apps |

## Documentation

The docs site is **https://cell.cellbang.com** (English and Chinese), with a page for every error code.

- Guides: [getting started](https://cell.cellbang.com/guide/getting-started), [project structure and configuration](https://cell.cellbang.com/guide/project), [components and dependency injection](https://cell.cellbang.com/guide/components), [HTTP APIs](https://cell.cellbang.com/guide/web), [frontend and RPC](https://cell.cellbang.com/guide/frontend), [testing](https://cell.cellbang.com/guide/testing), [building and deploying](https://cell.cellbang.com/guide/deployment), [working with coding agents](https://cell.cellbang.com/guide/coding-agents), [package catalog](https://cell.cellbang.com/guide/packages)
- For agents: [`llms.txt`](https://cell.cellbang.com/llms.txt) and [`llms-full.txt`](https://cell.cellbang.com/llms-full.txt) (every page in one file); inside a project, `npx cell docs <words>` searches the docs of the installed versions
- [`cell` CLI reference](https://cell.cellbang.com/cli): commands, presets, deployers, `cell.config.ts`
- [Migrating from Cell 3.x](https://cell.cellbang.com/migration-4) (Cell 3.x remains available at tag `v3.9.0`)
- Design: [architecture](https://github.com/cellbang/cell/blob/main/docs/design/architecture.md), [modules](https://github.com/cellbang/cell/blob/main/docs/design/modules.md), [agent-first principles](https://github.com/cellbang/cell/blob/main/docs/design/agent-first.md)
- [API reference](https://cell.cellbang.com/api/), generated with TypeDoc
- [Ta](https://cell.cellbang.com/ta): the coding agent built on Cell, with a page for each of its packages
- [Changelog](https://github.com/cellbang/cell/blob/main/CHANGELOG.md)

## Contributing

Issues and pull requests are welcome. The repository is a Bun workspace monorepo built with Turborepo and TypeScript 7.

Prerequisites: [Bun](https://bun.sh) (version pinned in `package.json` → `packageManager`) and Node.js `^20.19.0 || >=22.12.0`.

```bash
bun install                                   # install dependencies and sync tsconfig references
bun run build                                 # build all packages
bun run test                                  # run all tests
bunx turbo run test --filter=@celljs/core     # test one package
bun run lint                                  # Biome (bun run format to fix)
bun changeset                                 # describe your change for the next release
```

## Activity

![Repobeats analytics](https://repobeats.axiom.co/api/embed/59b39c98717cf1ae18b57f24d2efe91617e3a6f1.svg "Repobeats analytics image")

## License

[MIT](https://github.com/cellbang/cell/tree/main/LICENSE)

<!-- https://cell.cellbang.com/guide/getting-started (dev-packages/cli/docs/getting-started.md) -->

# Getting started

This page takes you from an empty directory to a tested, built and deployable Cell backend. It assumes Node.js `^20.19.0 || >=22.12.0` for development; the built application runs on Node.js 18 or later, Bun 1.2 or later and Deno 2.

## Create a project

```bash
npx @celljs/cli init backend my-app      # or: fullstack (React frontend + backend over RPC)
cd my-app
npm install
npx cell dev                             # http://127.0.0.1:3000, reloads on save
```

`cell init` never asks questions. Without a template name it lists the templates; a non-empty directory needs `--force`. The project it writes:

```text
my-app/
├── cell.yml                  # application configuration, read with @Value
├── package.json              # scripts: dev, build, preview, check, test
├── tsconfig.json             # experimentalDecorators + emitDecoratorMetadata
├── src/node/
│   ├── module.ts             # the backend DI module: imports every file with components
│   └── home-controller.ts
├── test/app.spec.ts          # bun test + createTestApp()
├── AGENTS.md, CLAUDE.md      # guide for coding agents, matched to the installed version
├── .agents/skills/cell/      # the same guide as an agent skill
└── .mcp.json                 # `npx cell mcp` for agents that speak MCP
```

## Add an endpoint

Create a controller, then import its file from `src/node/module.ts`. **A file that no module imports is not loaded**, so its components do not exist.

```ts
// src/node/todo-controller.ts
import { Body, Controller, Delete, Get, Param, Post } from '@celljs/mvc/lib/node';
import { NotFoundError } from '@celljs/web/lib/node';

interface Todo { id: number; title: string }

@Controller('todos')
export class TodoController {
    protected readonly todos = new Map<number, Todo>();
    protected nextId = 1;

    @Get()
    list(): Todo[] {
        return [...this.todos.values()];
    }

    @Get(':id')
    get(@Param('id') id: number): Todo {
        const todo = this.todos.get(id);
        if (!todo) {
            throw new NotFoundError(`No todo ${id}`);     // 404
        }
        return todo;                                       // objects are sent as JSON
    }

    @Post()
    create(@Body('title') title: string): Todo {
        const todo = { id: this.nextId++, title };
        this.todos.set(todo.id, todo);
        return todo;
    }

    @Delete(':id')
    remove(@Param('id') id: number): void {
        this.todos.delete(id);
    }
}
```

```ts
// src/node/module.ts
import './home-controller';
import './todo-controller';
import { autoBind } from '@celljs/core';

export default autoBind();
```

`@celljs/web` is a dependency of `@celljs/mvc`; add it to `package.json` too when you import from it (`npm install @celljs/web`).

```bash
curl -X POST localhost:3000/todos -H 'content-type: application/json' -d '{"title":"write docs"}'
curl localhost:3000/todos/1
```

Move the state into a service when it grows: see [Components and dependency injection](https://cell.cellbang.com/guide/components). The controller decorators are listed in [HTTP APIs](https://cell.cellbang.com/guide/web).

## Configure it

`cell.yml` holds the application configuration: keys of the components (`server.port`, ...) at the top level, your own under `app`. Configuration is server-only; only `app.public` and keys components mark public reach the browser:

```yaml
app:
  greeting: Hello from my-app
  todos:
    max: ${(env.TODOS_MAX ?? 100) * 1}   # evaluated when the server starts; keys under app have no schema type, * 1 makes the env text a number
```

```ts
@Value('app.todos.max')
protected readonly max: number;
```

`npx cell config get app.todos.max --why` shows the merged value and every file or variable that set it. More in [Project structure and configuration](https://cell.cellbang.com/guide/project).

## Check and test

```bash
npx cell check        # TypeScript, configuration, decorator settings, DI bindings
bun test              # the tests under test/
```

```ts
// test/todo.spec.ts
import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
import { join } from 'node:path';
import { createTestApp, type TestApp } from '@celljs/cli';

describe('todos', () => {
    let app: TestApp;
    beforeAll(async () => { app = await createTestApp({ root: join(__dirname, '..') }); }, 60000);
    afterAll(() => app?.close());

    it('creates a todo', async () => {
        const res = await app.fetch('/todos', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{"title":"a"}' });
        expect(await res.json()).toEqual({ id: 1, title: 'a' });
    });
});
```

`createTestApp()` starts the whole application inside the test process without opening a port. See [Testing](https://cell.cellbang.com/guide/testing).

## Build and run

```bash
npx cell build                 # .cell/output/server/index.mjs: one file with every dependency inlined
npx cell preview               # runs the output as production would
node .cell/output/server/index.mjs
```

`--single` puts the frontend into the same file, `--compile` makes an executable that needs no Node.js on the host.

## Deploy

```bash
npx cell deploy --preset cloudflare --dry-run   # the plan, nothing is uploaded
npx cell deploy --preset cloudflare
```

The presets are `node` (default), `cli`, `cloudflare`, `fc`, `scf`, `lambda` and `vercel`. See [Building and deploying](https://cell.cellbang.com/guide/deployment).

## Next

- [Package catalog](https://cell.cellbang.com/guide/packages): which `@celljs/*` package to add for databases, caching, scheduled jobs, security, AI and more.
- [Working with coding agents](https://cell.cellbang.com/guide/coding-agents): the AGENTS.md, skill and MCP tools that `cell init` set up.

<!-- https://cell.cellbang.com/guide/project (dev-packages/cli/docs/project.md) -->

# Project structure and configuration

## Layout

A Cell project is an npm package. Its source follows a few conventions; nothing has to be registered elsewhere.

| Path | What |
| --- | --- |
| `src/node/` | Backend code: controllers, services, middleware |
| `src/browser/` | Frontend code (when the project has a frontend) |
| `src/common/` | Code both sides import, such as RPC interfaces |
| `src/node/module.ts` | The backend DI module |
| `src/browser/module.ts` | The frontend DI module |
| `cell.yml`, `cell.<mode>.yml` | Application configuration |
| `cell.config.ts` (optional) | Toolchain configuration |
| `.cell/` | Generated: `generated/` (DI wiring, merged configuration) and `output/` (the build); add it to `.gitignore` |

### DI modules

A DI module is a file that imports the files declaring components and exports `autoBind()`:

```ts
// src/node/module.ts
import './todo-controller';
import './todo-service';
import { autoBind } from '@celljs/core';

export default autoBind();
```

`autoBind()` registers every class decorated so far (`@Component`, `@Controller`, `@Rpc`, ...). **A file that no module imports is never loaded**: if `cell check` reports `CELL_DI_NO_BINDING` for a class you wrote, import its file here.

The toolchain looks for these module files of the project, in this order, and loads the ones that exist:

| Target | Files (under `src/`, extension `.ts`, `.tsx`, `.js` or `.mjs`) |
| --- | --- |
| backend | `common/module`, `node/backend-module`, `node/module`, `module`, `backend-module` |
| frontend | `common/module`, `browser/frontend-module`, `browser/module`, `module`, `frontend-module` |

`src/common/module` and `src/module` are loaded on both sides. A package can declare other paths in the `cell.modules` field of its `package.json`.

### Components

Every dependency whose `package.json` has a `cell` field is a **component**: installing it adds its DI modules and its `cell.yml` to the application. Installing `@celljs/security` turns on login, installing `@celljs/serve-static` serves the frontend. To leave out a component that a dependency brings in, list it in `cell.config.ts`:

```ts
export default defineConfig({ modules: ['!@celljs/serve-static'] });
```

`npx cell info` lists the components, their DI modules, the entry and the preset Cell resolved; `--json` gives the same as data.

## Application configuration: `cell.yml`

```yaml
# yaml-language-server: $schema=./.cell/schema/cell.yml.json
server:
  port: ${env.PORT ?? 8080}      # keys of the components are at the top level
typeorm:
  ormConfig:
    - type: mysql
      password: ${env.DB_PASSWORD}
app:                              # your own configuration goes under app
  greeting: Hello
  public:                         # only app.public reaches the browser
    apiBase: /api
```

- Top-level keys are configuration keys; there is no `cell:`, `frontend:` or `backend:` level. Read them with `@Value('server.port')`, `@Value('app.greeting')` on a property or constructor parameter.
- **Every top-level key has an owner**: a component declares the keys it owns in its `cell.schema.json` (`server` belongs to `@celljs/web`, `security` to `@celljs/security`...). Writing under them overrides the component's defaults.
- **Your own configuration goes under `app`**, which no component takes, so an upgrade never collides with it.
- Mistakes are errors: a top-level key nobody owns, an option a component does not have, a wrong type — `cell build`, `cell dev` and `cell check` report `CELL_CONFIG_INVALID` with the file, the line and a "did you mean".
- `cell dev`, `cell build` and `cell check` write `.cell/schema/cell.yml.json`; with the `yaml-language-server` comment above as the first line of `cell.yml`, editors (the YAML extension of VS Code, ...) complete and check it.

### What the frontend sees

**Configuration is server-only by default.** The browser only receives the keys components mark public (such as `server.path`, `rpc`, `react`, the page redirects of `security`) and `app.public`. A secret never reaches the frontend bundle unless you put it under `app.public`.

- Frontend values are evaluated at build time; their expressions may refer to server keys, only the results ship.
- `npx cell config get <key> --target frontend` shows what the frontend gets; a server-only key is reported as such.
- A project may have its own `cell.schema.json` describing the keys under `app` (types, descriptions, `"x-cell-public": true`).

### Merge order

The files merge in this order: the `cell.yml` of every component (in dependency order), the project's `cell.yml`, then `cell.<mode>.yml` for each active mode. Later files win; objects merge deeply, arrays are replaced.

### Modes

| Command | Mode |
| --- | --- |
| `cell dev` | `development` |
| `cell build` | `production` |
| `createTestApp()` | `test` |

Add more with `-m <mode>` (repeatable): `cell build -m staging` also reads `cell.staging.yml`. A mode without any file is reported by `cell check` (`CELL_MODE_UNKNOWN`).

### Expressions

`${...}` is evaluated against the configuration itself plus `env` (the process environment):

```yaml
server:
  endpoint: http://localhost:${server.port}     # another key
cloud:
  region: ${env.REGION ?? 'eu-west-1'}          # environment variable with a default
typeorm:
  ormConfig:
    - port: ${env.DB_PORT ?? 5432}              # the schema says integer: DB_PORT=6543 gives the number 6543
      synchronize: ${env.DB_SYNC ?? false}      # the schema says boolean: true or false only
```

- Defaults use `??`, as in JavaScript; **an empty environment variable counts as unset**. Values need no quotes.
- **Schema types convert**: when a key is a number or a boolean, the text an expression gives is converted, and a value that does not convert is an error naming the key. Keys without a schema (those under `app`) keep the type of the result.
- **Backend values are evaluated when the server starts**, so one build runs in every environment and secrets are not baked into it. Frontend values are evaluated at build time.
- An expression inside other text gives a string; the result of an expression is never evaluated again, even when an environment variable contains `${...}`.

### Environment variables

Override any existing key without editing files, with a variable starting with `CELL_`:

```bash
CELL_SERVER__PORT=8080 node .cell/output/server/index.mjs   # server.port, applied at startup
CELL_SERVER__HOST=0.0.0.0                                    # listen on all interfaces (containers)
CELL_APP__PUBLIC__API_BASE=https://api.example.com npx cell build   # app.public.apiBase of the frontend, at build time
```

- One underscore after the prefix, `__` between levels (`CELL_SERVER__PORT`). `CELL_PRESET`, `CELL_MODE`, `CELL_EVENT`, `CELL_OUT_DIR` and `CELL_DEBUG` belong to the toolchain and are never configuration; a one-segment variable that is no top-level key (another tool's `CELL_REGION`) is left alone; a name with `__` that matches no key is reported, with the right spelling for the earlier `CELL__…` / `CELL_BACKEND__…`.
- `__` separates levels, matched ignoring case, `_` and `-` (`ORM_CONFIG` matches `ormConfig`); array items by index.
- The same variables apply to both sides: the server applies them at startup; `cell build` applies them, then picks the public keys for the frontend.
- Only existing keys can be overridden; give a new key a default in `cell.yml` first.
- Values convert to the type of the value (or the schema): numbers, booleans, JSON for objects and arrays. A value that is one `${...}` is kept and evaluated: `CELL_SERVER__PORT='${env.PORT}'`.
- A variable that matches no key or does not fit its type is ignored with a warning; `cell check` and `cell info` report it.

### Where a value comes from

```bash
npx cell config get server.port --why
# server.port (backend) = 8080
#   server-only, owned by @celljs/web
#   Port the server listens on. Override with CELL_SERVER__PORT.
#   node_modules/@celljs/web/cell.yml: 3000
#   cell.yml: 8080
```

Common keys of the framework:

| Key | Default | Package |
| --- | --- | --- |
| `server.port` / `server.host` | `3000` / `127.0.0.1` | `@celljs/web` |
| `server.path` | `/` | `@celljs/web` (prefix of every route; public) |
| `web.body.limit` | `100kb` | `@celljs/web` |
| `web.cors` | any origin (`*`) | `@celljs/web` |
| `web.session` / `web.cookies` | see the README of `@celljs/web` | `@celljs/web` |
| `html.title` / `html.rootId` | `Cell Framework` / `cell-root` | `@celljs/core` (the generated HTML page) |
| `logger.level` | `info` | `@celljs/core` |
| `rpc.path` | `api` | `@celljs/rpc` |
| `serveStatic.spa` | `true` | `@celljs/serve-static` |

Each package's README lists its keys; every key with its type and description is in `.cell/schema/cell.yml.json`.

## Toolchain configuration: `cell.config.ts`

Optional, and only for the toolchain. Application configuration never goes here.

```ts
import { defineConfig } from '@celljs/cli';

export default defineConfig({
    preset: 'cloudflare',                          // default: node
    modules: ['!@celljs/serve-static'],            // remove a component
    build: { external: ['sharp'], sourcemap: true },
    vite: { resolve: { alias: { '~': '/src' } } }, // merged into the Vite configuration
    hooks: { 'build:before': 'prisma generate' },  // shell commands on toolchain events
    fc: { region: 'cn-shanghai', memory: 512 },    // options of a preset, under its name
});
```

Unknown fields are reported with the closest valid name (`CELL_CONFIG_INVALID`, `CELL_CONFIG_UNKNOWN_OPTION`). The full reference, including toolchain modules that add Vite plugins, checks, MCP tools or output files, is the [CLI reference](https://cell.cellbang.com/cli).

## Generated files

`cell dev` and `cell build` write the code they generate to `.cell/generated/`: the DI modules each target loads, the merged configuration and the project model. Read them when you need to know exactly what the container contains; never edit them.

<!-- https://cell.cellbang.com/guide/components (dev-packages/cli/docs/components.md) -->

# Components and dependency injection

Every part of a Cell application is a **component**: a class the DI container creates, wires and keeps. Controllers, services, middleware and RPC services are all components. Cell's container is its own (`@celljs/core`), with no third-party IoC library.

## Declaring and injecting

```ts
import { Autowired, Component, Value } from '@celljs/core';

@Component()
export class TodoRepository {
    protected readonly todos: string[] = [];
    add(title: string) { this.todos.push(title); }
    all() { return [...this.todos]; }
}

@Component()
export class TodoService {
    @Autowired()                         // by the declared type
    protected readonly repository: TodoRepository;

    @Value('app.todos.max')             // configuration, see cell.yml
    protected readonly max: number;

    add(title: string) {
        if (this.repository.all().length >= this.max) {
            throw new Error('Too many todos');
        }
        this.repository.add(title);
    }
}
```

- Components are **singletons** by default: one instance per application. `@Component({ scope: Scope.Transient })` makes a new one for every injection.
- Inject into properties (above) or constructor parameters (`constructor(@Autowired(TodoRepository) protected readonly repository: TodoRepository)`). Constructor parameters without a decorator are injected by their declared class.
- The file must be imported by a [DI module](https://cell.cellbang.com/guide/project#di-modules), or the class is never registered.
- `@Value('key')` reads the merged `cell.yml`; `@Value()` without a key uses the property name.

## Interfaces: a Symbol with the same name

TypeScript interfaces do not exist at runtime, so the identifier of an interface is a `Symbol` exported under the same name. This is the convention throughout Cell:

```ts
// src/common/mailer.ts
export const Mailer = Symbol('Mailer');

export interface Mailer {
    send(to: string, text: string): Promise<void>;
}
```

```ts
// src/node/mailer-impl.ts
import { Component } from '@celljs/core';
import { Mailer } from '../common/mailer';

@Component(Mailer)
export class MailerImpl implements Mailer {
    async send(to: string, text: string): Promise<void> { /* ... */ }
}

// elsewhere
@Autowired(Mailer)
protected readonly mailer: Mailer;
```

`@Component(Mailer)` registers the class under the symbol **and** under the class itself; both give the same instance. `@Component({ id: [A, B] })` registers more identifiers.

## Several implementations

| Need | Write |
| --- | --- |
| All implementations | `@Autowired(Handler) protected readonly handlers: Handler[]` (an array type) |
| None is fine | add `@Optional()`: `undefined`, or `[]` for an array |
| Pick one by name | `@Component({ id: Store, name: 'redis' })` and `@Autowired(Store) @Named('redis')` |
| Pick one by tag | `@Component({ id: Store, tag: { tag: 'region', value: 'eu' } })` and `@Autowired(Store) @Tagged('region', 'eu')` |
| A default among several | `@Component({ id: Store, default: true })`: plain `@Autowired(Store)` gets it |
| Replace a framework component | `@Component({ id: ErrorHandler, rebind: true })`: removes the earlier bindings of that id |
| Many, sorted, created lazily | `@AutowiredProvider(Step) protected readonly steps: Provider<Step>`, then `this.steps.sortSync()` (highest `priority` first) |

Extension points of the framework (`Middleware`, `ErrorHandler`, `ApplicationLifecycle`, `HealthIndicator`, ...) are such multi-implementation symbols: you add an implementation by declaring `@Component(Middleware)` on your class, and `rebind: true` replaces the built-in one.

## Lifecycle

```ts
import { Application, ApplicationLifecycle, Component, PostConstruct } from '@celljs/core';

@Component(ApplicationLifecycle)
export class Warmup implements ApplicationLifecycle<Application> {
    initialize(): void { /* synchronous, before any onStart */ }
    async onStart(app: Application): Promise<void> { /* awaited one after another */ }
    onStop(app: Application): void { /* on shutdown and before every reload in cell dev */ }
}

@Component()
export class Cache {
    @PostConstruct()
    protected init(): void { /* after the properties are injected, once per instance */ }
}
```

An error thrown in `initialize`, `onStart` or `onStop` is logged and does not stop the other lifecycles. For work that must not run at module load (opening connections, timers), use `onStart`, not the constructor: `cell check` creates the components without starting the application.

## Logging

```ts
import { Autowired, Component, Logger } from '@celljs/core';

@Component()
export class TodoService {
    @Autowired(Logger)
    protected readonly logger: Logger;

    add(title: string) {
        this.logger.info(`added ${title}`);
    }
}
```

The level comes from `logger.level` (`verbose`, `debug`, `info` (default), `warn`, `error`). `@celljs/logger` replaces the console logger with winston.

## Aspects (AOP)

An aspect runs code around the methods of components created with `proxy: true` (controllers and RPC services are proxied by default):

```ts
import { Aspect, MethodBeforeAdvice } from '@celljs/core';

@Aspect({ id: MethodBeforeAdvice, pointcut: 'Audited' })
export class AuditAdvice implements MethodBeforeAdvice {
    async before(method: string | number | symbol, args: any[], target: any): Promise<void> {
        console.log('call', String(method), args);
    }
}

@Component({ proxy: true, sysTags: ['Audited'] })
export class AccountService { /* ... */ }
```

`AfterReturningAdvice` and `AfterThrowsAdvice` run after a method returns or throws. Without `pointcut` an advice applies to every proxied component. A proxied method always returns a Promise, also when it is synchronous. `aop.enabled: false` turns proxies off.

## Outside the container

There is no global container. A component that picks components at run time injects the container (`@Autowired(Container)`); code that is not a component (a script, a test) uses the container it created: `ApplicationFactory.createContainer(props, ...modules)` (`@celljs/core/lib/common/application/application-factory`) returns it, and [`createTestApp()`](https://cell.cellbang.com/guide/testing) has `app.get()`. A `{ detached: true }` property is read from the container that created the instance, so it only works on components.

## When wiring fails

The container reports wiring problems as structured errors, and `npx cell check` finds them without starting the application:

| Code | Meaning | Usual fix |
| --- | --- | --- |
| `CELL_DI_NO_BINDING` | Nothing is registered for an identifier | Import the file from a DI module; add `@Component(Id)`; install the package |
| `CELL_DI_AMBIGUOUS` | Several bindings match a single injection | Inject an array, or use `@Named` / `@Tagged` / `default: true`, or `rebind: true` |
| `CELL_DI_CIRCULAR` | Components need each other while being created | Get one side lazily (`@AutowiredProvider`, or `@Autowired({ detached: true })` on a property), or move the shared part into another component |
| `CELL_DI_MISSING_INJECT` | A constructor parameter has no identifier | Add `@Autowired(Id)` |

The message names the identifier, who needs it and the resolution chain. The [core reference](https://cell.cellbang.com/packages/core) covers every decorator in detail.

<!-- https://cell.cellbang.com/guide/web (dev-packages/cli/docs/web.md) -->

# HTTP APIs

HTTP in Cell is two packages: `@celljs/web` (server, middleware chain, body parsing, cookies, sessions, CORS, errors) and `@celljs/mvc` (controllers on top of it). Both run on Node's `node:http` with no third-party framework. Import the decorators from `@celljs/mvc/lib/node` and the request-level types from `@celljs/web/lib/node`.

## Controllers and routes

```ts
import { Body, Controller, Delete, Get, Param, Patch, Post, Query } from '@celljs/mvc/lib/node';

@Controller('users')                       // prefix: /users
export class UserController {
    @Get()                                 // GET /users?role=admin
    list(@Query('role') role?? string) { /* ... */ }

    @Get(':id')                            // GET /users/42
    get(@Param('id') id: number) { /* ... */ }

    @Post()
    create(@Body() user: CreateUser) { /* ... */ }

    @Patch(':id')
    rename(@Param('id') id: number, @Body('name') name: string) { /* ... */ }

    @Delete(':id')
    remove(@Param('id') id: number): void { /* ... */ }
}
```

- Method decorators: `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`, `@Head`, `@Options`, `@All` (every method). Without a path the method answers the controller path itself.
- Paths: `:name` is one segment, `*` matches anything, `(...)` is optional. `server.path` (default `/`) prefixes every route.
- A request no route matches gets `404`.
- Controllers are components: inject services with `@Autowired`, read configuration with `@Value`. Import the controller's file from `src/node/module.ts`.

## Parameters

| Decorator | Value |
| --- | --- |
| `@Param('id')` / `@Param()` | One path parameter / all of them |
| `@Query('q')` / `@Query()` | One query parameter / the parsed query (`?a[b]=1` → `{ a: { b: '1' } }`) |
| `@Body('name')` / `@Body()` | One field / the whole body |
| `@Header('x-api-key')` / `@Header()` | One request header / all headers |
| `@Cookie('sid')` | A request cookie |
| `@Session('cart')` | A value of the session |
| `@Req()` / `@Res()` | Node's request and response (`IncomingMessage` / `ServerResponse` with extras) |

Parameters typed `string`, `number`, `boolean` or `Date` are converted (`'42'` → `42`). The body is parsed from JSON, `text/plain`, `application/octet-stream` (a Buffer) or a URL-encoded form; gzip, deflate and br bodies are decompressed. Malformed JSON answers `400`, a body over `web.body.limit` (default `100kb`) answers `413`.

### Validating the body

Add `@celljs/validation` and `class-validator`, then type the parameter with a class:

```ts
import { IsString, Length } from 'class-validator';

export class CreateUser {
    @IsString()
    @Length(1, 20)
    name: string;
}

@Post()
create(@Body() user: CreateUser) { /* user is a CreateUser instance and is valid */ }
```

An invalid body answers `400` with the errors as JSON; the method is not called. Options are under `validation` ([@celljs/validation](https://cell.cellbang.com/packages/validation)).

## Responses

| Return / decorator | Response |
| --- | --- |
| an object, array, number, ... | JSON (`application/json`); the default view |
| `@Text()` and a string | `text/plain` |
| `@Html('page.mustache')` and an object | the Mustache template from `mvc.mustache.baseViewDir` (default `assets/views`) rendered with it |
| `@File()` and a Buffer or a stream | the bytes, streamed |
| `undefined` (`void`) | `200` with an empty body |
| `@Header('cache-control', 'no-store')` | adds a response header |
| `@Cookie('flavor', 'oat')` / `@Session('step', 'two')` | sets a cookie / a session value |

`async` methods work the same way. To choose the status code, take the response: `@Res() res: Response` (with `import type { Response } from '@celljs/web/lib/node'`: it is an interface) or `Context.getResponse()`, and set `res.statusCode = 201`, then return the body as usual.

## Errors

```ts
import { HttpError, NotFoundError } from '@celljs/web/lib/node';

throw new NotFoundError('No user 42');          // 404
throw new HttpError(409, 'Name already taken'); // any status
throw new Error('boom');                        // 500
```

The status comes from `HttpError.statusCode`; any other error answers `500`. Stack traces are never sent to the client: a `500` is logged with its stack (and its `cause`) at the error level, a 4xx `HttpError` (or an error a handler answered with a redirect or a 4xx) only at the debug level. The client gets the message of a 4xx `HttpError`; in production a 5xx or any other error answers only its status text, unless the `HttpError` was created with `{ expose: true }` or `web.errors.exposeMessages` is set.
**Per controller**, a method marked `@Catch(ErrorType)` handles the errors of that type thrown in the controller, and its return value is the response:

```ts
@Catch(QuotaError)
@Text()
onQuota(err: QuotaError) { return `Quota exceeded: ${err.message}`; }
```

**For the whole application**, add an `ErrorHandler`. Handlers are asked in order of `priority` (highest first) whether they `canHandle` the error; the first that can handles it, and if its `handle` throws, the next one is tried. The built-in handlers have priorities up to `2000`, so give yours more to run first:

```ts
import { Component } from '@celljs/core';
import { Context, ErrorHandler } from '@celljs/web/lib/node';

@Component(ErrorHandler)
export class QuotaErrorHandler implements ErrorHandler {
    readonly priority = 2100;

    async canHandle(ctx: Context, err: Error) { return err instanceof QuotaError; }

    async handle(ctx: Context, err: Error) {
        ctx.response.statusCode = 429;
        ctx.response.setHeader('content-type', 'application/json');
        ctx.response.end(JSON.stringify({ error: err.message }));
    }
}
```

## Middleware

A middleware is a component bound to `Middleware`. It sees every request before the controllers; higher `priority` runs earlier.

```ts
import { Component } from '@celljs/core';
import { Context, HTTP_MIDDLEWARE_PRIORITY, HttpError, Middleware } from '@celljs/web/lib/node';

@Component(Middleware)
export class ApiKeyMiddleware implements Middleware {
    readonly priority = HTTP_MIDDLEWARE_PRIORITY - 10;   // after trace, CORS and body parsing

    async handle(ctx: Context, next: () => Promise<void>): Promise<void> {
        if (ctx.request.path.startsWith('/admin') && ctx.request.get('x-api-key') !== process.env.API_KEY) {
            throw new HttpError(401, 'Missing or wrong API key');
        }
        await next();
    }
}
```

Middleware written for express that only needs Node's `req` / `res` can be wrapped with `convertExpressMiddleware(fn)`.

### The request context

Anywhere during a request, also in services far from the controller, `Context` from `@celljs/web/lib/node` gives the current request: `Context.getRequest()`, `Context.getResponse()`, `Context.getSession()`, `Context.getCookies()`, `Context.getTraceId()`, and request-scoped attributes with `Context.setAttr(key, value)` / `Context.getAttr(key)`. It follows `await`, timers and promise chains.

## Built in

| Feature | Configuration |
| --- | --- |
| Trace id: every response has an `X-Cell-Trace-ID` header (`Context.getTraceId()`) | `web.trace` |
| Health check: `GET /health` | `web.health` |
| CORS headers, every origin by default | `web.cors` (`origin`, `methods`, `credentials`, ...) |
| Signed cookies and sessions stored in a cookie | `web.cookies.keys`, `web.session`. **Set your own `web.cookies.keys` in production** |
| Request body limits | `web.body` |

The [@celljs/web reference](https://cell.cellbang.com/packages/web) has every option.

## More

| Need | Package |
| --- | --- |
| OpenAPI document (`/openapi.json`) and Swagger UI (`/api-docs`) from the controllers | [`@celljs/openapi`](https://cell.cellbang.com/packages/openapi) |
| Login, sessions, `@Authenticated()`, `@PreAuthorize()` | [`@celljs/security`](https://cell.cellbang.com/packages/security) |
| JSON Web Tokens | [`@celljs/jwt`](https://cell.cellbang.com/packages/jwt) |
| Serving the frontend build | [`@celljs/serve-static`](https://cell.cellbang.com/packages/serve-static) |
| Typed calls from the frontend or other services | [Frontend and RPC](https://cell.cellbang.com/guide/frontend) |
| gRPC services | [`@celljs/grpc`](https://cell.cellbang.com/packages/grpc) |

<!-- https://cell.cellbang.com/guide/frontend (dev-packages/cli/docs/frontend.md) -->

# Frontend and RPC

A Cell application can have a React frontend in the same project as its backend. `cell dev` serves both on one port (HMR for the frontend, hot reload for the backend), and `cell build` puts the frontend into `.cell/output/public/`, served by the backend through `@celljs/serve-static` or by the platform's CDN (Cloudflare, Vercel).

```bash
npx @celljs/cli init fullstack my-app
```

The fullstack template depends on `@celljs/react` (which adds the `frontend` build target), `@celljs/rpc` and `@celljs/serve-static`.

## Pages

Pages are the files of `src/browser/pages/`; the default export of each is the page component.

```text
src/browser/pages/
├── _layout.tsx        around every page below it
├── index.tsx          /
├── about.tsx          /about
└── users/
    ├── index.tsx      /users
    └── [id].tsx       /users/:id
```

```tsx
// src/browser/pages/users/[id].tsx
import { Link, useParams } from '@celljs/react';

export default function User() {
    const { id } = useParams();
    return <><h1>User {id}</h1><Link to="/users">All users</Link></>;
}
```

```tsx
// src/browser/pages/_layout.tsx
import { NavLink } from '@celljs/react';
import type { PropsWithChildren } from 'react';

export default function Layout({ children }: PropsWithChildren) {
    return <><nav><NavLink to="/">Home</NavLink> <NavLink to="/users">Users</NavLink></nav>{children}</>;
}
```

- `[...rest].tsx` matches the rest of the path: `pages/[...rest].tsx` is the page for unknown URLs.
- `_layout.tsx` gets the page as `children`. Layouts nest, outermost first, and stay mounted while the user moves between their pages; pages without one get the `@DefaultLayout`.
- A page that throws, or whose chunk does not load, shows an error inside its layout instead of blanking the application, and is tried again when the user goes to another path. The nearest `_error.tsx` (its directory or above) is what shows, with `{ error, reset }` as props (`ErrorFallbackProps` of `@celljs/react`); without one, a message and a button to try again.
- Files and directories whose name starts with `_`, and tests, are not pages: keep the components of a page next to it in `_components/`.
- Every page is a chunk of its own, loaded when it is visited. Two files for one path (`about.tsx` and `about/index.tsx`) fail with `CELL_ROUTE_CONFLICT`.
- No imports to add anywhere: `cell dev` picks up added and removed pages. The routes are generated into `.cell/generated/frontend/routes.js`, and `npx cell info --json` lists them (`frontend.routes`).

Routing is React Router 7. `@celljs/react` re-exports what pages need: `Link`, `NavLink`, `Navigate`, `Outlet`, `useParams`, `useNavigate`, `useLocation`, `useSearchParams`, `useMatch`. `react.router.type` in `cell.yml` chooses `browser` (default) or `hash` routing. `@App`, `@DefaultLayout` and `@Router` from `@celljs/react` replace the root component, the default layout and the router; a package adds pages with `@View` (see the reference).

`src/browser/module.ts` is the DI module of the frontend: it imports the files of your frontend services (see below).

The frontend gets the configuration keys components mark public and your `app.public`; they are evaluated at build time and visible to anyone. In the browser, read it with `useValue('html.title')` in a React component and `@Value` in a DI component.

## Services in components

Frontend services (state, API clients, anything shared) are DI components, as on the backend. React components get them, and configuration, with hooks from `@celljs/react`:

```tsx
import { useInject, useValue } from '@celljs/react';
import { UserService } from './user-service';             // @Component(UserService) in a file module.ts imports

function Header() {
    const userService = useInject<UserService>(UserService); // resolved once per component instance
    const title = useValue<string>('app.public.title', 'My app');
    return <header>{title}: {userService.name}</header>;
}
```

The shell provides the application's container through `ContainerContext`. To test a component, render it inside `<ContainerContext.Provider value={container}>` with a container of your own. Keep pages, layouts and contexts plain React components; what they use comes from the container.

`useRpc(id)` gives a backend service (next section) and `useLocale()` gives `[locale, setLocale]`: the language the user selected among `widget.locales`, kept in `localStorage`. For translated messages, install react-intl and import `@celljs/react/lib/browser/intl` once in `src/browser/module.ts`; `useIntl()` and `<FormattedMessage>` then follow the selected locale. The hooks are listed in the [README of @celljs/react](https://cell.cellbang.com/packages/react).

## Calling the backend: RPC

Instead of writing HTTP endpoints and fetch calls for your own frontend, share an interface and call it like a local object.

```ts
// src/common/greeting-protocol.ts: imported by both sides
export const GreetingServer = Symbol('GreetingServer');

export interface GreetingServer {
    greet(name: string): Promise<string>;
}
```

```ts
// src/node/greeting-server.ts: imported by src/node/module.ts
import { Rpc } from '@celljs/rpc';
import { GreetingServer } from '../common/greeting-protocol';

@Rpc(GreetingServer)
export class GreetingServerImpl implements GreetingServer {
    async greet(name: string): Promise<string> {
        return `Hello, ${name}!`;
    }
}
```

```tsx
// src/browser/pages/index.tsx
import { useRpc } from '@celljs/react';
import { GreetingServer } from '../../common/greeting-protocol';

export default function Home() {
    const greetingServer = useRpc<GreetingServer>(GreetingServer);
    const [message, setMessage] = React.useState('Loading…');
    React.useEffect(() => {
        greetingServer.greet('browser').then(setMessage);
    }, [greetingServer]);
    return <h1>{message}</h1>;
}
```

- `@Rpc(Id)` is a component (inject services into it as usual) and also an endpoint: JSON-RPC over HTTP `POST` at `/<rpc.path>/<Id>`, by default `/api/GreetingServer` (the description of the symbol).
- Every method returns a Promise; arguments and results travel as JSON (JSON-RPC 2.0). Only the methods the class declares can be called. An error thrown on the server rejects the promise in the caller: an `ApplicationError` as itself, others as an `RpcError` with `status`, whose message is hidden in production unless it is a 4xx `HttpError`.
- Parameters typed with a class are validated when `@celljs/validation` is installed, as for controllers.
- In tests, `app.get(GreetingServer)` from [`createTestApp()`](https://cell.cellbang.com/guide/testing) calls the implementation directly.

### The backend calls the frontend: WebSocket

```yaml
rpc:
  transport: websocket
```

Calls then go over one WebSocket connection per browser tab (`/<rpc.path>/ws`), through the same middlewares, session and security as over HTTP, and the backend can call the frontend back. Declare what the frontend offers with `@RpcClient` (an interface in `src/common/`, the class in `src/browser/`, imported by its module):

```ts
// src/browser/notice-client.ts
import { RpcClient } from '@celljs/rpc';
import { NoticeClient } from '../common/notice-protocol';

@RpcClient(NoticeClient)
export class NoticeClientImpl implements NoticeClient {
    async notify(text: string): Promise<void> {
        console.log(text);
    }
}
```

```ts
// in an @Rpc service of the backend
import { RpcContext } from '@celljs/rpc/lib/node';

const connection = RpcContext.requireConnection();          // the caller's tab
await connection.client<NoticeClient>(NoticeClient).notify('order shipped');
connection.onClose(() => { /* the tab went away */ });
```

`RpcConnectionManager` (`@celljs/rpc/lib/node`) lists every open connection, to notify all tabs. Where no connection can be made (the serverless presets, a proxy without WebSocket support) calls use HTTP, and `RpcContext.requireConnection()` throws `RpcNoConnectionError`. Pages of other origins cannot connect unless `rpc.websocket.allowedOrigins` lists them. The [reference](https://cell.cellbang.com/packages/rpc) has the other keys.

### From another backend

A backend calls a service of another Cell backend with an injected proxy:

```ts
import { Component } from '@celljs/core';
import { Autorpc } from '@celljs/rpc';

@Component()
export class Greeter {
    @Autorpc(GreetingServer)
    protected readonly greetingServer: GreetingServer;
}
```

```yaml
rpc:
  defaultEndpoint: "http://greetings.internal:3000{rpcPath}/{serviceIdentifier}"
  endpoint:                                    # per service, wins over defaultEndpoint
    GreetingServer: "${env.GREETING_URL}"
```

`RpcUtil.create<T>(endpoint, Id)` makes the same proxy without the container.

## Frontend-only and backend-only projects

The targets follow the installed components: `@celljs/react` adds `frontend`, and `backend` is always there. `targets` in `cell.config.ts` sets them explicitly.

The [@celljs/react reference](https://cell.cellbang.com/packages/react) lists the annotations and configuration keys.

<!-- https://cell.cellbang.com/guide/testing (dev-packages/cli/docs/testing.md) -->

# Testing and checking

Two tools close the loop after every change: `cell check` finds mistakes without running the application, and `createTestApp()` runs it inside the test process.

## `cell check`

```bash
npx cell check            # exit code 1 when there are errors
npx cell check --json     # one JSON document: passed, summary, issues
```

| Check | Finds |
| --- | --- |
| `config` | Missing entry, unknown `-m` modes, `CELL_*` environment variables that match no key |
| `types` | `tsc --noEmit` of the project, each diagnostic with file, line and `TSxxxx` code |
| `decorators` | `experimentalDecorators` / `emitDecoratorMetadata` missing in `tsconfig.json` |
| `di` | Loads the backend container without starting it and resolves every binding: `CELL_DI_NO_BINDING`, `CELL_DI_AMBIGUOUS`, `CELL_DI_CIRCULAR`, ... |

Each issue has a `code`, a `file` and `line` when known, and a `hint`: a one-sentence fix. `--skip <check>` leaves one out; components can add their own checks (`typeorm:entities`, for example).

## `createTestApp()`

```ts
// test/users.spec.ts
import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
import { join } from 'node:path';
import { createTestApp, type TestApp } from '@celljs/cli';

describe('users', () => {
    let app: TestApp;

    beforeAll(async () => {
        app = await createTestApp({ root: join(__dirname, '..') });
    }, 60000);                                   // the first start compiles the sources

    afterAll(() => app?.close());                // stops the application: onStop runs

    it('creates a user over HTTP', async () => {
        const res = await app.fetch('/users', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ name: 'Ada' }),
        });
        expect(res.status).toBe(200);
        expect(await res.json()).toMatchObject({ name: 'Ada' });
    });

    it('calls a service directly', async () => {
        const { UserService } = await app.import('/src/node/user-service.ts');   // the module the application loaded
        expect(await app.get<any>(UserService).count()).toBe(1);
    });
});
```

- The backend is loaded from source the way `cell dev` loads it: nothing is built and no port is opened. `fetch(path, init)` sends the request through the whole HTTP chain (middleware, security, controllers, error handlers) and returns a standard `Response`.
- `app.get(Id)` returns a component of the application, `app.container.getAll(Id)` all of them. The application runs in its own module instances: **take classes from `await app.import('/src/node/user-service.ts')`** (a package by its name), not from an `import` of the test file. A class or `Symbol` the test imports itself is matched by name, which works for symbols and for classes without injections, but a class with `@Value` / `@Autowired` imported into the test process fails with `CELL_DI_NO_BINDING`.
- The active mode is `test`: put test-only configuration in `cell.test.yml`, for example an in-memory database. `createTestApp({ mode: ['seed'] })` adds modes after `test`.
- Startup failures throw a `CellError` (`CELL_DEV_BACKEND_FAILED` with the failing file). `fetch` without an HTTP backend throws `CELL_TEST_APP_NO_HTTP`.

Run the tests with `bun test` (the templates' `npm test` runs `bun test ./test`). Each test file gets one application; tests in a file share its state, so make them independent of order or reset data in `beforeEach`.

### Example: a test database

```yaml
# cell.test.yml
typeorm:
  ormConfig:
    - type: sqljs          # in memory, from the sql.js package
      synchronize: true
```

## Unit tests without the application

Plain classes can be tested with `new`, passing collaborators by hand. Components that use property injection need the container: prefer `createTestApp()` over assembling one yourself.

## Debugging a running application

While `cell dev` runs, `POST /_cell/mcp` on the same port is an MCP server for coding agents with `get_errors` (startup errors, failed reloads, 5xx requests, error logs), `list_routes`, `list_bindings`, `get_config`, `recent_requests` and `logs`. See [Working with coding agents](https://cell.cellbang.com/guide/coding-agents).

<!-- https://cell.cellbang.com/guide/deployment (dev-packages/cli/docs/deployment.md) -->

# Building and deploying

Your code does not change between platforms: a **preset**, chosen at build time, decides the shape of the output and how it is deployed.

```bash
npx cell build                                # preset node: .cell/output
npx cell build --preset cloudflare
npx cell deploy --preset fc --dry-run         # the plan; nothing is uploaded
```

The preset comes from `--preset`, else `preset` in `cell.config.ts`, else the `CELL_PRESET` variable, else the CI platform (`cloudflare` in Workers Builds, `vercel` on Vercel), else `node`. `npx cell info` shows which one applies and why.

## Presets

| Preset | Output | Run locally | Deploy |
| --- | --- | --- | --- |
| `node` (default) | Node.js HTTP server, `server/index.mjs` | `cell preview` | Copy `.cell/output` anywhere Node.js 18+, Bun or Deno runs |
| `cli` | A command-line program on Cell DI, no HTTP server | `cell preview` | Distribute the file or an executable |
| `cloudflare` | Worker + static assets + `wrangler.json` | `cell preview` (workerd through Wrangler) | `cell deploy --preset cloudflare` |
| `fc` | Alibaba Cloud Function Compute 3.0, custom runtime | `cell preview` | `cell deploy --preset fc` |
| `scf` | Tencent Cloud SCF web function | `cell preview` | `cell deploy --preset scf` |
| `lambda` | AWS Lambda with a function URL | `cell preview` | `cell deploy --preset lambda` |
| `vercel` | Vercel Build Output API (`.vercel/output`) | `cell preview` | `cell deploy --preset vercel` |

## The output

```text
.cell/output/
├── server/index.mjs     # the backend: one ES module with every dependency inlined
├── public/              # the frontend build, when there is one
└── manifest.json        # preset, format, targets: what cell preview and cell deploy read
```

The output does not need the project's `node_modules`. Packages that cannot be bundled (native modules, `build.external` in `cell.config.ts`) are copied into `server/node_modules`.

| Option | Result |
| --- | --- |
| `--single` | The frontend is embedded in `server/index.mjs`: one file runs the whole application |
| `--compile [bun\|node\|deno]` | An executable `.cell/output/app` that needs no Node.js on the host |
| `-m <mode>` | Also reads `cell.<mode>.yml` (`production` is always active in builds) |
| `--sourcemap`, `--format cjs`, `--out-dir <dir>` | Source maps, CommonJS output, another directory |

## Configuration in production

- **Backend configuration is evaluated when the server starts.** The same build runs everywhere; give each environment its values through environment variables, either referenced in `cell.yml` (`"${env.DATABASE_URL}"`) or as overrides (`CELL_SERVER__PORT=8080`). See [configuration](https://cell.cellbang.com/guide/project#application-configuration-cell-yml).
- **Never mark a secret public.** Configuration is server-only unless a schema marks it public or it is under `app.public`; frontend values are evaluated at build time and shipped to browsers.
- The server listens on `127.0.0.1:3000` by default. In a container set `CELL_SERVER__HOST=0.0.0.0`; when the platform gives the port in `PORT`, set `CELL_SERVER__PORT='${env.PORT}'`.
- Set your own `web.cookies.keys` (signing key of cookies and sessions), e.g. `CELL_WEB__COOKIES__KEYS='["..."]'`.
- **Security checks.** `cell check` lists settings that are unsafe in production (`CELL_SECURITY_*` warnings: the development cookie key, a short `jwt.secret`...). A production start (`NODE_ENV=production`, which `cell build` writes into the server bundle) logs the same warnings; set `securityChecks: fail` (or `CELL_SECURITY_CHECKS=fail`) to refuse to start instead, `off` to skip them.
- **Error messages.** In production a server error answers with its status text only (`Internal Server Error`); its message and stack go to the log. 4xx `HttpError` messages are sent. `web.errors.exposeMessages` overrides this.

### A container image

```dockerfile
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npx cell build

FROM node:22-alpine
ENV NODE_ENV=production
ENV CELL_SERVER__HOST=0.0.0.0
WORKDIR /app
COPY --from=build --chown=node:node /app/.cell/output ./
USER node
EXPOSE 3000
CMD ["node", "server/index.mjs"]
```

## `cell deploy`

`cell deploy` builds with the preset, makes a plan (the resources it will create or update), then applies it. `--dry-run` stops after the plan and works without credentials; `--skip-build` deploys the existing output.

| Preset | Credentials (environment) | Platform options in `cell.config.ts` |
| --- | --- | --- |
| `cloudflare` | `CLOUDFLARE_API_TOKEN` (and `CLOUDFLARE_ACCOUNT_ID`), or `npx wrangler login` | `wrangler.jsonc` in the project root: name, vars, bindings, routes |
| `fc` | `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | `fc: { name, region, memory, cpu, timeout, concurrency, env }` |
| `scf` | `TENCENTCLOUD_SECRET_ID`, `TENCENTCLOUD_SECRET_KEY` | `scf: { name, region, namespace, memory, timeout, env }` |
| `lambda` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE` | `lambda: { name, region, architecture, memory, timeout, role, env }` |
| `vercel` | `VERCEL_TOKEN`, or `npx vercel login` | `vercel: { project, scope, environment, memory, maxDuration, regions }` |

```ts
// cell.config.ts
import { defineConfig } from '@celljs/cli';

export default defineConfig({
    preset: 'fc',
    fc: { region: 'cn-shanghai', memory: 512, env: { DATABASE_URL: process.env.DATABASE_URL ?? '' } },
});
```

The function platforms (`fc`, `scf`, `lambda`) call the cloud APIs directly: no vendor SDK or CLI is installed. Wrangler and the Vercel CLI are used from the project when installed, otherwise through `npx`. Every failure has a code: `CELL_DEPLOY_CREDENTIALS_MISSING`, `CELL_DEPLOY_UNAUTHORIZED`, `CELL_DEPLOY_PACKAGE_TOO_LARGE`, ...

Platform details (custom domains, runtimes, package size limits, what each deployer creates) are in the [CLI reference](https://cell.cellbang.com/cli#presets).

## Hooks

Shell commands on toolchain events, for steps such as code generation:

```ts
export default defineConfig({
    hooks: {
        'build:before': 'prisma generate',                      // a failure cancels the build
        'output:done': 'cp extra/* "$CELL_OUT_DIR/server/"',
    },
});
```

Extensions that need code (Vite plugins, extra output files, checks, MCP tools) are toolchain modules; see the [CLI reference](https://cell.cellbang.com/cli).

<!-- https://cell.cellbang.com/guide/coding-agents (dev-packages/cli/docs/coding-agents.md) -->

# Working with coding agents

Cell is designed so that a coding agent (Claude Code, Codex, Cursor, CodeBuddy, pi, ...) can use it correctly on the first try: one way to write each thing, structured errors with fixes, machine-readable commands and documentation that matches the installed version. This page is for the people who set agents up; the guide the agents themselves read is [AGENTS.md](https://cell.cellbang.com/agent-guide).

## What a project gets

`cell init` writes these files, and `npx cell agent sync` rewrites the Cell part of them after you upgrade Cell or add a component:

| File | For |
| --- | --- |
| `AGENTS.md` | The Cell guide of the installed `@celljs/cli` version, followed by the guide snippets of installed components. Cell only rewrites the part between `<!-- cell:begin -->` and `<!-- cell:end -->`; write project rules outside it |
| `CLAUDE.md` | `@AGENTS.md`, for Claude Code |
| `.agents/skills/cell/SKILL.md` | The same guide as an agent skill |
| `.mcp.json` | Starts `npx cell mcp` |

Add `npx cell agent sync` to your upgrade routine, or run it in a `postinstall` script.

## MCP

`npx cell mcp` is a stdio MCP server for the project. Its tools return the same JSON as the commands:

| Tool | Command | Side effects |
| --- | --- | --- |
| `info` | `cell info` | none |
| `check` | `cell check` | none |
| `config_get` | `cell config get` | none |
| `docs_search` | `cell docs` | none |
| `build` | `cell build` | writes the output directory |
| `deploy_plan` | `cell deploy --dry-run` | writes the output directory; may reach the network |

There is deliberately no deploy tool: deploying stays with a person running `cell deploy`.

```jsonc
// .mcp.json (Claude Code, Cursor, CodeBuddy) or .cursor/mcp.json
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }
```

```toml
# Codex: ~/.codex/config.toml
[mcp_servers.cell]
command = "npx"
args = ["cell", "mcp"]
```

While `cell dev` runs, `http://127.0.0.1:<port>/_cell/mcp` is a second MCP server (HTTP) for the running application: `get_errors`, `list_routes`, `list_bindings`, `get_config`, `recent_requests` and `logs`. It only accepts requests from the local machine.

## Commands agents use

| Command | Gives |
| --- | --- |
| `npx cell check --json` | Every type, configuration, decorator and DI problem with `code`, `file`, `line` and `hint` |
| `npx cell info --json` | Preset, components, DI modules, entries, hooks, output state |
| `npx cell config get <key> --why` | A merged configuration value and where each layer came from |
| `npx cell docs <words>` | Sections of the docs shipped with the installed packages (their READMEs, these guides and the CLI reference) |
| `npx cell build --json`, `npx cell deploy --dry-run --json` | One-line results instead of progress output |

Every command accepts `--json` (one document with `schemaVersion` on stdout, everything else on stderr), never prompts when not on a terminal, and side-effecting commands have `--dry-run`. Exit codes: 0 success, 1 failure, 2 usage error.

## Errors

Every toolchain and runtime error has a stable code, a message, a one-sentence fix and a docs link:

```text
[CELL_DI_NO_BINDING] No binding for Symbol(Mailer), needed by Signup.mailer (TodoController → Signup → Symbol(Mailer)).
  fix: Bind the identifier in a DI module (@Component(<id>) in a file the module imports), or mark the injection @Optional().
  docs: https://cell.cellbang.com/errors/cell-di-no-binding
```

The [error code list](https://cell.cellbang.com/errors/) has a page per code. Codes and `--json` fields stay stable within 4.x.

## Documentation for models

The docs site publishes [`llms.txt`](https://cell.cellbang.com/llms.txt) (an index of every page) and [`llms-full.txt`](https://cell.cellbang.com/llms-full.txt) (the guides, the CLI reference and the package references in one file) for agents that read the web. Inside a project, `cell docs` is better: it searches the version you have installed.

## Habits that work

- Ask the agent to run `npx cell check` and the tests after every change; both are fast and their output is made for it.
- Keep project rules in `AGENTS.md` outside the Cell markers.
- Let the agent use `cell deploy --dry-run` freely; keep `cell deploy` itself, and the credentials it needs, for people.

<!-- https://cell.cellbang.com/guide/packages (dev-packages/cli/docs/packages.md) -->

# Package catalog

All packages are published under [`@celljs`](https://www.npmjs.com/org/celljs) with the same version; keep them on one version. Installing a component package is enough to use it: its DI modules and `cell.yml` are loaded automatically (see [components](https://cell.cellbang.com/guide/project#components)). Each name links to its reference.

## Which package do I need?

| I want to | Add |
| --- | --- |
| Write REST controllers | `@celljs/mvc` (with `@celljs/express-adapter` as the server entry; both are in the templates) |
| Validate request bodies | `@celljs/validation` + `class-validator` |
| Publish OpenAPI / Swagger UI | `@celljs/openapi` |
| Call my backend from my frontend with types | `@celljs/rpc` |
| Build a React frontend | `@celljs/react` + `@celljs/serve-static` |
| Use a SQL database | `@celljs/typeorm` + a driver (`mysql2`, `pg`, `better-sqlite3`, `sql.js`, ...) |
| Cache values in memory or Redis | `@celljs/cache` |
| Run cron jobs | `@celljs/schedule` |
| Retry failing calls with back-off | `@celljs/retry` |
| Separate commands, queries and events | `@celljs/cqrs` |
| Log with winston | `@celljs/logger` |
| Log users in, protect routes | `@celljs/security` |
| Issue and verify JWTs | `@celljs/jwt` |
| Sign in with GitHub, Google or another OAuth2 / OIDC provider | `@celljs/oauth2-client` (with `@celljs/security`) |
| Call other HTTP APIs | `@celljs/http` (`RestOperations`) |
| Serve or call gRPC services | `@celljs/grpc` |
| Talk to LLMs | `@celljs/ai-core` + `@celljs/ai-pi` |
| Build an agent whose tools are my services | `@celljs/ai-agent` |
| Run a coding agent inside my application | `@celljs/ai-coding-agent` |
| Build a terminal UI | `@celljs/tui` (with the `cli` preset) |
| Store files in Alibaba Cloud OSS / Tencent Cloud COS | `@celljs/oss` / `@celljs/cos` |
| Take payments with WeChat Pay, Alipay or Stripe | `@celljs/wechat-pay` / `@celljs/alipay` / `@celljs/stripe` |

## Runtime

| Package | What it provides |
| --- | --- |
| [`@celljs/core`](https://cell.cellbang.com/packages/core) | DI container, `@Component` / `@Autowired` / `@Value`, AOP, configuration, application lifecycle, logger, request context. Every application depends on it |
| [`@celljs/web`](https://cell.cellbang.com/packages/web) | HTTP server on `node:http`: middleware chain, body parsing, cookies, sessions, CORS, trace ids, health check, error handlers |
| [`@celljs/mvc`](https://cell.cellbang.com/packages/mvc) | Controllers: `@Controller`, `@Get` / `@Post` / ..., parameter decorators, JSON / text / HTML / file responses, `@Catch` |
| [`@celljs/express-adapter`](https://cell.cellbang.com/packages/express-adapter) | The backend entry that starts the application and listens on `server.host` / `server.port`. Despite its name it has no express dependency |
| [`@celljs/http`](https://cell.cellbang.com/packages/http) | HTTP client (`RestOperations`, on `fetch`) and the shared `HttpStatus`, `HttpHeaders`, `MediaType` |
| [`@celljs/validation`](https://cell.cellbang.com/packages/validation) | class-validator / class-transformer validation of controller and RPC parameters |
| [`@celljs/openapi`](https://cell.cellbang.com/packages/openapi) | OpenAPI 3.0 document and Swagger UI built from the controllers |
| [`@celljs/rpc`](https://cell.cellbang.com/packages/rpc) | `@Rpc` services and typed proxies (`useRpc` of `@celljs/react`, `@Autorpc`) over JSON-RPC on HTTP |
| [`@celljs/serve-static`](https://cell.cellbang.com/packages/serve-static) | Serves the frontend build with ETags, ranges and single-page-application fallback |
| [`@celljs/typeorm`](https://cell.cellbang.com/packages/typeorm) | TypeORM data sources, `OrmContext` repositories and `@Transactional()` |
| [`@celljs/cache`](https://cell.cellbang.com/packages/cache) | Named cache managers on cache-manager (memory, Redis and other stores) |
| [`@celljs/schedule`](https://cell.cellbang.com/packages/schedule) | `@Scheduler` classes with `@Cron` methods |
| [`@celljs/retry`](https://cell.cellbang.com/packages/retry) | Retry templates with retry and back-off policies |
| [`@celljs/cqrs`](https://cell.cellbang.com/packages/cqrs) | Command, query and event buses, sagas and aggregates |
| [`@celljs/grpc`](https://cell.cellbang.com/packages/grpc) | gRPC servers and clients on `node:http2` with its own `.proto` parser, no code generation |
| [`@celljs/logger`](https://cell.cellbang.com/packages/logger) | winston-backed `Logger` |
| [`@celljs/security`](https://cell.cellbang.com/packages/security) | Form login, HTTP Basic, logout, `@Authenticated()`, `@PreAuthorize()`, policies, password hashing |
| [`@celljs/jwt`](https://cell.cellbang.com/packages/jwt) | `JwtService`: sign and verify JSON Web Tokens with `node:crypto` |
| [`@celljs/oauth2-core`](https://cell.cellbang.com/packages/oauth2-core) | OAuth 2.0 / OpenID Connect types shared by the OAuth2 packages |
| [`@celljs/oauth2-client`](https://cell.cellbang.com/packages/oauth2-client) | Login with OAuth2 / OIDC providers; client credentials, password and refresh-token grants |
| [`@celljs/oauth2-jose`](https://cell.cellbang.com/packages/oauth2-jose) | JWK sets and JWS / JWT decoding for the OAuth2 packages |
| [`@celljs/wechat-pay`](https://cell.cellbang.com/packages/wechat-pay) | WeChat Pay API v3 client and a verified notification endpoint |
| [`@celljs/alipay`](https://cell.cellbang.com/packages/alipay) | Alipay gateway client and a verified notification endpoint |
| [`@celljs/stripe`](https://cell.cellbang.com/packages/stripe) | Stripe client and a verified webhook endpoint |

## Frontend

| Package | What it provides |
| --- | --- |
| [`@celljs/react`](https://cell.cellbang.com/packages/react) | React frontend: pages of `src/browser/pages`, routing, layouts, hooks to the DI container, the application shell |
| [`@celljs/widget`](https://cell.cellbang.com/packages/widget) | Frontend infrastructure `@celljs/react` builds on: widgets, themes, locales |
| [`@celljs/tui`](https://cell.cellbang.com/packages/tui) | Terminal user interfaces on pi-tui, including a chat for agents |

## AI

| Package | What it provides |
| --- | --- |
| [`@celljs/ai-core`](https://cell.cellbang.com/packages/ai-core) | Provider-neutral `ChatModel`, `EmbeddingModel`, `PromptTemplate` and the routing `ProxyChatModel` |
| [`@celljs/ai-pi`](https://cell.cellbang.com/packages/ai-pi) | 20+ model providers through pi-ai, addressed as `pi:<provider>/<model>` |
| [`@celljs/ai-agent`](https://cell.cellbang.com/packages/ai-agent) | Tool-using agents whose tools are Cell components; events over SSE |
| [`@celljs/ai-coding-agent`](https://cell.cellbang.com/packages/ai-coding-agent) | pi coding agent sessions managed by DI |

## Cloud

| Package | What it provides |
| --- | --- |
| [`@celljs/cloud`](https://cell.cellbang.com/packages/cloud) | Shared cloud abstractions: credentials, region, account and the `ObjectStorageService` interface |
| [`@celljs/oss`](https://cell.cellbang.com/packages/oss) | `ObjectStorageService` on Alibaba Cloud OSS |
| [`@celljs/cos`](https://cell.cellbang.com/packages/cos) | `ObjectStorageService` on Tencent Cloud COS |

Deploying to Function Compute, SCF, Lambda, Vercel or Cloudflare needs no package: choose the preset ([Building and deploying](https://cell.cellbang.com/guide/deployment)).

## Toolchain

| Package | What it provides |
| --- | --- |
| [`@celljs/cli`](https://cell.cellbang.com/cli) | The `cell` command, presets, deployers, `createTestApp()`, these guides |
| [`@celljs/vite`](https://cell.cellbang.com/packages/vite) | The Vite plugin and `CellBuilder` behind `cell build` and `cell dev` |
| [`@celljs/kit`](https://cell.cellbang.com/packages/kit) | Shared types for toolchain modules and presets: `CellError`, events, `definePreset` |

<!-- https://cell.cellbang.com/cli (dev-packages/cli/README.en.md) -->

# @celljs/cli

The Cell 4 command-line tool. Reads `cell.config.ts`, builds applications according to presets, runs the built application, and deploys build artifacts. For getting started and usage guides, see the [guide](https://cell.cellbang.com/guide/getting-started) (distributed with this package in `docs/`, searchable with `cell docs`). For architecture details, see [docs/design/architecture.md](https://github.com/cellbang/cell/blob/main/docs/design/architecture.md); for migrating from 3.x, see [docs/migration-4.md](https://github.com/cellbang/cell/blob/main/docs/migration-4.md).

Requires Node.js `^20.19.0 || >=22.12.0`. Install in your project:

```bash
npm install -D @celljs/cli
npx cell build
```

## Commands

| Command | Purpose |
| --- | --- |
| `cell init [template] [dir]` | Create a project from a template (`backend`, `fullstack`), with AGENTS.md, cell skill, and `.mcp.json` included; lists templates when invoked without arguments |
| `cell dev` | Development: frontend and backend on the same port, HMR for frontend, automatic backend reload on file changes, auto-restart on config changes |
| `cell build` | Build to `.cell/output`: `server/index.mjs` (single file with inlined dependencies), `public/` (frontend), `manifest.json` |
| `cell info` | Describe the project: preset and its source, mode, targets, components, DI modules, hooks, and build status. Read-only; does not build or execute hooks |
| `cell check` | Perform config, TypeScript types, decorator setup, backend DI binding, and module registration checks; exits with code 1 on error |
| `cell preview` | Run build artifacts according to `manifest.json` without rebuilding |
| `cell deploy` | Build with the selected preset, then publish via its deployer; use `--dry-run` to show the plan only |
| `cell config get <key>` | Get the merged value of a config key; use `--why` to see which files and environment variables set it |
| `cell docs <query>` | Search the documentation shipped with installed components and modules, plus guides and this document from `@celljs/cli` (matching the project's Cell version) |
| `cell mcp` | MCP server on stdio that exposes `info`, `check`, `config_get`, `docs_search`, `build`, `deploy_plan`, and tools registered by modules to coding agents |
| `cell agent sync` | Rewrite the parts of AGENTS.md managed by Cell and `.agents/skills/cell/SKILL.md` according to installed versions |


## Presets

| preset | Artifact | Run / preview | Deployer |
| --- | --- | --- | --- |
| `node` (default) | Node.js HTTP server: `node .cell/output/server/index.mjs` | `cell preview` runs the application with Node.js | None; deploy artifacts manually |
| `cloudflare` | Cloudflare Workers: `server/worker.mjs` + `wrangler.json`, frontend as static assets | `cell preview` runs via `wrangler dev` in local workerd | `cloudflare` (Wrangler) |
| `cli` | Node.js CLI program: `node .cell/output/server/index.mjs` starts the application without listening on a port; components (e.g., `ApplicationLifecycle`) perform the work. Does not require `@celljs/express-adapter` or report missing entry | `cell preview` runs with Node.js, inherits the current terminal | None |
| `fc` | Alibaba Cloud Functions (3.0) custom runtime: artifact with `bootstrap` startup script, frontend served from `public/` by the server | Run with Node.js | `fc` (Functions API) |
| `scf` | Tencent Cloud SCF Web functions: artifact with `scf_bootstrap` | Run with Node.js | `scf` (Cloud Functions API) |
| `lambda` | AWS Lambda + function URL: artifact with `server/lambda.mjs` handler | Run with Node.js | `lambda` (AWS API) |
| `vercel` | Vercel Build Output API: `.vercel/output`, frontend on CDN, backend as a single function | Run the function bundle with Node.js; frontend served from `static/` | `vercel` (Vercel CLI) |

Options for each preset are written in `cell.config.ts` in fields matching the preset name (e.g., `fc: { region: 'cn-shanghai' }`), validated against the preset's schema, and unknown options raise `CELL_CONFIG_INVALID`. Switching presets preserves other preset fields without error.

### cloudflare

```bash
cell build --preset cloudflare          # Build to .cell/output
cell preview                            # wrangler dev runs in workerd (Cloudflare runtime), default port 8787
cell deploy --preset cloudflare --dry-run   # Build and run wrangler deploy --dry-run, show plan, do not upload
cell deploy --preset cloudflare         # Build and deploy, output workers.dev address
```

- **Runtime**: The Cell backend runs on Workers' `node:http` server (requires `nodejs_compat`), provided by `@celljs/express-adapter`'s `http` entry—same as the `node` preset. Cloudflare serves the frontend (`public/`) as static assets; only requests that don't match static files enter the Worker. Artifacts support ESM only; `--format cjs` raises `CELL_CONFIG_CONFLICT`.
- **Startup timing**: Workers allow code generation only during module loading phase (`new Function`, which some dependencies use), and I/O only during request handling. Application modules load when the Worker starts; `Application.start()` and `onStart` execute on the first request (`ApplicationHost.beforeStart`). Module load failures cause Worker startup to fail; `wrangler dev` / `wrangler deploy` report the error directly.
- **Cloudflare configuration**: Write configuration in `wrangler.jsonc` or `wrangler.json` at the project root (optional, following Cloudflare's format): `name`, `compatibility_date`, `vars`, KV / D1 / R2 bindings, `routes`, etc. go here. During build, Cell generates `.cell/output/wrangler.json` from this as a base and sets: `main` (ignored with a warning if you specified it), `assets.directory` if a frontend exists, and `nodejs_compat` in `compatibility_flags`. Without a config file, `name` defaults to the package name from package.json (e.g., `@acme/shop` → `acme-shop`), and `compatibility_date` defaults to `2026-03-17`, the earliest allowed date (`node:http` server and `node:tty` have been available by default since then). `wrangler.toml` is not supported; convert to `wrangler.jsonc`.
- **Single-page applications**: With a frontend, `assets.not_found_handling: "single-page-application"` is set by default. When the browser navigates to a nonexistent path, Cloudflare returns `index.html` (same as `@celljs/serve-static`'s `spa`); other requests like API calls still enter the Worker. If you specify `not_found_handling` in `wrangler.jsonc`, your project setting takes precedence. Without frontend files in the Worker, `@celljs/serve-static` detects the missing frontend directory and passes through; unknown paths return a normal 404.
- **Custom domains**: If your domain's DNS is hosted on Cloudflare, add `"routes": [{ "pattern": "app.example.com", "custom_domain": true }]` to `wrangler.jsonc`. Cloudflare automatically creates DNS records and certificates on deploy, and `deployment.url` reports the domain. Networks that cannot reach `*.workers.dev` require a custom domain for access.
- **Application config**: `vars` and secrets (set via `wrangler secret put`) enter `process.env`, so `${env.X}` and `CELL_*` variables in `cell.yml` work as expected.
- **Wrangler**: Not a Cell dependency. If Wrangler is installed in your project, Cell uses it; otherwise, `npx --yes wrangler@4` installs it on first use (cached by npm). Wrangler manages credentials: set `CLOUDFLARE_API_TOKEN` (and optionally `CLOUDFLARE_ACCOUNT_ID`), or run `npx wrangler login` once. Alternatively, skip `cell deploy` and run `npx wrangler deploy --config .cell/output/wrangler.json` directly.
- **Workers Builds** (Cloudflare's CI; set `WORKERS_CI=1`): automatically selects the `cloudflare` preset, build command `npx cell build`, and deploy command `npx cell deploy --skip-build`.
- `wrangler dev` creates `.wrangler/` in the project root; add it to `.gitignore`.

### fc, scf, lambda

These three function platforms use the same approach. The Cell server runs unchanged; the artifact directory is zipped as function code. The deployer calls cloud APIs directly (Cell implements request signing: Alibaba Cloud ACS3, Tencent Cloud TC3, AWS SigV4); no cloud SDK or CLI is needed. Function name defaults to the package name (`@acme/shop` → `shop`), or specify with `name`. Environment variables are written to the function (also includes `NODE_ENV=production`), and `${env.X}` and `CELL_*` in `cell.yml` work as expected.

| preset | Runtime | Options | Credentials (environment variables) | Deploy result |
| --- | --- | --- | --- | --- |
| `fc` | `custom.debian10` runtime; `bootstrap` uses Node.js 20 from the image runtime (`node: '18'` optional) on port 9000 (`FC_SERVER_PORT`) | `name`, `region` (defaults to `ALIBABA_CLOUD_REGION_ID` or `cn-hangzhou`), `node`, `memory` (MB, default 1024), `cpu` (default based on 2 GB/core), `timeout` (default 60), `concurrency` (single instance, default 20), `env` | `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET` (optionally `ALIBABA_CLOUD_SECURITY_TOKEN`) | Create or update function; create an anonymous HTTP trigger `http` if none exists (existing triggers are unchanged); return the `fcapp.run` address |
| `scf` | Web functions (`Type: HTTP`); `scf_bootstrap` uses Node.js 18 from the runtime (`runtime: 'Nodejs16.13'` optional) on port 9000; only `/tmp` is writable | `name`, `region` (defaults to `TENCENTCLOUD_REGION` or `ap-guangzhou`), `namespace` (default `default`), `runtime`, `memory` (default 512), `timeout` (default 60), `env` | `TENCENTCLOUD_SECRET_ID`, `TENCENTCLOUD_SECRET_KEY` (optionally `TENCENTCLOUD_SESSION_TOKEN`) | Create or update function (deploy code first, then config, wait for Active state); create a public, unauthenticated function URL if none exists |
| `lambda` | `nodejs22.x`; initialize on loopback port; `server/lambda.handler` converts function URL / HTTP API (payload v2) events to requests; responses are returned as base64, with multiple cookies in `cookies` | `name`, `region` (defaults to `AWS_REGION` or `us-east-1`), `runtime`, `architecture` (`x86_64` / `arm64`), `memory` (default 1024), `timeout` (default 30), `role`, `env` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (optionally `AWS_SESSION_TOKEN`), or `AWS_PROFILE` / default from `~/.aws/credentials` | Create or reuse execution role `cell-lambda-execution` (log permissions only) if `role` is not specified; create or update function; create an `AuthType: NONE` function URL and its two public invoke permissions if none exists |

- Code packages are uploaded directly with requests. Size limits: FC 100 MB, SCF 20 MB, Lambda 50 MB (after zipping). Oversized packages raise `CELL_DEPLOY_PACKAGE_TOO_LARGE`. Large sizes usually come from packages left in `server/node_modules` by `build.external`.
- Without credentials, `--dry-run` still shows a plan (action is `deploy`, with a warning that the function's existence is unknown). With credentials, the cloud is queried and the action is `create` or `update`. Deployment without credentials raises `CELL_DEPLOY_CREDENTIALS_MISSING`; cloud API errors raise `CELL_DEPLOY_API_ERROR` / `CELL_DEPLOY_UNAUTHORIZED` with the cloud provider's error code and request ID.
- The default domain `fcapp.run` causes browsers to download HTML pages. Web applications should bind a custom domain; APIs are unaffected.
- Runtimes include older Node.js versions (FC 20.10, SCF 18.15). Server bundles include patches for `import.meta.dirname` / `filename`.

### vercel

```bash
cell build --preset vercel     # .vercel/output (Build Output API v3)
cell preview                   # Run function bundle with Node.js, frontend served from .vercel/output/static
cell deploy --preset vercel    # vercel deploy --prebuilt, no rebuild on Vercel
```

- The frontend is placed in `static/` and returned by Vercel CDN (`/assets/*` with one-year immutable cache headers). Other requests enter function `functions/index.func` (`nodejs22.x`), where the Cell server handles APIs and serves `public/index.html` for single-page fallback. Files in `.vercel/output` are cleared during build.
- Options: `project` (defaults to package name), `scope` (team), `environment` (`production` default or `preview`), `runtime`, `memory`, `maxDuration`, `regions` (comma-separated). Output directory is fixed at `.vercel/output`; deploying with `--out-dir` elsewhere raises `CELL_DEPLOY_OUTPUT_MISMATCH`. `--single` / `--compile` are not accepted.
- Vercel CLI is not a dependency. If installed in your project, Cell uses it; otherwise `npx --yes vercel@65` is used. Credentials: `VERCEL_TOKEN`, or run `npx vercel login` once. The project is auto-created if it doesn't exist (`--create-if-missing`).
- In Vercel's build environment (`VERCEL=1`), the `vercel` preset is automatically selected. Add `.vercel/` to `.gitignore`

### cell dev

| Option | Description |
| --- | --- |
| `--preset <name>` | Which preset's entry to use for running the backend; default is `node` |
| `-m, --mode <mode>` | Additional mode(s), repeatable; `development` is always added automatically |
| `-p, --port <port>` | Port, defaults to `server.port` (considering `CELL_SERVER__PORT`), otherwise 3000; `0` means random port |
| `--host <host>` | Listen address, defaults to `server.host`, otherwise `127.0.0.1` |

- Single port: Vite provides frontend pages and modules (HMR), `/favicon.ico`, and component `assets`. Files in `public/` match their location in the build output, and remaining requests go to the backend.
- The backend is not bundled. In Vite's server environment, it loads via module runner: Cell packages and project source pass through the Cell plugin (generated DI container and config written to `.cell/generated/`); other dependencies load directly via Node. The entry passes the request handler function to `cell dev` via `ApplicationHost` (`@celljs/core`), not listening on a port itself.
- When backend files change, the old application stops (triggering `onStop`), then restarts from new modules and triggers `dev:reload`. On startup failure, requests return 500 with `CellError` (`CELL_DEV_BACKEND_FAILED`) and retry automatically after saving.
- When project or component `cell*.yml`, `package.json`, or `cell.config.*` changes, the toolchain is re-parsed and restarts on the same port, triggering `dev:ready` again. Config errors are reported; the process waits for the next change.
- `require()` in source code and CommonJS files in the project (e.g., generated Prisma client) work normally.
- `POST /_cell/mcp`: MCP endpoint of the running application (Streamable HTTP, JSON response). Tools include `get_errors` (backend startup errors, failed reloads, 5xx requests, error logs), `list_routes`, `list_bindings`, `get_config` (`${...}` already evaluated), `recent_requests`, and `logs`. Only accepts local requests (no `Origin` or loopback address); returns 403 for others.
- `--json`: outputs one-line result on stdout when ready (`url`, `port`, `mode`, `targets`, `mcp`, or `backendError` if backend failed). Application and Vite output go to stderr. On SIGINT / SIGTERM, stops the application and exits with 0.
- React Fast Refresh and other framework plugins are provided by the component's toolchain module (after the module host is complete). Before that, frontend changes trigger a full page refresh and CSS hot replacement.

### cell build

| Option | Description |
| --- | --- |
| `--preset <name>` | Build output format: `node` (default), `cloudflare`, `cli`, `fc`, `scf`, `lambda`, `vercel` |
| `-m, --mode <mode>` | Additional mode(s), reads `cell.<mode>.yml`, repeatable; `production` is always added automatically |
| `--format <esm\|cjs>` | Server bundle format, defaults by preset (`node` uses `esm`) |
| `--single` | Embed frontend into `server/index.mjs`: run the whole app from one file (see below) |
| `--compile [bun\|node\|deno]` | Compile into an executable `.cell/output/app`, default bun (see below) |
| `--compile-target <target>` | Cross-compile, passed to bun (e.g., `bun-linux-x64`) or deno (e.g., `x86_64-unknown-linux-gnu`) |
| `--sourcemap` | Generate source maps |
| `--out-dir <dir>` | Output directory, default `.cell/output` |

**Frontend static files**: After building the frontend, copy files into `public/` without overwriting build artifacts. Include: `favicon.ico` from the project root; files from each component's (including the project itself) `public/` or `src/browser/public/` directories, placed as-is at the site root (web app manifest, Service Worker, `robots.txt`, etc.); project files take priority on conflict. If no favicon exists, Cell's favicon is used. Files from each component's `assets/`, `src/assets/`, or `src/browser/assets/` directories are placed under `/assets/`.

**Single file (`--single`)**: Build the frontend first, then encode all files in `public/` (pages, scripts, favicon, component assets) as base64 and embed them in the server bundle. At startup, register them to `Symbol.for('@celljs/serve-static/assets')`; `@celljs/serve-static` serves them from memory (Content-Type, ETag / 304, and Cache-Control match disk serving; single-page apps fall back to `index.html`). Artifacts contain only `server/index.mjs` and `manifest.json` (`single: true`, no `public`). Copy this one file to any directory and run with `node index.mjs`. If the project has only a backend, behavior is the same as without `--single` (a message appears); packages left in `server/node_modules` by `build.external` must still be placed beside it. Alternatively, write `build: { single: true }` in `cell.config.ts`.

**Executable (`--compile`)**: Compile the single-file bundle into `.cell/output/app` (Windows: `app.exe`). The result runs on machines without Node.js or node_modules. `manifest.json` records `executable`, and `cell preview` runs it directly.

| Tool | Method | Requires |
| --- | --- | --- |
| `bun` (default) | `bun build --compile` | Bun installed locally |
| `deno` | `deno compile --allow-all` | Deno installed locally |
| `node` | Node.js Single Executable Application (SEA): the CommonJS bundle generates a blob, injected into node's copy via `npx postject`, and re-signed on macOS | Output format auto-switches to `cjs`; npx downloads postject on first use; cross-compilation is not supported |

Packages left outside the bundle (`build.external`, component `optionalDependencies`, usually native modules) cannot be included in the executable; `CELL_COMPILE_EXTERNALS` is raised, listing them. `cloudflare` and `vercel` presets have frontends managed by platforms and do not accept `--single` / `--compile`.

### cell info

Accepts the same `--preset`, `-m`, `--format`, and `--out-dir` options as `cell build`, describing what `cell build` would use with the same parameters. Additionally:

| Option | Description |
| --- | --- |
| `--app-config` | Also output the application config for each target (`cell.yml`): backend has all keys with `${...}` preserved (evaluated at runtime); frontend has only public keys, already evaluated |

Reads only package.json, `cell*.yml`, `cell.config.ts`, and `manifest.json`. Does not run project code or execute `hooks`. Key fields in `--json` result:

| Field | Content |
| --- | --- |
| `name`, `version`, `cellVersion`, `configFile` | Project and CLI versions, `cell.config` file (relative to root) |
| `preset` | `name`, `source` (`flag` / `config` / `env` / `ci` / `default`), `entry`, `format`, `runtime` (Cloudflare Workers use `workerd`), `deployer`, `available` |
| `mode`, `targets`, `targetSources` | Active modes; build targets and their sources (`cell.config.ts`, `default`, or declaring component) |
| `build` | Active `format`, `outDir`, `external`, `sourcemap`, `single`, `compile` |
| `components` | In load order; `dir` and `configFiles` relative to root; `targets`, `entries`, `toolchain`, and `optionalDependencies` are shown only when declared by the component |
| `frontend`, `backend` | `entry`, `entryComponent` providing it, `staticModules` / `modules` (DI modules, in load order), and `config` (only with `--app-config`). If the frontend has pages, also includes `routes` (`path`, `file`, `layouts` from `src/browser/pages`, plus `error` if an `_error` file exists) |
| `hooks`, `modules`, `moduleOptions` | Hooks in `cell.config.ts`, `modules` entries, toolchain module option keys |
| `output` | `dir`, `built`, and manifest fields (`preset`, `format`, `targets`, `server`, `public`) if outdated |
| `frontend.envOverrides`, `backend.envOverrides` | `CELL_*` variables in the current environment: `applied` (variable → config path) and `problems` (key not found or type mismatch). Only present if such variables exist; values are not output |

`warnings` point out settings that won't take effect or cause `cell build` to fail: no component provides the preset's entry, `-m` specifies a mode with no `cell.<mode>.yml` (with spelling suggestions), or non-working `CELL_*` variables.

### cell check

| Option | Description |
| --- | --- |
| `--preset <name>`, `-m, --mode <mode>` | Same as `cell build` |
| `--skip <check>` | Skip a specific check (repeatable); unknown names raise `CELL_ARGUMENT_INVALID` and list available checks |

| Check | Content |
| --- | --- |
| `config` | Same as `cell info` warnings: missing entry (`CELL_ENTRY_MISSING`), invalid mode (`CELL_MODE_UNKNOWN`), or ineffective or shadowed environment variables (`CELL_ENV_OVERRIDE_IGNORED` / `CELL_ENV_OVERRIDE_SHADOWS`) |
| `types` | Run `tsc --noEmit -p tsconfig.json` with the project's TypeScript. Each diagnostic includes file, line/column, and `TSxxxx` code. Skipped if no tsconfig.json or TypeScript is not installed |
| `decorators` | tsconfig must enable `experimentalDecorators` and `emitDecoratorMetadata` (`CELL_TSCONFIG_DECORATORS`) to match build-time decorator semantics |
| `di` | Load the backend DI container the same way `cell dev` does (without starting the application), then resolve each binding. Container errors (`CELL_DI_NO_BINDING`, `CELL_DI_AMBIGUOUS`, `CELL_DI_CIRCULAR`, `CELL_DI_MISSING_INJECT`, `CELL_DI_INCOMPLETE_BINDING`) are reported as errors with resolution chain and fix suggestions; each cause is reported once. Bindings that can only be created at injection point or request time are info |
| `security` | Settings reported by the backend `SecurityCheck` component as unsafe for production. All are warnings (do not fail the check), the same set handled at production startup by `securityChecks`: `CELL_SECURITY_DEFAULT_COOKIE_KEYS`, `CELL_SECURITY_COOKIE_KEYS_MISSING`, `CELL_SECURITY_WEAK_COOKIE_KEYS` (`@celljs/web`), and `CELL_SECURITY_WEAK_JWT_SECRET` (`@celljs/jwt`). Reads config for the selected mode. Shares one backend load with `di` |
| Module-registered checks | Registered by toolchain modules via `addCheck`, named like `typeorm:entities` |

`--json` result: `passed`, `summary` (errors / warnings / info counts), `issues` (each with `check`, `level`, `code`, `message`, and possibly `file`, `line`, `column`, `hint`), and `checks` (duration, problem counts, skip reason for each). Without `--json`, output is in compiler format `src/a.ts:3:5 error TS2322 …`; info is not shown.

### cell init

```bash
npx @celljs/cli init backend my-app     # or fullstack: React frontend + backend communicating via RPC
cd my-app && npm install && npx cell agent sync && npx cell dev
```

| Option | Description |
| --- | --- |
| `--name <name>` | Package name, defaults to directory name (lowercased, spaces removed) |
| `--force` | Allow writing to non-empty directory (same-name files overwritten) |

Never prompts. Raises `CELL_INIT_NOT_EMPTY` if the directory is non-empty, or `CELL_TEMPLATE_NOT_FOUND` if the template doesn't exist (with spelling suggestions). Project dependencies on `@celljs/*` are set to `^<cli version>`; tests use `bun test` + `createTestApp()`. Generates for coding agents: `AGENTS.md` (Cell guide matching version), `.agents/skills/cell/SKILL.md`, `CLAUDE.md` (`@AGENTS.md`), and `.mcp.json` (`npx cell mcp`).

### cell agent sync

Writes the Cell guide from `@celljs/cli` and `AGENTS.md` fragments from installed components and toolchain modules (`addDocs` directories) into the `<!-- cell:begin -->` … `<!-- cell:end -->` region of `AGENTS.md` (other content unchanged; if no markers exist, appends to the end). Also rewrites `.agents/skills/cell/SKILL.md`. Run once after upgrading Cell or changing components.

### cell config get

```bash
cell config get server.port --why
# server.port (backend) = 8080
#   server-only, owned by @celljs/web
#   Port the server listens on. Override with CELL_SERVER__PORT.
#   node_modules/@celljs/web/cell.yml: 3000
#   cell.yml: 8080
```

| Option | Description |
| --- | --- |
| `-m, --mode <mode>` | Additional mode(s), repeatable |
| `--target <target>` | `backend` or `frontend` (only public keys), default is `backend` if present |
| `--why` | List the key's owning component, whether it reaches frontend, description, and files and environment variables that set it in merge order |

Keys can be written as `a.b.c` or `items[0].name`. `--json` result has `value`, `owners` (components declaring this key in `cell.schema.json`), `public` (whether frontend sees it), `description`, `layers` (`file`, `component`, `value`), `env` (variables setting this key or ancestors), and `expressions` (backend value contains `${...}`, evaluated at server startup). Raises `CELL_CONFIG_KEY_NOT_FOUND` if the key doesn't exist (with nearest keys). Querying server-only keys with `--target frontend` indicates they are server-only.

### cell docs

`cell docs <query> [--limit n]`: Search by title sections in each component's `README.md`, `docs/`, module `addDocs()` directories, and `@celljs/cli`'s included docs and guide (`docs/`: getting started, config, dependency injection, HTTP, RPC, testing, deploy, coding agent, component directory; English). Returns the best-matching sections and `file:line` (`source` is `@celljs/cli` for CLI docs).

### cell mcp

Run an MCP server on stdio (one JSON-RPC message per line) until stdin closes. Tools correspond to same-named commands' `--json` results:

| Tool | Corresponding command | Side effects |
| --- | --- | --- |
| `info` | `cell info` | Read-only |
| `check` | `cell check` | Read-only |
| `config_get` | `cell config get` | Read-only |
| `docs_search` | `cell docs` | Read-only |
| `build` | `cell build` | Write output directory |
| `deploy_plan` | `cell deploy --dry-run` | Write output directory, deployer may access network; does not deploy |

Deployment tools are not provided. Actual deployment is done by running `cell deploy`.

Tools registered by toolchain modules via `addMcpTool` are also included (tools with the same name as built-ins are ignored with a warning); automatically reloaded after `cell.config.*`, package.json, or module files change. Each tool is marked with `readOnlyHint` / `openWorldHint`; parameters are validated against `inputSchema`, raising `isError` and `CellError` on failure. stdout contains only protocol messages; module and hook output goes to stderr.

Configure in an agent (run from project root):

```jsonc
// Claude Code / Cursor / CodeBuddy: .mcp.json or .cursor/mcp.json
{ "mcpServers": { "cell": { "command": "npx", "args": ["cell", "mcp"] } } }
```

```toml
# Codex: ~/.codex/config.toml
[mcp_servers.cell]
command = "npx"
args = ["cell", "mcp"]
```

While `cell dev` is running, you can also configure `http://127.0.0.1:<port>/_cell/mcp` as an HTTP MCP server to inspect the running application.

### cell preview

| Option | Description |
| --- | --- |
| `-p, --port <port>` | Listen port, defaults to `server.port` (3000); equivalent to setting `CELL_SERVER__PORT`. For `cloudflare` artifacts, passed to `wrangler dev --port`, default 8787 |
| `--out-dir <dir>` | Artifact directory, default `.cell/output` |

The artifact runs according to which preset built it: `node`, `cli`, `fc`, `scf`, `lambda` run `server/index.mjs` with Node.js (stdin/stdout inherited from the current terminal); `cloudflare` runs `wrangler dev`; `vercel` runs the function bundle with Node.js and serves the frontend from `static/`.

### cell deploy

| Option | Description |
| --- | --- |
| `--preset <name>` | Deploy to which platform: `cloudflare`, `fc`, `scf`, `lambda`, `vercel`; `node`, `cli` have no deployers and raise `CELL_DEPLOY_UNSUPPORTED` (checked before build) |
| `--dry-run` | Build and plan without uploading (`cloudflare`: `wrangler deploy --dry-run`; `fc` / `scf` / `lambda`: zip and check if function exists; `vercel`: list functions and static files) |
| `--skip-build` | Deploy existing artifacts in `--out-dir`. Raises `CELL_DEPLOY_OUTPUT_MISMATCH` if the artifact preset doesn't match `--preset` |
| `-m, --mode <mode>`, `--sourcemap`, `--out-dir <dir>` | Same as `cell build` |

Plan first, then apply. The plan lists resources to deploy (`resources`, each with `type`, `name`, `action`, `details`); `--dry-run` stops here. Then fire `deploy:before` (gate; command failures in hooks cancel deploy), `deploy:plan`, and `deploy:done` events. Deploy tool output (Wrangler, Vercel CLI) goes to stderr on `--json`. `--json` result: `preset`, `deployer`, `dryRun`, `plan`, and on actual deploy also `deployment` (`url` and `details.versionId`).

### Common options

| Option | Description |
| --- | --- |
| `--root <dir>` | Project root (default: current directory) |
| `--json` | stdout outputs one-line JSON result; other output (progress, hook command output) goes to stderr |
| `-h, --help` / `-v, --version` | Help or version |

Commands never prompt interactively. Exit codes: success 0, execution failure 1, usage error (unknown command, option, or value) 2.

## --json output

```json
{"schemaVersion":1,"command":"build","ok":true,"root":"/app","preset":"node","format":"esm","mode":["production"],"targets":["backend"],"outDir":".cell/output","entry":"@celljs/express-adapter/lib/node/http-application-entry","durationMs":480,"warnings":[]}
```

On failure:

```json
{"schemaVersion":1,"command":"build","ok":false,"error":{"code":"CELL_PRESET_NOT_FOUND","message":"Unknown preset 'nod'. Available: node.","hint":"Did you mean 'node'?","docs":"https://cell.cellbang.com/errors/cell-preset-not-found"},"warnings":[]}
```

`schemaVersion` remains constant; fields only grow and never change.

## cell.config.ts

Optional. Contains toolchain configuration only; application config (read by `@Value`) goes in `cell.yml`.

```ts
import { defineConfig } from '@celljs/cli';

export default defineConfig({
    preset: 'node',
    targets: ['frontend', 'backend'],
    modules: ['!@celljs/serve-static', { source: '@x/ui', runtime: false }],
    build: { format: 'esm', external: ['sharp'], sourcemap: false, outDir: '.cell/output' },
    vite: {},
    hooks: { 'build:before': 'prisma generate' },
});
```

| Field | Description |
| --- | --- |
| `preset` | Build output format. Priority: `--preset` → this field → `CELL_PRESET` → CI environment detection → `node` |
| `targets` | Build targets. Default is `backend` plus targets declared by components (installing `@celljs/react` adds `frontend` via `@celljs/widget`). Specifying this field overrides the default completely |
| `modules` | `'!package-name'` excludes a component (and dependencies only imported via it); `{ source, runtime: false }` excludes its DI module but keeps config; `{ source, toolchain: false }` excludes its toolchain module; local paths or package names specify additional toolchain modules (see below) |
| `build.format` | `esm` or `cjs` |
| `build.external` | Packages not to inline; copied to `server/node_modules` in dependency order |
| `build.sourcemap`, `build.outDir` | Same as command-line options |
| `build.single`, `build.compile` | Same as `--single` / `--compile` (`compile` can be `true`, `bun`, `node`, or `deno`) |
| `vite` | Merged into Vite config for each environment |
| `hooks` | Shell commands executed on toolchain events (see below) |

Other top-level fields are options for toolchain modules and must be objects. The file supports `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, and `.cjs` extensions; multiple files raise `CELL_CONFIG_AMBIGUOUS`. Command-line arguments take priority over the config file.

## Override configuration with environment variables

Any key already in `cell.yml` can be overridden with environment variables without editing:

```bash
CELL_SERVER__PORT=8080 cell preview      # Applied at server startup: server.port
CELL_APP__PUBLIC__API_BASE=/api cell build   # Applied at build time, reaches frontend: app.public.apiBase
```

After the `CELL_` prefix, use one underscore, then `__` between levels (e.g., `CELL_SERVER__PORT`). `CELL_PRESET`, `CELL_MODE`, `CELL_EVENT`, `CELL_OUT_DIR`, and `CELL_DEBUG` are toolchain variables, not treated as config. Single-segment variables that don't match top-level keys (like another tool's `CELL_REGION`) are ignored. Variables with `__` that don't match keys report an error; using the old `CELL__…` / `CELL_BACKEND__…` format suggests the correct format. `__` separates levels; one key can only be set by one variable. Variables are case-insensitive, and `_` / `-` are ignored. Values are converted by schema type or original value type (limited numbers in JSON notation, `true` / `false`, and objects/arrays as JSON). Values that are a single `${...}` are preserved until evaluation (e.g., `CELL_SERVER__PORT='${env.PORT}'`), taking effect before `${...}` evaluation. Only existing keys can be overridden. Non-existent or mistyped variables don't apply and warn: the server prints during startup; `cell build` and `cell info` also check. See [docs/design/config.md](https://github.com/cellbang/cell/blob/main/docs/design/config.md) for full rules.

## hooks

```ts
hooks: {
    'build:before': 'prisma generate',
    'output:done': 'cp extra/* "$CELL_OUT_DIR/server/"',
}
```

- Commands run in the shell from the project root and do not read stdin. PATH has project and parent `node_modules/.bin` at the front.
- Environment variables: `CELL_EVENT`, `CELL_PRESET`, `CELL_MODE` (comma-separated), and `CELL_OUT_DIR` (absolute output directory path).
- `cell dev` fires `modules:done` → `config:resolved` → `dev:ready`, then `dev:reload` on backend reload, and repeats after `close` on restart.
- `cell build` fires in order: `modules:done` → `config:resolved` → `build:before` → build → `output:done` → `close`.
- `build:before` is a gate event: non-zero exit cancels the build (`CELL_BUILD_CANCELLED`). Non-zero exit in other events raises `CELL_HOOK_FAILED`.
- Only string commands are accepted. Extensions requiring code or event modification (like `build:done` or `deploy:plan`) should be written as toolchain modules.

## toolchain modules

Write extensions that require code as toolchain modules: export a factory function that, given `cell`, registers capabilities (see [docs/design/modules.md](https://github.com/cellbang/cell/blob/main/docs/design/modules.md) for design details).

```ts
// modules/audit.ts, write modules: ['./modules/audit'], audit: { url: '...' } in cell.config.ts
import type { CellAPI } from '@celljs/kit';

export default function (cell: CellAPI) {
    const { url } = cell.options('audit', { url: 'http://localhost:9000' });
    cell.addVitePlugin({ name: 'audit', transform: code => code }, { env: 'server' });
    cell.on('build:done', event => {
        event.files['audit.json'] = JSON.stringify({ url, targets: event.project.targets });
    });
}
```

- Load order is fixed: components in dependencies (package.json's `cell.toolchain`, by dependency order) → `cell.config.ts` `modules` (local paths or package names, in order). `{ source, toolchain: false }` disables a component's module; `'!package-name'` removes the component too.
- The factory only registers; it doesn't start processes, ports, listeners, or timers. `cell info` also executes the factory.
- Top-level fields in `cell.config.ts` besides `preset`, `targets`, `modules`, `build`, `vite`, and `hooks` are module options and must be objects. Each must be claimed by some module via `options()` or `addConfigSchema()`, raising `CELL_CONFIG_UNKNOWN_OPTION` (with spelling suggestions) if not. `addConfigSchema` accepts Standard Schema (zod, valibot, etc.); invalid schemas raise `CELL_CONFIG_INVALID`.
- Factory errors raise `CELL_MODULE_ERROR` (with module name); non-function default export raises `CELL_MODULE_INVALID`. Notification-type event handlers that error in `cell dev` report without interrupting; any handler that fails in `cell build` stops the build.
- Each module's registrations are listed in `cell info --json` under `toolchainModules`.

| API | Purpose |
| --- | --- |
| `command`, `mode`, `dev`, `ci`, `root`, `preset`, `components`, `logger` | Read-only info. `preset` is the name from command-line / config / environment; resolved preset is in the `config:resolved` event |
| `options(key, defaults)`, `addConfigSchema(key, schema)` | Read and claim `key` from `cell.config.ts` (only callable synchronously in the factory) |
| `updateConfig({ build: { external }, vite })` | Append external packages; merge Vite config below the project's config (project takes priority). Application config remains in the component's `cell.yml` |
| `addVitePlugin(plugin, { env })` | Add a Vite plugin. `env` as `client` / `server` applies only to frontend / backend |
| `addRuntimeModule(path, { target, static })`, `addVirtualModule(id, code)`, `setEntry(target, path)` | Append a DI module, provide a virtual module, or specify entry |
| `addDevHandler(path, handler)`, `addWatchFile(path)` | In `cell dev`, handle a path before the backend; restart on file changes |
| `addPreset(preset)`, `addOutputFile(path, content)` | Register a preset (participates in `--preset` and CI detection); write a file to the output directory after build (`build:done` `event.files` can add/remove/modify) |
| `addCheck(def)`, `addMcpTool(def)`, `addDocs(dir)` | Supply tools for `cell check`, `cell mcp`, and `cell docs` |
| `on(event, handler)`, `events` | Subscribe to toolchain events (composition rules in modules.md §3.2); event bus for inter-module communication |
| `exec(cmd, args, opts)`, `resolve(spec)` | Run commands without shell; resolve modules from the project root |

## Error codes

All failures output as `CellError { code, message, file?, line?, hint, docs }`, with `code` stable within 4.x.

| Error code | Meaning |
| --- | --- |
| `CELL_ARGUMENT_INVALID` | Unknown command, option, or value (exit code 2) |
| `CELL_PROJECT_NOT_FOUND`, `CELL_PACKAGE_JSON_INVALID` | No package.json in root, or a package.json cannot be read |
| `CELL_CONFIG_LOAD`, `CELL_CONFIG_AMBIGUOUS` | `cell.config.ts` load or execution failure, multiple config files exist |
| `CELL_CONFIG_INVALID`, `CELL_CONFIG_CONFLICT` | Config field error (with field path and suggestions), option conflicts |
| `CELL_CONFIG_PARSE`, `CELL_CONFIG_NOT_OBJECT`, `CELL_CONFIG_EXPRESSION` | `cell.yml` not valid YAML, top level not a mapping, `${...}` expression error |
| `CELL_CONFIG_INVALID` (cell.yml) | Top-level key with no owner, option not in component, type mismatch; with file, line, suggestions; put custom config under `app` |
| `CELL_CONFIG_KEY_CONFLICT`, `CELL_CONFIG_SCHEMA_INVALID` | Two components' `cell.schema.json` declare same key, schema uses unsupported keywords, or project schema declares keys outside `app` |
| `CELL_COMPONENT_NOT_FOUND`, `CELL_LOCAL_MODULE_NOT_FOUND` | Component or local module in `modules` not found |
| `CELL_MODULE_NOT_FOUND`, `CELL_CORE_NOT_FOUND` | DI module declared by component cannot resolve, project doesn't depend on `@celljs/core` |
| `CELL_ROUTE_CONFLICT`, `CELL_ROUTE_INVALID` | Two files in `src/browser/pages` map to same path (`about.tsx` and `about/index.tsx`), filename not valid path segment |
| `CELL_CORE_EL_MISSING` | Project's `@celljs/core` predates 4.1.0, missing `@celljs/core/el` entry for build-time config evaluation |
| `CELL_PRESET_NOT_FOUND`, `CELL_PRESET_DUPLICATE`, `CELL_PRESET_CYCLE` | Preset not found, duplicate name, `extends` cycles |
| `CELL_BUILD_FAILED` | Build failed, with error file and location |
| `CELL_BUILD_CANCELLED`, `CELL_HOOK_FAILED` | Hook or module cancelled build, hook command failed |
| `CELL_MODULE_ERROR`, `CELL_MODULE_INVALID` | Toolchain module factory or handler error, default export not a factory |
| `CELL_CHECK_FAILED`, `CELL_DI_MODULE_FAILED` | A check had internal error, `cell check` failed loading backend DI module |
| `CELL_SECURITY_*`, `CELL_SECURITY_CHECK_FAILED` | Unsafe production settings (reported as warnings by `cell check` `security`); production startup refuses with `securityChecks: fail` |
| `CELL_CONFIG_UNKNOWN_OPTION` | `cell.config.ts` has option fields unclaimed by any module |
| `CELL_DEV_FAILED`, `CELL_DEV_BACKEND_FAILED`, `CELL_DEV_START_TIMEOUT` | `cell dev` cannot start (port, etc.), backend startup failed, backend entry timeout without ready |
| `CELL_DEV_BACKEND_NOT_RUNNING` | dev MCP tool requires running backend, but backend failed or not started |
| `CELL_CONFIG_KEY_NOT_FOUND` | `cell config get` / `get_config` key doesn't exist |
| `CELL_COMPILE_TOOL_MISSING`, `CELL_COMPILE_FAILED` | `--compile` requires bun / deno / node not found, compiler error (last few lines of output) |
| `CELL_COMPILE_EXTERNALS`, `CELL_COMPILE_NO_SERVER` | Packages left outside bundle, project has no backend to compile |
| `CELL_TEMPLATE_NOT_FOUND`, `CELL_INIT_NOT_EMPTY` | `cell init` template not found, target directory non-empty |
| `CELL_UNSUPPORTED` | Using a feature not yet available |
| `CELL_OUTPUT_NOT_FOUND`, `CELL_PREVIEW_NO_SERVER` | No build before `cell preview` / `cell deploy --skip-build`, output has no server |
| `CELL_DEPLOY_UNSUPPORTED`, `CELL_DEPLOY_OUTPUT_MISMATCH`, `CELL_DEPLOYER_NOT_FOUND` | Preset has no deployer, existing artifact not from this preset, deployer not found |
| `CELL_DEPLOY_PLAN_FAILED`, `CELL_DEPLOY_FAILED`, `CELL_DEPLOY_CANCELLED` | Plan failed (e.g., build failed), deploy failed (hint shows how to set credentials), hook or module cancelled deploy |
| `CELL_DEPLOY_CREDENTIALS_MISSING`, `CELL_DEPLOY_UNAUTHORIZED` | No cloud credentials, credentials invalid or insufficient permissions |
| `CELL_DEPLOY_API_ERROR`, `CELL_DEPLOY_NETWORK`, `CELL_DEPLOY_TIMEOUT`, `CELL_DEPLOY_PACKAGE_TOO_LARGE` | Cloud API error (with cloud error code and request ID), cannot reach cloud API, function timeout, code package exceeds direct upload limit |
| `CELL_CLOUDFLARE_CONFIG_INVALID`, `CELL_CLOUDFLARE_CONFIG_UNSUPPORTED`, `CELL_CLOUDFLARE_COMPATIBILITY_DATE` | `wrangler.json(c)` not valid JSON or field type wrong, using `wrangler.toml`, `compatibility_date` before `2026-03-17` |
| `CELL_INTERNAL_ERROR` | Cell or module defect; set `CELL_DEBUG=1` to see stack trace |

## Testing: createTestApp

```ts
import { createTestApp } from '@celljs/cli';

const app = await createTestApp({ root, mode: ['extra'] });   // mode always has test in front
const res = await app.fetch('/users', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
const { UserService } = await app.import('/src/user-service.ts');   // the backend-loaded module
app.get(UserService);                                         // object from DI container
await app.close();                                            // stop application (onStop)
```

In `app.get(X)`, importing a class or `Symbol('X')` from project source gives a different module instance than the app uses (app runs in Vite's module runner), matched by class name or symbol description; raises `CELL_DI_NO_BINDING` / `CELL_DI_AMBIGUOUS` if missing or duplicate. To get the app's version (on duplicates, or to use other exports from the module), use `app.import()`: project files as `/src/...`, packages as package name. Classes with `@Value` / `@Autowired` must come from `app.import()`: importing these in the test file, then resolving by name, fails (raises `CELL_DI_NO_BINDING`).

In the test process, backend loads from source like `cell dev` does, no build or port listening; requests go through the complete HTTP handler chain via in-memory req/res objects, `fetch` returns standard `Response`. Startup failure throws `CellError` (like `CELL_DEV_BACKEND_FAILED`, with error file); backend without HTTP entry raises `CELL_TEST_APP_NO_HTTP` on `fetch`.

## Programming interface

```ts
import { CellCli } from '@celljs/cli';

const code = await new CellCli({ stdout, stderr, env }).run(['build', '--json']);
```

Also exports `defineConfig`, `ConfigResolver`, `PresetRegistry`, `DeployerRegistry`, `EventBus`, `HookRunner`, etc., for testing and tool writing.

<!-- https://cell.cellbang.com/agent-guide (dev-packages/cli/agent/guide.md) -->

# Cell

This project uses Cell 4.8.0: TypeScript with dependency injection, MVC controllers on Node's `http` server, and the `cell` toolchain (Vite). This guide matches the installed version; `npx cell agent sync` rewrites it after an upgrade.

## Layout

- `src/node/` is the backend, `src/browser/` the frontend, `src/common/` code for both. `src/<node|browser>/module.ts` is the DI module of its side: it imports every file that has components and ends with `export default autoBind();`. A file it does not import is not loaded.
- `cell.yml` holds the application configuration: keys of the components at the top level (`server.port`), your own under `app`; only keys marked public and `app.public` reach the browser; a wrong key is a `CELL_CONFIG_INVALID` error. `cell.<mode>.yml` adds to it per mode (`development` in `cell dev`, `production` in `cell build`, `test` in tests, more with `-m <mode>`).
- `cell.config.ts` (optional) configures the toolchain only: `preset`, `modules`, `build`, `vite`, `hooks`. Application configuration never goes there.
- A dependency whose package.json has a `cell` field is a component: installing it is enough, its DI modules and `cell.yml` load automatically. Keep every `@celljs/*` package on the same version.

## Writing code

- Services: `@Component()` on the class, `@Autowired(Type)` on a property to inject. For an interface, export a `Symbol` with the same name and bind the class with `@Component(Symbol)`.
- Configuration: `@Value('app.key')` reads your keys under `app` in `cell.yml`, `@Value('server.port')` a key of a component. `${env.NAME ?? 'default'}` is evaluated at startup and converted to the key's schema type. `CELL_SERVER__PORT=8080` overrides an existing key. `npx cell config get <key> --why` tells the owner and whether the frontend sees it.
- HTTP: `@Controller('path')` with `@Get()`, `@Post()`, `@Put(':id')`, `@Delete(':id')` from `@celljs/mvc/lib/node`; parameters `@Param('id')`, `@Query('q')`, `@Body()`. Returned objects are JSON; add `@Text()` for text. `String`, `Number`, `Boolean` and `Date` parameters are converted. To validate a body, add `@celljs/validation` (with `class-validator`) to the dependencies and type the `@Body()` parameter with a class that has class-validator decorators: invalid bodies get 400.
- API docs: add `@celljs/openapi` to the dependencies; the app serves the OpenAPI document at `/openapi.json` and Swagger UI at `/api-docs`, built from the routes, parameter and return types and class-validator decorators. Async methods and arrays need `@ApiResponse({ type: [Pet] })`; properties without class-validator decorators need `@ApiProperty()`.
- gRPC: add `@celljs/grpc`; `Proto.parse(source).service('pkg.Service')` from the `.proto` text (`import source from './x.proto?raw'`), `@GrpcService(Service)` on the class implementing its methods in lowerCamelCase (streams are async iterables), `new GrpcChannel('host:50051').createClient(Service)` to call one. Throw `GrpcError(GrpcStatus.X, 'details')` for statuses. The server listens on `grpc.server.port` (50051).
- Errors: throw `HttpError(status, message)` or `NotFoundError(message)` from `@celljs/web/lib/node` for a status; other errors answer 500. `@Catch(ErrorType)` on a controller method handles that type for the controller; an `@Component(ErrorHandler)` with `priority` above 2000 for the whole app.
- Middleware: `@Component(Middleware)` implementing `handle(ctx, next)` and `priority` (`@celljs/web/lib/node`); `Context.getRequest()` gives the current request anywhere.
- Startup and shutdown work: `@Component(ApplicationLifecycle)` with `onStart` / `onStop`, not constructors. Logging: `@Autowired(Logger)`.
- Payments: `@celljs/wechat-pay` (WeChat Pay API v3), `@celljs/alipay` (Alipay gateway) and `@celljs/stripe` (with the official `stripe` package) inject a client (`WechatPayClient`, `AlipayClient`, `StripeClient`) configured under `backend.wechatPay` / `alipay` / `stripe` with `${env.X}` secrets, and serve a notification endpoint (`/wechat-pay/notify`, `/alipay/notify`, `/stripe/webhook`) that verifies signatures and runs `@WechatPayNotificationHandler('TRANSACTION.SUCCESS')`, `@AlipayNotificationHandler('TRADE_SUCCESS')` or `@StripeWebhookHandler('checkout.session.completed')` components. Handlers must be idempotent; throwing makes the provider retry. WeChat amounts are integers in fen, Alipay amounts strings in yuan.
- Frontend and backend: `@Rpc(Symbol)` on the backend class, `useRpc<T>(Symbol)` (`@celljs/react`) in a frontend component, `@Autorpc(Symbol)` in a frontend DI component. With `rpc.transport: websocket` the backend calls `@RpcClient(Symbol)` components of the frontend through `RpcContext.requireConnection().client<T>(Symbol)` (`@celljs/rpc/lib/node`).
- Frontend pages are files of `src/browser/pages/` with the component as default export (`users/[id].tsx` is `/users/:id`, `_layout.tsx` wraps a directory); do not import them anywhere. Router hooks and `Link` come from `@celljs/react`.
- React components get frontend DI components with `useInject<T>(Id)` and configuration with `useValue(key)` from `@celljs/react`; there is no global container. A page that throws shows the nearest `src/browser/pages/_error.tsx` inside its layout. Tests render a component inside `<ContainerContext.Provider value={container}>`.
- Packages for common needs: database `@celljs/typeorm` (+ driver; `autoBindEntities`, `OrmContext`, `@Transactional()`), cache `@celljs/cache`, cron `@celljs/schedule`, login `@celljs/security`, tokens `@celljs/jwt`, outgoing HTTP `@celljs/http`, LLMs `@celljs/ai-core` + `@celljs/ai-pi`, payments (above). Read a package's docs with `npx cell docs <package or topic>` before using it.

## Verify

- `npx cell check --json` checks types, configuration, decorator settings and DI bindings. Every issue has `code`, `file`, `line` and a `hint`. Run it after each change.
- Tests run with `bun test`; `createTestApp()` from `@celljs/cli` starts the application in the test process:

  ```ts
  const app = await createTestApp({ root: join(__dirname, '..') });
  const res = await app.fetch('/todos', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
  const { TodoService } = await app.import('/src/node/todo-service.ts');   // classes from app.import(), not from a test import
  const service = app.get(TodoService);
  await app.close();
  ```

- `npx cell dev` runs the application and reloads it on save; `npx cell build` builds into `.cell/output` (`--single`: one file, `--compile`: one executable); `npx cell preview` runs the build.
- `npx cell deploy --preset <cloudflare|fc|scf|lambda|vercel> --dry-run` builds and shows what a deployment would change, without credentials. Platform options go in `cell.config.ts` under the preset's name (`fc: { region: 'cn-shanghai' }`); credentials come from environment variables. Leave the real `cell deploy` to the user unless asked.

## Find out

- `npx cell info --json`: components, DI modules, entries, preset, hooks, output.
- `npx cell config get <key> --why`: a merged configuration value and the files and variables that set it.
- `npx cell docs <words>`: the docs of the installed Cell packages and the Cell guides (configuration, DI, HTTP, RPC, testing, deployment), in the installed versions.
- `npx cell mcp` serves these as MCP tools. While `cell dev` runs, `http://127.0.0.1:<port>/_cell/mcp` has `get_errors`, `list_routes`, `list_bindings`, `get_config`, `recent_requests` and `logs` of the running application.
- Errors read `[CELL_CODE] message`, then `fix:` and a docs link: do what the fix says.

<!-- https://cell.cellbang.com/migration-4 (docs/migration-4.en.md) -->

# Migrating from Cell 3.x to 4.0

This guide is for existing Cell 3.x projects and describes the changes required when upgrading to 4.0. The 4.0 toolchain is completely redesigned (see [design/architecture.md](https://github.com/cellbang/cell/blob/main/docs/design/architecture.md)) and is **not backward compatible with 3.x commands, hooks, config expressions, or output directories, with no compatibility layer provided**. Review each section below and apply the necessary changes. The runtime API (`@Component`, `@Autowired`, `@Value`, MVC, RPC, typeorm, etc.) remains unchanged, so business code generally requires no modification.

## 0. Capabilities included in 4.0

| Capability | Status |
| --- | --- |
| `cell dev`, `cell build`, `cell info`, `cell preview`, `cell.config.ts`, `hooks`, `--json` | Available |
| `node` preset (Node.js HTTP service) | Available, default |
| `cell check` | Available |
| `cell mcp`, `cell dev` `/_cell/mcp` endpoint, `cell config get`, `cell docs` | Available |
| `cloudflare` preset and `cell deploy` (Cloudflare Workers) | Available, see [@celljs/cli README](https://cell.cellbang.com/cli#cloudflare) |
| Cloud platform presets and `cell deploy` (fc / scf / lambda / vercel) | Available, see [@celljs/cli README](https://cell.cellbang.com/cli#fc-scf-lambda) |
| `--single`, `--compile` single-file and executable | Available |
| `cell init` and project templates (`backend`, `fullstack`), `cell agent sync` | Available |
| Override any config key with environment variables (`CELL_*`) | Available |
| In-process test utility `createTestApp()` (`@celljs/cli`) | Available |

## 1. Environment

- Node.js `^20.19.0 || >=22.12.0` (Vite 8 requirement). The built service bundle runs on Node.js 18+, Bun 1.2+, and Deno 2 (fc and scf images use older Node.js). Runtime packages have `engines` set to `>=18.0.0` (those based on pi—`ai-pi`, `ai-agent`, `ai-coding-agent`, `tui`—require `>=22.19.0`).
- Package manager is flexible. The repository itself is developed with Bun.

## 2. Dependencies

```jsonc
{
  "dependencies": {
    "@celljs/core": "^4.0.0",
    "@celljs/express-adapter": "^4.0.0",   // New: provides HTTP entry point
    "@celljs/mvc": "^4.0.0"
  },
  "devDependencies": {
    "@celljs/cli": "^4.0.0"                // Install locally, no longer global
  }
}
```

- **Add `@celljs/express-adapter`.** In 3.x, the HTTP entry point was implicitly provided by a runtime plugin. In 4.0, the preset selects an entry by name (the `node` preset uses `http`) from the `cell.entries` declared by components. This entry is provided by `@celljs/express-adapter`. If missing, `cell build` will issue a warning, and the bundle will not listen on a port when started.
- **Remove** `@celljs/cli-service`, `@celljs/cli-common`, `@celljs/cli-runtime`, `@celljs/dev-server`, `@celljs/frameworks`, `@celljs/testing`, and `@celljs/*-plugin`, along with dependencies that only served webpack (various `*-loader`, `mini-css-extract-plugin`, babel, etc.).
- When using Sass / Less / Stylus, install the preprocessor yourself (e.g., `sass`); Vite will detect and use it.
- For native dependencies with install scripts (e.g., `better-sqlite3`), ensure your package manager runs their install script (Bun requires them in `trustedDependencies`). Otherwise, the build may succeed but runtime will fail with a `.node` file not found error.

## 3. Commands

| 3.x | 4.0 |
| --- | --- |
| `cell serve` | `cell dev`: frontend and backend share one port, frontend HMR enabled, backend auto-reloads on file changes, auto-restarts on `cell.yml` / `cell.config.ts` / `package.json` changes |
| `cell build -m prod` | `cell build -m prod` |
| Run `.cell/dist/backend/index.js` | `cell preview`, or `node .cell/output/server/index.mjs` directly |
| `cell deploy -m fc` | `cell deploy --preset fc` (also `scf`, `lambda`, `vercel`, `cloudflare`; `--dry-run` shows the plan). 3.x platform configs like `cell.fc.yml` become `fc: { region, memory, ... }` in `cell.config.ts`; credentials are read from environment variables, not from `~/.cell` or profile files |
| `cell init` | `cell init <template> <dir>`: new templates `backend` and `fullstack` (React + RPC) include `AGENTS.md` and `.mcp.json` by default; 3.x templates are no longer provided |
| `cell props` / `cell config` / `cell update` / `cell runtime` | Removed. Use `cell info` to view project and config (`--app-config` outputs merged `cell.yml`); use `cell config get <key> --why` for a specific config key and its origin |

All commands support `--json`: stdout outputs a single line containing `schemaVersion`; exit code is 1 on failure, 2 for usage error. See [@celljs/cli README](https://cell.cellbang.com/cli) for full documentation.

## 4. Output

| 3.x | 4.0 |
| --- | --- |
| `.cell/dist/backend/index.js` (webpack, CommonJS) | `.cell/output/server/index.mjs`: a single file with all dependencies inlined (`index.cjs` with `--format cjs`) |
| `.cell/dist/frontend/` | `.cell/output/public/` |
| `npm install` external dependencies before deploy | Only native modules, `build.external`, and optional dependencies declared by components are copied into `server/node_modules` |
| — | `.cell/output/manifest.json`: preset, format, entry, for `cell preview` and deployers to read |
| — | `.cell/generated/`: DI assembly code, merged config, project model for troubleshooting |

`.cell/output` can be copied entirely to another location and run independently of the project's `node_modules` (see [examples/docker-app](https://github.com/cellbang/cell/tree/main/examples/docker-app/Dockerfile) for a Dockerfile example). The port comes from `server.port` (default 3000), and the bind address comes from `server.host` (default `127.0.0.1`; use `0.0.0.0` in containers); both can be overridden with environment variables (see 5.3). 3.x `SERVER__PORT` and `SERVER__HOST` no longer work; use `CELL_SERVER__PORT` and `CELL_SERVER__HOST` instead.

Add `.cell` to `.gitignore`.

## 5. Config Files

4.0 divides config into two categories with non-overlapping responsibilities:

| File | Content |
| --- | --- |
| `cell.yml`, `cell.<mode>.yml` | Application config, the values read by `@Value` |
| `cell.config.ts` (optional) | Toolchain config: `preset`, `targets`, `modules`, `build`, `vite`, `hooks` |

### 5.1 Content to remove from `cell.yml`

| 3.x usage | 4.0 |
| --- | --- |
| `mode: [database]` | Remove. Mode comes from command line only (`cell build -m database`); write this in your package.json `build` script |
| `targets: [backend]`, `entry: ...` | Remove. The default target is `backend`, plus targets from component declarations (installing `@celljs/react` adds a frontend target via `@celljs/widget`); to change this, use `targets` in `cell.config.ts` |
| `webpack:`, `devServer:`, `webpackHooks`, `serveHooks` | Remove. Modify Vite config using the `vite` field in `cell.config.ts` |
| `cell.webpack.filterWarningsPlugin` (optional dependency) | Declare in `cell.optionalDependencies` in package.json; if unresolved, it is automatically externalized |
| `cell-test.yml` and similar mode files | Only `cell.<mode>.yml` (e.g., `cell.test.yml`) is recognized; rename any `cell-<mode>.yml` files |

`cell build` automatically includes `production` mode; `cell dev` includes `development`. Write environment-specific differences in `cell.production.yml` and `cell.development.yml`. Merge order: component `cell.yml` (by dependency order) → project `cell.yml` → mode files (by `-m` order). Objects are deep-merged; arrays are replaced entirely.

### 5.2 Structure of `cell.yml`

Complete rules in [docs/design/config.md](https://github.com/cellbang/cell/blob/main/docs/design/config.md); key points:

- **No `cell:` level, no `frontend:` or `backend:` sections.** Component config keys go at the top level (`server.port`, `security.username`); your own config goes under `app` and is read with `@Value('app.greeting')`.
- **Config defaults to server-only.** The browser receives only keys marked `x-cell-public` in the component's `cell.schema.json` and `app.public`; custom config from 3.x `frontend:` sections moves to `app.public`.
- **Wrong keys cause an error** (`CELL_CONFIG_INVALID`, including file and line number): top-level keys with no owner, missing component options, or type mismatches.
- 3.x key mapping:

  | 3.x | Now |
  | --- | --- |
  | `cell.<key>` | `<key>` (e.g., `cell.server.port` becomes `server.port`) |
  | `cell.name`, `cell.hostDomId` | `html.title`, `html.rootId` |
  | `cell.annotation.Component` | `component` |
  | `cell.client.config` | `http.client` |
  | `cell.session`, `cell.cookies`, `cell.trace`, `cell.health` | `web.session`, `web.cookies`, `web.trace`, `web.health` |
  | `cell.mustache` | `mvc.mustache` |
  | `cell.serve-static` | `serveStatic` |
  | `cell.locales`, `cell.themes` | `widget.locales`, `widget.themes` |
  | Custom `cell.<key>` | `app.<key>` (place shared frontend config in `app.public`) |

### 5.3 Expressions and Environment Variables

- Only `${...}` interpolation is preserved; context is `{ ...config, env }`: `${env.DB_HOST ?? 'localhost'}`, `${server.path}`. Use `??` for default values (`?:` is no longer an operator). Empty environment variables are treated as unset; values do not need quotes.
- When a key's schema type is number or boolean, the expression's text result is automatically converted to that type: `port: ${env.DB_PORT ?? 5432}` no longer needs `* 1`.
- **Backend evaluates at runtime**: the same bundle can be deployed to multiple environments without exposing secrets in the output. The frontend evaluates at build time. Removed `onTarget`, `cliContext`, `currentMode`, and other build-only context variables; use mode files for environment differences.
- Expression results are not re-evaluated: if an environment variable contains `${...}`, it is used as-is. Write `${env.X | eval}` explicitly to enable re-evaluation.
- Any existing key can be overridden with a `CELL_`-prefixed environment variable without modifying the file:

  ```bash
  CELL_SERVER__PORT=8080 node server/index.mjs            # server.port
  CELL_SERVER__HOST=0.0.0.0                                # server.host
  CELL_TYPEORM__ORM_CONFIG__0__HOST=db.internal            # typeorm.ormConfig[0].host
  CELL_APP__PUBLIC__API_BASE=https://api.example.com cell build   # frontend app.public.apiBase
  ```

  `__` separates levels; matching is case-insensitive and ignores `_` and `-`; array elements use standard indices. You can only override existing keys. Values are converted by schema type or inferred type (numbers use JSON syntax, booleans accept only `true` or `false`, objects and arrays use JSON). If the entire value is `${...}`, it remains as-is until evaluation (e.g., `CELL_SERVER__PORT='${env.PORT}'`). Each key can be set by only one variable; conflicts are ignored. Variables are applied at server startup; `cell build` also applies them before extracting public keys. Ineffective variables: the backend logs `[cell] CELL_… is ignored: …` to stderr; `cell build`, `cell info`, and `cell check` report them. 3.x `SERVER__PORT` and early 4.0 `CELL_BACKEND__` and `CELL_FRONTEND__` no longer work (will be reported with the correct form suggested). The prefix is followed by a single underscore, with levels separated by `__` (e.g., `CELL_SERVER__PORT`). `CELL_PRESET`, `CELL_MODE`, `CELL_EVENT`, `CELL_OUT_DIR`, and `CELL_DEBUG` are toolchain variables, not config variables; single-segment variables that are not top-level keys (e.g., another tool's `CELL_REGION`) are ignored; variables with `__` that do not match a key are reported, with suggestions provided if written as old `CELL__…` or `CELL_BACKEND__…`.
- The backend also has `paths.public`: the frontend output directory (default `public`, relative to `.cell/output`); `serve-static` uses `root: ${paths.public}` and can be overridden with `CELL_PATHS__PUBLIC=/srv/www`.

### 5.4 `cell.config.ts`

```ts
import { defineConfig } from '@celljs/cli';

export default defineConfig({
    preset: 'node',                                   // default node; also --preset, CELL_PRESET
    targets: ['frontend', 'backend'],                 // usually not needed
    modules: ['!@celljs/serve-static'],               // exclude a component
    build: { format: 'esm', external: ['sharp'], sourcemap: true },
    vite: { resolve: { alias: { '~': '/src' } } },    // merge into Vite config
    hooks: { 'build:before': 'prisma generate' },
});
```

Configuration is validated item by item after loading; typos report `CELL_CONFIG_INVALID` with the field path and suggestions. Application config must not be in `cell.config.ts`.

## 6. Hooks

3.x convention file hooks (`src/hooks/webpack.ts`, `serve.ts`, `deploy.ts`, `build.ts`, etc.) no longer work:

- **Run commands before or after build**: write them in `cell.config.ts` `hooks`. Commands run in the project root with `node_modules/.bin` in PATH and environment variables `CELL_EVENT`, `CELL_PRESET`, `CELL_MODE`, and `CELL_OUT_DIR`. Failed commands in `build:before` cancel the build. Subscribable events are: `modules:done`, `config:resolved`, `build:before`, `output:done`, `close`, plus `dev:ready` and `dev:reload` for `cell dev`, and `deploy:before`, `deploy:plan`, `deploy:done` for `cell deploy`.
- **Change webpack config**: use the `vite` field in `cell.config.ts` or write a Vite plugin.
- **Extensibility requiring code logic** (changing output, registering presets, etc.): write a toolchain module (a factory function; see [design/modules.md](https://github.com/cellbang/cell/blob/main/docs/design/modules.md)). Local modules go in `cell.config.ts` `modules` (TypeScript does not need pre-compilation); see [@celljs/cli README](https://cell.cellbang.com/cli#toolchain-modules) for available capabilities.

For example, in a Prisma project (see [examples/prisma-app](https://github.com/cellbang/cell/blob/main/examples/prisma-app/cell.config.ts)):

```ts
hooks: {
    'build:before': 'prisma generate',
    // After inlining, the Prisma client looks for schema and query engine beside server/index.mjs
    'output:done': 'cp prisma-client/schema.prisma prisma-client/libquery_engine-* "$CELL_OUT_DIR/server/"',
}
```

## 7. Testing

`@celljs/testing` (`Test.createHttpServer()`, `Test.createContainer()`) has been removed; use `@celljs/cli` `createTestApp()` instead. It starts the backend from source in the test process (DI container and HTTP handler chain), without building or listening on a port. `cell.config.ts`, toolchain modules, and preset entries work the same as in `cell dev`, and the mode is `test` (reading `cell.test.yml`).

```ts
import { afterAll, beforeAll, expect, it } from 'bun:test';
import { createTestApp, type TestApp } from '@celljs/cli';

let app: TestApp;
beforeAll(async () => (app = await createTestApp()));   // project root defaults to current directory; can be passed as argument
afterAll(() => app.close());

it('lists users', async () => {
    const res = await app.fetch('/users');                // standard Response; init works like fetch
    expect(await res.json()).toEqual([]);
});
```

- `app.fetch(path, init)` supports methods, headers, and request body; the response preserves status, redirects, and multiple `Set-Cookie` headers (without following redirects).
- `app.container` and `app.get(id)` get objects from the DI container.
- To test only DI and services without HTTP, use `ApplicationFactory.createContainer({}, AppModule)` (see [examples/standalone-app/test](https://github.com/cellbang/cell/blob/main/examples/standalone-app/test/app.service.spec.ts) for an example).
- `@celljs/cli` is ES module only. CommonJS projects (without `"type": "module"` in package.json) that import it in TypeScript require `module` and `moduleResolution` in tsconfig to be set to `nodenext` (TypeScript ≥ 5.8, treating `require(esm)` as Node 22 does); otherwise, TS1479 error occurs.
- Change tests using supertest to use `app.fetch` (see [examples/backend-app/test](https://github.com/cellbang/cell/blob/main/examples/backend-app/test/home-controller.spec.ts) for an example).

## 8. Component Authors

All component declarations are in the package.json `cell` field; `cell.yml` holds only default application config:

```jsonc
{
  "cell": {
    "modules": { "backend": ["lib/node/module"] },          // DI runtime modules (frontend and backend)
    "staticModules": { "frontend": ["lib/browser/static-module"] },
    "targets": ["frontend"],                                  // additional targets to build when this component is installed
    "entries": { "http": "lib/node/http-application-entry" }, // named backend entries; selected by preset by name
    "optionalDependencies": ["pg-native"],                    // dependencies that might not be installed; externalized if unresolved
    "toolchain": "lib/cell-module"                            // toolchain module
  }
}
```

- Remove `src/hooks` and `cell.remote.yml` from components, along with `targets`, `entry`, and `webpack` from `cell.yml`.
- Framework packages are built as ES modules; at pack time, the `import` condition in `exports` resolves to `esm/`.

## 9. Post-Migration Checklist

1. `cell info` shows no `warnings` (also check with `CELL_*` variables set as they would be in the deployment environment); `targets` and `components` match expectations (typos in mode will show up here).
2. `cell build --json` outputs `"ok": true` with no `warnings`; `entry` is `@celljs/express-adapter/lib/node/http-application-entry` (or your chosen entry).
3. After `cell preview`, verify that endpoints and pages work correctly.
4. Copy `.cell/output` to an empty directory outside the project; run with `node server/index.mjs` and verify it does not depend on the project's `node_modules`.
5. When using native modules or runtime file-reading libraries (Prisma, sqlite driver, etc.), verify that needed files are in `server/` or `server/node_modules`.

## 10. Changes after 4.0.0 (unreleased, merged into main)

These changes provide no compatibility layer; review each one when upgrading:

- **Removed packages**: `@celljs/config`, `@celljs/rpc-core`, `@celljs/ai-openai`, `@celljs/ai-anthropic`, `@celljs/ai-ollama`, `@celljs/ai-deepseek`, `@celljs/shell`, `@celljs/grommet`, and `@celljs/vue`. Use [`@celljs/ai-pi`](https://cell.cellbang.com/packages/ai-pi) for all models (model name format: `pi:<provider>/<model>`); use `@celljs/react` for the frontend.
- **`@celljs/security` no longer includes built-in users.** Applications relying on the built-in `admin` account (which has been impossible to log in with since 2022) must configure their own users: set `security.username` and `password` in `cell.yml` (using hashes from `PasswordEncoder`), or bind your own `UserService` (see [@celljs/security](https://cell.cellbang.com/packages/security#users)). Startup will warn if there is no user source.
- **Password hash upgrades are irreversible.** Hashes from 4.0.x still verify correctly; when `UserService` implements `updatePassword()`, a user's hash is upgraded to the new format (`pbkdf2-sha256$…`) after a successful login. Rolling back to 4.0.x after the upgrade makes that user unable to log in.
- **HTTP Basic** now authenticates correctly (all passwords failed in 4.0.x); it is still off by default. It calculates PBKDF2 per request (~45 ms), making it suitable only for low-frequency machine-to-machine calls.
- **OpenID Connect**: the ID Token must include the nonce from the authorization request, or it is rejected as `invalid_nonce`; each authorization response is accepted only once.
- **Access log defaults off**: each request's `starting` and `ending` logs have been moved to debug level. To see them, set `logger.level: debug` (or `CELL_LOGGER__LEVEL=debug`).
- **`cell.yml` structure changed**: the `cell:` level and `frontend:` and `backend:` sections have been removed; component key ownership is now declared and validated in `cell.schema.json`; your config goes in `app`; only public keys reach the frontend; `?:` becomes `??`; environment variables all use `CELL_` prefix. Key mapping in [5.2](#52-structure-of-cellyml).
- **`mysql2` now requires manual install**: it is now an optional peer dependency of `@celljs/typeorm`; install the driver for your database. If missing, startup reports `CELL_TYPEORM_DRIVER_MISSING` with the install command.

<!-- https://cell.cellbang.com/packages/kit (dev-packages/kit/README.en.md) -->

# @celljs/kit

Shared types of the Cell 4 toolchain for `@celljs/cli`, `@celljs/vite`, toolchain modules, and preset authors, with no runtime dependencies.

- `CellError`: the shape of all toolchain errors `{ code, message, file?, line?, column?, hint, docs }`. `CellError.is(e)` identifies by name and works even with cross-package copies; `format()` is the CLI output format, `toJSON()` is the `--json` format.
- Events: `CELL_EVENTS`, `EVENT_RULES` (each event's fixed combination of rules: `notify` / `mutate` / `gate`), `HOOKABLE_EVENTS` (events that a project's `hooks` can subscribe to).
- `Preset` and `definePreset`.
- `ComponentManifest`: the `cell` field of component package.json (`modules`, `staticModules`, `targets`, `entries`, `optionalDependencies`, `toolchain`).
- `ProjectModel` / `TargetModel`: the project model produced by `@celljs/vite`.
- `CellModuleOptions`: toolchain modules extend it to declare option types for `cell.config.ts`.

```ts
declare module '@celljs/kit' {
    interface CellModuleOptions {
        audit?: { url: string };
    }
}
```

<!-- https://cell.cellbang.com/packages/vite (dev-packages/vite/README.en.md) -->

# @celljs/vite

Cell 4's build core: takes a Cell project (component graph, DI modules, `cell.yml` config) and builds it with Vite to `.cell/output`. Usually used through [`@celljs/cli`](https://github.com/cellbang/cell/tree/main/dev-packages/cli)'s `cell build`, but can also be used standalone.

- `ProjectLoader`: reads only package.json and `cell*.yml`, generates a JSON-serializable project model (components, modes, DI modules per target, entries, merged config), and executes no project code.
- `CellPlugin` / `cell()`: Vite plugin providing `client` (frontend, outputs `public/`) and `server` (backend, outputs single `server/index.mjs`) environments. DI assembly code, merged config, and project model are written to `.cell/generated/` simultaneously.
- `CellBuilder`: builds all targets at once, throws `CellError` (`@celljs/kit`) on failure.

```ts
import { CellBuilder } from '@celljs/vite';

const project = await new CellBuilder({
    root: process.cwd(),
    mode: ['production'],
    entryName: 'http',          // backend entry name, choose from component's cell.entries
    format: 'esm',
    outDir: '.cell/output',
}).build();
```

Build rules:

- All backend dependencies are inlined. `cell.optionalDependencies` declared by components that can't be resolved are external; native modules and `external` are copied to `server/node_modules` by dependency closure. The output can be copied elsewhere and run standalone.
- `${...}` in backend config is evaluated at runtime; frontend config and `index.html` are evaluated at build time.
- `CELL_*` environment variables override backend config at service startup; `CELL_*` at build time overrides frontend config. Both happen before `${...}` evaluation (`@celljs/core`'s `EnvConfigUtil`); results are recorded in `TargetModel.envOverrides`.
- Backend config has `paths.public` (default `public`, relative to output), resolved to an absolute path when the service starts.
- User source is transpiled by Oxc with legacy decorators and `emitDecoratorMetadata` enabled.
- Class names: bundling renames duplicate classes (e.g., `Context$1`), frontend minification shortens names, and Rolldown's `keepNames` doesn't reach modules lazy-initialized by `import()`. So `cell build` adds a static block to each named class in the project, Cell packages, and components, defining its source-code name. Logs, errors, security resource names, OpenAPI names, and cqrs's `on<Event>` all depend on it. Cost: hello world frontend gzip ~+3%. Function names (e.g., function components) are not kept; don't use them as identifiers.
- Frontend polyfills for Node builtins are only enabled if the project installs the corresponding polyfill package.

Requires Node.js `^20.19.0 || >=22.12.0`.

<!-- https://cell.cellbang.com/packages/alipay (packages/alipay/README.md) -->

# Cell - Alipay Component

Add `@celljs/alipay` to the dependencies to take payments with [Alipay](https://opendocs.alipay.com/open/00a0ut) (支付宝): an injectable `AlipayClient` signs gateway requests (RSA2), verifies the signatures of the answers and builds the page, WAP and App payments, and a notification endpoint verifies asynchronous notifications and hands them to your handlers. Public key mode and certificate mode are supported. It uses Node's `crypto` and `fetch`, with no third-party dependency.

```yaml
# cell.yml: configuration is server-only unless a schema marks it public; take credentials from the environment
alipay:
  appId: ${env.ALIPAY_APP_ID}
  privateKey: ${env.ALIPAY_PRIVATE_KEY}             # 应用私钥: PEM, base64 (PKCS#8 or PKCS#1) or a file path
  alipayPublicKey: ${env.ALIPAY_PUBLIC_KEY}         # 支付宝公钥 (public key mode)
  notifyUrl: https://shop.example.com/alipay/notify
  # gateway: https://openapi-sandbox.dl.alipaydev.com/gateway.do   # the sandbox
```

```ts
import { Autowired } from '@celljs/core';
import { Body, Controller, Post } from '@celljs/mvc/lib/node';
import { AlipayClient, AlipayNotification, AlipayNotificationHandler } from '@celljs/alipay';

@Controller('orders')
export class OrderController {
    @Autowired(AlipayClient)
    protected readonly alipay: AlipayClient;

    @Post('page')        // 电脑网站支付: redirect the browser to the URL
    page(@Body() order: { id: string }) {
        return { url: this.alipay.pagePay({ out_trade_no: order.id, total_amount: '88.88', subject: 'Cell T-shirt' }, { return_url: 'https://shop.example.com/paid' }) };
    }

    @Post('qr')          // 当面付扫码: show qr_code as a QR code
    async qr(@Body() order: { id: string }) {
        const { qr_code } = await this.alipay.precreate({ out_trade_no: order.id, total_amount: '88.88', subject: 'Cell T-shirt' });
        return { qr_code };
    }
}

@AlipayNotificationHandler(['TRADE_SUCCESS', 'TRADE_FINISHED'])
export class PaidHandler implements AlipayNotificationHandler {
    async handle(notification: AlipayNotification) {
        // out_trade_no, trade_no, total_amount... as Alipay sent them, signature verified.
        // Mark the order paid once: the same notification can come again.
    }
}
```

## Client

`biz_content` uses the field names of Alipay's documentation (snake_case); amounts are strings in yuan (`'88.88'`). Payment methods default `notify_url` to `alipay.notifyUrl`; the second argument sets other common parameters (`return_url`, `app_auth_token`...).

| Method | API |
| --- | --- |
| `pagePay(request, { httpMethod?, return_url? })` | alipay.trade.page.pay (电脑网站支付): a URL to redirect to, or with `httpMethod: 'POST'` an HTML form that submits itself |
| `wapPay(request, options?)` | alipay.trade.wap.pay (手机网站支付), same results |
| `appPay(request)` | alipay.trade.app.pay (App 支付): the order string for the App SDK |
| `precreate(request)` → `{ qr_code }` | alipay.trade.precreate (当面付扫码) |
| `create(request)` → `{ trade_no }` | alipay.trade.create (JSAPI / 小程序, `buyer_id` or `buyer_open_id`); the page calls `my.tradePay({ tradeNO })` |
| `query(query)` / `close(query)` | alipay.trade.query / alipay.trade.close |
| `refund(request)` / `queryRefund(query)` | alipay.trade.refund / alipay.trade.fastpay.refund.query; give `out_request_no` for partial refunds |
| `billDownloadUrl({ bill_type, bill_date })` | alipay.data.dataservice.bill.downloadurl.query |
| `execute(method, biz?, options?)` | Any other API: resolves with `<method>_response` |
| `pageExecute(method, biz?, options?)` / `sdkExecute(method, biz?, options?)` | Any other browser or App SDK API |
| `verifyNotification(params)` | Verifies a notification received on a route of your own |

Answers whose `code` is not `10000` reject with `CELL_ALIPAY_API_ERROR`; `detail` is the answer (`sub_code: 'ACQ.TRADE_NOT_EXIST'`...). The signature of an answer is checked over its JSON text as Alipay sent it.

## Notifications

The endpoint is `POST /alipay/notify` (`alipay.notification.url`, under `server.path`); set its absolute URL as `notifyUrl`. It runs before the body parser and authentication, verifies the signature of the form and that `app_id` is this application's, then runs the `@AlipayNotificationHandler` components of its `trade_status` (`WAIT_BUYER_PAY`, `TRADE_SUCCESS`, `TRADE_FINISHED`, `TRADE_CLOSED`; the `notify_type` for notifications without one), then those declared without types, one after the other. It answers `success` when they all succeed and `fail` otherwise (400 for a bad signature, 500 when a handler throws), so Alipay sends the notification again later: handlers must be idempotent. A partial refund comes as a notification with `refund_fee` and `gmt_refund`.

Notifications only say what happened: check `total_amount` against the order before shipping it.

## Certificate mode

Applications created with certificates (公钥证书) give the three certificates instead of `alipayPublicKey` (PEM text or file paths):

```yaml
alipay:
  appId: ${env.ALIPAY_APP_ID}
  privateKey: ${env.ALIPAY_PRIVATE_KEY}
  appCert: certs/appCertPublicKey_2021000000000001.crt
  alipayPublicCert: certs/alipayCertPublicKey_RSA2.crt
  alipayRootCert: certs/alipayRootCert.crt
```

Requests carry `app_cert_sn` and `alipay_root_cert_sn` computed as Alipay's SDKs do; an answer signed with another Alipay certificate is refused, so replace `alipayPublicCert` when Alipay renews it.

## Configuration

```yaml
alipay:
  gateway: https://openapi.alipay.com/gateway.do
  timeout: 10000               # milliseconds per request
  notification:
    enabled: true
    url: /alipay/notify
```

## Errors

Failures are `AlipayError`s with a stable `code` and a `hint`:

| Code | When |
| --- | --- |
| `CELL_ALIPAY_NOT_CONFIGURED` | `appId` or `privateKey` is missing, or neither `alipayPublicKey` nor all three certificates are set |
| `CELL_ALIPAY_API_ERROR` | The answer's `code` is not `10000`: `detail.sub_code` says why |
| `CELL_ALIPAY_HTTP_ERROR` | The gateway answered with an HTTP error or not with JSON |
| `CELL_ALIPAY_SIGNATURE_INVALID` | An answer or a notification is not signed by Alipay |
| `CELL_ALIPAY_APP_ID_MISMATCH` | A notification is for another application |

Content encryption (`encrypt_key`, AES) is not supported.

<!-- https://cell.cellbang.com/packages/cache (packages/cache/README.md) -->

# Cell - Cache Component with cache-manager

Named cache managers for Cell backends, on [cache-manager](https://github.com/jaredwray/cache-manager) 5.

```bash
npm install @celljs/cache
```

```ts
import { Autowired, Component, Named } from '@celljs/core';
import { CacheManager } from '@celljs/cache';

@Component()
export class UserService {
    @Autowired(CacheManager)                 // the cache named "default"
    protected readonly cache: CacheManager;

    @Autowired(CacheManager) @Named('sessions')
    protected readonly sessions: CacheManager;

    getUser(id: string) {
        return this.cache.wrap(`user:${id}`, () => this.load(id), 60_000);   // computed once, kept 60 s
    }
}
```

`CacheManager` has `get`, `set(key, value, ttl?)`, `del`, `reset` and `wrap(key, fn, ttl?)`. A manager is created the first time it is injected.

## Configuration (`cache.config`)

One entry per cache name:

```yaml
cache:
  config:
    default:
      store: memory
      max: 100            # entries
      ttl: 3600000        # milliseconds
    sessions:
      store: redis-yet    # needs the cache-manager-redis-yet package
      url: "${env.REDIS_URL}"
      ttl: 86400000
```

- `ttl` is in **milliseconds**, as in cache-manager 5. The default cache keeps entries 3600 ms.
- `store` is `memory` or the name of a store package you install: `redis` (`cache-manager-redis`), `redis-store`, `redis-yet`, `ioredis`, `ioredis-yet`, `mongodb`, `mongoose`, `fs-binary`, `fs-hash`, `hazelcast`, `memcached-store`, `memory-store` (each `cache-manager-<name>`). The other keys are the options of that store.
- A list of entries makes a multi-level cache (`multiCaching`): reads try each store in order.
- Injecting a name without configuration throws `Not found cache options.`

Bind your own `CacheStoreFactory` (`rebind: true`) to create stores another way.

<!-- https://cell.cellbang.com/packages/core (packages/core/README.en.md) -->

# Cell - Core Component

## Overview

Cell Core is a lightweight application framework for building modern applications. It provides a straightforward API through dependency injection, AOP (aspect-oriented programming), configuration properties, and logging, supporting registration, resolution, and lifecycle management of class objects. The dependency injection container (`Container`) is implemented by Cell itself with no third-party IoC dependencies and full TypeScript support.

## Features

- Dependency Injection
- Aspect-Oriented Programming
- Configuration Properties
- Logging

## Installation

Install Cell Core Component using npm:

```bash
npm install @celljs/core
```

## Quick Start

Below is a simple dependency injection example that shows how to register a class object in the IoC container:

```typescript
import { Component } from '@celljs/core';

@Component()
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}
```


Next, use the `@Autowired` decorator in another object to inject the `HelloWorld` class:

```typescript
import { Autowired } from '@celljs/core';
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';
import { HelloWorld } from './hello-world';

export class SampleService {
    @Autowired()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

Next, import these two files in the DI module and export `autoBind()`. A Cell project's backend module is `src/node/module.ts`, and the toolchain (`cell dev`, `cell build`, `createTestApp()`) loads it automatically; files not imported by the module are not loaded:

```typescript
// src/node/module.ts
import './hello-world';
import './sample-service';
import { autoBind } from '@celljs/core';

export default autoBind();
```

Run `npx cell dev` to start the application and `npx cell check` to verify that DI bindings resolve correctly. Create a new project with `npx @celljs/cli init backend my-app`; see [Getting Started](https://cell.cellbang.com/guide/getting-started) for details.

To assemble the container in your own script without the toolchain, use `ApplicationFactory`:

```typescript
import { autoBind } from '@celljs/core';
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';
import './hello-world';
import './sample-service';

const app = await ApplicationFactory.create({}, autoBind());
await app.start();
```

## Dependency Injection

Cell Core provides dependency injection capabilities: register class objects in the IoC container with `@Component`, then inject them in other classes using `@Autowired`. Here's a simple example:

```typescript
import { Component, Autowired } from '@celljs/core';

@Component()
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}

@Component()
export class SampleService {
    @Autowired()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

## Property Injection

Cell Core supports property injection with the `@Value` decorator, which injects configuration properties into class objects. Here's a simple example:

```typescript
import { Component, Value } from '@celljs/core';

@Component()
export class SampleService {
    @Value('app.name')
    appName: string;

    run() {
        console.log(`App Name: ${this.appName}`);
    }
}
```

Inject properties by passing the `appProps` object to `ApplicationFactory.create()` at application startup. For example:

```typescript
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';
import { SampleService } from './sample-service';

(async () => {
    const appProps = {
        app: { name: 'MyApp' }
    };
    const app = await ApplicationFactory.create(appProps, SampleModule);
    app.start();
})();
```

Use `.` to access nested properties in `@Value`, for example `@Value('app.name')`.

The `@Value` string supports EL expressions, evaluated by Cell's built-in `ExpressionEngine` (syntax identical to jexl 2; Cell previously used jexl but now has no third-party dependencies, evaluation is synchronous, and expressions cannot call object methods). For example:

```typescript
import { Component, Value } from '@celljs/core';

@Component()
export class SampleService {

    // Object access
    @Value('app.name')
    appName: string;

    // Ternary expression
    @Value('app.name == "MyApp" ? "Hello, MyApp!" : "Hello, World!"')
    greeting: string; 
    
    // Provide default value
    @Value('app.version ?? "1.0.0"')
    appVersion: string;

    // Mathematical operations
    @Value('app.port + 1')
    port: number;

    // Logical operations
    @Value('app.debug && app.env == "dev"')
    debug: boolean;

    // Array access
    @Value('app.tags[0]')
    tag: string;

    // Array filtering
    @Value('employees[.age >= 30 && .age < 40]')
    middleAgedEmployees: Employee[];

    // Transformation
    // Suppose the following two transforms were added to ExpressionEngine:
    // engine.addTransform('split', (val, char) => val.split(char))
    // engine.addTransform('lower', (val) => val.toLowerCase())
    @Value('"Pam Poovey"|lower|split(" ")[1]')
    lastName: string;

    // Function call
    // Suppose the following function was added:
    // engine.addFunction('min', Math.min)
    @Value('min(3, 5)')
    min: number;
    
}
```

## IoC Container

Cell Core Component provides a lightweight IoC container for managing the lifecycle and dependencies of class objects. Use the `@Component` decorator to register class objects in the IoC container, and the `@Autowired` decorator to inject dependency objects in other class objects.

The IoC container `Container` is implemented by Cell itself, supporting class object registration, resolution, and lifecycle management: identified by class or Symbol, singleton/transient scope, multiple injections, selection by name (`@Named`) or tag (`@Tagged`), and activation hooks (AOP proxies are created here). Inspired by Spring Framework's design philosophy, it provides a set of decorators similar to Spring, such as `@Component`, `@Autowired`, `@Value`, etc. Container resolution is synchronous, and singletons are created on first access.

The IoC container is composed of a series of container modules, each containing class objects registered with the `@Component` decorator. For convenient registration of class objects to container modules, Cell Core Component provides the `autoBind` method, which automatically registers class objects to container modules without manual registration. `autoBind` performs file module dependency analysis to automatically register class objects to container modules.

Below is a simple IoC container example:

```typescript
import { Component, Autowired } from '@celljs/core';
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';

@Component()
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}

@Component()
export class SampleService {
    @Autowired()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}

export const SampleModule = autoBind();
```

The `autoBind` method also provides a series of callback functions for customizing binding behavior. For example:

```typescript
import { autoBind } from '@celljs/core';

export const SampleModule = autoBind((bind, unbind, isBound, rebind) => {
    bind(HelloWorld).to(HelloWorld).inSingletonScope();
    bind(Greeting).toConstantValue('Hello');
    bind(Clock).toDynamicValue(({ container, target }) => new SystemClock()).inSingletonScope();
    bind(Store).to(RedisStore).whenTargetNamed('redis');
    rebind(Logger).to(MyLogger).inSingletonScope();
});
```

Binding syntax: `to(Class)`, `toConstantValue(value)`, `toDynamicValue(context => value)` (where `context.target` is the injection point: identifier, `name`, `tags`, owning class `owner`, and property name `key`), `toService(id)` (alias for another identifier); scopes `inSingletonScope()` / `inTransientScope()` (`bind` defaults to transient, `@Component` defaults to singleton); constraints `whenTargetNamed(name)`, `whenTargetTagged(key, value)`, `whenTargetIsDefault()`, `when(target => boolean)`; `onActivation((context, instance) => instance)` runs after each new instance is created.

You can also create a container directly, such as in tests:

```typescript
import { Container } from '@celljs/core';
import { SampleModule } from './sample-module';

const container = new Container(SampleModule);
const sampleService = container.get(SampleService);
sampleService.run();
```

Container query methods: `get(id)` returns the unique matching implementation, `getAll(id)` returns all implementations, `isBound(id)` checks if a binding exists. All support query conditions like `{ name }` or `{ tags: { key: value } }`, for example `container.get(Store, { name: 'redis' })`. Without conditions, `getAll` and `isBound` ignore constraints; `get` matches only bindings with no constraints or with `whenTargetIsDefault()`.

On error, containers throw `ContainerError` with a stable `code`, a one-line fix suggestion `hint`, and the identifier chain being resolved `path` (what `cell check` reports):

| code | Meaning |
| --- | --- |
| `CELL_DI_NO_BINDING` | No matching binding; message shows who needs it (`HomeController.mailer`), the resolution chain, and unmatched bindings or another identifier with the same name |
| `CELL_DI_AMBIGUOUS` | Expected one implementation but multiple bindings match; message lists all candidates |
| `CELL_DI_CIRCULAR` | Circular dependency, e.g., `A → B → A` |
| `CELL_DI_MISSING_INJECT` | Constructor parameter or property missing `@Autowired`, and the type cannot serve as an identifier (interface, union type, primitive type) |
| `CELL_DI_INCOMPLETE_BINDING` | `bind(id)` has no `to...` clause |
| `CELL_DI_NO_CONTAINER` | Object reading `detached` property was not created by the container (created with `new`) |

There is no global container; components access each other only through injection. The container binds itself, so when a component needs to retrieve another component by a runtime-determined identifier, inject `Container`:

```typescript
import { Autowired, Component, Container } from '@celljs/core';

@Component()
export class HandlerRegistry {

    @Autowired(Container)
    protected readonly container: Container;

    handler(id: symbol) {
        return this.container.get(id);
    }
}
```

Non-component code (scripts, tests) obtains the container from where it was created: `ApplicationFactory.createContainer(props, ...modules)` returns it, and test hosts receive it in `ApplicationHost.started()`.

## Configuration Properties

Cell Core provides configuration property capabilities: inject configuration properties into class objects with `@Value`, which supports EL expressions.

Define configuration properties in the `appProps` object passed to `ApplicationFactory.create()` at startup. For example:

```typescript
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';
import { SampleService } from './sample-service';

(async () => {
    const appProps = {
        app: { name: 'MyApp' }
    };
    const app = await ApplicationFactory.create(appProps, SampleModule);
    app.start();
})();
```

Cell Core also provides a `ConfigProvider` interface for loading configuration files with a default implementation; you can provide a custom implementation. For example:

```typescript
import { ConfigProvider } from '@celljs/core';

@Component({ id: ConfigProvider, rebind: true })
export class MyConfigProvider implements ConfigProvider {
    get<T>(key: string, defaultValue?: T): T {
        return process.env[key] || defaultValue;
    }
}
```

Besides `@Value`, you can also inject `ConfigProvider` and retrieve values by key at runtime. For example:

```typescript
import { Autowired, Component, ConfigProvider } from '@celljs/core';

@Component()
export class SampleService {

    @Autowired(ConfigProvider)
    protected readonly config: ConfigProvider;

    run() {
        console.log(`App Name: ${this.config.get('app.name')}`);
    }
}
```

## Decorators

Cell Core provides Spring-like decorators for registering class objects in the IoC container. Here are the commonly used ones:

- `@Component`: Register a class in the IoC container.
- `@Autowired`: Inject a dependency.
- `@Value`: Inject a configuration property.
- `@PostConstruct`: Execute after property injection completes (one per class, inherited by subclasses).
- `@Service`: Alias for `@Component`; registers a service object.
- `@Named`: Select the implementation to inject by name (corresponds to `@Component({ id, name })`).
- `@Optional`: Inject `undefined` when no implementation exists (array becomes `[]`); property retains its initial value.
- `@Tagged`: Select the implementation to inject by tag (corresponds to `@Component({ id, tag })`).
- `@Aspect`: Define an aspect object and provide AOP capability.
- `@AutowiredProvider`: Inject a dependency provider; access a list of objects of a class with sorting support.
- `@Constant`: Register a constant in the IoC container.

`@Autowired`, `@Value`, and `@AutowiredProvider` all have a `detached` form (option `{ detached: true }`, or import from `@celljs/core/lib/common/annotation/detached`): the property is retrieved from the container that created the instance only on first read, which breaks circular dependencies. It applies only to properties, and instances must be created by the container; reading on objects created with `new` throws `CELL_DI_NO_CONTAINER`. React components use `@celljs/react`'s `useInject` / `useValue`.

```typescript
import { Autowired, Component } from '@celljs/core';

@Component()
export class OrderService {

    // InvoiceService also depends on OrderService: retrieve on first use
    @Autowired({ id: InvoiceService, detached: true })
    protected readonly invoices: InvoiceService;
}
```

## @Component Decorator

`@Component` registers class objects in the IoC container. It has these properties:

- `id`: The identifier of the class, can be one or multiple.
- `scope`: The scope of the class, defaults to `Scope.Singleton`.
- `name`: The name of the class.
- `tag`: The tag of the class.
- `default`: Whether this is the default class. When multiple bindings exist for a service identifier, set this to specify which one is returned by default.
- `when`: A function that determines whether to create the class. Returns `true` to create it; `false` otherwise.
- `rebind`: Whether to rebind the class. Defaults to `false`.
- `proxy`: Whether to use a proxy for the class. Defaults to `false`. When `true`, AOP aspects can intercept it.
- `sysTags`: System tags to identify the class. In AOP aspects, you can intercept classes by system tag.
- `onActivation`: A callback function executed when the class is activated.

For example:

```typescript
import { Component, Scope } from '@celljs/core';

@Component({ id: 'HelloWorld', scope: Scope.Singleton })
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}
```

When `id` is an array, the class has multiple identifiers. For example:

```typescript
import { Component } from '@celljs/core';

@Component({ id: ['HelloWorld', 'Hello'] })
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}
```

When `id` is not set, the class itself is used as the identifier. For example:

```typescript
import { Component } from '@celljs/core';

@Component()
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}
```

Regardless of whether `id` is set, the decorated class is always an identifier and can be used to retrieve the class object. For example:

```typescript
import { Component } from '@celljs/core';

@Component()
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}

@Component()
export class SampleService {
    @Autowired()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

## @Autowired Decorator

`@Autowired` injects dependencies. It has these properties:

- `id`: The identifier of the class.
- `multi`: Whether to inject multiple objects. Defaults to automatic detection based on whether the property type is an array; explicitly set to `true` when needed.
- `detached`: The property is retrieved from the container that created the instance only on first read (`@Value` retrieves on each read); used to break circular dependencies. Defaults to `false`.

For example:

```typescript
import { Autowired } from '@celljs/core';

@Component()
export class SampleService {
    @Autowired({ id: HelloWorld })
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

When `id` is not set, the property type is used as the identifier. For example:

```typescript
import { Autowired } from '@celljs/core';

@Component()
export class SampleService {
    @Autowired()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

When multiple objects exist for an identifier, set the property type to an array to inject all of them. For example:

```typescript
import { Autowired } from '@celljs/core';

@Component()
export class SampleService {
    @Autowired()
    helloWorlds: HelloWorld[];

    run() {
        console.log(this.helloWorlds.map(helloWorld => helloWorld.greet()));
    }
}
```

Alternatively, use `@AutowiredProvider` to inject a dependency provider that gives you a list of objects with sorting support. For example:

```typescript
import { AutowiredProvider } from '@celljs/core';

@Component()
export class SampleService {
    @AutowiredProvider({ id: HelloWorld })
    helloWorldProvider: Provider<HelloWorld>;

    run() {
        const helloWorlds = this.helloWorldProvider.sortSync();
        console.log(helloWorlds.map(helloWorld => helloWorld.greet()));
    }
}
```

In esbuild-compiled projects, type information is absent, so you cannot automatically detect multiple dependencies. Explicitly set `multi` to `true`, or use `@AutowiredProvider`.

## @Value Decorator

`@Value` injects configuration properties. It has these properties:

- `el`: The EL expression for the property.
- `detached`: The property is retrieved from the container that created the instance only on first read (`@Value` retrieves on each read); used to break circular dependencies. Defaults to `false`.

For example:

```typescript
import { Value } from '@celljs/core';

@Component()
export class SampleService {
    @Value('app.name')
    appName: string;

    run() {
        console.log(`App Name: ${this.appName}`);
    }
}
```

## @Constant Decorator

`@Constant` registers constants in the IoC container. It has these properties:

- `id`: The identifier for the constant.
- `constantValue`: The constant's value.
- `rebind`: Whether to rebind the constant. Defaults to `false`.

For example:

```typescript
import { Constant } from '@celljs/core';

@Constant('app.name', 'MyApp')
@Constant('app.version', '1.0.0')
export  default class {
}

@Component()
export class SampleService {
    @Autowired('app.name')
    name: string;

    @Autowired('app.version')
    version: string;
}
```

## @PostConstruct Decorator

`@PostConstruct` executes after a class object is initialized. For example:

```typescript
import { Component, PostConstruct } from '@celljs/core';

@Component()
export class SampleService {
    @PostConstruct()
    init() {
        console.log('SampleService initialized.');
    }
}
```

## @Named Decorator

`@Named` specifies the name of the injected object. For example:

```typescript
import { Autowired, Named } from '@celljs/core';

@Component({ name: 'HelloWorld' })
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}

@Component()
export class SampleService {
    @Autowired()
    @Named('HelloWorld')
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

## @Tagged Decorator

`@Tagged` marks the injected object with a tag. For example:

    tag?: { tag: string | number | symbol, value: any };


```typescript
import { Autowired, Tagged } from '@celljs/core';

@Component({ tag: { tag: 'tag1', value: 'HelloWorld' } })
export class HelloWorld {
    greet() {
        return 'Hello, World!';
    }
}

@Component()
export class SampleService {
    @Autowired()
    @Tagged('tag1', 'HelloWorld')
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld.greet());
    }
}
```

## @Optional Decorator

`@Optional` marks the injected object as optional. Without it, `@Autowired` throws if the object is not found. With `@Optional`, the property is set to `undefined` if not found. For example:

```typescript
import { Autowired, Optional } from '@celljs/core';

@Component()
export class SampleService {
    @Autowired()
    @Optional()
    helloWorld: HelloWorld;

    run() {
        console.log(this.helloWorld?.greet());
    }
}
```

## @Aspect Decorator

`@Aspect` defines an aspect object and provides AOP capability. It inherits all `@Component` properties and adds a `pointcut` property. It has these properties:

- `id`: The class identifier. Unlike `@Component`, `id` must be a single identifier, not an array.
- `pointcut`: The pointcut. Defaults to `COMPONENT_TAG`, which intercepts all `@Component`-registered classes. You can define custom pointcuts, such as `AOP_TAG`.

For example:

```typescript
import { MethodBeforeAdvice, Autowired, Aspect, AfterReturningAdvice, Value, ConfigUtil } from '@celljs/core';
import { AccessDecisionManager, MethodSecurityMetadataContext, ResourceNameResolver, SecurityMetadataSource, SECURITY_EXPRESSION_CONTEXT_KEY } from './access-protocol';
import { AOP_POINTCUT } from '@celljs/web';
import { SecurityContext } from '../context';
import { AuthorizeType } from '../../common';
import { Context } from '@celljs/web/lib/node';

const pointcut = ConfigUtil.getRaw().security.aop?.pointcut || AOP_POINTCUT;

export abstract class AbstractSecurityMethodAdivice {

    @Autowired(AccessDecisionManager)
    protected readonly accessDecisionManager: AccessDecisionManager;

    @Autowired(SecurityMetadataSource)
    protected readonly securityMetadataSource: SecurityMetadataSource;

    @Autowired(ResourceNameResolver)
    protected readonly resourceNameResolver: ResourceNameResolver;

    @Value('security.enabled')
    protected readonly enabled: boolean;

    protected needAccessDecision(method: string | number | symbol) {
        return this.enabled && typeof method === 'string' && SecurityContext.getCurrent();
    }
}

@Aspect({ id: MethodBeforeAdvice, pointcut })
export class SecurityMethodBeforeAdivice extends AbstractSecurityMethodAdivice implements MethodBeforeAdvice {

    async before(method: string | number | symbol, args: any[], target: any): Promise<void> {
        if (this.needAccessDecision(method)) {
            const ctx: MethodSecurityMetadataContext = { method: method as string, args, target, authorizeType: AuthorizeType.Pre, grant: 0 };
            const securityMetadata = await this.securityMetadataSource.load(ctx);
            const resouces = await this.resourceNameResolver.resolve(ctx);
            for (const resource of resouces) {
                securityMetadata.resource = resource;
                await this.accessDecisionManager.decide(securityMetadata);
            }
        }
    }

}

@Aspect({ id: AfterReturningAdvice, pointcut })
export class SecurityAfterReturningAdvice extends AbstractSecurityMethodAdivice implements AfterReturningAdvice {

    async afterReturning(returnValue: any, method: string | number | symbol, args: any[], target: any): Promise<void> {
        if (this.needAccessDecision(method)) {
            const oldCtx = Context.getAttr<MethodSecurityMetadataContext>(SECURITY_EXPRESSION_CONTEXT_KEY);
            const newCtx = { method: method as string, args, target, returnValue, authorizeType: AuthorizeType.Post, grant: oldCtx.grant };
            const securityMetadata = await this.securityMetadataSource.load(newCtx);
            const resouces = await this.resourceNameResolver.resolve(newCtx);
            for (const resource of resouces) {
                securityMetadata.resource = resource;
                await this.accessDecisionManager.decide(securityMetadata);
            }
        }
    }

}
```


## AOP Aspect-Oriented Programming

Cell Core provides aspect-oriented programming capability: execute operations before, after, and on exception during method execution. Use `@Aspect` to define aspects and `MethodBeforeAdvice`, `AfterReturningAdvice`, `AfterThrowsAdvice` interfaces to define advice.

AOP involves these interfaces:

- `MethodBeforeAdvice`: Execute before the method.
- `AfterReturningAdvice`: Execute after the method.
- `AfterThrowsAdvice`: Execute on method exception.

Use `@Aspect` to define aspects and specify the pointcut with the `pointcut` property. For example:

```typescript
import { MethodBeforeAdvice, Autowired, Aspect, AfterReturningAdvice, Value, ConfigUtil } from '@celljs/core';

const pointcut = 'test';

@Component({ id: MethodBeforeAdvice, pointcut })
export class TestMethodBeforeAdvice implements MethodBeforeAdvice {

    async before(method: string | number | symbol, args: any[], target: any): Promise<void> {
        console.log('before');
    }

}

@Component({ id: AfterReturningAdvice, pointcut })
export class TestAfterReturningAdvice implements AfterReturningAdvice {

    async afterReturning(returnValue: any, method: string | number | symbol, args: any[], target: any): Promise<void> {
        console.log('after');
    }

}

@Component({ id: AfterThrowsAdvice, pointcut })
export class TestAfterThrowsAdvice implements AfterThrowsAdvice {
    
    async afterThrows(error: any, method: string | number | symbol, args: any[], target: any): Promise<void> {
        console.log('throws');
    }

}
```

The example above defines an aspect with pointcut `test`. When a method of a class with sysTag `test` executes before, after, or on exception, the corresponding operations run. The pointcut `test` intercepts all `@Component`-registered classes with sysTag `test`.


## Building Applications

Cell Core provides a lightweight application framework. Use the `Application` interface to define applications, `ApplicationLifecycle` to define lifecycle, and `ApplicationStateService` for state management. `ApplicationFactory` creates application instances.

Use `ApplicationFactory` to create instances, load IoC modules, and assemble a complete container (`createContainer` returns the container, `create` returns the application). For example:

```typescript
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';
import { SampleService } from './sample-service';
import { SampleModule } from './sample-module';

(async () => {
    const appProps = {
        app: { name: 'MyApp' }
    };
    const app = await ApplicationFactory.create(appProps, SampleModule);
    app.start();
})();
```

Define application lifecycle with the `ApplicationLifecycle` interface. For example:

```typescript
import { ApplicationLifecycle, Application } from '@celljs/core';

export class SampleLifecycle implements ApplicationLifecycle {
    onStart(app: Application): Promise<void> {
        return Promise.resolve();
    }

    onStop(app: Application): void {
        console.log('Application stopped.');
    }
}
```

`Application` has one implementation, the same on frontend and backend: lifecycle runs sequentially, then mounts `ApplicationShell` if present (bound by `@celljs/core/lib/browser` on the browser, replaced by `@celljs/react`). On Node.js, `ExitSignalLifecycle` stops the application and exits the process on SIGINT / SIGTERM.

## Directory Structure

```shell
.
├── browser                        # Browser-side application
│   ├── browser.ts                 # Browser utility methods
│   ├── index.ts                   # Export module
│   ├── shell                      # Frontend startup entry
│   └── static-module.ts           # IoC container module with static-loaded types
├── common                         # Common module
│   ├── annotation                 # Decorator definitions
│   ├── aop                        # AOP-related code
│   ├── application                # Application (same implementation on frontend and backend)
│   ├── config                     # Configuration properties
│   ├── constants.ts               # Constants
│   ├── container                  # IoC container
│   ├── el                         # EL expressions
│   ├── error                      # Error handling
│   ├── index.ts                   # Export module
│   ├── logger                     # Logging
│   ├── provider                   # Dependency provider
│   ├── static-module.ts           # IoC container module with static-loaded types
│   ├── test                       # Testing
│   └── utils                      # Utility methods
├── node                           # Node.js-side application
│   ├── application                # Exit signal lifecycle
│   ├── constants.ts               # Constants
│   ├── context                    # Context
│   ├── index.ts                   # Export module
│   ├── static-module.ts           # IoC container module with static-loaded types
│   └── utils                      # Utility methods
└── package.spec.ts                # Unit tests
```

## Error Types

Cell Core provides common error types for exception handling:

- `CustomError`: Custom error.
- `IllegalArgumentError`: Illegal argument error.
- `IllegalStateError`: Illegal state error.
- `InvalidMimeTypeError`: Invalid MIME type error.

For example:

```typescript
import { IllegalArgumentError } from '@celljs/core';

if (condition) {
    throw new IllegalArgumentError('Invalid argument.');
}
```

Since JavaScript's built-in error types cannot be checked with `instanceof`, Cell Core provides a `CustomError` base class. All custom error types should inherit from `CustomError`.

## Security Checks

Components can report settings unsafe in production (public default keys, overly short keys, etc.): implement `SecurityCheck`, bind it, and `check()` returns `SecurityWarning` with a stable `code` (`CELL_SECURITY_*`) and a one-sentence `hint`.

```typescript
import { Component, SecurityCheck, SecurityWarning, Value } from '@celljs/core';

@Component(SecurityCheck)
export class ApiKeySecurityCheck implements SecurityCheck {
    @Value('app.apiKey')
    protected readonly apiKey?: string;

    check(): SecurityWarning[] {
        return this.apiKey === 'changeme'
            ? [{ code: 'CELL_SECURITY_DEFAULT_API_KEY', message: 'app.apiKey is the example key.', hint: 'Set app.apiKey from the environment.' }]
            : [];
    }
}
```

These warnings take effect in two places:

- The `security` check in `cell check` reports them in any environment (warning, does not fail).
- At startup (`AbstractApplication.doStart`, before lifecycle hooks), only in `NODE_ENV=production` per `securityChecks`: `warn` (default) logs each warning, `fail` throws `SecurityCheckError` (`CELL_SECURITY_CHECK_FAILED`) and exits with code 1, `off` skips the check. Override with `CELL_SECURITY_CHECKS=fail`.

Built-in checks: cookie signing keys in `@celljs/web` (`CELL_SECURITY_DEFAULT_COOKIE_KEYS`, `CELL_SECURITY_COOKIE_KEYS_MISSING`, `CELL_SECURITY_WEAK_COOKIE_KEYS`), HMAC key length in `@celljs/jwt` (`CELL_SECURITY_WEAK_JWT_SECRET`).

## Logging

Cell Core provides logging with log levels, formats, and output. Use the `Logger` interface to define loggers and the `TraceIdProvider` interface for trace IDs.

Log levels are:

- `verbose`: Verbose output.
- `debug`: Debug output.
- `info`: Informational messages.
- `warn`: Warnings.
- `error`: Errors.

For example:

```typescript
import { Logger } from '@celljs/core';

@Component()
export class SampleService {

    @Autowired(Logger)
    logger: Logger;

    run() {
        this.logger.info('Info message.');
        this.logger.error('Error message.');
    }
}
```

`Error` objects passed to logging methods are written with the call stack and `cause` chain (`ErrorUtil.describe(error)` can also be used standalone).

By default, output is `console`. Injected logger objects are independent to support different classes; set context information with `setContext`. For example:

```typescript
import { Logger } from '@celljs/core';

@Component()
export class SampleService {

    @Autowired(Logger)
    logger: Logger;

    run() {
        this.logger.setContext('SampleService');
        this.logger.info('Info message.');
        this.logger.error('Error message.');
    }
}
```

Customize the `Logger` interface to replace the default. For example:

```typescript
import { Component } from '@celljs/core';

@Component({ id: Logger, rebind: true })
export class MyLogger implements Logger {
    // TODO
}
```


## Context Capabilities

Cell Core provides context capabilities: application context, request context, session context. Use the `Context` class to set and retrieve context information.

Context types include:

- `App`: Application context
- `Request`: Request context
- `Session`: Session context


```typescript
import { Context, AttributeScope } from '@celljs/core';

Context.setAttr('key', 'value', AttributeScope.Request);
const value = Context.getAttr('key', AttributeScope.Request);
```


Context execution ensures context information persists during function execution. For example:

```typescript
import { Context } from '@celljs/core';

Context.run(async () => {
    Context.setAttr('key', 'value1', AttributeScope.Request);
    const value = Context.getAttr('key', AttributeScope.Request);
    console.log(value); // value1
});

Context.run(() => {
    Context.setAttr('key', 'value2', AttributeScope.Request);
    const value = Context.getAttr('key', AttributeScope.Request);
    console.log(value); // value2
});
```

## Common Utility Classes and Methods

Cell Core provides common utility classes and methods:

- `AnnotationUtil`: Annotation utilities
- `Assert`: Assertions
- `Async`: Async utilities
- `Cancellation`: Cancellation utilities
- `ClassUtil`: Class utilities
- `Disposable`: Disposable utilities
- `Emitter`: Event emission
- `Event`: Event utilities
- `GlobalUtil`: Global utilities
- `MetadataUtil`: Metadata utilities
- `Prioritizeable`: Prioritization utilities
- `PromiseUtil`: Promise utilities
- `ProxyUtil`: Proxy utilities
- `Types`: Type utilities
- `UrlUtil`: URL utilities
- `generateUUID`: UUID generation
- `OS`: Operating system utilities
- `MimeTypeUtil`: MIME type utilities
- `MimeType`: MIME type definitions

For example:

```typescript
import { Assert } from '@celljs/core';

Assert.isTrue(condition, 'Invalid argument.');
```

## EL Expressions

Cell Core supports EL expressions, a simple templating language for dynamic content generation. Use `ExpressionCompiler` to compile and `ExpressionHandler` to handle them.

Key interfaces:

- `ExpressionCompiler`: Compiles EL expressions
- `ExpressionHandler`: Handles EL expressions
- `ExpressionContext`: EL expression context
- `ContextInitializer`: Context initializer
- `ExpressionContextProvider`: EL expression context provider
- `ExpressionEngine`: The expression engine; use `@Autowired(ExpressionEngine)` to get the app's engine, extend with `addTransform` and `addFunction`, evaluate with `compile(source)` / `evaluate(source, context)`. Syntax errors or undefined transforms/functions throw `ExpressionSyntaxError` (`CELL_EL_SYNTAX`, `CELL_EL_UNKNOWN_TRANSFORM`, `CELL_EL_UNKNOWN_FUNCTION`) with error location in the message

For example:

```typescript
import { ExpressionHandler } from '@celljs/core';

@Component()
export class SampleService {

    @Autowired(ExpressionHandler)
    expressionHandler: ExpressionHandler;

    run() {
        const result = this.expressionHandler.handle('Hello, ${name}!', { name: 'World' });
        console.log(result); // Hello, World!
    }
}
```

Add context variables, functions, and transforms to EL expressions. For example:

```typescript
import { ContextInitializer } from '@celljs/core';

@Component(ContextInitializer)
export class CoreContextInitializer implements ContextInitializer {

    @Autowired(ExpressionEngine)
    protected readonly engine: ExpressionEngine;

    @Autowired({ id: ExpressionHandler, detached: true })
    protected readonly expressionHandler: ExpressionHandler;

    initialize(ctx: ExpressionContext): void {
        if (typeof process !== 'undefined') {
            ctx.env = { ...process.env, _ignoreEl: true };
        }
        this.engine.addTransforms({
            replace: (val: string, searchValue: string | RegExp, replaceValue: string) => val && val.replace(new RegExp(searchValue, 'g'), replaceValue),
            regexp: (pattern: string, flags?: string) => new RegExp(pattern, flags),
            eval: (text: string) => this.expressionHandler.handle(text)
        });
    }

    priority = 500;

}
```

Application properties support EL expression template strings by default. For example:

```typescript
import { ApplicationFactory } from '@celljs/core/lib/common/application/application-factory';

(async () => {
    const appProps = {
        app: { name: 'MyApp' },
        env: '${env}',
        version: '${version}',
        appVersion: '${app.name}-${version}',
        appVersion2: '${app.name}-${version}-${env}',
    };
    const app = await ApplicationFactory.create(appProps, SampleModule);
    app.start();
})();
```

## License

This project is licensed under the MIT License.

<!-- https://cell.cellbang.com/packages/cqrs (packages/cqrs/README.md) -->

# Cell - CQRS Component

`@celljs/cqrs` separates the code that changes state (commands) from the code that reads it (queries), and lets the rest of the application react to what happened (events), in the way of [`@nestjs/cqrs`](https://docs.nestjs.com/recipes/cqrs). Handlers are Cell components: they are found by their decorators, get injections like any other component, and are created when the first message of their kind is dispatched. No dependencies besides `@celljs/core`; backend only.

```bash
npm install @celljs/cqrs
```

## Commands and queries

A command or query is an instance of a class; its class selects its one handler. Extend `CommandMessage<R>` / `QueryMessage<R>` to give `execute` the result type (optional: without it, `execute<R>()` takes the type).

```ts
import { Autowired } from '@celljs/core';
import { Body, Controller, Get, Param, Post } from '@celljs/mvc/lib/node';
import { CommandBus, CommandHandler, CommandMessage, QueryBus, QueryHandler, QueryMessage } from '@celljs/cqrs';

export class CreateUser extends CommandMessage<string> {
    constructor(readonly name: string) {
        super();
    }
}

export class GetUser extends QueryMessage<User | undefined> {
    constructor(readonly id: string) {
        super();
    }
}

@CommandHandler(CreateUser)
export class CreateUserHandler implements CommandHandler<CreateUser> {
    @Autowired(UserRepository)
    protected readonly users: UserRepository;

    execute(command: CreateUser): Promise<string> {
        return this.users.insert(command.name);
    }
}

@QueryHandler(GetUser)
export class GetUserHandler implements QueryHandler<GetUser> {
    @Autowired(UserRepository)
    protected readonly users: UserRepository;

    execute(query: GetUser): Promise<User | undefined> {
        return this.users.findById(query.id);
    }
}

@Controller('users')
export class UserController {
    @Autowired(CommandBus)
    protected readonly commandBus: CommandBus;

    @Autowired(QueryBus)
    protected readonly queryBus: QueryBus;

    @Post()
    create(@Body() body: { name: string }): Promise<string> {
        return this.commandBus.execute(new CreateUser(body.name));
    }

    @Get(':id')
    get(@Param('id') id: string): Promise<User | undefined> {
        return this.queryBus.execute(new GetUser(id));
    }
}
```

`execute` resolves to what the handler returns and rejects with what it throws. The decorators take the options of `@Component` as second argument (`scope`, `proxy` for AOP...).

## Events and sagas

An event class can have any number of `@EventHandler`s and `@Saga`s. A saga turns an event into the commands that follow from it: the event bus runs what it returns (a command, an array of commands or nothing) with the command bus, in order.

```ts
import { EventBus, EventHandler, Saga } from '@celljs/cqrs';

export class UserCreated {
    constructor(readonly id: string, readonly name: string) { }
}

@EventHandler(UserCreated)                    // or @EventHandler([UserCreated, UserRenamed])
export class UserProjection implements EventHandler<UserCreated> {
    async handle(event: UserCreated): Promise<void> { ... }
}

@Saga(UserCreated)
export class WelcomeSaga implements Saga<UserCreated> {
    handle(event: UserCreated): SendWelcomeMail {
        return new SendWelcomeMail(event.id);
    }
}

await eventBus.publish(new UserCreated(id, name));
```

`publish(event)` runs the handlers and sagas of the event concurrently and resolves when they are all done, so a serverless function does not return before them; `publishAll(events)` publishes one event after the other. What a handler or saga throws does not reject `publish` nor stop the other handlers: it is logged and handed to the `UnhandledExceptionBus`:

```ts
@Component(ApplicationLifecycle)
export class CqrsAlerts implements ApplicationLifecycle<Application> {
    @Autowired(UnhandledExceptionBus)
    protected readonly exceptions: UnhandledExceptionBus;

    initialize(): void {
        this.exceptions.onException(({ error, event, handler }) => { ... });
    }
}
```

## Aggregates

An `AggregateRoot` records its changes as events: `apply(event)` records the event and calls the method `on<EventClassName>` of the aggregate, if there is one, to change the state; `commit()` publishes the recorded events with the event bus. Connect the aggregate to the event bus with `EventPublisher` first.

```ts
import { AggregateRoot, EventPublisher } from '@celljs/cqrs';

export class User extends AggregateRoot {
    name: string;

    constructor(readonly id: string) {
        super();
    }

    rename(name: string): void {
        this.apply(new UserRenamed(this.id, name));
    }

    onUserRenamed(event: UserRenamed): void {
        this.name = event.name;
    }
}

@CommandHandler(RenameUser)
export class RenameUserHandler implements CommandHandler<RenameUser> {
    @Autowired(EventPublisher)
    protected readonly publisher: EventPublisher;

    @Autowired(UserRepository)
    protected readonly users: UserRepository;

    async execute(command: RenameUser): Promise<void> {
        const user = this.publisher.mergeObjectContext(await this.users.load(command.id));
        user.rename(command.name);
        await this.users.save(user);
        await user.commit();
    }
}
```

- `loadFromHistory(events)` rebuilds the state from stored events without recording them again.
- `getUncommittedEvents()` returns the recorded events; `uncommit()` forgets them.
- `eventPublisher.mergeClassContext(User)` returns a subclass whose instances are connected when created.
- The recorded events are not properties of the aggregate: `JSON.stringify(user)` gives its state only.

## Errors

The buses and `commit()` reject with a `CqrsError` whose `code` is stable and whose `hint` says how to fix it:

| Code | When |
| --- | --- |
| `CELL_CQRS_NO_HANDLER` | No `@CommandHandler` / `@QueryHandler` for the class of the command or query |
| `CELL_CQRS_DUPLICATE_HANDLER` | Two handlers for one command or query class |
| `CELL_CQRS_NOT_AN_INSTANCE` | The message is a plain object, `null` or a primitive instead of an instance of a class |
| `CELL_CQRS_AGGREGATE_NOT_MERGED` | `commit()` on an aggregate that `EventPublisher` did not connect; the events stay recorded |

## Customizing

`CommandBus`, `QueryBus`, `EventBus`, `EventPublisher` and `UnhandledExceptionBus` are components: replace one with `rebind: true`, for example to also send the events to a message broker:

```ts
@Component({ id: EventBus, rebind: true })
export class BrokerEventBus extends EventBusImpl {
    override async publish(event: object): Promise<void> {
        await super.publish(event);
        await this.broker.send(event);
    }
}
```

## Coming from @nestjs/cqrs

| @nestjs/cqrs | @celljs/cqrs |
| --- | --- |
| `CqrsModule.forRoot()` | Add the dependency; the module is loaded with the backend |
| `ICommandHandler`, `IQueryHandler`, `IEventHandler` | `CommandHandler`, `QueryHandler`, `EventHandler`: one name for the decorator and the interface |
| `@EventsHandler(A, B)` | `@EventHandler([A, B])` |
| `Command<R>`, `Query<R>` | `CommandMessage<R>`, `QueryMessage<R>` (`@celljs/mvc` has a `@Query` decorator) |
| `@Saga()` with RxJS streams | `@Saga(Event)` class whose `handle(event)` returns the commands; no RxJS |
| `eventBus.publish()` returns at once | `await eventBus.publish()` waits for the handlers and sagas |
| `aggregate.commit()` | `await aggregate.commit()`; rejects when the aggregate is not connected instead of doing nothing |
| `autoCommit` | Not supported: call `commit()` |
| `UnhandledExceptionBus` (RxJS subject) | `UnhandledExceptionBus.onException` (a Cell `Event`) |

<!-- https://cell.cellbang.com/packages/express-adapter (packages/express-adapter/README.md) -->

# Cell - Express Adapter Component

The backend entry of an HTTP application: it starts the application and serves it with `node:http`. Despite the name it no longer depends on express; the handler is `HttpServerUtil.createHandler()` of `@celljs/web`.

```bash
npm install @celljs/express-adapter
```

Every HTTP backend needs it (the `cell init` templates include it). The `node`, `cloudflare`, `fc`, `scf`, `lambda` and `vercel` presets all run this entry; the `cli` preset does not need it.

| Key | Default | |
| --- | --- | --- |
| `server.host` | `127.0.0.1` | Use `0.0.0.0` in containers: `CELL_SERVER__HOST=0.0.0.0` |
| `server.port` | `3000` | `CELL_SERVER__PORT` overrides it; `'${env.PORT}'` follows a platform's `PORT` |
| `server.path` | `/` | Base path of every route |

Under `cell dev` and `createTestApp()` the entry hands its request handler to the toolchain instead of listening itself.

<!-- https://cell.cellbang.com/packages/grpc (packages/grpc/README.md) -->

# Cell - gRPC Component

gRPC servers and clients for Cell on `node:http2`, with a built-in `.proto` parser and protobuf codec: no third-party dependency, no code generation. Unary, server-streaming, client-streaming and bidirectional methods; interoperable with other gRPC implementations (tested against `@grpc/grpc-js` in both directions).

## Define the service

Keep the `.proto` file in the sources and parse it once. With Vite (`cell build`, `cell dev`, `createTestApp()`), a `?raw` import bundles its text:

```ts
// src/greeter.ts
import { Proto, type UnaryCall, type ServerStreamCall } from '@celljs/grpc';
import source from './greeter.proto?raw';   // declare module '*?raw' once, see examples/grpc-app/src/raw.d.ts

export const Greeter = Proto.parse(source).service('helloworld.Greeter');
```

`Proto.parse(...sources)` takes every file the service needs (imports are resolved by type name across the sources); the `google/protobuf` well-known types (`empty`, `timestamp`, `duration`, `wrappers`, `struct`, `any`, `field_mask`) are built in. Names are full (`helloworld.Greeter`) or short when unambiguous. `proto.message('HelloRequest')` gives a message type with `encode()` / `decode()` for protobuf without gRPC.

## Serve it

```ts
import { GrpcError, GrpcService, GrpcStatus, type ServerCall } from '@celljs/grpc';
import { Greeter } from './greeter';

@GrpcService(Greeter)
export class GreeterService {

    @Autowired(UserService)                       // a component like any other
    protected readonly users: UserService;

    // rpc SayHello (HelloRequest) returns (HelloReply)
    sayHello({ name }: HelloRequest, call: ServerCall): HelloReply {
        if (!name) {
            throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'name is required');
        }
        return { message: `Hello ${name}` };
    }

    // rpc SayHelloStream (HelloRequest) returns (stream HelloReply)
    async *sayHelloStream({ name }: HelloRequest): AsyncIterable<HelloReply> {
        yield { message: `Hello ${name}` };
    }

    // rpc SayHelloToAll (stream HelloRequest) returns (HelloReply)
    async sayHelloToAll(requests: AsyncIterable<HelloRequest>): Promise<HelloReply> { ... }

    // rpc Chat (stream HelloRequest) returns (stream HelloReply)
    async *chat(requests: AsyncIterable<HelloRequest>): AsyncIterable<HelloReply> { ... }
}
```

Import the file from a DI module (`src/module.ts`). When the application starts with at least one `@GrpcService`, `GrpcServerLifecycle` starts the gRPC server (`gRPC serve 127.0.0.1:50051` in the log); it closes when the application stops. Methods are the `.proto` methods in lowerCamelCase (`SayHello` → `sayHello`); a method without implementation answers `UNIMPLEMENTED`. The types `UnaryHandler`, `ServerStreamHandler`, `ClientStreamHandler` and `BidiStreamHandler` describe the four signatures.

The last argument, `call: ServerCall`, has the request `metadata` (lowercase keys), a `signal` aborted when the client cancels or the deadline passes, the `deadline`, `setHeader(key, value)` (before the first response) and `setTrailer(key, value)`.

Errors: throw a `GrpcError(code, details, metadata?)` to answer that status. Any other error answers `UNKNOWN` with the error's message and is logged.

```yaml
grpc:
  server:
    enabled: true                 # false: no server even with @GrpcService components
    port: 50051                   # CELL_GRPC__SERVER__PORT; 0 takes a free port
    host: 127.0.0.1               # CELL_GRPC__SERVER__HOST=0.0.0.0 in containers
    maxReceiveMessageSize: 4194304
```

The gRPC server is a second port next to the HTTP one of `@celljs/express-adapter`; an application without HTTP needs no adapter (`cell build` then warns that no component provides the `http` entry, which is expected). Outside a Cell application, `new GrpcServer(options).addService(Greeter, impl).listen(port, host)` does the same, and `server.handleStream(stream, headers)` serves the streams of an HTTP/2 server of your own (e.g. `http2.createSecureServer()` for TLS).

## Call it

```ts
import { GrpcChannel } from '@celljs/grpc';

export interface GreeterClient {
    sayHello: UnaryCall<Partial<HelloRequest>, HelloReply>;
    sayHelloStream: ServerStreamCall<Partial<HelloRequest>, HelloReply>;
}

const channel = new GrpcChannel('localhost:50051', { metadata: { authorization: 'Bearer ...' }, timeout: 5000 });
const greeter = channel.createClient<GreeterClient>(Greeter);

const { message } = await greeter.sayHello({ name: 'Cell' });
for await (const reply of greeter.sayHelloStream({ name: 'Cell' })) { ... }   // break cancels the call
await greeter.sayHelloToAll([{ name: 'a' }, { name: 'b' }]);                 // any (async) iterable
await greeter.sayHello({ name: 'Cell' }, { timeout: 1000, signal, metadata: { 'x-trace-bin': bytes } });
channel.close();
```

A channel is one HTTP/2 connection, opened on the first call and reopened when lost; share it between clients of the same server. An idle channel does not keep the process alive. Failed calls reject with a `GrpcError` (`code`, `details`, trailing `metadata`): `UNAVAILABLE` when the server cannot be reached, `DEADLINE_EXCEEDED`, `CANCELLED`... A request that cannot be encoded rejects with a `TypeError` naming the field, before anything is sent.

## Values

| Protobuf | JavaScript |
| --- | --- |
| field `user_id` | property `userId` (encoding also takes `user_id`) |
| `int32`, `uint32`, `sint32`, `fixed32`, `sfixed32`, `float`, `double` | `number` |
| `int64`, `uint64`, `sint64`, `fixed64`, `sfixed64` | decimal `string` (encoding also takes `number` and `bigint`) |
| `bool`, `string` | `boolean`, `string` |
| `bytes` | `Uint8Array` (encoding also takes base64) |
| enum | value name (encoding also takes the number; unknown numbers decode as numbers) |
| message | object; `google.protobuf.Timestamp` is `{ seconds: '…', nanos: 0 }` |
| `repeated` / `map<K, V>` | array / plain object with string keys |
| `oneof kind` | the set member, and `kind: 'memberName'` |

Decoded messages have every field without explicit presence at its default (`0`, `''`, `false`, first enum value, `[]`, `{}`); message fields, `optional` fields and oneof members are left out when not set. Unknown fields are skipped.

## Testing

In `cell.test.yml`, `backend.grpc.server.port: 0` gives the test application a free port; read it from the lifecycle the application loaded:

```ts
const app = await createTestApp();
const { GrpcServerLifecycle } = await app.import('@celljs/grpc');
const channel = new GrpcChannel(`127.0.0.1:${app.get(GrpcServerLifecycle).port}`);
```

## Limits

- Runtimes: Node.js >= 18 and Deno 2 for servers and clients; Bun as a client, and as a server from 1.4 (the HTTP/2 cleartext server of earlier versions answers Bun clients only). Not on Cloudflare Workers or FaaS presets: the server needs a long-running process with its own port.
- The server speaks cleartext HTTP/2 (h2c); terminate TLS in front of it, or serve `handleStream()` from your own TLS server.
- Received messages may be compressed with gzip or deflate; sent messages are not compressed.
- `.proto`: proto2 and proto3. Options, `reserved`, extensions and `extend` are read and ignored; groups and editions are rejected. No server reflection, health service or gRPC-Web.

<!-- https://cell.cellbang.com/packages/http (packages/http/README.md) -->

# Cell - Http Component

The shared HTTP vocabulary of Cell and an HTTP client for calling other services, in the frontend and the backend.

```bash
npm install @celljs/http
```

## Constants

`HttpStatus` (`HttpStatus.NOT_FOUND`, ...), `HttpMethod`, `MediaType` (`MediaType.APPLICATION_JSON`, ...) and `HttpHeaders` (`HttpHeaders.AUTHORIZATION`, ...), used by `@celljs/web`, `@celljs/mvc` and `@celljs/security`.

## HTTP client

`RestOperations` is an HTTP client on the `fetch` of the runtime (Node.js 18+, Bun, Deno, workerd, browsers), with no third-party dependency. Its API is the familiar subset of axios: `get`, `delete`, `head`, `options`, `post`, `put`, `patch` and `request` resolve to `{ status, statusText, headers, data, config }`.

```ts
import { Autowired, Component } from '@celljs/core';
import { RestOperations } from '@celljs/http';

@Component()
export class WeatherClient {
    @Autowired(RestOperations)
    protected readonly rest: RestOperations;

    async today(city: string) {
        const { data } = await this.rest.get('https://api.example.com/weather', { params: { city } });
        return data;
    }
}
```

The request config (`RequestConfig`):

| Option | Meaning |
| --- | --- |
| `url`, `method`, `baseURL` | `baseURL` is prefixed to `url` unless `url` is absolute |
| `headers` | merged with the default headers, case-insensitively; `undefined` leaves a header out |
| `params` | the query string; an array repeats the key (`tag=a&tag=b`), `undefined` / `null` are left out |
| `data` | the body: a string, `URLSearchParams`, `FormData`, `Blob`, binary data or a stream is sent as is, anything else as JSON (`content-type: application/json` unless set). `GET` and `HEAD` send no body |
| `timeout` | milliseconds; no limit by default |
| `signal` | an `AbortSignal` that cancels the request |
| `responseType` | `json` (default: JSON is parsed, anything else stays text), `text`, `arraybuffer`, `blob` or `stream` (the `ReadableStream` of the body) |
| `validateStatus` | which statuses resolve, default 2xx; `null` resolves every status |
| `withCredentials` | in the browser, sends cookies cross-origin too (`credentials: 'include'`) |

Answer headers have lower-case names. A failed request rejects with an `HttpClientError` whose `code` says why: `CELL_HTTP_BAD_STATUS` (the status did not pass `validateStatus`; `error.response` holds the answer), `CELL_HTTP_TIMEOUT`, `CELL_HTTP_ABORTED` or `CELL_HTTP_NETWORK` (`error.cause` is the error of `fetch`). `HttpClientError.is(error, 'CELL_HTTP_BAD_STATUS')` tests for one.

```ts
try {
    await this.rest.post('/orders', order);
} catch (error) {
    if (HttpClientError.is(error, 'CELL_HTTP_BAD_STATUS') && error.response!.status === 409) {
        // ...
    }
    throw error;
}
```

`http.client` in `cell.yml` holds the defaults of every request, with the options above; the frontend receives it too. The defaults send `X-Requested-With: XMLHttpRequest`, which tells `@celljs/security` to answer `401` instead of redirecting to the login page, and `withCredentials: true`, which only the browser uses.

Interceptors work as in axios, except that both kinds run in the order they were added: `rest.interceptors.request.use(config => config)` changes the config before the request is sent, `rest.interceptors.response.use(onAnswer, onError)` the answer or the failure; `use` returns an id for `eject`. To add them to the shared instance, inject `RestOperations` in a component and call `use` in a `@PostConstruct` method, or bind your own `RestOperationsFactory` (`rebind: true`). `new DefaultRestOperations(config)` gives a separate client.

On the server, URLs must be absolute (or relative to `baseURL`). Behind an HTTP proxy, the `fetch` of Node.js ignores `HTTP_PROXY` / `HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is set, which only recent Node.js versions support; Bun and Deno read them by themselves.

For calls between Cell applications, [`@celljs/rpc`](https://github.com/cellbang/cell/tree/main/packages/rpc) gives typed proxies instead.

<!-- https://cell.cellbang.com/packages/jwt (packages/jwt/README.md) -->

# Cell - JWT Component

`JwtService` signs, verifies and decodes JSON Web Tokens with `node:crypto` (no third-party dependency). Algorithms: `HS256/384/512`, `RS256/384/512`, `PS256/384/512`, `ES256/384/512`, and `none` only when listed in `algorithms`.

```yaml
jwt:
  secret: ${env.JWT_SECRET}      # or privateKey / publicKey (PEM)
  signOptions:
    expiresIn: 2h
```

The options, defaults, checks and error messages are those of the `jsonwebtoken` package, so tokens made by either verify with the other: `expiresIn` / `notBefore` / `maxAge` take seconds or `'2h'`, `'7 days'`; `verify` checks `audience` (strings or RegExps), `issuer`, `subject`, `jwtid`, `nonce`, with `clockTolerance`. Failures are `JsonWebTokenError`, `TokenExpiredError` (`expiredAt`) and `NotBeforeError` (`date`). The key must fit the algorithm: an HMAC secret for `HS*`, an RSA key of at least 2048 bits for `RS*` / `PS*` (`allowInsecureKeySizes` to allow less), an EC key on the matching curve for `ES*`.

An HMAC `secret` shorter than 32 bytes (without `privateKey`) is reported as `CELL_SECURITY_WEAK_JWT_SECRET` by `cell check` and by a production start (`securityChecks` of `@celljs/core`): a short secret can be brute-forced from one token. Use `openssl rand -base64 48`, or an RSA / EC key pair.

`JwtUtil.sign / verify / decode` do the same without the container.

<!-- https://cell.cellbang.com/packages/logger (packages/logger/README.md) -->

# Cell - Logger Component with winston

Replaces the default console `Logger` of `@celljs/core` with one backed by [winston](https://github.com/winstonjs/winston).

```bash
npm install @celljs/logger
```

Nothing else changes in your code: components keep injecting `@Autowired(Logger)`.

```yaml
logger:
  level: debug                 # default info
  winstonConfig:               # merged into the winston options
    defaultMeta: { service: my-app }
```

The level comes from `logger.level` (default `info`); `logger.winstonConfig` is merged into the winston options. The per-request access log of `@celljs/web` is written at `debug`, so it is not printed by default; set `logger.level: debug` (or `CELL_LOGGER__LEVEL=debug`) to see it.

<!-- https://cell.cellbang.com/packages/mvc (packages/mvc/README.md) -->

# Cell - MVC Component

Controllers for Cell backends: classes with `@Controller` whose methods answer HTTP requests. It runs on `@celljs/web` (`node:http`, no express). Guide: [HTTP APIs](https://cell.cellbang.com/guide/web).

```bash
npm install @celljs/mvc @celljs/express-adapter
```

`@celljs/express-adapter` is the backend entry that starts the server; the `cell init` templates already depend on both.

```ts
import { Body, Controller, Get, Param, Post } from '@celljs/mvc/lib/node';

@Controller('users')
export class UserController {
    @Get(':id')
    get(@Param('id') id: number) {
        return { id };                       // JSON
    }

    @Post()
    create(@Body() user: { name: string }) {
        return user;
    }
}
```

Import the controller's file from the DI module (`src/node/module.ts`), or it is not loaded.

## Routes

| Decorator | |
| --- | --- |
| `@Controller(path?)` | A component (singleton, proxied for AOP) whose methods are routes under `path`. Also takes `ComponentOption`s: `@Controller({ path: 'users', rebind: true })` |
| `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`, `@Head`, `@Options` | One HTTP method; the argument is the path under the controller (`':id'`), empty for the controller path |
| `@All(path?)` | Every method |

Path syntax: `:name` is one segment, `*` matches anything, `(...)` is optional. Routes are mounted under `server.path` (default `/`); `mvc.path` (default `/*`) is the pattern of requests the MVC handler takes. A request that matches no route gets `404` with the method and path in the message.

## Parameters

| Decorator | Value |
| --- | --- |
| `@Param(name?)` | A path parameter, or all of them |
| `@Query(name?)` | A query parameter, or the whole parsed query |
| `@Body(name?)` | A field of the parsed body, or the whole body |
| `@Header(name?)` | A request header, or all headers |
| `@Cookie(name?)` | A request cookie |
| `@Session(name?)` | A session value |
| `@Req()` / `@Res()` | The request / response objects of `@celljs/web` |

Parameters typed `String`, `Number`, `Boolean` or `Date` are converted. Parameters typed with a class are validated when [`@celljs/validation`](https://github.com/cellbang/cell/tree/main/packages/validation) is installed.

## Responses

| Decorator | Response |
| --- | --- |
| none or `@Json()` | The return value as JSON (`mvc.defaultViewName: json`) |
| `@Text()` | The return value as `text/plain` |
| `@Html(template?)` | A Mustache template rendered with the return value (see below) |
| `@File(file?)` | A Buffer or stream returned by the method, or the file `file` in `mvc.baseFileDir` (default `assets`, relative to the directory of the server code) |
| `@View(name, metadata?)` | A view by name; add views by binding `View` |
| `@Header(name, value)` | Sets a response header |
| `@Cookie(name, value)` | Sets a response cookie |
| `@Session(name, value)` | Stores a value in the session |

A method may be `async`. Returning `undefined` answers `200` with an empty body. Set another status on the response (`@Res() res`, `res.statusCode = 201`) and return the body as usual.

`mvc.jsonView.template` wraps every JSON response and error in a template, for APIs that answer `{ "success": ..., "data": ... }`: `{{model}}` (JSON, `null` when there is none), `{{error}}`, `{{success}}` and `{{code}}` are replaced, every occurrence; `{{error}}` and `{{code}}` are escaped for a JSON string, so write them inside quotes.

## Errors

Throw `HttpError(status, message)` or a subclass such as `NotFoundError` from `@celljs/web/lib/node` to answer with that status; other errors answer `500`. Stack traces are not sent. The error handlers of `@celljs/web` answer with the message `ErrorMessageResolver` allows: in production a server error gives only its status text (`web.errors.exposeMessages` changes it). With `mvc.jsonView.template`, `JsonViewErrorHandler` (priority 2000) answers every error with the template instead and keeps the status of the response.

`@Catch(ErrorType | ErrorType[])` on a method of the controller handles the errors of those types thrown by its routes; the method gets the error and its return value is the response:

```ts
@Catch(QuotaError)
@Text()
onQuota(err: QuotaError) {
    return `handled: ${err.message}`;
}
```

Application-wide error handling is an `ErrorHandler` of `@celljs/web`.

## HTML views

`@Html('page.mustache')` renders a template from `mvc.mustache.baseViewDir` (default `assets/views`) with the value the method returns. `mvc.mustache.cache: true` keeps compiled templates in memory.

Templates use the Mustache syntax, without a third-party engine:

- `{{name}}` writes a value HTML-escaped, `{{{name}}}` or `{{& name}}` as it is; `user.name` reads a path, `.` is the current item;
- `{{#list}}...{{/list}}` repeats for each item, enters an object, or shows when the value is truthy; `{{^list}}...{{/list}}` shows when it is falsy or empty;
- `{{! comment }}` writes nothing.

Partials (`{{> name}}`) and other delimiters (`{{=<% %>=}}`) are not supported: such a template fails when it is compiled.

<!-- https://cell.cellbang.com/packages/oauth2-client (packages/oauth2-client/README.md) -->

# Cell - OAuth2 Client Component

Sign users in with an OAuth 2.0 / OpenID Connect provider (GitHub, Google, Okta, Facebook or any other), and get access tokens for calling APIs with the client-credentials, password and refresh-token grants. It plugs into [`@celljs/security`](https://github.com/cellbang/cell/tree/main/packages/security): a successful login is a normal security login.

```bash
npm install @celljs/oauth2-client @celljs/security
```

## Login with a provider

Register the client in `cell.yml` (server-only, like all configuration):

```yaml
oauth2:
  client:
    registrations:
      github:
        clientId: "${env.GITHUB_CLIENT_ID}"
        clientSecret: "${env.GITHUB_CLIENT_SECRET}"
```

- `google`, `github`, `facebook` and `okta` have templates (`registrationTemplates`, `providerTemplates` in this package's `cell.yml`) with their endpoints and scopes; Okta and other providers need their URLs under `oauth2.client.providers.<id>` (`authorizationUri`, `tokenUri`, `userInfoEndpoint.uri`, `userInfoEndpoint.userNameAttributeName`, `jwkSetUri`, `issuerUri`).
- A registration has `clientId`, `clientSecret`, `scopes`, `authorizationGrantType`, `clientAuthenticationMethod`, `redirectUri`, `provider` (default: its id) and `clientName`.
- Send the browser to `/oauth2/authorization/github` (`oauth2.client.authorizationRequestBaseUri`). The provider redirects back to `/login/oauth2/code/github`; the default redirect URI is built from `server.endpoint`, so set `server.endpoint` to the public URL of the application.
- With the `openid` scope the login is OpenID Connect: the ID token is verified with the provider's JWK set (`@celljs/oauth2-jose`).
- The user's attributes are mapped by `security.userMapperRule.<provider>` of `@celljs/security`.

## Tokens for API calls

`AuthorizedClientManager` authorizes a registration with the grant it declares (`client_credentials`, `password`, `refresh_token`, `authorization_code`) and keeps the tokens, refreshing them `oauth2.client.clockSkew` (60 s) before they expire.

<!-- https://cell.cellbang.com/packages/oauth2-core (packages/oauth2-core/README.md) -->

# Cell - OAuth2 Core Component

The OAuth 2.0 and OpenID Connect vocabulary shared by [`@celljs/oauth2-client`](https://github.com/cellbang/cell/tree/main/packages/oauth2-client) and [`@celljs/oauth2-jose`](https://github.com/cellbang/cell/tree/main/packages/oauth2-jose): authorization requests and responses, access and refresh tokens, grant types, client authentication methods, OIDC scopes, standard claim names, parameter names and error codes (`OAuth2Error`, `OAuth2ErrorCodes`).

```bash
npm install @celljs/oauth2-core
```

Applications usually do not depend on it directly: install `@celljs/oauth2-client`, which brings it in. Import from it when you write your own grant, token store or user service:

```ts
import { AuthorizationGrantType, OidcScopes } from '@celljs/oauth2-core';
```

All exports are backend-only.

<!-- https://cell.cellbang.com/packages/oauth2-jose (packages/oauth2-jose/README.md) -->

# Cell - OAuth2 JOSE Component

JSON Object Signing and Encryption for the OAuth2 packages: JWK set retrieval and caching (`JwkSetManager`), JWS algorithms, and decoding and verifying JWTs such as OpenID Connect ID tokens.

```bash
npm install @celljs/oauth2-jose
```

[`@celljs/oauth2-client`](https://github.com/cellbang/cell/tree/main/packages/oauth2-client) depends on it to verify ID tokens against a provider's `jwkSetUri`; applications rarely use it directly. To sign and verify your own tokens, use [`@celljs/jwt`](https://github.com/cellbang/cell/tree/main/packages/jwt).

All exports are backend-only.

<!-- https://cell.cellbang.com/packages/openapi (packages/openapi/README.md) -->

# Cell - OpenAPI Component

Add `@celljs/openapi` to the dependencies to document the API of your `@celljs/mvc` controllers: the application serves an [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) document at `/openapi.json` and [Swagger UI](https://swagger.io/tools/swagger-ui/) at `/api-docs`. The document is built from the routes themselves (paths, `@Param` / `@Query` / `@Header` / `@Cookie` / `@Body`, TypeScript parameter and return types), so it stays in step with the code; `@Api*` decorators add what types cannot say. Example: [examples/openapi-app](https://github.com/cellbang/cell/tree/main/examples/openapi-app).

```ts
import { Body, Controller, Get, Param, Post, Query } from '@celljs/mvc/lib/node';
import { ApiOperation, ApiProperty, ApiPropertyOptional, ApiResponse, ApiTags } from '@celljs/openapi';
import { IsInt, IsOptional, IsString, Min } from 'class-validator';

export class CreatePet {
    @IsString()                       // class-validator decorators become the schema: type, required, enum, length, range...
    @ApiProperty({ example: 'Tom' })  // ...and @ApiProperty adds a description, an example or the type of an array
    name: string;

    @IsInt() @Min(0) @IsOptional()
    age?? number;
}

export class Pet extends CreatePet {
    @ApiProperty()
    id: number;
}

@Controller('pets')
@ApiTags('Pets')
export class PetController {
    @Get()
    @ApiResponse({ type: [Pet] })    // async methods and arrays need the type: TypeScript emits only Promise / Array
    list(@Query() query: PetQuery): Promise<Pet[]> { ... }

    @Get(':id')
    @ApiOperation({ summary: 'Find a pet' })
    @ApiResponse({ status: 404, description: 'No such pet' })
    get(@Param('id') id: number): Pet { ... }   // the return type is the 200 response

    @Post()
    create(@Body() pet: CreatePet): Pet { ... } // the class of the body is the request schema
}
```

What goes into the document:

- **Paths**: every route of a controller, `:id` as `{id}`; an optional part (`/users(/:id)`) gives one path with it and one without. Routes with a RegExp path are left out.
- **Parameters**: `@Param('id')`, `@Query('q')`, `@Header('x-name')`, `@Cookie('name')` with the type of the parameter; `@Query() query: PetQuery` gives one query parameter per property of the class. Path parameters missing from the method are added as strings.
- **Body**: `@Body() pet: CreatePet` as an `application/json` body; named `@Body('name')` parameters as the properties of an object.
- **Responses**: the `@ApiResponse` ones (on the class for all its methods, or on the method); without a 2xx one, `200` with the return type. The content type follows the view: JSON by default, `text/plain` for `@Text()`, `text/html` for `@Html()`.
- **Schemas**: each class becomes an entry of `components.schemas`, referred to by `$ref`. Its properties are the ones with class-validator decorators (read from class-validator's metadata when it is installed, e.g. with [@celljs/validation](https://cell.cellbang.com/packages/validation); it is not a dependency of this package) or with `@ApiProperty`. A property is required unless it has `@IsOptional()` or `@ApiPropertyOptional()`.
- **Tags**: `@ApiTags`, otherwise the controller name without `Controller`.

| Decorator | On | Purpose |
| --- | --- | --- |
| `@ApiTags(...tags)` | class, method | Groups operations |
| `@ApiOperation({ summary, description, operationId, deprecated })` | method | Describes an operation; `operationId` defaults to `<Class>_<method>` |
| `@ApiResponse({ status, description, type, schema, contentType })` | class, method | A response; repeat it per status; `type: [Pet]` for a list |
| `@ApiProperty(options)` / `@ApiPropertyOptional(options)` | property | A property of a request or response class; `type`, `enum` (a list or a TypeScript enum), `description`, `example`, `format` and any other schema field |
| `@ApiParam` / `@ApiQuery` / `@ApiHeader({ name, ... })` | method | Describes a parameter, or documents one the method reads from the request itself |
| `@ApiSecurity(name, scopes?)` / `@ApiBearerAuth()` | class, method | Requires a security scheme; `bearer` is declared for `@ApiBearerAuth()` when `components.securitySchemes` has none |
| `@ApiExclude()` | class, method | Leaves it out of the document |

## Configuration

```yaml
openapi:
  enabled: true                   # false: serve neither the document nor the UI
  url: /openapi.json              # under server.path
  ui:
    enabled: true
    url: /api-docs
    cdn: https://cdn.jsdelivr.net/npm/swagger-ui-dist@5   # where the page loads Swagger UI from
  document:                       # merged into the generated document
    openapi: 3.0.3
    info:
      title: Pet Store
      version: 1.0.0
    servers:
      - url: https://api.example.com
    components:
      securitySchemes:
        apiKey: { type: apiKey, in: header, name: X-API-Key }
```

The document and the page answer GET requests no controller answered, so a route of the application with the same path wins and other requests pay nothing. They are public unless [@celljs/security](https://cell.cellbang.com/packages/security) protects them; to hide them in production, set `enabled: false` in the production config (`cell.production.yml`).

To write the document to a file without starting a server (for API clients, code generators or a review), fetch it from `createTestApp()` of `@celljs/cli`, as `scripts/export-openapi.ts` of the example does.

`OpenApiDocumentProvider` (`@celljs/openapi/lib/node`) gives the document in code; rebind it to change how it is built.

<!-- https://cell.cellbang.com/packages/retry (packages/retry/README.en.md) -->

# Cell - Retry Component

This project provides retry support for Cell applications. It is used in Cell AI and other applications.

The NPM package for this library is:

```bash
@celljs/retry
```

## Quick Start

This section provides a quick introduction on how to get started with Cell Retry.

### Example

The following example shows how to use Cell Retry:

```typescript

@Component()
export class Service {
    @Autowired(RetryOperations)
    protected retryOperations: RetryOperations;

    service(): void {
        this.retryOperations.execute(async () => {
            // do something
        },
        {
            maxAttempts: 3,
            timeout: 1000,
            recoveryCallback: async () => {
                // recovery logic here
            } 
        });
    }
}
```

This example retries at most three times after the first attempt (`maxAttempts` is the number of retries, not including the first, so at most four executions total). If still unsuccessful, it calls `recoveryCallback`, whose return value becomes the result of `execute`. With no recovery callback or if it also fails, `execute` throws `RetryError` with `cause` being the last error. The `execute` method has various options to include or exclude error types, limit retry attempts, and set backoff strategies.

## Installation

```bash
npm install @celljs/retry
```

## Features and API

This section discusses the features of Cell Retry and shows how to use its API.

### Using `RetryOperations`

To make processing more robust and less prone to failure, sometimes automatically retrying failed operations can succeed on subsequent attempts. Errors suitable for this approach are typically transient. For example, remote calls to web services or RMI services that fail due to network problems or database deadlocks (such as `DeadLockLoserError`) may resolve in a short time. To automatically retry such operations, Cell Retry provides the `RetryOperations` strategy. The `RetryOperations` interface is defined as follows:

```typescript
/**
 * RetryOperations interface represents the operation to retry tasks with different options.
 */
export interface RetryOperations {
    /**
     * Execute a callback function with the given options.
     *
     * @template T - The return type of the callback function.
     * @param {RetryCallback<T>} callback - The callback function to execute.
     * @param {RetryOptions<T>} options - Options for the retry task.
     * @returns {Promise<T>} - The result of the callback function
     * @throws {RetryError} - An error occurred during retrying.
     * @example
     * const result = await retryOperations.execute(async () => {
     *     // do something
     * }, { maxAttempts: 3, timeout: 1000 });
     * console.log(result);
     * @example
     * const result = await retryOperations.execute(async () => {
     *     // do something
     * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000 } });
     * console.log(result);
     * @example
     * const result = await retryOperations.execute(async () => {
     *     // do something
     * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2 } });
     * console.log(result);
     * @example
     * const result = await retryOperations.execute(async () => {
     *     // do something
     * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2, random: true } });
     * console.log(result);
     * @example
     * const result = await retryOperations.execute(async () => {
     *     // do something
     * }, { maxAttempts: 3, timeout: 1000, backOffOptions: { delay: 1000, multiplier: 2, random: true, maxDelay: 5000 } });
     * console.log(result);
     */
    execute<T>(callback: RetryCallback<T>, options?: RetryOptions<T>): Promise<T>;
}
```

A basic callback function is a simple interface that allows you to insert some business logic for retry:

```typescript
export interface RetryCallback<T> {
    (): Promise<T>;
}
```

The callback function will be attempted, and if it fails (throws an error), it will retry until it succeeds or the implementation decides to stop.

The following example shows how to use it:

```typescript
@Component()
export class Service {
    @Autowired(RetryOperations)
    protected retryOperations: RetryOperations;

    service(): void {
        this.retryOperations.execute(async () => {
            // do something
        },
        {
            maxAttempts: 3,
            timeout: 1000,
            backOffOptions: {
                delay: 1000,
                multiplier: 2,
                random: true,
                maxDelay: 5000
            },
        });
    }
}
```

In the example above, we execute the `service` method with at most three retries. The `execute` method has various options to include or exclude error types, limit retry attempts, and set backoff strategies.

### Using `RetryContext`

The method parameter of `RetryCallback` is a `RetryContext`. Many callbacks ignore the context. However, if needed, you can use it as a property bag to store data during iterations. It also has some useful properties, such as `retryCount`.

### Using `RecoveryCallback`

When retries are exhausted, `RetryOperations` can pass control to a different callback function: `RecoveryCallback`. To use this feature, the client can pass the callback function together to the same method, as shown in the example below:

```typescript
@Component()
export class Service {
    @Autowired(RetryOperations)
    protected retryOperations: RetryOperations;

    service(): void {
        this.retryOperations.execute(async () => {
            // do something
        },
        {
            maxAttempts: 3,
            timeout: 1000,
            recoveryCallback: async () => {
                // recovery logic here
            } 
        });
    }
}
```

If the business logic does not succeed before the template decides to stop, the client has a chance to do some alternative processing through the recovery callback function.

## Retry Strategies

Inside `RetryOperations`, the retry or failure decision in the `execute` method is determined by `RetryPolicy`. `RetryOperations` is responsible for creating `RetryContext` and passing it to `RetryCallback` on each attempt. After the callback fails, `RetryOperations` must call `RetryPolicy` to ask it to update the state (stored in `RetryContext`). Then it asks the policy whether another attempt can be made. If another attempt cannot be made (for example, a limit is reached or a timeout is detected), the policy is also responsible for identifying the exhausted state, but not for handling the exception. `RetryOperations` throws the original exception, which is `RetryError` in this case.
> *Tip:* Failure is inherently either retryable or not retryable—if the same exception is always thrown from business logic, retrying it is useless. Therefore, you should not retry on all exception types. Instead, try to focus only on exceptions you expect to be retryable. For business logic, more aggressive retrying usually will not hurt, but it is wasteful because if failure is deterministic, you are wasting time retrying something you know is fatal.

Cell Retry provides a generic `RetryPolicy` implementation. This implementation provides options for the maximum number of retries, timeouts, exception types, and more to control retry behavior.

## Backoff Strategies

When retrying after a temporary failure, waiting a while before trying again is usually helpful, because (usually) the failure is caused by something that can only be resolved by waiting. If `RetryCallback` fails, `RetryOperations` can pause execution according to `BackoffPolicy`. The following listing shows the definition of the `BackoffPolicy` interface:

```typescript
export interface BackOffPolicy {
    start(ctx: RetryContext): Promise<BackOffContext>;
    backOff(ctx: BackOffContext): Promise<void>;
}
```

`BackoffPolicy` can be freely implemented in any way to backoff. The policies provided by Cell Retry all use `timeout`. A common use case is exponentially increasing wait periods for backoff to avoid two retries entering lockstep and both failing (a lesson learned from Ethernet). Cell Retry also provides a version with a randomized delay strategy, which is useful for avoiding resonance between related failures in complex systems.

The default `BackOffPolicy` calculates the wait time in milliseconds between two attempts based on `backOffOptions`:

| Option | Wait Time |
| --- | --- |
| `backOffOptions` not set | no wait |
| only `delay` (default 100) | wait `delay` each time |
| `multiplier` | Multiply by `multiplier` each time (if `random: true`, randomly pick between the previous and previous multiplied by `multiplier`). Does not exceed `maxDelay`; if `maxDelay` is not set, the limit is 30000 (`DEFAULT_MAX_DELAY`). |
| `maxDelay` with `multiplier` not set | Randomly pick between `delay` and `maxDelay`. |

<!-- https://cell.cellbang.com/packages/rpc (packages/rpc/README.md) -->

# Cell - Rpc Component

Typed remote calls between the frontend and the backend of a Cell application, or between Cell backends: [JSON-RPC 2.0](https://www.jsonrpc.org/specification) over HTTP or over one WebSocket connection, with the same TypeScript interface on both sides. Over WebSocket the backend can also call the frontend. Guide: [Frontend and RPC](https://cell.cellbang.com/guide/frontend).

```bash
npm install @celljs/rpc
```

```ts
// src/common/greeting-protocol.ts
export const GreetingServer = Symbol('GreetingServer');
export interface GreetingServer {
    greet(name: string): Promise<string>;
}

// src/node/greeting-server.ts
import { Rpc } from '@celljs/rpc';

@Rpc(GreetingServer)
export class GreetingServerImpl implements GreetingServer {
    async greet(name: string) { return `Hello, ${name}`; }
}

// frontend (a React component)
import { useRpc } from '@celljs/react';
const greetingServer = useRpc<GreetingServer>(GreetingServer);
const text = await greetingServer.greet('web');
```

## Services

`@Rpc(id)` registers the class as a component (it takes `ComponentOption`s like `@Component`) and serves it at `POST /<rpc.path>/<id>`, by default `/api/GreetingServer` (`rpc.path: api`, under `server.path`). The body is a JSON-RPC request (`{ "jsonrpc": "2.0", "id": 1, "method": "greet", "params": ["web"] }`), a batch (an array), or a notification (no `id`, answered with 204). Only methods declared by the class (and its superclasses) can be called, not `constructor` or those of `Object`. Parameters typed with a class are converted and validated by `@celljs/validation` when it is installed.

Errors answer as HTTP errors do: an `ApplicationError` keeps its code, message and data; a 4xx `HttpError` its message; any other error only `Internal Server Error` in production (`web.errors.exposeMessages`), and it is logged. Stacks never leave the server. The caller gets an `RpcError` with `code` (JSON-RPC), `status` (HTTP) and a stack that leads to the call, or the `ApplicationError` again.

## Clients

| Where | How |
| --- | --- |
| A React component of the same application | `useRpc<T>(Id)` of `@celljs/react`: the endpoint is the page's origin |
| A component (frontend or backend) | `@Autorpc(Id) protected readonly service: T` |
| Anywhere, with an explicit URL, over HTTP | `RpcUtil.create<T>('https://host/api', Id)` |

The endpoint of a service is resolved from:

```yaml
rpc:
  endpoint:                     # per service id; always HTTP
    GreetingServer: "http://greetings:3000/api/GreetingServer"
  defaultEndpoint: "http://gateway:3000{rpcPath}/{serviceIdentifier}"
```

`{rpcPath}` and `{serviceIdentifier}` are replaced. Without either, a browser uses `location`; a backend without them fails with `EndpointNotFoundError`.

## WebSocket

```yaml
rpc:
  transport: websocket          # default http
```

Proxies then call the services without their own `rpc.endpoint` over one WebSocket connection per client, at `/<rpc.path>/ws` (methods are `<service>/<method>`). Each call passes the middlewares like an HTTP call, with the headers and cookies of the connection's upgrade request, so sessions and `@celljs/security` apply. While no connection can be made (an old browser, a platform without WebSocket support such as the serverless presets, a proxy that drops upgrades) calls go over HTTP, and the client tries again later; a connection that drops answers its pending calls with `RpcError` code `-32003` (they are not sent again: they may have run).

The backend calls the frontend through the connection of a call, or any open connection:

```ts
// src/common/notice-protocol.ts
export const NoticeClient = Symbol('NoticeClient');
export interface NoticeClient {
    notify(text: string): Promise<void>;
}

// src/browser/notice-client.ts (imported by src/browser/module.ts)
import { RpcClient } from '@celljs/rpc';

@RpcClient(NoticeClient)
export class NoticeClientImpl implements NoticeClient {
    async notify(text: string) { /* show it */ }
}

// src/node/order-server.ts
import { Autowired } from '@celljs/core';
import { Rpc } from '@celljs/rpc';
import { RpcConnectionManager, RpcContext } from '@celljs/rpc/lib/node';

@Rpc(OrderServer)
export class OrderServerImpl implements OrderServer {
    @Autowired(RpcConnectionManager)
    protected readonly connections: RpcConnectionManager;

    async watch(): Promise<void> {
        const connection = RpcContext.requireConnection();   // the caller's connection
        connection.onClose(() => { /* stop watching */ });
        await connection.client<NoticeClient>(NoticeClient).notify('watching');
    }

    async announce(text: string): Promise<void> {
        await Promise.all(this.connections.connections.map(c => c.client<NoticeClient>(NoticeClient).notify(text)));
    }
}
```

With `@RpcClient` components the frontend opens the connection as it starts and reopens it when it drops. `RpcContext.connection()` is undefined for a call over HTTP; `requireConnection()` then throws `RpcNoConnectionError` (400, `CELL_RPC_NO_CONNECTION`). Calls to a client time out after `rpc.websocket.callTimeout`; a closed connection rejects them.

| Key | Default | |
| --- | --- | --- |
| `rpc.websocket.allowedOrigins` | | Origins besides the server's own whose pages may connect, or `*`. Browsers send the cookies of the server with a WebSocket request from any page, so other origins are refused (403) |
| `rpc.websocket.maxPayload` | `1048576` | Largest message in bytes; a larger one closes the connection (1009) |
| `rpc.websocket.heartbeat` | `30000` | Milliseconds between pings of the server; a client that answers none is dropped |
| `rpc.websocket.callTimeout` | `30000` | Milliseconds a call waits for its answer |
| `rpc.websocket.reconnectDelay` | `1000` | Milliseconds before a client tries again; doubles up to 30 s |
| `rpc.websocket.endpoint` | the page's origin | `ws://` / `wss://` URL to connect to; needed by a backend calling another backend over WebSocket |

The server side is part of the package (no dependency); it needs a runtime whose `node:http` hands over upgrades: Node.js, Deno, and Bun 1.4 or later (older Bun versions log a warning and the clients use HTTP).

A `RpcWebSocketGuard` component (`allows(request): boolean`) decides on the upgrade request whether a connection may open, before anything runs over it; refused connections get a 401. All guards must agree.

## Batching

Over HTTP, `rpc.merge.enabled: true` makes the proxies send the calls made within `timerDelay` (35 ms) in one request (a JSON-RPC batch), up to `maxCount` calls or `maxLength` bytes.

<!-- https://cell.cellbang.com/packages/schedule (packages/schedule/README.md) -->

# Cell - Schedule Component

Cron jobs for Cell backends, on the [cron](https://github.com/kelektiv/node-cron) package.

```bash
npm install @celljs/schedule
```

```ts
import { Autowired } from '@celljs/core';
import { Cron, CronExpression, Scheduler } from '@celljs/schedule';

@Scheduler()
export class ReportScheduler {
    @Autowired(ReportService)
    protected readonly reports: ReportService;

    @Cron(CronExpression.EVERY_5_MINUTES)
    async refresh(): Promise<void> {
        await this.reports.refresh();
    }

    @Cron('0 30 2 * * *', { name: 'nightly', timeZone: 'Asia/Shanghai' })
    nightly(): Promise<void> {
        return this.reports.archive();
    }
}
```

Import the file from the backend DI module like any component.

- `@Scheduler(cronJobOptions?, componentOption?)` makes the class a component whose `@Cron` methods are jobs. Its `cronJobOptions` apply to every job of the class.
- `@Cron(cronTime, options?)`: `cronTime` is a cron expression with an optional seconds field (`'*/10 * * * * *'`) or a `Date`. `options` are those of the cron package's `CronJob` (`timeZone`, `utcOffset`, `runOnInit`, ...) plus `name`. `CronExpression` has common expressions (`EVERY_SECOND`, `EVERY_5_MINUTES`, `EVERY_DAY_AT_MIDNIGHT`, ...).
- Jobs start with the application and stop with it. An error thrown by a job is logged; the job keeps its schedule.
- `schedule.disabled: true` starts no job, for example in `cell.test.yml`.
- `SchedulerRegistry` adds, gets and deletes jobs at runtime: `registry.add('cleanup', { cronTime: '0 * * * *', onTick: () => ... }).start()`.

Jobs run inside the server process: they only run while it runs. On serverless presets (`fc`, `scf`, `lambda`, `vercel`, `cloudflare`) instances are created and stopped by requests, so use the platform's timers instead.

<!-- https://cell.cellbang.com/packages/security (packages/security/README.md) -->

# @celljs/security

Authentication and authorization for Cell backends: form login, HTTP Basic, logout, `@Authenticated()` / `@Anonymous()` / `@PreAuthorize()` on controllers, and password hashing. Install it and it is active; no registration is needed.

```bash
npm install @celljs/security
```

## Users

**There is no built-in user.** Give the login a user source in one of two ways:

1. One user in `cell.yml`. `password` is a hash made by the `PasswordEncoder`, never the plain password:

   ```yaml
   security:
     username: admin
     password: pbkdf2-sha256$600000$<salt>$<key>
   ```

   Make a hash with the encoder of the version you deploy, for example:

   ```js
   // hash.mjs — node hash.mjs 'the password'
   import 'reflect-metadata';
   import { Pbkdf2PasswordEncoder } from '@celljs/security/lib/node/crypto/password/password-encoder';
   console.log(await new Pbkdf2PasswordEncoder().encode(process.argv[2]));
   ```

   If you set `security.passwordEncoder.secret` (a pepper), new hashes depend on it: make them inside the application (inject `PasswordEncoder`), not with the script above.

2. Your own `UserService`, for users stored in a database:

   ```ts
   import { Component } from '@celljs/core';
   import { User, UserType } from '@celljs/security/lib/common';
   import { UserService, UsernameNotFoundError } from '@celljs/security/lib/node';

   @Component({ id: UserService, rebind: true })
   export class DbUserService implements UserService<string, User> {
       async load(username: string): Promise<User> {
           const row = await findUser(username);              // your data access
           if (!row) {
               throw new UsernameNotFoundError(`Could not find: ${username}`);
           }
           return {
               type: UserType.Database, username, password: row.passwordHash, policies: [],
               accountNonExpired: true, accountNonLocked: true, credentialsNonExpired: true, enabled: true
           };
       }

       // Optional: lets a login replace an outdated hash (see "Password hashes").
       async updatePassword(user: User, encodedPassword: string): Promise<void> {
           await saveHash(user.username, encodedPassword);
       }
   }
   ```

With neither, the application starts and logs a warning that no user can log in (an application may log in with OAuth2 only, or use this package for authorization alone).

## Logging in

| Way | Request | Result |
| --- | --- | --- |
| Form | `POST /login` with `username` and `password`, as JSON or as a form (`security.loginUrl`, `loginMethod`, `usernameKey`, `passwordKey`) | `302` to `loginSuccessUrl` (or the `redirect` query parameter) with a session cookie; wrong credentials `401` |
| Basic | `Authorization: Basic …` on any request, e.g. `curl -u admin:secret http://localhost:3000/users` | The request itself is authenticated and continues to the resource; wrong credentials `401` |
| Logout | `POST /logout` | `302` to `logoutSuccessUrl` |

Basic is **off by default**; turn it on with `security.basic.enabled: true`. It checks the password on **every request**, and one check is one PBKDF2 derivation with 600000 iterations (about 45 ms of CPU). Use Basic only for low-frequency machine-to-machine calls; for frequent calls log in once and use the session, or use JWT (`@celljs/jwt`).

## Protecting endpoints

```ts
import { Controller, Get } from '@celljs/mvc/lib/node';
import { Anonymous, Authenticated } from '@celljs/security/lib/node';

@Controller('users')
@Authenticated()            // requires a logged-in user; anonymous requests get 401
export class UserController {
    @Get()
    list() { return []; }
}

@Controller()
@Anonymous()                // reachable without logging in
export class HomeController {}
```

`@PreAuthorize(el)` / `@PostAuthorize(el)` check an expression before or after the method; `@Authorize`, `@Resource` and `@Action` work with policies. In an ACL policy, `resource` and `action` are globs matched against a part of the name, as `micromatch.contains` did: `order:*` matches `order:1` and `tenant:order:1`; `*` stops at `/`, `**` does not; `?`, `[0-9]` and `{a,b}` work as in globs.

In the browser, `UserManager.userInfoSubject` is Cell's own `BehaviorSubject` (`value`, `next()`, `subscribe()` that returns `{ unsubscribe() }`), not an rxjs one.

## Password hashes

`PasswordEncoder` (`Pbkdf2PasswordEncoder`) stores `pbkdf2-sha256$<iterations>$<salt>$<key>`: PBKDF2-HMAC-SHA256, 600000 iterations, a random 16-byte salt, compared in constant time.

Hashes stored by 4.0.x keep matching. After a successful login (form or Basic), such a hash is replaced by a new one when your `UserService` implements `updatePassword()`. **The upgrade is one-way: once a user has logged in, an application rolled back to 4.0.x can no longer check that user's password.** Hashes made with crypto-js 4.1 or older are not supported.

## Configuration

Keys under `security` (defaults in this package's `cell.yml`):

| Key | Default | |
| --- | --- | --- |
| `username`, `password` | — | The single user of the default `UserService`; `password` is a hash |
| `loginUrl`, `loginMethod` | `/login`, `POST` | Form login endpoint |
| `usernameKey`, `passwordKey` | `username`, `password` | Field names of the form login |
| `loginSuccessUrl` | `/` | Where a form login redirects |
| `logoutUrl`, `logoutMethod`, `logoutSuccessUrl` | `/logout`, `POST`, the login page | Logout |
| `basic.enabled`, `basic.realm` | `false`, `realm` | HTTP Basic |
| `passwordEncoder.secret` | — | Optional pepper mixed into new hashes |

<!-- https://cell.cellbang.com/packages/serve-static (packages/serve-static/README.md) -->

# Cell - Serve Static Component

Serves the frontend build from the backend. The `fullstack` template depends on it; projects without a frontend do not need it.

```bash
npm install @celljs/serve-static
```

It serves `serveStatic.root` (default `${paths.public}`, the `public/` directory of the build output) with Cell's own file sender: Content-Type, a weak ETag, Last-Modified, Cache-Control, `304` for fresh requests, `412` for failed `If-Match` / `If-Unmodified-Since`, single byte ranges (`206` / `416`), dotfiles ignored, and paths that leave the root refused. With `spa: true` (default) unknown paths get `/index.html`, so client-side routes work on reload. When there is no frontend directory, requests pass through.

`serveStatic.options`: `maxAge` (milliseconds, default one year), `immutable` (default `true`), `htmlMaxAge` (Cache-Control of HTML files and web app manifests, `.webmanifest`, default 0), `headers` (added to every file), `index` (default `index.html`, `false` for none), `extensions` (tried when a path has none), `dotfiles` (`ignore` default, `allow`, `deny`), `redirect` (`301` from a directory to its path with `/`), `acceptRanges`, `cacheControl`, `etag`, `lastModified` (default `true`), `fallthrough` (default `true`).

With `cell build --single`, the files are embedded in the server bundle and served from memory with the same headers.

<!-- https://cell.cellbang.com/packages/stripe (packages/stripe/README.md) -->

# Cell - Stripe Component

Add `@celljs/stripe` and [`stripe`](https://www.npmjs.com/package/stripe) (the official SDK, a peer dependency) to the dependencies to use [Stripe](https://stripe.com/docs/api): `@Autowired(StripeClient)` gives the Stripe client of the configuration, and a webhook endpoint verifies the `Stripe-Signature` of events and routes them to your handlers by type. The API itself is the official SDK's, with its types.

```bash
bun add @celljs/stripe stripe
```

```yaml
# cell.yml: configuration is server-only unless a schema marks it public; take secrets from the environment
stripe:
  apiKey: ${env.STRIPE_SECRET_KEY}
  webhook:
    secret: ${env.STRIPE_WEBHOOK_SECRET}     # whsec_...
```

```ts
import { Autowired } from '@celljs/core';
import { Body, Controller, Post } from '@celljs/mvc/lib/node';
import { StripeClient, StripeWebhookHandler } from '@celljs/stripe';
import type Stripe from 'stripe';

@Controller('checkout')
export class CheckoutController {
    @Autowired(StripeClient)
    protected readonly stripe: StripeClient;

    @Post()
    async create(@Body() order: { id: string }) {
        const session = await this.stripe.checkout.sessions.create({
            mode: 'payment',
            line_items: [{ price: 'price_123', quantity: 1 }],
            client_reference_id: order.id,
            success_url: 'https://shop.example.com/paid',
        });
        return { url: session.url };
    }
}

@StripeWebhookHandler('checkout.session.completed')
export class CheckoutCompletedHandler implements StripeWebhookHandler<Stripe.CheckoutSessionCompletedEvent> {
    async handle(event: Stripe.CheckoutSessionCompletedEvent) {
        // event.data.object is the session; mark the order paid once: Stripe can deliver an event more than once.
    }
}
```

## Webhooks

The endpoint is `POST /stripe/webhook` (`stripe.webhook.url`, under `server.path`): register its URL in the Stripe Dashboard, or forward events to it during development with `stripe listen --forward-to localhost:3000/stripe/webhook` (set `secret` to the one it prints). It runs before the body parser and authentication, verifies the signature over the body as sent with each `secret` (a list serves several endpoints or a rotation) and a `tolerance` of 300 seconds, then runs the `@StripeWebhookHandler` components of the event type, then those declared without types, one after the other. It answers:

- 200 `{"received":true}` when they all succeed (or when no handler takes the type: logged as a warning);
- 400 when the signature does not match;
- 500 when a handler throws (or the secret is not configured): Stripe retries the event for up to three days.

`StripeWebhookVerifier` verifies a request received on a route of your own: `verify(rawBody, signatureHeader)`.

## Configuration

```yaml
stripe:
  apiKey: ${env.STRIPE_SECRET_KEY}
  config:                      # options of the Stripe client
    maxNetworkRetries: 2
    # apiVersion: 2025-...     # pin one; the SDK's own by default
  webhook:
    enabled: true
    url: /stripe/webhook
    secret: ${env.STRIPE_WEBHOOK_SECRET}   # or a list
    tolerance: 300             # seconds
```

The client is created on first use; rebind `StripeFactory` (`@Component({ id: StripeFactory, rebind: true })`) to create it another way, for example with a key per tenant. The SDK picks its fetch and SubtleCrypto build on Bun, Deno and Cloudflare Workers. Current versions of `stripe` need Node.js 20 or later (the rest of Cell runs on 18).

## Testing without a Stripe account

[stripe-mock](https://github.com/stripe/stripe-mock) answers every API of Stripe's OpenAPI spec and validates the parameters (it keeps no state). Point the client at it with `config: { host: '127.0.0.1', port: 12111, protocol: 'http' }` and any `sk_test_<letters and digits>` key; this package's own tests against it run with:

```bash
docker run --rm -p 12111:12111 stripe/stripe-mock
STRIPE_MOCK_URL=http://127.0.0.1:12111 bunx turbo run test --filter=@celljs/stripe
```

## Errors

Stripe's API errors are the SDK's (`Stripe.errors.StripeError`). Configuration and webhook failures are `CellStripeError`s with a stable `code` and a `hint`:

| Code | When |
| --- | --- |
| `CELL_STRIPE_NOT_CONFIGURED` | `stripe.apiKey` is not set when the client is injected |
| `CELL_STRIPE_WEBHOOK_NOT_CONFIGURED` | An event arrived and `stripe.webhook.secret` is not set |
| `CELL_STRIPE_SIGNATURE_INVALID` | No secret verifies the `Stripe-Signature`, or its timestamp is outside `tolerance` |

<!-- https://cell.cellbang.com/packages/typeorm (packages/typeorm/README.md) -->

# Cell - typeorm Component

[TypeORM](https://typeorm.io) data sources, repositories and `@Transactional()` for Cell backends.

## Install

```bash
npm install @celljs/typeorm mysql2
```

Database drivers are not dependencies of this package: install the one your data source uses (`mysql2`, `pg`, `better-sqlite3`, `sql.js`, …). `mysql2` is an optional peer dependency; when the driver of a configured data source is missing, the application fails at startup with `CELL_TYPEORM_DRIVER_MISSING` and the command that installs it.

## Configure the data source

`typeorm.ormConfig` is a list of TypeORM `DataSourceOptions` (or one object). The default, from this package's `cell.yml`, reads the environment:

| Variable | Default |
| --- | --- |
| `DB_TYPE` | `mysql` |
| `DB_HOST` | `localhost` |
| `DB_PORT` | `3306` |
| `DB_SYNC` | `true` (only `'true'` enables `synchronize`) |
| `DB_DATABASE` | `test` |

Write your own in `cell.yml`; configuration is server-only, so credentials stay on the server:

```yaml
typeorm:
  ormConfig:
    - type: postgres
      host: "${env.DB_HOST ?? 'localhost'}"
      port: "${ (env.DB_PORT ?? 5432) * 1 }"
      username: "${env.DB_USER}"
      password: "${env.DB_PASSWORD}"
      database: app
      synchronize: false
```

Override single values per environment with `CELL_TYPEORM__ORM_CONFIG__0__HOST=db.internal`. For tests, `cell.test.yml` can switch to SQLite in memory (`type: sqljs` with the `sql.js` package). The data sources are created when the application starts and destroyed when it stops.

## Entities

Register the entity classes in the DI module; the `entities` of the data source are filled from them:

```ts
// src/node/module.ts
import './todo-controller';
import { autoBind } from '@celljs/core';
import { autoBindEntities } from '@celljs/typeorm';
import { Todo } from './todo';

autoBindEntities({ Todo });          // an object or an array of classes
export default autoBind();
```

```ts
// src/node/todo.ts
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class Todo {
    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    title: string;

    @Column({ default: false })
    done: boolean;
}
```

## Repositories and transactions

```ts
import { Body, Controller, Get, Post } from '@celljs/mvc/lib/node';
import { OrmContext, Transactional } from '@celljs/typeorm/lib/node';
import { Todo } from './todo';

@Controller('todos')
export class TodoController {
    @Get()
    @Transactional({ readOnly: true })
    list(): Promise<Todo[]> {
        return OrmContext.getRepository(Todo).find({ order: { id: 'ASC' } });
    }

    @Post()
    @Transactional()
    create(@Body() body: { title: string }): Promise<Todo> {
        return OrmContext.getRepository(Todo).save(Object.assign(new Todo(), { title: body.title }));
    }
}
```

- `@Transactional()` runs the method in a transaction: committed when it returns, rolled back when it throws. Within it, `OrmContext.getRepository()`, `getTreeRepository()`, `getMongoRepository()` and `getEntityManager()` use the transaction's entity manager, also in the services the method calls.
- `readOnly: true` uses the data source's manager without a transaction. `isolation` sets the isolation level.
- `propagation`: `Propagation.Required` (default) joins a transaction that is already active; `Propagation.RequiresNew` always starts one. Pass it together with the data source name: `@Transactional({ name: 'default', propagation: Propagation.RequiresNew })`.
- It works on any component method and outside of requests (it creates the context it needs).

## Several data sources

Give each entry of `ormConfig` a `name`; the entry without one is `default`. Then name it everywhere:

```ts
autoBindEntities([AuditLog], 'audit');

@Transactional('audit')
async record() {
    await OrmContext.getRepository(AuditLog, 'audit').save(...);
}
```

`DataSourceManager` (`@celljs/typeorm`) gives the TypeORM `DataSource` objects themselves.

<!-- https://cell.cellbang.com/packages/validation (packages/validation/README.md) -->

# Cell - Validation Component

Add `@celljs/validation` to the dependencies to check request data: a controller or RPC parameter whose type is a class becomes an instance of it ([class-transformer](https://github.com/typestack/class-transformer)) and is validated with its [class-validator](https://github.com/typestack/class-validator) decorators. Failures answer `400` with the errors as JSON.

```ts
import { IsInt, IsString, Min } from 'class-validator';

export class CreateUser {
    @IsString()
    name: string;

    @IsInt()
    @Min(0)
    age: number;
}

@Controller('users')
export class UserController {
    @Post()
    create(@Body() user: CreateUser) { ... }
}
```

Without this package `@celljs/web` passes such parameters the plain request data, and still converts `String`, `Number`, `Boolean` and `Date` parameters (`TypeConversionPipe`).

```yaml
validation:
  detailedOutputDisabled: false   # true: answer 400 without the errors
  transformEnabled: true          # false: hand the method the request data, not the instance
  transformOptions: {}            # options of plainToInstance
  validatorOptions: {}            # options of validate, e.g. whitelist: true
```

<!-- https://cell.cellbang.com/packages/web (packages/web/README.md) -->

# Cell - Web Component

The HTTP layer of Cell: server, middleware chain, context, request body, cookies, sessions, CORS and route matching, on `node:http` with no third-party runtime dependency. Controllers come from [`@celljs/mvc`](https://github.com/cellbang/cell/tree/main/packages/mvc); the guide is [HTTP APIs](https://cell.cellbang.com/guide/web).

## Middleware

A middleware is a component bound to `Middleware`; every request passes through all of them in order of `priority`, highest first, before reaching a handler (MVC, RPC).

```ts
import { Component } from '@celljs/core';
import { Context, HTTP_MIDDLEWARE_PRIORITY, Middleware } from '@celljs/web/lib/node';

@Component(Middleware)
export class TimingMiddleware implements Middleware {
    readonly priority = HTTP_MIDDLEWARE_PRIORITY - 10;

    async handle(ctx: Context, next: () => Promise<void>): Promise<void> {
        const start = Date.now();
        await next();
        ctx.response.setHeader('server-timing', `app;dur=${Date.now() - start}`);
    }
}
```

The built-in ones, highest first: trace (`TRACE_MIDDLEWARE_PRIORITY`, 2200), CORS (2100), body and `HttpRequest` (2000), cookies and health (1900), session (1800); `@celljs/security` adds its own below them. A middleware that throws hands the error to the error handlers.

## Errors

Throw `HttpError(status, message?, { cause?, expose? })` or `NotFoundError(message)` to answer with a status; anything else answers `500`. Without a message, the message is the status text (`Not Found`). The stack, with each `cause`, is logged at the error level and never sent; a 4xx `HttpError`, or any error a handler answered with a redirect or a 4xx (login required, access denied), is an answer, not a failure, and is only logged at the debug level.

What the client sees is decided by `ErrorMessageResolver`: the message of an `HttpError` with `expose` (the default for 4xx); for anything else the message when `web.errors.exposeMessages` is true, else the status text (`Internal Server Error`). `exposeMessages` defaults to true outside production (`NODE_ENV` other than `production`), so messages of internal errors (SQL, hosts, file paths) stay in the log in production.

Error handlers are components bound to `ErrorHandler` with `priority`, `canHandle(ctx, err)` and `handle(ctx, err)`: the handler with the highest priority that can handle the error answers, and when its `handle` throws the next one is tried; when none answers, the response ends with a bare `500`, so no request hangs. `ErrorResponseUtil.end(ctx, status, body, contentType?)` ends a failed response (only ends it when the headers were sent). The built-in handlers have priorities up to 2000.

## Request context

`Context` (`@celljs/web/lib/node`) is the current request wherever the code runs during it, carried across `await` with `AsyncLocalStorage`: `Context.getRequest()`, `getResponse()`, `getCookies()`, `getSession()`, `getTraceId()`, and attributes with `Context.setAttr(key, value)` / `Context.getAttr(key)` (request scope by default, `AttributeScope.App` for the application).

## Trace ids and health

Every response carries the trace id in `X-Cell-Trace-ID` (`web.trace.responseField`; `requestField` names the request header it can come from). `GET /health` (`web.health.url`, `web.health.method`) answers the aggregated status of the `HealthIndicator` components as JSON.

## Sessions (`web.session`)

The session is stored in a signed cookie (`CookieSessionStore`) and saved after the request when it changed (`autoCommit`). `maxAge` defaults to one day. Read it with `Context.getSession()` or `@Session()` in a controller; bind your own `SessionStore` to keep sessions elsewhere.

## Requests and responses

`Request` is Node's `IncomingMessage` with `path` (no query, not decoded), `query` (with brackets, as express parsed it: `?a[b]=1&c=2&c=3` → `{ a: { b: '1' }, c: ['2', '3'] }`), `protocol` / `secure` (from the connection; `X-Forwarded-Proto` is not read), `hostname`, `ip`, `originalUrl`, `body` and `get(header)`. `Response` is Node's `ServerResponse` plus `body`, which the http middleware writes after the handler; there is no `res.status()` / `res.send()`: set `statusCode` and `body`, or call `end()`.

`HttpServerUtil.createHandler(container)` is the `(req, res)` handler of the application and `HttpServerUtil.createHttpServer(handler)` a server whose requests are `HttpRequest`s; requests of another server (a dev server, a test, a serverless proxy) get the members with `HttpRequest.enhance(req)`. Express middleware still mounts with `convertExpressMiddleware()` when it only needs Node's `req` / `res`.

## Parameter types

`TypeConversionPipe` converts request data to `String`, `Number`, `Boolean` and `Date` parameters as class-transformer did (`'5'` → `5`). Parameters of other classes get the data as it is; add `@celljs/validation` to turn it into instances and validate them with class-validator.

## Request body (`web.body`)

`request.body` is JSON (`application/json`), text (`text/plain`), a Buffer (`application/octet-stream`) or a form (`application/x-www-form-urlencoded`, with brackets: `a[b]=1` → `{ a: { b: '1' } }`); any other request gets `{}`. gzip, deflate and br bodies are decompressed.

| Key | Default | |
| --- | --- | --- |
| `limit` | `100kb` | Largest body after decompression, in bytes or as `'5mb'` |
| `inflate` | `true` | `false` refuses compressed bodies |
| `strict` | `true` | JSON must be an object or an array |
| `parameterLimit` | `1000` | Most parameters in a form |
| `depth` | `32` | Most levels of brackets in a form |

A malformed body answers `400`, a large one `413`, an unsupported charset or encoding `415`.

## Cookies (`web.cookies`)

With `keys`, cookies are signed (a `<name>.sig` cookie, HMAC-SHA1 with the first key, the format of the `cookies`/`keygrip` packages, so existing signed cookies stay valid); any of the keys verifies, so keys can be rotated by putting the new one first. `Cookies.get(name, { signed: true })` checks the signature; `get(name)` without options does not.

The default `keys` are a placeholder (`['abcdef']`): set your own in production, for example `keys: ["${env.COOKIE_KEY}"]`, since they also sign the session cookie. `CookiesSecurityCheck` reports the placeholder (`CELL_SECURITY_DEFAULT_COOKIE_KEYS`), no keys (`CELL_SECURITY_COOKIE_KEYS_MISSING`: the session cookie can then be edited by the client) and keys shorter than 16 characters (`CELL_SECURITY_WEAK_COOKIE_KEYS`) to `cell check` and to a production start (see `securityChecks` in `@celljs/core`).

## CORS (`web.cors`)

The options of the express `cors` package: `origin` (default `'*'`; a string, `true` for the request's origin, a RegExp or a list, `false` for none), `methods`, `allowedHeaders`, `exposedHeaders`, `credentials`, `maxAge`, `preflightContinue`, `optionsSuccessStatus`.

## Route patterns

`RequestMatcher.match(pattern)` takes a `PathPattern`: `:name` is one segment, `*` is anything (into `_`), `(...)` is optional, `\\` makes the next character plain. `/users/:id` on `/users/42` gives `{ id: '42' }`; no match gives `null`.

<!-- https://cell.cellbang.com/packages/wechat-pay (packages/wechat-pay/README.md) -->

# Cell - WeChat Pay Component

Add `@celljs/wechat-pay` to the dependencies to take payments with [WeChat Pay API v3](https://pay.weixin.qq.com/doc/v3/merchant/4012062524) (微信支付): an injectable `WechatPayClient` signs the requests and verifies the signatures of the answers, and a notification endpoint verifies, decrypts and hands payment and refund notifications to your handlers. It uses Node's `crypto` and `fetch`, with no third-party dependency.

```yaml
# cell.yml: configuration is server-only unless a schema marks it public; take credentials from the environment
wechatPay:
  mchId: ${env.WECHAT_PAY_MCH_ID}                 # 商户号
  appId: ${env.WECHAT_PAY_APP_ID}                 # 公众号 / 小程序 / App 的 AppID
  serialNo: ${env.WECHAT_PAY_SERIAL_NO}           # 商户 API 证书序列号
  privateKey: ${env.WECHAT_PAY_PRIVATE_KEY}       # apiclient_key.pem: its PEM text or its path
  apiV3Key: ${env.WECHAT_PAY_API_V3_KEY}          # APIv3 密钥
  publicKeyId: ${env.WECHAT_PAY_PUBLIC_KEY_ID}    # 微信支付公钥 ID: PUB_KEY_ID_...
  publicKey: ${env.WECHAT_PAY_PUBLIC_KEY}         # 微信支付公钥, PEM
  notifyUrl: https://shop.example.com/wechat-pay/notify
```

```ts
import { Autowired } from '@celljs/core';
import { Body, Controller, Post } from '@celljs/mvc/lib/node';
import { WechatPayClient, WechatPayNotification, WechatPayNotificationHandler, WechatPayTransaction } from '@celljs/wechat-pay';

@Controller('orders')
export class OrderController {
    @Autowired(WechatPayClient)
    protected readonly wechatPay: WechatPayClient;

    @Post('native')      // 扫码支付: show code_url as a QR code
    async native(@Body() order: { id: string }) {
        return this.wechatPay.createNativeOrder({ description: 'Cell T-shirt', out_trade_no: order.id, amount: { total: 100 } }); // in fen: 1 yuan
    }

    @Post('jsapi')       // 小程序 / 公众号: the page calls wx.requestPayment(params)
    async jsapi(@Body() order: { id: string; openid: string }) {
        const { prepay_id } = await this.wechatPay.createJsapiOrder({ description: 'Cell T-shirt', out_trade_no: order.id, amount: { total: 100 }, payer: { openid: order.openid } });
        return this.wechatPay.jsapiParams(prepay_id);
    }
}

@WechatPayNotificationHandler('TRANSACTION.SUCCESS')
export class PaidHandler implements WechatPayNotificationHandler<WechatPayTransaction> {
    async handle({ resource }: WechatPayNotification<WechatPayTransaction>) {
        // resource is decrypted: out_trade_no, transaction_id, trade_state, amount.total...
        // Mark the order paid once: the same notification can come again.
    }
}
```

## Client

The payloads use the field names of WeChat Pay's documentation (snake_case), so its pages apply as they are. `appid`, `mchid` and `notify_url` default to the configuration.

| Method | API |
| --- | --- |
| `createJsapiOrder(order)` → `{ prepay_id }` | JSAPI / 小程序下单; then `jsapiParams(prepayId, appId?)` for `wx.requestPayment` / `getBrandWCPayRequest` |
| `createAppOrder(order)` → `{ prepay_id }` | App 下单; then `appParams(prepayId, appId?)` for the App SDK |
| `createNativeOrder(order)` → `{ code_url }` | Native 扫码下单 |
| `createH5Order(order)` → `{ h5_url }` | H5 下单 (`scene_info.h5_info` required) |
| `queryOrder({ out_trade_no } \| { transaction_id })` | 查询订单 |
| `closeOrder(outTradeNo)` | 关闭订单 |
| `refund(request)` / `queryRefund(outRefundNo)` | 申请退款 / 查询单笔退款 |
| `tradeBill(query)` / `fundFlowBill(query)`, then `download(download_url)` | 交易账单 / 资金账单 |
| `request(method, path, body?, { query, headers })` | Any other API, signed and verified |
| `parseNotification(headers, rawBody)` | Verifies and decrypts a notification received on a route of your own |

`WechatPayUtil` has the primitives: `signMessage`, `verifyMessage`, `decrypt` (AEAD_AES_256_GCM), `encrypt` (RSA-OAEP for sensitive fields; send the key's serial as `Wechatpay-Serial` in `headers`).

## Notifications

The endpoint is `POST /wechat-pay/notify` (`wechatPay.notification.url`, under `server.path`); set its absolute URL as `notifyUrl`. It runs before the body parser and authentication, reads the body as sent, checks the signature and that the timestamp is within `tolerance` seconds (300), decrypts the resource and runs the `@WechatPayNotificationHandler` components of the event type (`TRANSACTION.SUCCESS`, `REFUND.SUCCESS`, `REFUND.ABNORMAL`, `REFUND.CLOSED`), then those declared without types, one after the other. It answers:

- 204 when they all succeed (or when no handler takes the event type: logged as a warning);
- 401 `{"code":"FAIL"}` when the signature or the timestamp is wrong;
- 500 `{"code":"FAIL"}` when a handler throws: WeChat Pay sends the notification again later, so handlers must be idempotent.

Notifications only say what happened: for amounts that matter, check `resource.amount.total` against the order, or call `queryOrder`.

## Keys that verify WeChat Pay

Merchants created since 2024 have a **WeChat Pay public key** (`publicKeyId` + `publicKey`). Older merchants verify with **platform certificates** (平台证书): leave `publicKey` out and the client downloads them from `/v3/certificates` when a signature names a serial it does not know (at most once a minute), or give them as `platformCertificates` (PEM, one or a list). Both can be set during a migration: the serial in `Wechatpay-Serial` selects the key.

## Configuration

```yaml
wechatPay:
  baseUrl: https://api.mch.weixin.qq.com
  timeout: 10000               # milliseconds per request
  notification:
    enabled: true
    url: /wechat-pay/notify
    tolerance: 300             # seconds
```

## Errors

Failures are `WechatPayError`s with a stable `code` and a `hint`:

| Code | When |
| --- | --- |
| `CELL_WECHAT_PAY_NOT_CONFIGURED` | `mchId`, `serialNo`, `privateKey`, `apiV3Key` or the AppID is missing |
| `CELL_WECHAT_PAY_API_ERROR` | WeChat Pay answered an error: `status` and `detail.code` (`ORDER_NOT_EXIST`, `PARAM_ERROR`...) |
| `CELL_WECHAT_PAY_SIGNATURE_INVALID` | An answer or a notification is not signed by WeChat Pay |
| `CELL_WECHAT_PAY_TIMESTAMP_EXPIRED` | A notification's timestamp is outside `tolerance` |
| `CELL_WECHAT_PAY_UNKNOWN_SERIAL` | No public key or platform certificate has the serial of a signature |
| `CELL_WECHAT_PAY_DECRYPT_FAILED` | The resource cannot be decrypted: wrong `apiV3Key` |

WeChat Pay API v3 has no sandbox: test with a real merchant and small amounts, and expose the notification endpoint with a tunnel during development.

<!-- https://cell.cellbang.com/packages/cloud (cloud-packages/cloud/README.md) -->

# Cell - Cloud Component

Shared abstractions of the cloud packages: where credentials, region and account come from, and the `ObjectStorageService` interface that [`@celljs/oss`](https://github.com/cellbang/cell/tree/main/cloud-packages/oss) and [`@celljs/cos`](https://github.com/cellbang/cell/tree/main/cloud-packages/cos) implement.

```bash
npm install @celljs/cloud
```

## Credentials, region, account

| Component | Default source |
| --- | --- |
| `CredentialsProvider` | `cloud.credentials`: `{ accessKeyId, accessKeySecret, token? }` |
| `RegionProvider` | `cloud.region` |
| `AccountProvider` | `cloud.account`: `{ id }` |
| `ClientOptionsProvider` | `cloud.client`: extra options of the vendor client |

```yaml
cloud:
  region: cn-hangzhou
  credentials:
    accessKeyId: "${env.ACCESS_KEY_ID}"
    accessKeySecret: "${env.ACCESS_KEY_SECRET}"
```

Keep credentials in environment variables (`${env.X}` in `cell.yml`); configuration is server-only. Bind your own provider (`rebind: true`) to read them from somewhere else, such as a secrets manager.

## Object storage

`ObjectStorageService` has `createBucket`, `deleteBucket`, `listBuckets`, `listObjects`, `getObject`, `getStream`, `putObject`, `copyObject`, `deleteObject` and `headObject`, with the same request shapes for every vendor:

```ts
import { Autowired, Component } from '@celljs/core';
import { ObjectStorageService } from '@celljs/cloud';

@Component()
export class Uploads {
    @Autowired(ObjectStorageService)
    protected readonly storage: ObjectStorageService<any>;

    save(key: string, body: Buffer) {
        return this.storage.putObject({ bucket: 'uploads', key, body });
    }
}
```

Install one implementation: `@celljs/oss` (Alibaba Cloud) or `@celljs/cos` (Tencent Cloud). `getRawCloudService()` returns the vendor's own client for anything else.

Deploying an application to a cloud platform does not need this package: see the presets of `cell deploy`.

<!-- https://cell.cellbang.com/packages/cos (cloud-packages/cos/README.md) -->

# Cell - COS Component

`ObjectStorageService` of [`@celljs/cloud`](https://github.com/cellbang/cell/tree/main/cloud-packages/cloud) on [Tencent Cloud COS](https://www.tencentcloud.com/products/cos), with the `cos-nodejs-sdk-v5` SDK.

```bash
npm install @celljs/cos
```

```yaml
cloud:
  region: ap-guangzhou
  credentials:
    accessKeyId: "${env.TENCENTCLOUD_SECRET_ID}"
    accessKeySecret: "${env.TENCENTCLOUD_SECRET_KEY}"
```

```ts
@Autowired(ObjectStorageService)
protected readonly storage: ObjectStorageService<any>;

await this.storage.putObject({ bucket: 'my-bucket-1250000000', key: 'a.txt', body: 'hello' });
```

COS bucket names include the APPID. `cloud.client` passes extra options to the COS client. See [@celljs/cloud](https://github.com/cellbang/cell/tree/main/cloud-packages/cloud) for the interface and the credential sources.

<!-- https://cell.cellbang.com/packages/oss (cloud-packages/oss/README.md) -->

# Cell - OSS Component

`ObjectStorageService` of [`@celljs/cloud`](https://github.com/cellbang/cell/tree/main/cloud-packages/cloud) on [Alibaba Cloud OSS](https://www.alibabacloud.com/product/object-storage-service), with the `ali-oss` SDK.

```bash
npm install @celljs/oss
```

```yaml
cloud:
  region: cn-hangzhou            # the client uses oss-<region>
  credentials:
    accessKeyId: "${env.ALIBABA_CLOUD_ACCESS_KEY_ID}"
    accessKeySecret: "${env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}"
```

```ts
@Autowired(ObjectStorageService)
protected readonly storage: ObjectStorageService<OSS>;

await this.storage.putObject({ bucket: 'my-bucket', key: 'a.txt', body: 'hello' });
const body = await this.storage.getObject({ bucket: 'my-bucket', key: 'a.txt' });
```

`cloud.client` passes extra options to the `ali-oss` client (`endpoint`, `internal`, `timeout`, ...). See [@celljs/cloud](https://github.com/cellbang/cell/tree/main/cloud-packages/cloud) for the interface and the credential sources.

<!-- https://cell.cellbang.com/packages/ai-agent (ai-packages/ai-agent/README.en.md) -->

# Cell - AI Agent Component

A general-purpose agent based on [pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core): agent loop, parallel tool execution, and event streams—without code editing or file system permissions, suitable as an assistant in business logic. Models come from [@celljs/ai-pi](https://github.com/cellbang/cell/tree/main/ai-packages/ai-pi). Use [@celljs/ai-coding-agent](https://github.com/cellbang/cell/tree/main/ai-packages/ai-coding-agent) for code reading/writing or command execution scenarios.

- Tools are written as `AgentTool` components and can directly use injected services; the same components also serve as tools in a coding session.
- `AgentFactory` creates an `Agent` from pi-agent-core per `ai.agent` configuration.
- `AgentEventUtil.stream()` writes agent (or coding session) events as Server-Sent Events.

pi-agent-core loads with dynamic `import()` and requires Node.js >= 22.19 or Bun.

## Configuration

```yaml
ai:
  agent:
    model: anthropic/claude-sonnet-4-5   # <provider>/<model id> from pi-ai; defaults to first available model with credentials
    systemPrompt: You are the support assistant of ACME.
    thinkingLevel: low
    tools: [find_order, refund]          # AgentTool component names; defaults to all
    toolExecution: parallel              # or sequential
```

API keys are configured in `ai.pi.apiKeys` or the provider's environment variables.

## Usage

```typescript
import { AgentEventUtil, AgentFactory, AgentTool } from '@celljs/ai-agent';
import { Autowired, Component } from '@celljs/core';
import { Body, Controller, Post, Res } from '@celljs/mvc/lib/node';
import { OrderService } from './order-service';

@Component(AgentTool)
export class FindOrderTool implements AgentTool {
    readonly name = 'find_order';
    readonly label = 'Find order';
    readonly description = 'Finds an order by its number.';
    readonly parameters = { type: 'object', properties: { number: { type: 'string' } }, required: [ 'number' ] };

    @Autowired(OrderService)
    protected readonly orderService: OrderService;

    async execute(_toolCallId: string, params: any) {
        const order = await this.orderService.find(params.number);
        return { content: [ { type: 'text' as const, text: JSON.stringify(order) } ], details: {} };
    }
}

@Controller('assistant')
export class AssistantController {
    @Autowired(AgentFactory)
    protected readonly agentFactory: AgentFactory;

    @Post()
    async ask(@Body('text') text: string, @Res() response: any): Promise<void> {
        const agent = await this.agentFactory.create();
        await AgentEventUtil.stream(agent, response, () => agent.prompt(text));
    }
}
```

Parameters to `create()` (`model`, `systemPrompt`, `thinkingLevel`, `tools`) override configuration; pass `messages` (previously saved `agent.state.messages`) to continue a conversation. Throws `AgentToolNotFoundError` if a tool name does not exist, and `AgentModelMissingError` if no model is available. The `Agent` you get is a native pi-agent-core object: see its documentation for `prompt`, `steer`, `followUp`, `abort`, `subscribe`, and `state`.

Each SSE frame is `event: <type>\ndata: <JSON>`; `message_update` carries only increments and usage, matching pi coding agent's JSON mode; on failure, sends `{ "type": "error", "message": "..." }`.

## Testing

`@celljs/ai-agent/lib/node/test` provides `createAgentTestContainer(options, ...modules)` with `FauxPiModels` as the default model: use `faux.reply('text' | { tool, args } | { error })` to script responses, and `faux.contexts` records each request.

<!-- https://cell.cellbang.com/packages/ai-coding-agent (ai-packages/ai-coding-agent/README.en.md) -->

# Cell - AI Coding Agent Component

Run a [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) coding agent session in a Cell application. Pi handles model calls, tools (read, bash, edit, write, etc.), sessions, and context compression. This component integrates pi into Cell:

- Sessions and model runtime are managed by the DI container and are automatically released when the application stops;
- Configuration is written under `ai.codingAgent` in `cell.yml`, and option names match those of pi's `createAgentSession()`;
- Tools are written as `AgentTool` components (shared with @celljs/ai-agent), pi extensions as `AgentExtension` components, and both can use injected services directly;
- Pi's MCP client, codemode, and tool_search can be enabled by configuration;
- Events are output in pi's JSON-RPC format and can be returned directly to the frontend as Server-Sent Events.

## Requirements

Node.js >= 22.19 or Bun (pi requirement). Pi is an ES module package; this component loads it using dynamic `import()`. Both CommonJS and ESM builds are usable; it is loaded only when the first session is created.

## Installation

```bash
bun add @celljs/ai-coding-agent
```

## Configuration

```yaml
ai:
  codingAgent:
    cwd: /srv/repo                 # session working directory where tools read and write; default process cwd
    model: anthropic/claude-sonnet-4-5   # <provider>/<model id>; defaults to pi's settings, then first model with credentials
    thinkingLevel: medium
    tools: [read, grep, find, ls]  # tool whitelist, supports *; default read, bash, edit, write plus extension-registered tools
    appendSystemPrompt: Answer in Chinese.
    apiKeys:                       # in memory only, not written to pi's auth.json
      anthropic: "${ env.MY_ANTHROPIC_KEY }"
```

| Config | Default | Explanation |
| --- | --- | --- |
| `cwd` | Process cwd | Session working directory where tools read and write; this is also where project resources (AGENTS.md, `.pi/`) are discovered |
| `agentDir` | `~/.pi/agent` | pi global directory: auth.json, models.json, settings.json, extensions, skills |
| `model` / `thinkingLevel` | pi settings | Model as `<provider>/<model id>`, error `AgentModelNotFoundError` with available models if not found |
| `tools` / `excludeTools` | pi default tools | Tool whitelist or blacklist |
| `systemPrompt` / `appendSystemPrompt` | — | Replace or append the system prompt |
| `discoverResources` | `true` | Load extensions, skills, prompt templates, and AGENTS.md from the cwd and agentDir like the pi CLI does |
| `persistSessions` | `false` | Also write sessions as pi CLI JSONL files, visible to `pi --resume` |
| `allowModelNetwork` | `false` | Refresh the model directory online when creating the model runtime |
| `mcp.enabled` / `mcp.servers` | `false` / — | Enable pi's MCP client: connect servers in the agentDir (and trusted projects) `mcp.json`, plus `servers` (format like `mcpServers`) |
| `codemode` | `off` | `on` / `only`: model writes JavaScript, called in sandbox via tools |
| `toolSearch` | `false` | Enable `tool_search` to allow the model to find undeclared tools |
| `apiKeys` | — | Set API keys per provider; empty values are ignored. `ai.pi.apiKeys` (@celljs/ai-pi) is also used for sessions, and entries here take precedence. Pi also reads `ANTHROPIC_API_KEY` etc. from environment variables. |

## Usage

### Create a session and ask

`AgentSessionManager.create()` returns pi's `AgentSession`; you then use pi's API directly (`prompt`, `steer`, `followUp`, `abort`, `subscribe`, `messages`, etc.):

```typescript
import { Autowired, Component } from '@celljs/core';
import { AgentSessionManager } from '@celljs/ai-coding-agent';

@Component()
export class ReviewService {

    @Autowired(AgentSessionManager)
    protected readonly sessionManager: AgentSessionManager;

    async review(): Promise<string | undefined> {
        const session = await this.sessionManager.create({ tools: [ 'read', 'grep', 'find', 'ls' ] });
        try {
            await session.prompt('Review the changes in src/ and list the risks.');
            return session.getLastAssistantText();
        } finally {
            this.sessionManager.dispose(session.sessionId);
        }
    }
}
```

`create()` parameters (`cwd`, `model`, `thinkingLevel`, `tools`, `excludeTools`, `systemPrompt`, `appendSystemPrompt`) override the same-named settings in `ai.codingAgent`. Sessions are stored in memory by pi's `sessionId`: `get(id)` (throws `AgentSessionNotFoundError` if not found), `find(id)`, `info(id)`, `list()`, `dispose(id)`.

### Write tools as Cell components

Tools are [@celljs/ai-agent](https://github.com/cellbang/cell/tree/main/ai-packages/ai-agent) `AgentTool` components (also exported from this package). Tools can use injected services directly. One component serves both as a coding session tool and as a tool for general agents created by `AgentFactory`:

```typescript
import { AgentTool } from '@celljs/ai-coding-agent';
import { Autowired, Component } from '@celljs/core';
import { TicketService } from './ticket-service';

@Component(AgentTool)
export class CreateTicketTool implements AgentTool {
    readonly name = 'create_ticket';
    readonly label = 'Create ticket';
    readonly description = 'Creates a ticket in the issue tracker.';
    readonly parameters = { type: 'object', properties: { title: { type: 'string' } }, required: [ 'title' ] };

    @Autowired(TicketService)
    protected readonly ticketService: TicketService;

    async execute(_toolCallId: string, params: any) {
        const ticket = await this.ticketService.create(params.title);
        return { content: [ { type: 'text' as const, text: `Created ${ticket.id}` } ], details: {} };
    }
}
```

`parameters` is JSON Schema; tool failures are thrown as exceptions. If a `tools` whitelist is configured, the tool name must be listed in it.

### Write pi extensions as Cell components

Extension capabilities beyond tools (commands, event handlers, intercepting tool calls, registering MCP servers, etc.; see pi docs `docs/extensions.md`) are written as `AgentExtension` components. The `register` method receives pi's `ExtensionAPI` for each new session:

```typescript
import { AgentExtension, type ExtensionAPI } from '@celljs/ai-coding-agent';
import { Autowired, Component, Logger } from '@celljs/core';

@Component(AgentExtension)
export class AuditExtension implements AgentExtension {

    @Autowired(Logger)
    protected readonly logger: Logger;

    register(pi: ExtensionAPI): void {
        pi.on('tool_call', async event => {
            this.logger.info(`agent calls ${event.toolName}`);
            return event.toolName === 'bash' ? { block: true, reason: 'bash is disabled' } : undefined;
        });
    }
}
```

If `register` throws an error, session creation fails with `AgentExtensionError`. Errors in extensions discovered from disk are only logged as warnings.

### MCP, codemode, and tool_search

The pi CLI loads these three extensions by default; the SDK does not. Enable them in configuration. MCP server tool names are `mcp__<server>__<tool>`. Tools with `exposure: direct` are declared directly to the model; tools with the default setting (for example, in `codemode`) are only callable within codemode scripts:

```yaml
ai:
  codingAgent:
    codemode: "on"
    mcp:
      enabled: true
      servers:
        docs:
          url: https://example.com/mcp
          headers:
            Authorization: "Bearer ${ env.DOCS_TOKEN }"
        filesystem:
          command: npx
          args: [-y, "@modelcontextprotocol/server-filesystem", "."]
          exposure: direct
```

If a `tools` whitelist is configured, `codemode`, `tool_search`, and `mcp__*` must also be listed. `AgentExtension` can also use `pi.registerMcpServer(name, config)` to register servers on demand.

### Return events as Server-Sent Events

`AgentEventUtil.stream(session, response, run)` writes session events as SSE during the execution of `run` and closes the response when done. If `run` fails, it writes an `error` event:

```typescript
import { AgentEventUtil, AgentSessionManager, type EventStreamResponse } from '@celljs/ai-coding-agent';
import { Autowired } from '@celljs/core';
import { Body, Controller, Param, Post, Res } from '@celljs/mvc/lib/node';

@Controller('sessions')
export class AgentController {

    @Autowired(AgentSessionManager)
    protected readonly sessionManager: AgentSessionManager;

    @Post(':id/prompt')
    async prompt(@Param('id') id: string, @Body('text') text: string, @Res() response: EventStreamResponse): Promise<void> {
        const session = this.sessionManager.get(id);
        await AgentEventUtil.stream(session, response, () => session.prompt(text));
    }
}
```

Each frame is `event: <type>\ndata: <JSON>`. The JSON matches events from pi `--mode json` (pi docs `docs/json.md`): `message_update` carries only deltas and usage information, the full message is in `message_end`, and `agent_settled` marks the round as complete. The component also adds `{ "type": "error", "message": "..." }` when needed. Client disconnection does not abort the session; call `session.abort()` if needed. The full add/get/remove and prompt/abort API is documented in [examples/coding-agent-app](https://github.com/cellbang/cell/tree/main/examples/coding-agent-app).

### Configure model runtime

All sessions share one pi `ModelRuntime` (`ModelRuntimeProvider`). To register custom providers or load credentials from a secret service, implement `ModelRuntimeContribution`:

```typescript
import { type ModelRuntime, ModelRuntimeContribution } from '@celljs/ai-coding-agent';
import { Autowired, Component } from '@celljs/core';
import { SecretStore } from './secret-store';

@Component(ModelRuntimeContribution)
export class GatewayModels implements ModelRuntimeContribution {

    @Autowired(SecretStore)
    protected readonly secrets: SecretStore;

    async configure(runtime: ModelRuntime): Promise<void> {
        await runtime.setRuntimeApiKey('openai', await this.secrets.get('openai'));
    }
}
```

## Testing

`createTestContainer()` and `FauxModels` from `@celljs/ai-coding-agent/lib/node/test` provide scripted models based on pi's faux provider, with no network access and no reading or writing of `~/.pi`:

```typescript
import { AgentSessionManager } from '@celljs/ai-coding-agent';
import { createTestContainer } from '@celljs/ai-coding-agent/lib/node/test';

const { container, faux } = await createTestContainer({ tools: [ 'create_ticket' ] }, myModule);
faux.reply({ tool: 'create_ticket', args: { title: 'Fix login' } }, 'Created.');
const session = await container.get<AgentSessionManager>(AgentSessionManager).create();
await session.prompt('File a ticket for the login bug');
```

`createTestContainer` places the session `cwd` and `agentDir` in a new temporary directory, with the default model being `FauxModels.MODEL`, and resource discovery disabled.

## Security

Pi executes tools (read/write files, run commands) with the service process permissions and no sandbox. When exposing sessions over HTTP, add authentication (e.g., `@celljs/security`), open only the needed tools using `tools`, and limit `cwd` to directories the agent is allowed to access. Do not let clients pass `cwd`. See pi docs `docs/security.md` for details.

## Build Output

Pi remains an external dependency during `cell build` (in `cell.optionalDependencies`). It is copied along with its dependencies to `.cell/output/server/node_modules` (~160 MB); the output directory can be deployed independently.

<!-- https://cell.cellbang.com/packages/ai-core (ai-packages/ai-core/README.en.md) -->

# Cell - AI Core Component

## Overview

AI Core defines the common interfaces in Cell for interacting with AI models: chat model `ChatModel`, embedding model `EmbeddingModel`, prompt template `PromptTemplate`, and `ProxyChatModel` that routes by model name to concrete implementations. It doesn't call any model service itself; models are provided by components implementing these interfaces, currently [@celljs/ai-pi](https://github.com/cellbang/cell/tree/main/ai-packages/ai-pi) (based on pi-ai, connecting 20+ model providers).

## Features

- Generate chat responses, with streaming support
- Prompt templates (variable substitution)
- `ProxyChatModel` routes requests by `<provider>:<model>` to the corresponding `ChatModel` implementation
- Embedding model interface `EmbeddingModel` (no implementation in this repo yet)

## Installation

```bash
npm install @celljs/ai-core @celljs/ai-pi
```

Installing takes effect immediately, no manual registration is needed. Model credentials and provider configuration are in [@celljs/ai-pi](https://github.com/cellbang/cell/tree/main/ai-packages/ai-pi).

## Quick Start

```typescript
import { type ChatModel, PromptTemplate, ProxyChatModel } from '@celljs/ai-core';
import { Autowired, Component } from '@celljs/core';

@Component()
export class Assistant {
    @Autowired(ProxyChatModel)
    protected readonly chatModel: ChatModel;

    @Autowired(PromptTemplate)
    protected readonly promptTemplate: PromptTemplate;

    async chat(name: string): Promise<string> {
        const prompt = await this.promptTemplate.create('Hello {name}', {
            variables: { name },
            // pi:<provider>/<model id>: ProxyChatModel routes by pi before the first colon to @celljs/ai-pi
            chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' }
        });
        const response = await this.chatModel.call(prompt);
        return response.result.output.content;
    }

    async stream(name: string): Promise<void> {
        const prompt = await this.promptTemplate.create('Hello {name}', {
            variables: { name },
            chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' }
        });
        const response$ = await this.chatModel.stream(prompt);
        response$.subscribe({
            next: response => console.log(response.result.output.content),
            complete: () => console.log('Chat completed!')
        });
    }
}
```

Model names must be in `<provider>:<model>` form; `ProxyChatModel` throws `IllegalArgumentError` otherwise.

## License

This project is licensed under the MIT License.

<!-- https://cell.cellbang.com/packages/ai-pi (ai-packages/ai-pi/README.en.md) -->

# Cell - AI pi Component

Integrates [pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai) into Cell. Pi-ai unifies calls to 20+ model service providers (Anthropic, OpenAI, Google, DeepSeek, xAI, OpenRouter, Bedrock, Ollama, and other OpenAI-compatible services, etc.), model catalogs, credentials, and usage statistics. This component provides:

- `PiModelsProvider`: application-level pi-ai `Models` collection, configured via `ai.pi`;
- `PiChatModel`: an implementation of `ChatModel` from @celljs/ai-core that calls pi-ai via `ProxyChatModel` using `pi:<provider>/<model id>`;
- [@celljs/ai-agent](https://github.com/cellbang/cell/tree/main/ai-packages/ai-agent) agents use it to get models.

Pi-ai is an ES module package that the component loads via dynamic `import()`. It is loaded only when a model is first used. Node.js >= 22.19 or Bun is required.

## Configuration

```yaml
ai:
  pi:
    providers: [anthropic, deepseek]   # default all: register all built-in providers from pi-ai
    apiKeys:                           # kept only in memory; providers also read ANTHROPIC_API_KEY etc from environment
      deepseek: "${ env.MY_DEEPSEEK_KEY }"
```

### Compatible Endpoints

The `endpoints` option registers OpenAI or Anthropic-compatible services as providers. The model name is `<endpoint id>/<model id>`:

```yaml
ai:
  pi:
    endpoints:
      local:                                  # model is local/qwen3
        baseUrl: http://localhost:11434/v1    # Ollama; vLLM, LM Studio, custom gateway likewise
        models: [qwen3, { id: deepseek-r1, reasoning: true, contextWindow: 64000 }]
      gateway:
        baseUrl: https://llm.example.com/v1
        api: anthropic-messages               # default openai-completions; also supports openai-responses
        apiKey: "${ env.GATEWAY_KEY }"
        models: [claude-sonnet-4-5]
```

Endpoints without a key receive a placeholder key `no-key`. Items in `apiKeys` with the same name take precedence over `apiKey`.

## Usage

```typescript
import { type ChatModel, PromptTemplate, ProxyChatModel } from '@celljs/ai-core';
import { Autowired, Component } from '@celljs/core';

@Component()
export class Assistant {
    @Autowired(ProxyChatModel)
    protected readonly chatModel: ChatModel;

    @Autowired(PromptTemplate)
    protected readonly promptTemplate: PromptTemplate;

    async ask(question: string): Promise<string> {
        const prompt = await this.promptTemplate.create(question, { chatOptions: { model: 'pi:anthropic/claude-sonnet-4-5' } });
        return (await this.chatModel.call(prompt)).result.output.content;
    }
}
```

`PiChatOptions` supports `reasoning` (reasoning level) and `tools` (tools with JSON Schema parameters; model invocations appear in `AssistantMessage.toolCalls`) beyond @celljs/ai-core's `ChatOptions`. The `stream()` method sends a response for each text increment; the last response includes the complete message, the stop reason (pi-ai's stop reason: `stop`, `toolUse`, `length`), and usage information. When the model returns an error, it throws `PiModelError`. When the model name is incorrect, it throws `PiModelNotFoundError` and lists available models.

To register a custom provider (for example, a custom OpenAI-compatible gateway), implement `PiModelsContribution` and call `models.setProvider(...)` in the `configure(models)` method (see pi-ai documentation on Custom Providers).

## Testing

`createPiTestContainer()` and `FauxPiModels` from `@celljs/ai-pi/lib/node/test` are based on pi-ai's faux provider: they provide scripted responses, record request context on each call, and do not require internet access.

<!-- https://cell.cellbang.com/packages/react (ui-packages/react/README.md) -->

# Cell - React Component

The React frontend of a Cell application: pages declared with decorators, React Router routing, layouts and the application shell, all managed by the frontend DI container. Installing it adds the `frontend` build target (through [`@celljs/widget`](https://github.com/cellbang/cell/tree/main/ui-packages/widget)). Guide: [Frontend and RPC](https://cell.cellbang.com/guide/frontend).

```bash
npm install @celljs/react react
npm install -D @types/react
```

The `fullstack` template of `cell init` is set up with it. `cell dev` serves the frontend with HMR on the backend's port; `cell build` writes it to `.cell/output/public/`.

## Pages

Pages are the files of `src/browser/pages/`, each with the page component as default export: `index.tsx` is `/`, `about.tsx` is `/about`, `users/[id].tsx` is `/users/:id`, `[...rest].tsx` matches the rest of the path, `_layout.tsx` wraps the pages of its directory and below, and `_error.tsx` shows when one of them fails. Names starting with `_` and tests are not pages. The toolchain (`cell dev`, `cell build`) generates the routes (`.cell/generated/frontend/routes.js`, listed by `cell info --json`); each page is a chunk loaded when it is visited. Guide: [Frontend and RPC](https://cell.cellbang.com/guide/frontend).

```tsx
// src/browser/pages/users/[id].tsx
import { useParams } from '@celljs/react';

export default function User() {
    return <h1>User {useParams().id}</h1>;
}
```

Routing is React Router 7; `Link`, `NavLink`, `Navigate`, `Outlet`, `useParams`, `useNavigate`, `useLocation`, `useSearchParams` and `useMatch` are re-exported from here.

Packages, which have no pages directory, add pages and replace parts of the frontend with decorators on a class that their DI module imports:

| Decorator | |
| --- | --- |
| `@View(pathOrMetadata)` / `@Route(...)` | A route. A string is the path; the metadata has `path`, `index`, `component` (default: the decorated class), `layout`, `caseSensitive`, `priority` |
| `@DefaultLayout(component?)` | The layout around every route without its own `layout` (default: none) |
| `@App(component?)` | Replaces the root component |
| `@Router(component?)` | Replaces the router |
| `@Context(component?)` | Adds a React context provider around the application |

Paths are resolved against `react.path` (default `server.path`, `/`).

## Errors

A page that throws while rendering, or whose code does not load, does not blank the application: an `ErrorBoundary` inside its layout shows the fallback instead, and the page is tried again when the user goes to another path. The fallback is the default export of the nearest `_error.tsx` (in the directory of the page or above), which gets `{ error, reset }` (`ErrorFallbackProps`); without one, `DefaultErrorFallback` shows the message and a button to try again. The shell puts another boundary around the whole application, for errors of layouts and of the fallbacks themselves. React logs the errors to the console.

```tsx
// src/browser/pages/_error.tsx
import type { ErrorFallbackProps } from '@celljs/react';

export default function PageError({ error, reset }: ErrorFallbackProps) {
    return <p>Could not show this page ({String(error)}). <button onClick={reset}>Retry</button></p>;
}
```

`ErrorBoundary` (`fallback`, `resetKey`) is exported for parts of a page.

## Services in components

| Hook | |
| --- | --- |
| `useInject<T>(id)` | A component of the container, resolved once per component instance |
| `useValue<T>(key, default?)` | A configuration value, like `@Value(key)` (the frontend only has public keys) |
| `useContainer()` | The container itself |
| `useRpc<T>(id)` | The proxy of a backend service (needs [`@celljs/rpc`](https://github.com/cellbang/cell/tree/main/packages/rpc)), like `@Autorpc(id)` |
| `useLocale()` | `[locale, setLocale]`: the locale of `widget.locales` the user selected, and how to change it |

They use the container of `ContainerContext`, which the shell provides; there is no global container, so a component rendered outside the application fails with a message saying so. In a test, render the component inside `<ContainerContext.Provider value={container}>`; `reactTestModule` (`@celljs/react/lib/browser/test/test-module`) has the components of this package without the shell, which needs a DOM.

```tsx
function Header() {
    const userService = useInject<UserService>(UserService);
    const title = useValue<string>('app.public.title', 'My app');
    return <header>{title}: {userService.name}</header>;
}
```

## Configuration (public: the frontend receives it)

| Key | Default | |
| --- | --- | --- |
| `react.router.type` | `browser` | `hash` for hash-based URLs |
| `react.path` | `${server.path ?? '/'}` | Base path of the routes |
| `react.router.routes` | | Route metadata by path, merged over the decorator's: `{ '/about': { caseSensitive: true, priority: 2000 } }` |

Frontend configuration is evaluated at build time and is visible to anyone who loads the page: never put secrets in it.

## Widgets and slots

`<Slot area="header" />` renders the widgets registered for an area, in order of `priority`; register one with `@Widget({ area: 'header', component: Logo })` from `@celljs/widget`. Libraries use this to let applications add to their layouts without changing them.

## Calling the backend

`useRpc<T>(Id)` returns a typed proxy of a backend service of [`@celljs/rpc`](https://github.com/cellbang/cell/tree/main/packages/rpc); its methods return promises, so call them in an effect or an event handler. For other HTTP APIs, use `fetch` or `RestOperations` from [`@celljs/http`](https://github.com/cellbang/cell/tree/main/packages/http).

```tsx
function Greeting() {
    const greetingServer = useRpc<GreetingServer>(GreetingServer);
    const [text, setText] = React.useState('');
    React.useEffect(() => { greetingServer.greet('web').then(setText); }, [greetingServer]);
    return <p>{text}</p>;
}
```

## Translations with react-intl

react-intl is optional. To use it, install it and import `@celljs/react/lib/browser/intl` once in `src/browser/module.ts`: its `IntlContext` puts an `IntlProvider` with the messages of the selected locale around the application, so `useIntl()` and `<FormattedMessage>` work in every component.

<!-- https://cell.cellbang.com/packages/tui (ui-packages/tui/README.en.md) -->

# Cell - TUI Component

Use [pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui) to provide a terminal interface for Cell CLI applications: differential rendering without flicker, built-in editor, Markdown, list, loading animation and other components.

- `TuiFactory`: creates a main screen (preserves scroll history) or fullscreen `TUI`; stops all TUIs and restores the terminal when the application stops.
- `AgentChat`: agent conversation in the terminal. The target can be an `Agent` from [@celljs/ai-agent](https://github.com/cellbang/cell/tree/main/ai-packages/ai-agent), or a session from [@celljs/ai-coding-agent](https://github.com/cellbang/cell/tree/main/ai-packages/ai-coding-agent): answers are displayed as Markdown streams, tool calls and errors appear on separate lines. Send with Enter, cancel the current run with Escape, and exit with Ctrl+C.

pi-tui uses dynamic `import()`, which requires Node.js >= 22.19 or Bun.

## Usage

```typescript
import { AgentFactory } from '@celljs/ai-agent';
import { Autowired, Component } from '@celljs/core';
import { AgentChat } from '@celljs/tui';

@Component()
export class ChatCommand {
    @Autowired(AgentFactory)
    protected readonly agentFactory: AgentFactory;

    @Autowired(AgentChat)
    protected readonly agentChat: AgentChat;

    async run(): Promise<void> {
        const agent = await this.agentFactory.create();
        await this.agentChat.run(agent, { title: 'ACME assistant' });
    }
}
```

To customize the interface, use `TuiFactory.create({ screen: 'alt' })` to get `TUI`, then use pi-tui components (`PiTuiUtil.load()` returns the pi-tui module). `TuiThemeUtil` provides a default theme that follows terminal colors.

A complete CLI application (`cli` preset, enters conversation after startup, exits on Ctrl+C) is in [examples/tui-app](https://github.com/cellbang/cell/tree/main/examples/tui-app).

## Testing

`FakeTerminal` in `@celljs/tui/lib/node/test` records output (`text` removes escape sequences), `type()` simulates key-by-key input, passed to `create({ terminal })` or `run(target, { terminal })`.

<!-- https://cell.cellbang.com/packages/widget (ui-packages/widget/README.md) -->

# Cell - Widget Component

Frontend infrastructure that [`@celljs/react`](https://github.com/cellbang/cell/tree/main/ui-packages/react) builds on. Applications rarely depend on it directly; installing `@celljs/react` brings it in.

- **Frontend target.** Its `package.json` declares `cell.targets: ["frontend"]`, which is what makes the toolchain build a frontend when a UI package is installed.
- **Widgets.** `@Widget(area)` or `@Widget({ area, priority, component, id, rebind })` registers a component for a named area; `WidgetManager.get(area)` / `render(area)` return them ordered by priority (`<Slot area>` of `@celljs/react` renders them). Widgets can also be declared in configuration under `widget.widgets`, keyed by widget id (`area`, `priority`, `visible`, `props`; `${...}` in `props` is evaluated at each render). The id defaults to the name of the decorated class (`LogoWidget` below). A `WidgetFactory` renders the models whose `type` equals its own `type`.
- **Themes.** `Theme` components and the `ThemeManager`, configured by `widget.themes`. The id of the current theme is kept in `localStorage`; on load it selects that theme, else `default`, else the first one.
- **Locales.** `Locale` components and the `LocaleManager`, configured by `widget.locales`. The language of the current locale is kept in `localStorage`; on load it selects that one, else the browser's, else the first one.

Both managers have `current`, `setCurrent(value)` (which also saves it) and `onCurrentChanged(listener)`, an `Event` of `@celljs/core` that returns a `Disposable`. `useLocale()` of `@celljs/react` reads and changes the locale in a component.

```ts
import { Widget } from '@celljs/widget';

@Widget({ area: 'header', priority: 100, component: Logo })
export class LogoWidget {}
```

All exports are frontend-only (`@celljs/widget` resolves to `lib/browser`).

<!-- https://cell.cellbang.com/ta (apps/ta/README.en.md) -->

# Ta

A coding agent based on Cell and [pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). `ta` is pi renamed to Ta: the interactive interface, `-p`, `--mode json|rpc`, slash commands, the session tree, extensions, skills and pi packages all work as in pi. On top of that:

- **Codemode by default**: the model writes JavaScript scripts that call all tools through `codemode`, which can call them in parallel and filter large output within the script; only the script's output enters the context (see "pi Patches" below).
- **Session lock**: only one Ta process can write to a single session file at any time; pi has no lock, so two processes would interleave writes.
- **Ta's appearance and identity**: the terminal startup displays Cell's pixel dinosaur, version, and common keys (press the expand key to see all keys; set `quietStartup: true` to hide them); the system prompt, hint text, and MCP client name all refer to Ta. The `/bug` command opens Ta's GitHub issue page in the browser, including version, model, and platform information. The `/share` command, which depends on pi's official service (Radius), has been removed; `/changelog` displays Ta's release notes instead. Pi's version check and installation statistics for pi.dev are disabled by default (`TA_SKIP_VERSION_CHECK=0` or `TA_TELEMETRY=1` to enable). Pi's environment variables in Ta are named `TA_OFFLINE`, `TA_SELF_UPDATE_COMMAND`, and `TA_TELEMETRY`, though the original `PI_*` names still work.
- **`ta serve`**: provides pi agent sessions over WebSocket to any number of clients (Web, desktop, mobile) and includes a built-in Web client; see [@celljs/ta-host](https://cell.cellbang.com/ta/ta-host) and [@celljs/ta-web](https://cell.cellbang.com/ta/ta-web) for details.

## Install

```bash
npm i -g @celljs/ta     # Node.js >= 22.19
ta                      # Interactive mode
ta -p "Summarize this repository"     # One-off run
```

## Correspondence with pi

| | pi | Ta |
| --- | --- | --- |
| Global directory | `~/.pi/agent/` | `~/.ta/agent/` (auth.json, models.json, settings.json, sessions/, extensions/ …, content format same) |
| Project directory | `.pi/` | `.ta/`; project description is still `AGENTS.md` |
| Environment variable | `PI_CODING_AGENT_DIR` | `TA_CODING_AGENT_DIR`, `TA_CODING_AGENT_SESSION_DIR` |
| Subcommand | `install` `remove` `update` `list` `mcp` | Same, plus `serve`, `exec-server`, `pair`, `relay` |

Pi's extensions and pi packages work directly in Ta. Install them with `ta install npm:<package-name>`. To reuse existing `.pi/skills` from your project, add `"skills": ["../.pi/skills"]` to `.ta/settings.json`.

When [Cua Driver](https://cua.ai/cua-driver) is installed, Ta can use desktop applications on this machine in the background; see the built-in extension [@celljs/ta-computer-use](https://cell.cellbang.com/ta/ta-computer-use) for details.

When a reply changes files, the web client shows them above the message box with the lines added and removed; a click on a file shows its diff in the workbench, and one button takes the changes of that reply back. See the built-in extension [@celljs/ta-changes](https://cell.cellbang.com/ta/ta-changes).

Ta works on a schedule too: `/loop 30m <prompt>`, `/remind in 45m <prompt>`, or just say "sum up yesterday's commits every day at 9". The Ta service runs each one in a new conversation at its time, and the Scheduled page of the web client lists the tasks and the summary of each run. See the built-in extension [@celljs/ta-cron](https://cell.cellbang.com/ta/ta-cron).

Like pi, Ta does not request approval before tool calls by default; to enable approval requests, install the optional package [@celljs/ta-permission-gate](https://cell.cellbang.com/ta/ta-permission-gate).

## ta serve

```bash
ta serve                      # 127.0.0.1, last port (switches to free port if occupied)
ta serve --host 0.0.0.0 --port 4100
ta serve --web                # Start and open Web client in browser (token already included)
ta serve --exec ws://box:4200/exec   # Tools execute on ta exec-server on another machine (TA_EXEC_TOKEN)
ta exec-server --host 0.0.0.0 --port 4200 --cwd /workspace
ta pair                       # Pair phone or other device, connect back via Relay (default https://relay.cellbang.com)
ta relay --port 8080          # Run your own Relay
```

After startup, Ta writes the address and access token to `~/.ta/agent/serve.json` (mode 0600). The Web client is available at the same address at `/`: the page file contains no data and requires no token; all API calls under `/api` require the token. The `--web` flag places the token in the URL's `#` fragment (not sent to the server or included in the Referer header); the page reads it and stores it in localStorage, then removes it from the address bar. The port and token persist across restarts (stored in `serve-state.json` in the same directory, mode 0600; delete it to get a new token and port), allowing a Web client installed as a PWA to reconnect to ta serve and auto-login on the next visit. When `--port` is specified, that port is used instead. The `TA_SERVE_TOKEN` environment variable can set the token (for example, generated by a desktop shell), in which case it is not recorded. Clients connect using [@celljs/ta-client](https://cell.cellbang.com/ta/ta-client).

When the client does not specify a directory, conversations open in ta serve's working directory. The default is the directory where ta serve started; the Web client and desktop app can change it using "Open working directory…", and the selection is stored in `ta.json` in the agent directory. Model services can be signed in through the Web client (gear menu → "Model accounts…"), which writes credentials to the same `auth.json` file as the terminal's `/login` command. Conversations can also run on another machine, like VS Code's Remote SSH: in the directory picker, select a host (a Host from `~/.ssh/config` or `user@host`), and the directory becomes `ssh://<host>/<path>`. The agent and model credentials stay on the ta serve machine; commands, files, terminals, and git run on that remote host. Ta serve uses the system `ssh` to connect (keys, ssh-agent, ProxyJump all work as usual, and the page prompts for passwords or host confirmation when needed). On the first connection, it places a small server (and Node.js 22 if missing) in `~/.ta/server` on that host. Dev servers on that remote host open `localhost` addresses in the built-in browser, and ports are automatically forwarded. See [ta-remote-ssh.md](https://github.com/cellbang/cell/blob/main/docs/design/ta-remote-ssh.md).

Devices paired with `ta pair` connect to ta serve through [Relay](https://cell.cellbang.com/ta/ta-relay) with end-to-end encryption; the Web client's "Use on your phone…" feature does the same and displays a QR code for scanning.

## Build

`bun run build` first builds ta serve's server using `cell build --root serve`, outputting to `dist/serve/index.mjs`, and builds the Web client to `dist/public/` (the serve application loads `@celljs/ta-web` to build the frontend, and `@celljs/serve-static` hosts it). Then `scripts/assemble.ts` builds the `ta` command (from ta-harness's `TaCli`) to `dist/cli.mjs` and generates `dist/pi/`, which contains a `package.json` that renames pi to Ta (`piConfig`), along with pi's themes, HTML export template, documentation, and examples. When `ta` starts, it lets pi read branding information from this directory (`PI_PACKAGE_DIR`), using the same directory layout as pi's official binary. Built-in pi packages (defined in Ta's `TaPackages.BUILTIN`) are copied to `dist/pi/packages/<name>` after the build without source code or tests; they can be disabled in the Web client's Settings → Packages.

Everything `ta` needs at runtime is in `dist/`, so the published package has no `dependencies`, and installing `ta` does not install Cell or pi; the build places all dependencies in `devDependencies`. Ta serve's server is a separate Cell application under `serve/` (private, not included in workspaces). Cell collects components only from `dependencies`; its `serve/package.json` lists which components to include. The `@celljs/ta` package itself does not need `dependencies`. When adding a component to ta serve, add it to both files: components in `serve/package.json`'s `dependencies` determine the output content, and entries in `package.json`'s `devDependencies` determine the turbo build order.

The `ta` command itself does not load Cell; its startup time and memory usage match `pi`. Only `ta serve` loads Cell.

## pi Patches

The following hardcoded brand text in pi, the `/bug` and `/share` built-in commands, and the codemode default are patched:

- Patches are stored as `patches/@earendil-works%2Fpi-coding-agent@<version>.patch` in the repo root. They are generated by `bun run pi-patch` (see `scripts/pi-patch.ts` below), registered in the root `package.json`'s `patchedDependencies`, and automatically applied by `bun install`. Patches only modify pi's bundled output `dist/bundle` (what Ta runs).
- Package manager patches only work in this repository. During the build, `scripts/assemble.ts` copies the patched `dist/bundle` to `dist/pi/dist/bundle` for release (~9 MB). The `ta` command sets `PI_PACKAGE_DIR` to `dist/pi`, and `PiBundleUtil` loads that copy. There is only one pi instance per process; extensions access it through its built-in module table. The build fails directly if the patch is not applied.
- The bundle loads the following modules from node_modules at runtime: `jiti` (for loading extensions), `@silvia-odwyer/photon-node` (for image resizing), and `quickjs-wasi` (for codemode's WebAssembly). `scripts/assemble.ts` also copies these from pi's side to `dist/pi/node_modules`, using the same versions as pi. Extensions use `typebox` and pi's packages through the bundle's built-in module table. The build scans the bundle for packages loaded by name and fails if any are missing from the required or optional list. When upgrading pi, the script tells you which packages to add.

The following table shows what is changed, as defined by `scripts/pi-patch.ts`'s `REPLACEMENTS` (original and replacement per group):

| Group | Change |
| --- | --- |
| codemode by default | The default tools include `codemode` with `codemode.mode` set to `only`, so the model sees only the `codemode` tool. The tools read, bash, edit, write, extension tools, and MCP tools are called in the script using `tools.<name>()`. Pi has no host default setting layer; this change is only applied here. To revert to pi's behavior, write `"codemode": { "mode": "on" }` in `settings.json` (to provide other tools directly) or `"defaultTools": ["-codemode"]` (to disable codemode), or use `--tools -codemode` for a single run. |
| built-in commands | The `/share` command (which uploads to Radius) and pi's `/bug` command (for pi developers) are removed. The `/bug` command is provided by Ta's extension instead, and the crash-after `/bug` hint is rewritten. |
| system prompt | The opening is changed to Ta, and the pi docs section explains how pi's `~/.pi/agent`, `.pi/`, and `pi` command correspond to Ta. |
| help of ta | In `ta -h`, `ta update -h`, and `ta auth -h`, "pi" is changed to "Ta". Environment variables are listed as `TA_*` (converted to pi's `PI_*` by `TaBrand.activate`). The `PI_PACKAGE_DIR` variable set by Ta and `PI_SHARE_VIEWER_URL` (removed with `/share`) are excluded. MCP service examples change from `radius` to `github`. The commands `ta update ta` and `ta update self` are now equivalent. |
| update of ta | `ta update` (for self and ta) queries npm for the latest `@celljs/ta`, not pi.dev (which would return the pi package name and replace Ta with pi). It does not prompt to run pi's install script because Ta is a single-file package with no fixed dependencies. |
| messages | In tmux setup hints, project trust hints, and ChatGPT login port occupied hints, "pi" is changed to "Ta". The MCP client name changes from `pi` to `ta`. |

Changes are only made where pi has no setting, parameter, or extension point. If a change can be made using `piConfig`, environment variables (`TaBrand.activate`), or a Ta extension, it is not done in the patch. Do not edit patches manually: pi's bundle is chunked by hash and compressed into long lines, so manual edits will fail after a pi upgrade.

To upgrade pi, first change the pi version in `ai-packages/ai-coding-agent` and other places, then run `bun install`. Next, run `bun run pi-patch` in `apps/ta`. The script takes the unpatched pi from the Bun cache and applies replacements line by line according to `REPLACEMENTS` (ignoring filenames; each original must appear the specified number of times in the entire `dist/bundle`). It then generates a new version patch with `bun patch --commit`, removes the `.bun-tag-*` chunk, and deletes the old patch. Finally, remove the old version line from the root `package.json`'s `patchedDependencies` and run `bun run test`. If the original text has changed in the new pi, the script lists the find count and stops; update that line's `from` value and run the script again. Use `bun run pi-patch --check` to verify without generating a patch. `test/pi-patch.spec.ts` also checks the currently installed pi.

The following are not changed: pi's documentation body (the system prompt already tells the model how to map it), the Radius login option description (which belongs to pi's official service and is accurate), the settings page's "Pi's drawn cursor" option, and one error message in the package manager (which is buried in a tens of KB long line, so the patch cost exceeds the benefit).

## Performance Benchmarks

```bash
bun run bench               # All except long scenarios, ~3 min, outputs Markdown table
bun run bench streaming     # Specify scenario; --help lists all scenarios
```

The benchmarks use the locally built product (run `bun run build` first). The model runs as a standalone process with a fake OpenAI-compatible service (`bench/fake-model.ts`): the `rate` scenario has a first token latency of 200 ms and generates 100 tokens/sec; the `burst` scenario outputs 5000 tokens quickly. The baseline is `pi --mode rpc`: pi serving multiple sessions requires one process per session. Memory and CPU are sampled outside the process using `ps` (on Linux, this reads `/proc`), which does not interfere with the measured process.

Reference results from an Apple M4 Pro with Node.js 24:

| Scenario | pi | Ta |
| --- | --- | --- |
| `--version` / `-p` | 0.12 s 112 MB / 0.18 s 127 MB | 0.12 s 114 MB / 0.19 s 128 MB |
| ta serve idle | — | 66 MB, idle CPU 0 |
| 32 sessions | One process per session, ~127 MB × 32 | 181 MB (per session ~1.6 MB) |
| Single session stream (rate) first token / CPU | 209 ms / 5% | 209 ms / 5–6% |
| 10 sessions concurrent stream | 1693 MB, 4.57 s CPU | 191 MB, 1.92 s CPU |
| 50 clients viewing same session | — | Per client ~35 µs per delta |

The `endurance` scenario (a long scenario that must be specified explicitly) runs 60 bursts on a 64 MB heap limit and checks that memory converges.

## Tests

`bun run test` is an integration test that uses the real built product and a local fake OpenAI-compatible model service. It covers print and JSON modes, session locking, installation of pi packages and the permission gate, ta serve's multi-client broadcast, reconnect with resend, approval with first-come-first-served semantics, idempotent acknowledgments, session locking, idle session reclamation, and rate limiting.

<!-- https://cell.cellbang.com/ta/desktop (apps/ta-desktop/README.en.md) -->

# Ta Desktop

Ta's desktop application: one window displaying the Web client bundled with [ta serve](https://cell.cellbang.com/ta). The shell does only what a browser window cannot; everything else is in the Web client.

```text
Electron main process
 ├─ Single instance, menu, external links and permission guards, tray, task completion notifications
 ├─ If ta serve in serve.json is still responding → use it (e.g., started in terminal)
 ├─ Otherwise start the built-in ta serve in Node mode (ELECTRON_RUN_AS_NODE): on macOS use the app's Helper (not in dock), on other platforms use the app itself
 └─ Check every 5 seconds; 3 consecutive timeouts or process exit triggers a restart
              ↓
ta serve (listens only on 127.0.0.1, port and token persist across restarts)
```

- `ta serve` started by the app exits when the app quits; if tasks are running, it prompts first. `ta serve` started in the terminal is unaffected.
- When opened from Finder or Dock, PATH is short, so the app takes the login shell's PATH and passes it to `ta serve` so the agent can find commands like git and node.
- When closing the window, macOS and Windows continue running in the background (use Dock or tray to bring back), Linux exits (many desktop environments don't show a tray).
- The browser of the workbench shows sites in a `<webview>` (`src/embedded-browser.ts`; the preload tells the web client it can): sites that refuse frames open, signing in works and stays in a partition of its own (`persist:ta-browser`), apart from the web client. Only the page of `ta serve` may add one, with Node, preload and other webviews off; its pages go only to http(s), get no permission but full screen and writing the clipboard, and introduce themselves as Chrome. A popup with window features (a sign-in that needs `window.opener`) opens as a window in the same partition, a new tab in the same view, mail in the mail app. The context menu (links, images, editing, back and forward, Inspect) and the shortcuts Cmd/Ctrl+R, F5, Cmd+[ / ], Alt+← / →, F12 act on the page, not on Ta.
- The agent works that page with the DevTools protocol through the preload's `debugWebview` (`EmbeddedBrowser.debug`): only from the main frame of the page of `ta serve`, only to a webview of that page, only the domains that act on the page itself (Accessibility, CSS, DOM, DOMSnapshot, Emulation, Input, Log, Overlay, Page, Runtime), never Network, Storage, Target, Browser, nor the commands that read files, download or navigate around the guard; focus is emulated once the debugger attaches, and a command takes at most 30 s. While the agent works, and 10 s after, the window and the page are not throttled in the background, where every wait would otherwise take a second or more.
- Importing sign-ins (`src/browser-import.ts`, macOS and Windows): the profiles with cookies of Chrome, Edge, Brave, Arc, Vivaldi and Chromium come from their `Local State` (the page gets names and ids, never paths); once the user picks one, the app asks in a native dialog, which a page cannot draw. Only then is the key read: on macOS `security` reads the "… Safe Storage" item of the Keychain, and the system asks once more whether Ta may; on Windows PowerShell's DPAPI unwraps the key of `Local State`. A copy of the Cookies database is opened read-only with Node's `node:sqlite`, the 20,000 most recently used cookies are decrypted and set in `persist:ta-browser`; cookies of a session get 7 days so that they outlive a restart. Passwords and history are not read, and values never leave the main process. Chrome's app-bound encryption on Windows (`v20`, from Chrome 127) only Chrome can undo: those are counted and skipped, and need a sign-in on the site.
- Logs are in the system app log directory under `serve.log`; open it from the Help menu.
- Comes with [Cua Driver](https://cua.ai/cua-driver) (MIT, fixed version and SHA-256 in `scripts/cua-driver.ts`). When starting `ta serve`, point `TA_CUA_DRIVER` to it so the built-in extension [ta-computer-use](https://cell.cellbang.com/ta/ta-computer-use) can use desktop applications in the background without separate installation. On macOS, Cua's signature and notarization are preserved (`signIgnore`), so authorization belongs to CuaDriver.app; Ta updates do not require re-authorization. macOS uses a universal binary CuaDriver.app (~88 MB), Windows includes `cua-driver.exe` and cursor theme apps (~42 MB), and Linux includes `cua-driver`, cursor theme apps, and Wayland accessibility extension (~63 MB). When reusing a `ta serve` started in the terminal, it doesn't know about this copy and uses your own installation.

## Development

```bash
bun run build --filter=@celljs/ta   # first build apps/ta (from repo root)
cd apps/ta-desktop
bun run setup                       # download Electron (bun install doesn't run its install script) and Cua Driver (to vendor/)
bun run start
bun run test
bun run package                     # pack to release/, no installer
bun run package:mac                 # dmg and zip; ad hoc signing if no CSC_LINK
```

## Performance

```bash
bun run package
DIR=$(mktemp -d); bun bench/fake-model.ts $DIR & 
bun bench/measure.ts $DIR release/mac-arm64/Ta.app/Contents/MacOS/Ta   # outputs JSON
```

Uses an isolated agent directory and fake model to measure cold startup (ta serve ready, UI input available), RSS and macOS physical memory (footprint) for each process after 15 seconds idle, CPU after 30 seconds idle, and CPU and memory peaks during one ~8-second streaming response (1500 increments). Three runs on M4 Pro on 2026-11-11:

| Metric | Result |
| --- | --- |
| Cold startup | ta serve ready 0.86–0.96 s, UI input available 1.14–1.40 s |
| Idle memory (RSS total) | 590–660 MB: main process ~172, renderer ~162, ta serve 124–142, GPU ~90, network ~43 |
| Idle memory (footprint total) | 360–635 MB, variation mainly in GPU process graphics memory |
| Idle CPU | ~0.6–0.8% total (main process health check and task polling vs ta serve, split roughly equally) |
| Streaming response CPU | ~11–12% total single-core: ta serve 7%, renderer 2.3%, GPU and main ~1% each |

## Known Limitations

- No automatic updates yet: requires release channels and code signing certificates.
- The bundled Cua Driver doesn't include `cua-driver-uia.exe`: its uiAccess (for windows running as administrator) requires installation in Program Files, but the installer is per-user. Windows and Linux installer packages have not been verified on real machines.
- Electron lacks browser's speech recognition service; voice input on the double is not available in the desktop app; speech synthesis works.

<!-- https://cell.cellbang.com/ta/mobile (apps/ta-mobile/README.en.md) -->

# Ta Mobile

Ta's mobile application: uses [Capacitor](https://capacitorjs.com) to package Ta's Web client ([@celljs/ta-web](https://cell.cellbang.com/ta/ta-web)) into iOS and Android apps. The phone doesn't run an agent or execute tools; instead, it connects through [Relay](https://cell.cellbang.com/ta/ta-relay) to `ta serve` on your computer to watch progress, answer confirmations, and give additional instructions.

On first launch, run `ta pair <Relay address>` on your computer, then paste the printed link into the app. The key in the link exists only on the phone and computer; Relay cannot read the transmitted content.

## Development

```bash
bun run build --filter=@celljs/ta   # build the Web client in the repo root (apps/ta/dist/public)
cd apps/ta-mobile
bun run sync                        # copy the Web client into ios/ and android/
bun run open:ios                    # open with Xcode, requires installing the iOS platform
bun run open:android                # open with Android Studio
```

`ios/` and `android/` are native projects generated by Capacitor, committed to the repo; the Web client copied into them is not committed.

## Known limitations

- The device key is stored in the WebView's localStorage, not yet in Keychain / Keystore.
- When going through Relay, local file previews (images, videos, etc.) are not available.
- Push notifications are not yet available: the phone cannot receive confirmation requests when not in the foreground.

<!-- https://cell.cellbang.com/ta/relay (apps/ta-relay/README.en.md) -->

# Ta Relay on Cloudflare Workers

The relay of [@celljs/ta-relay](https://cell.cellbang.com/ta/ta-relay) on Cloudflare Workers: one Durable Object per host, which its devices connect to as well. It uses WebSocket hibernation, so the object does not stay in memory while no messages flow.

```bash
bun run dev       # run locally (wrangler dev), at http://127.0.0.1:8787
bun run deploy    # deploy to the current Cloudflare account (CLOUDFLARE_API_TOKEN), domain from routes in wrangler.jsonc
ta pair https://relay.cellbang.com
```

Relay only stores the hash of each host's key to prevent other hosts from claiming the same id. Forwarded content is encrypted. A single WebSocket message is constrained by the Workers' size limit.

<!-- https://cell.cellbang.com/ta/ta-agents (ta-packages/ta-agents/README.en.md) -->

# Cell - Ta Agents

A pi package that comes with Ta (on by default; turn it off in Settings → Extensions of the web client): other coding agents as models to pick. A conversation on CodeBuddy Code, Claude Code or Codex runs every turn on that agent's own harness: its system prompt, tools, context management, subagents and login, so you get the agent as it works with its own models. It is one pi extension (`src/extension.ts` → `extension/index.mjs`), with no change to Ta's core; pi can install it too:

```bash
pi install npm:@celljs/ta-agents
```

The agents are reached over the [Agent Client Protocol](https://agentclientprotocol.com) (ACP, stdio):

| Agent | Offered when | Started as |
| --- | --- | --- |
| CodeBuddy Code | `cbc` or `codebuddy` is installed | `cbc --acp` |
| Claude Code | `claude` is installed | `npx -y @agentclientprotocol/claude-agent-acp` (the ACP project's adapter, with Claude Code's own login) |
| Codex | `codex` is installed | `npx -y @agentclientprotocol/codex-acp` (likewise, with Codex's own login) |

CodeBuddy Code works as in its own terminal: in PTC (code mode, its tools called through REPL; it declares `mainAgentSupport` / `toolModeSupport` and sets `CODEBUDDY_CODE_MODE_ENABLED=1`, without which ACP clients get the standard mode only), and a new session has full access (`options.mode`, which the settings change). npx fetches an adapter the first time it is used; the versions are pinned in the package. Each agent keeps its own login: when it is not signed in, the conversation says which command to run in a terminal (`cbc`, `claude`, `codex login`).

## Use

Pick one in the model list of the + on the left of the input box, an agent's models are listed by their names, with the agent beside them (`Claude-Opus-5.5  codebuddy-code`, for example). Each agent is a provider (`codebuddy-code`, `claude-code`, `codex`) whose models are the ones the agent lists; `default` (the entry named only after the agent) uses the default model set up in the agent. The models are known once the agent ran, and kept in `~/.cache/ta-agents/models.json`. The thinking level becomes the agent's own (xhigh is CodeBuddy Code's `xhigh` or `max`, for example).

`agents` in pi's `settings.json` changes the built-in agents or adds other ACP agents:

```json
{
  "agents": {
    "codex": false,
    "claude-code": { "permissions": "ask" },
    "gemini": { "name": "Gemini", "command": "gemini", "args": ["--experimental-acp"] }
  }
}
```

Fields: `name`, `command`, `args`, `env`, `login` (the sign-in command to tell the user), `permissions`, `options` (the agent's settings of a new session, by the id or category of the option, such as `{ "mode": "default" }`), `clientMeta` (`_meta` of the client's capabilities in `initialize`). `env` and `options` of a built-in agent merge with those of the settings. `false` turns a built-in agent off. A built-in agent named in the settings is offered even when its program is not found, so it can run another one: the adapters read `CLAUDE_CODE_EXECUTABLE` (Claude Code's executable) and `CODEX_PATH` (the `codex` command), for example for wrappers built on the same code:

```json
{
  "agents": {
    "claude-code": { "env": { "CLAUDE_CODE_EXECUTABLE": "/usr/local/bin/tclaude" }, "login": "tclaude login" },
    "codex": { "env": { "CODEX_PATH": "tcodex" }, "login": "tcodex login" }
  }
}
```

## How it works

- **A turn**: each time pi asks the model, only what the user said since the agent last answered goes to the agent (`session/prompt`), since the agent keeps its own history. The agent's text and thinking stream as pi's message.
- **Tool calls**: the agent uses its own tools; each call is recorded in pi as a call of `agent_tool` (its arguments are a title, a kind and a target, such as `{ kind: "execute", target: "npm test" }`), so Ta shows it as a line like its own tools, with the agent's output as the result. As soon as a call of kind edit, delete or move names the file it changes (`locations`, or `file_path` and the like in its arguments), or brings an ACP diff, the extension emits `ta:file-write` on `pi.events` (`{ path, before? }`, `TA_FILE_WRITE_EVENT` of ta-protocol), so that ta-changes keeps the file as it was before the agent writes it. When the agent starts a call, the assistant message ends (`toolUse`); pi "running" `agent_tool` only waits for the agent to finish the call, and pi's next request goes on with the same turn. some agents (CodeBuddy Code) stream the arguments first, so a call shows once the agent says they are complete (`toolArgumentsComplete` in `_meta`, or announcing the call again as `pending` with them); without such a sign, 1.5 seconds without news of the call, or the agent saying something else, will do; calls started together go in one message and show in parallel. `agent_tool` is active only while the model is an agent.
- **Sessions**: a pi session uses one session of each agent; its id is kept in the pi session (the custom entry `ta-agents.session`), and reopening the conversation loads it again (`session/load`). A fork, or going back to an earlier message in pi (`/tree`), starts a new session of the agent on the next turn and hands it the conversation so far as text; so does switching to an agent in the middle of a conversation (30,000 characters at most).
- **Processes**: the sessions of one agent in one directory share a process (one of CodeBuddy Code takes about 650 MB); by directory, because CodeBuddy Code runs commands where it was started rather than in the directory of the session. A process stops after 10 minutes without a turn, and starts again, loading its sessions, when it is needed. It keeps pi's process alive only while a request waits for its answer, so `pi -p` exits once it answered.
- **When the agent goes on by itself**: after a background task, an agent may start a turn on its own (CodeBuddy Code starts it with `unsolicitedTurn` in a `session_info_update` and ends it with `session_end`; other agents give no end, and the turn ends after 3 quiet seconds). The extension sends pi a message that is not shown, which starts a pi turn that shows it.
- **When the user talks while the agent works**: ACP has no way to steer a turn, so it is kept and sent as the next turn as soon as this one ends. Stopping sends `session/cancel`; the next turn waits for the agent to end the cancelled one (5 seconds at most).
- **Permissions**: as in pi, nothing is held back: a permission request of the agent is answered "allow once". With `permissions: "ask"` the user picks in the UI. The agent's own permission mode (CodeBuddy Code's settings, for example) still applies.
- **Compaction**: the agent manages its context. pi's automatic compaction is cancelled for conversations with an agent; compacting by hand (Compact in the + menu, or `/compact`) sends `/compact` to the agent, which compacts with its own command.
- **Title**: when the agent names its session (`session_info_update`) and the conversation has no name yet, it becomes the conversation's name, also when the title comes late.
- **When a turn ends**: usually when the agent answers `session/prompt`. CodeBuddy Code answers only once it named the session (about 5 seconds later), so its turn ends when the phase it reports (`agentPhase` in `_meta`) goes from working back to `idle`, not counting phases of requests of earlier prompts (by `requestId` in `_meta`: the end of a `/compact`, for example); the next prompt waits for the answer to the one before (15 seconds at most).
- **Language of errors**: the language of Ta's pages (which they tell the Ta service with `TaSettingsServer.setLanguage`: `TA_LANGUAGE` of the process), else the computer's (`LC_ALL`, `LC_MESSAGES`, `LANG`, else Node's locale).
- **Slash commands**: `/command` goes to the agent as it is. Commands that only act in the agent's own interface (`/skills`, `/doctor`, `/clear` of CodeBuddy Code) return nothing over ACP; a line then says it ran with nothing back, so that it does not look ignored. After `/compact`, CodeBuddy Code returns nothing for its local commands (`/cost`, `/todos`) either: that is on its side.
- **Usage**: the tokens the agent reports (`usage_update`) are put on the last message of each turn. The adapters of Claude Code and Codex report the context only, no output tokens, so the output shows 0.
- **Several sessions**: the sessions of a process share one model runtime, where the provider registered last replaces the others; its `streamSimple` finds the extension of the session that asks by the `sessionId` pi passes. `agents` of `settings.json` is read when the extension loads, so that a session resumed on an agent's model finds it.
- **ACP dialects**: CodeBuddy Code streams the arguments first (`_meta.toolArgumentsComplete` says they are complete); Codex puts the output of commands in `_meta.terminal_output_delta`, its result being only the exit code; Claude Code's result is in the `content` of its last update.

## Not yet

- Conversations in `ssh://` directories (the agent runs on this computer and cannot see remote files).
- The agent's own slash commands (`available_commands_update`) are not in the + menu yet; typing `/command` in the box sends it to the agent as it is.
- The client file system and terminal of ACP are not offered: the agent reads and writes files and runs commands with its own tools.

<!-- https://cell.cellbang.com/ta/ta-changes (ta-packages/ta-changes/README.en.md) -->

# Cell - Ta Changes

A pi package that comes with Ta (on by default; turn it off in Settings → Extensions of the web client): which files each reply changed. When a reply ends, a pill stays above the message box, "N files changed +added −removed" (for the last reply of the conversation that changed files; it goes once they are taken back). It opens to a list above it of the files (name, directory, lines added and removed; files Ta created are marked "new"); a click on a file opens its diff in the workbench on the right (before and after, read-only). "Undo the changes of this reply" at the bottom of the list puts the files back as they were before the reply, and removes those Ta created.

It has three parts, none of which changes the core of Ta:

- **pi extension** (`pi.extensions`, `web-src/extension.ts` → `extension/index.mjs`): before the `edit` or `write` tool (also a nested call in a codemode script) writes a file the first time in a reply, it reads what the file holds. When the reply ends (`agent_settled`, also when it is stopped), it compares each file before and after and sends a `ta-changes` custom message that the conversation does not show (`display: false`), whose `details` hold the files, their lines added and removed, and the hashes of their contents before and after. The message is for people: the extension leaves it out of what the model reads, in the `context` event. Files are read and written through `files` of the answer to `TA_HOST_EVENT` (the files of the session's execution environment), so `ssh://` directories work as well.
- **Host** (`pi.host`, `web-src/host.ts` → `host/index.mjs`): keeps the contents before and after by their hash (`<agentDir>/changes/<first two>/<hash>`; the same contents once; what was not used for 30 days is removed when ta serve starts), and serves the page: `latest` for the last change set on the branch of a conversation, `read` for contents, `revert` to undo. Undoing is done by the pi extension of the session; the change sets taken back are listed under the `reverted` key of the package's data, the same in every browser.
- **Web extension** (`pi.web`, `web-src/index.tsx` → `web/index.js`): puts the pill and the list above the message box with `ui.setWidget` (placement `aboveEditor`): it asks the host for the last change set when a conversation is shown, then follows `message_end` events; the note of an undo is one line of the conversation (`registerMessageRenderer`); the diff is `pi.ui.DiffEditor`.

## Undo

- Only while Ta is not working in the conversation, and the conversation is open in the Ta service (a conversation the page shows is).
- When a file changed again after the reply (by hand, by a later reply or by another program), it asks first; only then does it overwrite them, and the later changes are lost. Files already as they were before the reply are skipped.
- After undoing, a line "Took back the changes to N files" is added to the conversation. That message reaches the model: it tells Ta the files are back, and to read them again before changing them.

## Limits

- Files written by the `edit` and `write` tools, and, with another coding agent as the model (CodeBuddy Code, Claude Code, Codex; see ta-agents), those it writes with its own editing tools: ta-agents emits `TA_FILE_WRITE_EVENT` on `pi.events` as soon as it knows which file a call changes (mostly before it runs), with the text before when the agent sends it (an ACP diff), which then counts; otherwise the file is read then. Files changed by `bash` and other commands are not listed, and not taken back.
- Lines added and removed are counted as `git diff --stat` counts them. Binary files count no lines and show no diff, but can be taken back. Files larger than 4 MB are counted, but their contents are not kept: they cannot be taken back.
- Only in the Ta service (ta serve); `ta` alone (in a terminal) records nothing.

<!-- https://cell.cellbang.com/ta/ta-channels (ta-packages/ta-channels/README.en.md) -->

# Cell - Ta Channels

A built-in Ta package (enabled by default but can be toggled in the Web client's Settings → Packages): agents and channels. It is composed of three parts, none of which modify Ta's core:

- **Server side** (`pi.host`, `web-src/host.ts` → `host/index.mjs`): ta serve runs it once in the same process. Teams, messages, and queues of pending answers are all managed and processed by it; **forwarding happens on the server and continues even when the page is closed**.
- **pi extension** (`pi.extensions`, `web-src/extension.ts` → `extension/index.mjs`): adds team tools to Ta's sessions and obtains teams from the server via `pi.events`.
- **Web extension** (`pi.web`, `web-src/index.tsx` → `web/index.js`): responsible only for display and initiating changes.

## Concepts

- **Agent**: a normal Ta session plus a name and responsibility (as `appendSystemPrompt`); the session name is the agent's name, and the session belongs to the `@celljs/ta-channels` group (folded into one row in the conversation list). Each agent has its own cartoon avatar (`web-src/faces.tsx`, with 16 shapes and color schemes stored in `face`; on creation, it tries to avoid duplicates with existing avatars; old data without `face` is assigned by id), blinks, and looks left and right while answering; Ta itself remains the Cell logo. The session file is recorded when first opened and reopened from the file next time. A session with an agent has no team tools.
- **Channel**: members (agents, with the first being the lead) and messages. Messages are sent to members `@`-mentioned; agents' answers are posted back to the channel, and if they `@` someone in their answer, it is passed on to them. Each agent processes one message at a time. Users can mute members in a channel (`muted`): they do not answer anything in this channel, even if `@`-mentioned; when the lead is muted, messages with no one `@`-mentioned go to the next unmuted member.
- **Loop prevention** (`ChannelsUtil.limit`): relaying between agents is at most 3 hops; one message yields at most 8 answers, with at most 2 per agent. When cut off, after this round a light-colored note is appended to the channel ("reached relay limit, waiting for you to continue"), only once per round; the return from `post_to_channel` includes this note too.
- **Tools**: each session in Ta (web pages and other clients connected to ta serve) has `create_agent`, `create_channel`, `add_to_channel`, `post_to_channel`, and `list_channels`. When a user specifies a goal ("assemble a team to do the landing page"), Ta creates agents and channels, posts the goal, and waits for answers from each member before replying to the user. When a role is missing from a channel, Ta uses `add_to_channel` to add an existing agent (added after existing members; lead unchanged). The open page marks this channel with a green dot in the sidebar, which disappears when opened. Pausing Ta just stops waiting; agents continue to answer in the channel.
- **UI**: the "Agents" tab at the top of the sidebar (next to the "Conversations" tab) puts the double, channels, and agents together (the double is a built-in page from ta-web, and once enabled is listed at the top, no longer appears separately in the navigation bar); the search box and + are on the right of the tab. + → create agent opens a draft page in the main area: first assigns an unused name and avatar, clicking the name in the top bar can rename or pick from 16 avatars, the sidebar has one more line "not started"; the agent is truly created when the first message is sent from the input box (responsibility is generic, what to do is written in this message), then switches to its session and sends the message. + → create channel is a dialog: name, search and check agents (1–12, first checked is lead), create; channel row has lead first, next member in overlapping avatars, lead is labeled beside the name, second line is the most recent message or who's answering; agents are grouped by working directory, second line is "idle" or which channel they're answering in, right side is time of most recent message. Click agent to open its session (`openAgent` request, server opens or finds the session then `pi.switchSession` displays it as the current conversation). Hovering over agent row (long-press on touch) shows …, menu has: stop (abort its current answer), restart (open new session), rename, responsibility (edit the role in the system prompt, takes effect in next session), move to… (switch working directory, open new session in that directory), copy working directory, export conversation (Markdown, strip channel context blocks), add to channel, delete (leave all channels it's in, delete channels that only have it, keep the session file); when near the bottom the menu expands upward. Channel is a page in the main area (not in the right workbench), displayed as a group chat: others' messages on the left with avatar and name, user's on the right, consecutive messages are grouped, after a long pause insert a time line; top bar is channel name and member avatars, click avatar to open "Channel Members" (`members`, `location: 'panel'` view, follows the current channel) in the right workbench: lists members, lead has a marker, answering ones are marked green; each row opens that agent's session, hovering (long-press on touch) shows set as lead, mute, restart session (forget earlier conversation, open new session next time it answers, old session stays in conversation list), and remove from channel (at least one left); top has "Add Members" as a searchable agent list, check to add, bottom of list has "New Agent" to open the draft page for creating a new agent; bottom has delete channel (confirm once more, messages deleted too, ongoing answers no longer posted). Input box is the conversation input box (`pi.ui.Composer`), `@` lists members, + allows naming members or adding members (opens the member list for adding); messages use the conversation's Markdown rendering (`pi.ui.Markdown`), `@`-mentioned members are bold.

## Data and Forwarding

Data is stored on the server in `<agentDir>/extension-data/@celljs/ta-channels.json`; only the server writes to it. Each channel keeps the most recent 200 messages.

| Key | Content |
| --- | --- |
| `team` | agents and channels |
| `messages/<channel>` | messages in the channel |
| `queue` | pending answers (job: which agent answers which message, how many hops, which round) and counts per round |
| `working` | agents currently answering |
| `focus` | channels Ta has created tools for or posted messages to; pages use this to mark them in the sidebar |
| `requests/<id>` / `results/<id>` | requests initiated by the page (create agent, create channel, add channel member, set lead / mute / remove member, delete channel, restart agent session, modify or delete agent, post message as user, open agent session) and server's responses; pages only write `requests/*` |

The page learns of changes via `pi.storage.onChange` and rereads them. Each answer is first recorded as a job in `queue` and removed only after the answer is posted to the channel. After ta serve restarts, it continues processing remaining jobs: jobs that already have an answer (the channel has this agent's reply to that message) are not asked again, and messages already forwarded are not forwarded again, so processed messages do not duplicate. On restart, the one message that was being answered and not yet posted is asked again.

## Limitations

- Only ta serve has teams: when running plain `ta` (CLI, without ta serve), the team tools still exist but calling them returns "ta serve required" and does not create or forward anything. When the package's server side fails to start, the tool explains the failure and asks to check ta serve's logs.
- Messages with no `@` to anyone (user or Ta) go to the lead, the first unmuted member of the channel; when an agent's answer has no `@` to anyone, relay ends.
- Changes on the page wait for server processing; when ta serve is not running or the package is disabled, operations on the page report "Ta service not responding" after 30 seconds.

## Future

- A task board can be another package, based on the same agents and channels.

## Why Not in Core

pi's core only manages how one session runs; multi-session is provided by ta serve (`openSession` with `appendSystemPrompt` and `group`, `prompt`, `getState`, `getLastAssistantText`); the server part of the package runs on the host (`pi.host`). Agents and channels are just one product form of combining these concepts. Switching to another organization (task board, pipeline) makes another package, so it is an optional pi package like ones users build themselves. The core only provides host capabilities: loading and toggling built-in packages, the server part of packages, package server data and its change notifications.

## Development

Source is in `web-src/` with three entry points: `index.tsx` (page), `host.ts` (server), and `extension.ts` (pi extension); `team.ts` is the server-side team, `channels.ts` is what the page sees, and `channels-util.ts` is shared pure logic. `bun run build` first checks with tsc and outputs to `lib/` (tests run `lib/**/*.spec.js`); then uses `bun build` to bundle the three entry points into separate files with no imports. React comes from the page (`web-src/react.ts`'s `bind(pi.React)`), and icons use `pi.ui.icons`. End-to-end tests (faux models, real ta serve) are in `apps/ta/test/builtin-packages.spec.ts`.

<!-- https://cell.cellbang.com/ta/ta-client (ta-packages/ta-client/README.en.md) -->

# Cell - Ta Client

The client for `ta serve`: depends only on platform-native `WebSocket`, and works in browsers, Electron, mobile apps, and Node.js >= 22.4.

```ts
import { SessionStore, TaConnection } from '@celljs/ta-client';

const connection = new TaConnection({ url, token });   // from ~/.ta/agent/serve.json
await connection.connect();
const { sessionId } = await connection.server.openSession({ cwd: '/repo' });

const store = new SessionStore(connection, sessionId);
store.subscribe(state => render(state));   // notified once per batch of events
await store.attach();
await store.prompt('Fix the failing tests');
```

- `TaConnection`: auto-reconnects after disconnect using exponential backoff. `onReconnecting(delayMs, attempt)` notifies you before each wait, and `reconnect()` skips the wait and retries immediately. `connection.server` (sessions), `workspace`, `terminals`, `settings`, `packages`, `auth` (login to model services, subscribe to events with `onAuthEvent`), and `relay` (paired devices) are typed proxies for ta serve's services, all sharing one connection. The `createSocket` option lets you use a different transport, like `RelaySocket` through Relay ([@celljs/ta-relay](https://cell.cellbang.com/ta/ta-relay)). Calls during disconnection fail immediately (`TaRemoteError`, `code` is `CELL_TA_CONNECTION_LOST`) without queuing; whether to retry is up to the caller (reuse `clientMessageId` when retrying). Connections that drop re-establish themselves; operations from before the drop complete with the previous code if the server still has them.
- `SessionStore`: the client-side state for one session (messages, tool runs, pending dialogs, extension status bars). After reconnect, it resends missed events by `seq`. If it can't catch up (a `gap`), it auto-syncs with `getMessages`.
- Client tools: the model can call tools run by the client (e.g., read clipboard, let the user pick something in the UI). Declare them when opening a session; `SessionStore` runs them and returns the results:

```ts
const pickColor: ClientTool = {
    definition: { name: 'pick_color', description: 'Ask the user to pick a color', parameters: { type: 'object', properties: {} } },
    run: async () => await showColorPicker(),   // text returned to model; errors mean tool failure
};
const { sessionId } = await connection.server.openSession({ cwd, clientTools: [pickColor.definition] });
const store = new SessionStore(connection, sessionId, { clientTools: [pickColor] });
```

  Call requests broadcast to all connected clients; the first result wins (same as dialogs). Each call runs once per client, and after disconnect, resends the already-calculated result instead of running again. If `run` is aborted or the session closes, the call ends as failed. The same client tools work in codemode scripts using `tools.pick_color()`.
- `openSession`'s `appendSystemPrompt` appends a system prompt line to the session (like pi's `--append-system-prompt`), allowing clients to give the Agent a role.
- `SessionReducer`: a pure function `(state, event) => state`, never mutating old state, so UIs can compare by reference.

<!-- https://cell.cellbang.com/ta/ta-computer-use (ta-packages/ta-computer-use/README.en.md) -->

# Cell - Ta Computer Use

A built-in pi package for Ta (enabled by default, can be disabled in Web client Settings → Extensions): lets Ta use desktop applications on this machine via [Cua Driver](https://cua.ai/cua-driver) in the background. It lists apps and windows, reads window accessibility trees, performs clicks, types text, scrolls, and takes screenshots, without taking your mouse and keyboard. It's just one pi extension (`src/extension.ts` → `extension/index.mjs`), does not modify Ta's core, and pi can use it as well.

[Ta Desktop](https://cell.cellbang.com/ta/desktop) comes with Cua Driver (fixed version) and works out of the box. For the terminal Ta, use your own installation:

```bash
/bin/bash -c "$(curl -fsSL https://cua.ai/driver/install.sh)"   # macOS, Linux
irm https://cua.ai/driver/install.ps1 | iex                    # Windows (PowerShell)
```

The `/computer-use` page shows which program is in use and checks what your system still needs (guiding you through setup like the first time); if nothing is installed, it shows the installation command.

## How It Works

- **Finding the program**: first checks the environment variable `TA_CUA_DRIVER` (set by Ta Desktop when starting ta serve, pointing to its bundled copy), then checks `PATH`, `~/.local/bin` (the default install location), and on macOS `/Applications/CuaDriver.app` and `~/Applications/CuaDriver.app`, in order. It only calls `stat`, never runs anything. If not found, it checks again before each message, so installing mid-session doesn't need a restart.
- **Hint**: when found, adds a `<computer_use>` section to the system prompt: tool names are `tools.mcp__cua_driver__*`, suggests calling `describeNamespace("mcp__cua_driver")` first to see usage, plus platform limitations (macOS: don't prompt user again while waiting for permissions; Windows: can't operate windows running as administrator; Linux: needs desktop session and AT-SPI). Adds nothing if not found.
- **On-demand startup**: the MCP server `cua-driver` (exposed in codemode) is not registered at session start. The first time a codemode script mentions `mcp__cua_driver` (per pi's `reachesTools`; scripts using tools must write it out), it registers with `pi.registerMcpServer` and waits for tools to appear (up to 5 seconds). Pi connects all registered MCP servers at session start, creating a `cua-driver mcp` process per session (~10–24 MB); on-demand registration means sessions not using desktop apps have no extra process.
- **System requirements and permissions** (`src/cua-driver-access.ts`, checked once per process on first use, shared by concurrent calls):
  - **macOS**: Cua Driver needs Accessibility (read and operate apps) and Screen Recording (screenshots), authorized to CuaDriver.app (`com.trycua.driver`, Cua's developer signature), not Ta. Check with `cua-driver call check_permissions` (~20 ms). When permissions are missing, CuaDriver.app shows a two-step guide; Ta posts a notification explaining which two toggles to enable, then checks every second. Once enabled, the call continues without retry. If the guide is dismissed, Ta opens the system settings page. Waits up to 3 minutes; the user can press "Stop" to cancel immediately. Without Accessibility, the call fails, and the model is told to ask the user to enable it; `/computer-use` can guide them again. Without only Screen Recording, the call continues (reading and operating work), with a one-time notification. The daemon returns `permissions_pending` for a few hundred ms after startup, so Ta silently waits up to 3 seconds to avoid false alarms.
  - **Linux**: no permissions needed, but requires a graphical session (X11 or Wayland with XWayland), AT-SPI accessibility bus, and libX11 / libXi / libxkbcommon. Check with `cua-driver doctor --json` (~0.3 s). Without a graphical session (e.g., SSH) or missing libraries, the call fails and explains why plus install commands; AT-SPI warnings notify the user once and continue.
  - **Windows**: no permissions needed; use `doctor` to check for desktop session. Windows running as administrator requires Ta to also run as administrator (UIPI), noted in the hint.
  - When the system can't tell (your daemon hasn't started yet), the call is not blocked; it checks next time.
- **Bundled Cua Driver on macOS** (`src/cua-driver-daemon.ts`): the MCP process only forwards; the actual daemon must launch as CuaDriver.app via LaunchServices for authorization to belong to it. Ta starts a daemon on its own socket (`~/Library/Caches/ta/cua-driver.sock`), and the MCP server is `cua-driver mcp --embedded --socket <it>`. Here's how:
  - An app nested inside another app bundle is treated by macOS as part of the outer app (permissions attach to Ta and are lost on each build). So on first use, Ta clones it by version to `~/Library/Application Support/Ta/cua-driver/<version>/` (APFS clone, ~30 ms, no extra disk), launches from there, and deletes older version clones.
  - LaunchServices picks variants by bundle id and might pick CuaDriver.app from another app (different version, forwarding reports incompatibility). So before launch, Ta registers this copy with `lsregister -f`, then verifies the actual running program's path after launch. If it doesn't match, Ta stops it and suggests `cua-driver doctor --fix`. An existing daemon on the socket (from another Ta process or left over) is checked the same way.
  - The bundled copy disables Cua's product telemetry and update checks (`CUA_DRIVER_RS_TELEMETRY_ENABLED=0`, `CUA_DRIVER_RS_UPDATE_CHECK=0`); Ta's version updates handle upgrades. Your own installation keeps your settings.
  - Before each use, the daemon is confirmed alive (one socket connect); if it crashed, it restarts. After 10 minutes idle, it exits (~60 MB), and the forwarder exits too; pi auto-reconnects on the next call. When the process that started it exits, it stops the daemon too.

Measured (M4 Pro, fake model running `ta -p`, bundled Cua Driver 0.47.5, from Ta.app bundle): the first call is ~0.3 s slower (clone + daemon start). Each subsequent first call in a new process is within measurement error compared to not calling (~1.18 s vs ~1.20 s). Daemon startup ~150–250 ms, permission check ~20 ms, idle ~33–60 MB.

## Limitations

- If `mcp.json` already has a server named `cua-driver`, the file takes precedence. Cua Driver configured under another name (e.g., from `cua-driver connect` as `cua-computer-use`) won't be recognized, and tools appear twice (you can disable this extension).
- When remote execution (`ta serve --exec`) is used, the MCP server runs in the execution environment, but the program is found on the ta serve machine. When paths differ on each side, it won't connect.
- On macOS, if the user clicks "Quit and Reopen" in the permission guide (Screen Recording requirement), macOS restarts CuaDriver.app without Ta's arguments; Ta then restarts its daemon and stops the extra instance after permissions are granted.
- Windows and Linux installer packages have not been verified on real machines; Linux's `doctor` output has been tested in containers.

<!-- https://cell.cellbang.com/ta/ta-cron (ta-packages/ta-cron/README.en.md) -->

# Cell - Ta Cron

A pi package that comes with Ta (on by default; turn it off in Settings → Extensions of the web client): scheduled tasks. Give Ta a prompt and a time rule; at its time the Ta service runs it in a new conversation, and you get the summary when it ends. For checking CI now and then, summing up commits, writing a daily report, or a reminder at a time.

```text
/loop 30m check whether CI on main passes
/loop @daily sum up yesterday's commits
/loop "0 18 * * 1-5" write the daily report from today's commits --name report
/remind in 45m remind me to check the release
/remind at 15:30 look at the alerts of production
/schedule                       # list the tasks
/schedule show <task>           # a task and its last runs
/schedule run <task>            # run it now; its schedule stays
/schedule enable|disable <task>
/schedule set <task> --model openai/gpt-5 --notify always   # a value of - clears
/schedule remove <task>
/schedule clear                 # remove the tasks of this directory
/schedule help
```

Or just say "sum up yesterday's commits every day at 9": Ta makes the task with the tool `schedule_task`. The Scheduled page in the navigation of the web client lists every task with its rule, its next run and a switch; opened, its prompt and the summary of each run, and "Open conversation" goes to the conversation of that run. Tasks are made, edited, run and deleted there too; the dialog picks a task's model from a list with a search box (type part of its name, id or provider; arrows and Enter pick; the models with credentials in the settings of its directory, pi packages' such as other agents included) and its thinking level, or leaves the defaults of the settings.

## Time rules

- **Once**: `/remind in 45m`, `/remind at 15:30` (tomorrow when it has passed today), `/remind at 2026-12-01 08:15`.
- **Interval**: `30m`, `2h`, `1d`, `1h30m`; at least 1 minute.
- **cron**: five fields (minute hour day month weekday) with `*`, ranges, lists, steps and names such as `jan` and `mon`, and `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`; when both days are restricted, either one matches (as in cron). Quote an expression with spaces.

Times are local to the machine of the Ta service. A command may end with `--name`, `--notify always|error|never`, `--model <provider>/<model>`, `--thinking <level>` and `--cwd <directory>`.

## How it runs

- Three parts, none of which changes Ta's core:
  - **Server side** (`pi.host`, `web-src/host.ts`): the scheduler. It runs in the Ta service with one timer, asleep until the next task is due (it looks again within a minute at the latest, to follow a changed clock or a machine that slept). Tasks and runs are kept in the data of the package (`extension-data/@celljs/ta-cron.json` of the agent directory), the last 20 runs of each task.
  - **pi extension** (`pi.extensions`, `web-src/extension.ts`): `/loop`, `/remind`, `/schedule` and the tool `schedule_task`. A command answers with a card in the conversation, which the model does not read.
  - **Web extension** (`pi.web`, `web-src/index.tsx`): the Scheduled page, the cards of the commands, and a notice when a run ends.
- **One run, one conversation**: each run opens a new session (in the `ta-cron` group) in the task's directory (by default that of the conversation that made it; an `ssh://` directory works too), with the task's model and thinking level if it has them. The system prompt it adds tells Ta that nobody watches, not to ask anything, and to end with a summary; the last answer is the summary of the run. Once the run ends its session closes (after whoever is looking at it leaves), and its file stays.
- **No scheduling from a run**: a run has no `schedule_task` and the commands refuse, so tasks do not breed tasks.
- **No overlap**: a task whose last run has not ended when its time comes again lets that time go. At most 3 runs at once; the others wait.
- **Timeout**: a run that takes more than 30 minutes is stopped and fails.
- **While the Ta service is not running**: the missed times of a repeating task collapse into one run as soon as the service starts; a task that runs once and is more than 5 minutes late is missed and not run (run it by hand if it is still wanted); a run that was going when the service stopped fails on the next start.
- **Notices**: when a run ends, open web pages tell of it by the task's notify level (with a notice of the system when the page is in the background and the user allowed them). By default a task that runs once always tells, a repeating one only when it fails.

## Limits

- Tasks run only while the Ta service runs (`ta serve`; Ta Desktop starts it); in `ta` in a terminal the commands and the tool say they need it.
- A run's tools cannot be limited: it is a conversation like any other, with your settings and the project's extensions and skills.
- No outside channels such as email or webhooks, and no export or import.

<!-- https://cell.cellbang.com/ta/ta-exec (ta-packages/ta-exec/README.en.md) -->

# Cell - Ta Exec

Where the agent runs commands and reads/writes files—similar to Codex's exec-server: the agent loop stays in the host, and command and file operations go to the execution environment. Independent of pi.

```ts
interface ExecEnvironment {
    readonly cwd: string;     // path in the execution environment
    readonly local: boolean;  // whether it is this machine
    exec(command, options?): Promise<ExecResult>;       // one-off execution; streams output; kills the process group on timeout/abort
    spawn(command, args, options?): ExecProcess;        // long-lived process; stdio communication (MCP, LSP)
    readFile / writeFile / stat / readdir / mkdir / remove
    connect?(port, host?): Promise<ExecSocket>;         // TCP connection on the execution environment's machine (only for non-local environments); used for port forwarding
}
```

All paths are paths in the execution environment. Never pass them to `node:fs`, and give the model only these paths.

## Implementation

| | |
| --- | --- |
| `LocalExecEnvironment` | This machine |
| `RemoteExecEnvironment` + `ExecClient` | `ta exec-server` on another machine (container, sandbox) |
| `ExecServer` | `ta exec-server` itself: an HTTP service that doesn't load Cell (~60 MB when empty) |
| `ExecStdio` | The same server runs on stdin/stdout (one message per line), serving only one host. Ends when input closes or 60 seconds pass without messages (host pings every 15 seconds), terminating everything it started. |
| `SshHost` | Connects to another machine via system `ssh`: uses its own ControlMaster for one login, other commands share it. Ssh prompts for the user go through `SSH_ASKPASS` to `ask`. Detects the host; if it lacks Node.js 18+, downloads it locally (verified by SHASUMS256) and installs to `~/.ta/server/node` over ssh. Places `EXEC_REMOTE_SOURCE` (the `ExecStdio` bundled in `scripts/remote-server.ts`, ~7 KB, named by hash) in `~/.ta/server/<hash>/` and starts it in the user's login shell; `client` is its `ExecClient`. |
| `SshConfig` | Hosts in `~/.ssh/config` (including `Include`) that don't use wildcards. |

```bash
# execution machine (container)
TA_EXEC_TOKEN=... ta exec-server --host 0.0.0.0 --port 4200 --cwd /workspace
# host
TA_EXEC_TOKEN=... ta serve --exec ws://exec-host:4200/exec
```

Protocol (`ExecRpc`) mirrors Codex exec-server: JSON-RPC 2.0 over WebSocket (or stdin/stdout, one message per line). Methods include `process/exec`, `process/spawn`, `process/write`, `process/kill`, `fs/readFile`, `fs/writeFile`, `fs/stat`, `fs/readdir`, `fs/mkdir`, `fs/remove`, `net/connect`, `net/write`, `net/close`. Process output is pushed as `process/output`, `process/stderr`, `process/exit` notifications; connection data is pushed as `net/data`, `net/closed` notifications. Bytes are base64-encoded. `ExecClient` doesn't care about transport: `ExecClient.webSocket(url, token)` or an `SshHost` provides the connection.

- **Auth**: Token (via `Authorization: Bearer` or `?token=`). The security boundary is the execution machine itself (like pi: no approval before each tool call, just OS/container isolation).
- **Environment variables**: Only new or changed variables on top of the host's environment are sent (`RemoteExecEnvironment.delta`); host variables (API keys, etc.) never reach the execution machine.
- **Epoch isolation**: The host connects with an epoch (default: host startup time). If a larger epoch connects, the execution machine closes connections and kills processes from smaller epochs; their subsequent calls fail with `CELL_TA_EXEC_STALE_EPOCH`. After a session moves to a new host instance, the old one cannot run tools.
- **Process lifecycle**: Processes belong to their connection. Disconnecting ends processes started by that connection; `ExecClient` reconnects on the next call.

Host-side pi built-in tools (read, bash, edit, write, ls, find, and `!` commands) and stdio MCP servers all run through the execution environment (see `ExecExtension` and `ExecMcpTransport` in @celljs/ta-harness). The ripgrep version of grep works only locally—remote sessions drop it, and the model uses bash `rg` instead.

<!-- https://cell.cellbang.com/ta/ta-extensions (ta-packages/ta-extensions/README.en.md) -->

# Cell - Ta Extensions

A built-in pi package for Ta (enabled by default, can be disabled in Settings → Extensions): tells users they can create extensions in natural language, handles sharing them, and provides a marketplace. Does not modify Ta's core—three components:

- **Skills** (`pi.skills`, `skills/ta-package`): Ta creates and edits pi packages (pi extensions, web extensions, skills, prompt templates) based on user descriptions, and exports or imports extensions on request. The skills are also available in the terminal Ta; disabling this package removes them as well.
- **Web Extension** (`pi.web`, `web-src/index.tsx` → `web/index.js`): The "Extensions" page in the navigation bar with two tabs at the top: "Mine" and "Marketplace" (the page's top-right menu also opens the marketplace directly).
  - A header line explains that the effect takes place when the response ends. Below the input are example illustrations for four extension types: cards, pages, commands, and skills (`web-src/pictures.tsx`; uses page CSS variables and follows the theme). Click one to see an example; submitted requests open a new session (`openSession` + `switchSession`) and send "Create an extension: ..." to Ta.
  - "My Extensions": packages in the `extensions/` directory (created by Ta or imported from files), showing name, version, content tags, and description. The right side has a toggle (`setPackageEnabled`; disabled ones fade). Hover to reveal edit, export, and remove actions; editing asks how to change the package, then opens a new session for Ta.
  - "Installed Extensions": packages from the `packages` setting (npm or Git), with toggles. You can copy the source or remove them.
  - Import: use the button, the page's top-right menu, or drag files to the page. In the dialog, select a `.tgz` file or enter an `npm:…` / Git address to install (`installPackage`, equivalent to `ta install`). After import, install, or remove, call `reloadExtensions` so the current session and page get the updates immediately.
  - "Share with Others": export → send .tgz file → they import. A three-step diagram shows this flow, with a note explaining that npm, Git sources, or telling Ta directly also work.
  - "Marketplace" (`market-view.tsx`, `market-detail.tsx`): npm packages with the `pi-package` keyword—the ones listed in pi's official package directory.
    - Search box (searches 300 ms after input stops) and a few popular topics. Without keywords, lists by npm's combined ranking (download volume dominates); scrolling to the bottom auto-loads the next page.
    - Each card shows an avatar from the first letter of the name (same name, same color), name (scope faded), author, monthly downloads, description, category tags, and publish date, with an "Install" button on the right: one-click install as user-level `npm:<name>` (`installPackage`, unpinned version, updatable with `ta update`). A loading spinner appears during install; "Installed" shows when done; built-in extensions show "Built-in". Installation continues if you leave the page.
    - Click a card to see its detail page (`Esc` or "Back" returns to the list, scroll position preserved): avatar, name, description, author/version/downloads/license/date, install or remove, npm/source/homepage links, previews from `pi.video` / `pi.image`, and README.
- **Server** (`pi.host`, `web-src/host.ts` → `host/index.mjs`): the page calls it via `callHost` (`TaPackageServer.callPackageHost`).
  - `exportPackage(id)`: packs a package directory into a `.tgz` file (gzip tar, top level is the package, skips `node_modules`, `.git`, and symlinks), sends it to the page as base64 for download. The format is the same as `tar -czf <name>.tgz <name>`, so it can be unpacked with `tar` without Ta.
  - `searchMarket(query, from?)`, `marketPackage(name)` (`market.ts`): queries npm on the server (packages are installed there). Results are cached for 5 minutes; identical requests are deduplicated. Search uses `/-/v1/search?text=<term> keywords:pi-package`. Npm still ranks all `pi-package` packages below relevant results, so this filters to keep only packages with the term in their name, description, or keywords, stopping at the first irrelevant result. The detail doesn't fetch npm's entire package doc (frequently-updated packages can be tens of MB)—just the `/<name>/latest` manifest and last month's downloads. The README is first fetched from jsDelivr for the published version; if not found, fetches from GitHub. HTML images, links, and headings in READMEs are converted to Markdown (Ta's Markdown doesn't render HTML), badges removed, relative links point to the GitHub repo.
  - `importPackage(data, overwrite?)`: validates the file (single top-level directory, contains `package.json`, paths don't escape, at most 5000 files and 20 MB; skips symlinks and macOS tar's `._*` files), places it in `extensions/<package-name-without-scope>` in the agent directory, and pi loads it without configuration. Returns `exists` if a directory with the same name already exists; the page asks the user and retries with `overwrite`. Writes to a hidden temporary directory first, then swaps it in, so the session won't load a half-written file. Packages output by `npm pack` (with top-level `package/`) can also be imported.

## Limitations

- Export and import require `ta serve` (both page and server run inside `ta serve`). When running `ta` alone, follow the skill's instructions to have Ta use `tar` and `ta install`.
- Extensions imported from files are placed only in the user's `extensions/`. To use one in a project, place the directory in the project's `.ta/extensions/` and commit it.
- Extensions run code on this machine. Before importing extensions from others, the page warns to only import from trusted sources, and the skill asks Ta to review it first and explain what it does. Marketplace installs are one-click (no approval prompts, following pi's practice); you can view the intro and source code at the bottom of the list or in the detail page.
- The marketplace only recognizes the official npm registry (search, manifests, and download counts at registry.npmjs.org). READMEs depend on jsDelivr or GitHub. If either is unreachable, the page shows why and offers "Retry"; this doesn't affect already-installed extensions. Installation still uses pi's npm, respecting your npm config.
- Most npm data is in English; Chinese searches won't find everything. Topic buttons use English keywords.

<!-- https://cell.cellbang.com/ta/ta-harness (ta-packages/ta-harness/README.en.md) -->

# Cell - Ta Harness

Ta's runtime component on pi: the `ta` command and `ta serve` share this code. Code here doesn't depend on the Cell container, so `ta` doesn't load Cell.

| Export | Purpose |
| --- | --- |
| `TaCli.run(argv, options)` | The `ta` command: `serve` starts the server; other arguments are passed to pi's `main()` |
| `TaBrand` | Renames pi to Ta before loading (`PI_PACKAGE_DIR` points to the directory with `piConfig`); `agentDir()` computes `~/.ta/agent` without loading pi |
| `SessionLock` / `SessionLockExtension`(`ta:session-lock`) | Lock file beside the session file (draft first, then hard link, atomic create); the lock is no longer valid when the process exits. `/resume` on a locked session is canceled, and opening a locked session on startup shows a prompt and exits |
| `BrandExtension`(`ta:brand`) | The startup header of the terminal interface: a pixel dinosaur `DinoLogo`, version, key bindings. It wraps by terminal width, doesn't show the dinosaur on narrow terminals or Apple Terminal, and changes the pi self-reference in the system prompt to Ta's |
| `ExecExtension`(`ta:exec`) | When the execution environment is not local, replaces read / bash / edit / write / ls / find tools and takes over the `!` command. pi's grep always runs ripgrep locally, so it's disabled (models call rg through bash) |
| `ExecOperations` | Adapts `ExecEnvironment` to pi tool `*Operations` |
| `ExecMcpTransport` | Starts a stdio MCP server in the execution environment, passes it to pi's `createMcpExtension({ createTransport })` |
| `TaPackages` | Ta's built-in pi packages (`@celljs/ta-workspace`, `@celljs/ta-channels`, `@celljs/ta-extensions`, `@celljs/ta-computer-use`, `@celljs/ta-changes`, `@celljs/ta-cron`, `@celljs/ta-agents`): on release they are in `dist/pi/packages/<name>`, in the repo they're resolved from the workspace. Enabled by default; disabled ones are recorded in `ta.json` in the agent directory. The `ta` command loads pi extensions, skills and prompt templates of enabled packages with `--extension` (except package management commands and `--no-extensions`); `ta serve` uses pi ResourceLoader's `additionalExtensionPaths` + `extensionsOverride` / `skillsOverride` / `promptsOverride`, and on `reload` selects by the current switches |
| `TaExtension` / `TaExtensionUtil` | The shape of Ta's built-in extension: a plain object; `bundle()` combines built-in extensions into one, shown in pi's loaded extension list as `ta` |

<!-- https://cell.cellbang.com/ta/ta-host (ta-packages/ta-host/README.en.md) -->

# Cell - Ta Host

The server-side component of `ta serve`. It is functionally equivalent to Codex's app-server: pi only supports RPC mode over stdio (one process per session, one controller), and this component adds multi-session, multi-client, disconnect recovery, remote authorization, idempotent acknowledgments, and session locking. Command and event semantics are consistent with pi's RPC mode.

## Components

| Component | Purpose |
| --- | --- |
| `TaServerImpl` | `@Rpc(TaServer)`, handles sessions and pi RPC commands. Each command is forwarded to `AgentSession` / `AgentSessionRuntime` following pi's `rpc-mode` approach (pi only exports `runRpcMode` bound to stdio, so each command is mapped here; verify against pi's `rpc-mode` when upgrading pi). |
| `TaWorkspaceServerImpl` / `TaTerminalServerImpl` / `TaSettingsServerImpl` / `TaPackageServerImpl` / `TaAuthServerImpl` / `RelayBridge` | Other services on the same WebSocket; each forwards to the component below. `TaAccess` rejects HTTP-style calls (`POST /api/<service>` returns 404). |
| `TaSettingsServerImpl.setLanguage` | Ta's pages tell the server their language (`zh-CN`, `en-US`), which becomes `TA_LANGUAGE` of the process; the pi packages of the server (ta-agents, ta-cron, ta-computer-use, `/bug`) speak it. The client that set it last wins |
| `ExtensionProvidersImpl` | Model providers that pi packages register with `pi.registerProvider` (the agents of `@celljs/ta-agents`, for example) are in the shared model runtime only once extensions loaded. Before any session, `TaAuthServerImpl.listProviders`, the model list of the settings and `openSession` with a `model` first load the user's extensions once, in the home directory (project resources not trusted), so that no sign-in is asked for and a new conversation can pick their models. About 7 MB more than without, measured, and only on the first call |
| `TaAuthServerImpl` | `@Rpc(TaAuthServer)`: runs pi's `/login` flow on the server (OAuth login page, device code, or API key). It sends only the page to open and fields for the user to fill to the initiating connection (`TaClient.onAuthEvent`); the user's answer is sent back via `answer`. The `logout` method deletes stored credentials. Credentials are written to the server-side pi's `auth.json` and shared across all sessions; they are never sent back to the client. |
| `RelayBridge` | `@Rpc(TaRelayServer)`: reads `relay.json` from the agent directory. When paired devices exist, it connects to Relay and opens a connection to `/api/ws` on this machine for each device (see [@celljs/ta-relay](https://cell.cellbang.com/ta/ta-relay)). The `pair` and `unpair` commands work the same as `ta pair`. If no Relay is provided, it uses `https://relay.cellbang.com`. |
| `TaWorkingDirectory` | The working directory set by `setWorkingDirectory`, recorded in `ta.json` in the agent directory (`workingDirectory`), persists across restarts. Open sessions are unaffected. |
| `TaSessionRegistry` | Manages open sessions. Rejects requests when exceeding `maxSessions`, closes sessions that are idle (no clients, not running, no pending dialogs) for longer than `idleTimeoutMs`. Session files are retained. |
| `TaSessionFactory` | Assembles sessions the same way the pi command does: project trust, settings, extensions, themes. All sessions share one model runtime. Can be replaced by `rebind`. |
| `TaSession` | One open session: event log, acknowledgments, connected clients. After `newSession`/`fork`/`switchSession` the id remains unchanged and broadcasts `session_replaced`. The `navigateTree` command (pi's `/tree`) also broadcasts when switching branches within the same session. |
| `RemoteUiContext` | The pi extension's `ctx.ui`: dialogs are broadcast to all clients. The first response takes effect; if timed out, the default value from the extension is used. |
| `EventLog` / `ClientChannel` | Each session retains recent events in bytes for reconnection recovery. Each client merges into a frame every 30ms and sends the next frame after the client acknowledges. Clients that fall too far behind are disconnected to force reconnection. |
| `TaAccess` | Validates tokens (WebSocket handshake and HTTP), listens on localhost and validates the `Host` header to prevent DNS rebinding, writes `serve.json`. The token and port are saved to `serve-state.json` and reused on the next startup. |
| `WebExtensionCatalog`(`WebExtensionCatalogImpl`) | `listWebExtensions` / `readWebExtension` / `removeWebExtension`: finds web extensions in packages using pi's package loading method (`packages` setting and `extensions/` directory, project packages only when trusted). Reads only declared, in-package files that are under 2 MB. |
| Packages (`listPackages` / `installPackage` / `removePackage`) | Lists all packages loaded by pi (with or without web extensions) and includes `resources` (`extensions`, `web`, `skills`, `prompts`, `themes`). The `installPackage` command works the same as `ta install` (`project` is `-l`, only for trusted projects). The `removePackage` command works the same as `removeWebExtension` and removes by package id. |
| Package host service (`callPackageHost`) | Calls methods on objects returned by the built-in package `pi.host` (arguments and return values are JSON), for use by its web extensions. Methods that cannot be called are `dispose`, `constructor`, methods starting with `_`, or methods built into objects. |
| Toggles (`setPackageEnabled`) | Ta's built-in pi packages ([`TaPackages`](https://cell.cellbang.com/ta/ta-harness)) are toggled by name and listed with `origin: 'builtin'`. They can only be toggled, not removed. The toggle state is saved to `ta.json` in the agent directory (`disabledPackages`). Other packages are toggled by the id from `listPackages` and work the same as `ta config`, writing each resource individually to pi's settings (`PackageSwitch`: paths in `extensions/` are written as `+path` / `-path` to the `extensions` list, items in `packages` are written to that item's filter). The terminal `ta` recognizes this as well. Packages with no pi loading and only web extensions are recorded in `ta.json`'s `disabledWeb`. `enabled`: set to true when pi loads any resource from it (for web-only packages check `disabledWeb`). Disabled packages' web extensions are not loaded. Takes effect after session `reload`. |
| `TaSettingsStore`(`TaSettingsStoreImpl`) | `getSettings` / `updateSettings`: ta's settings (keys listed in `TA_SETTINGS`) are pi's `settings.json`, user-level in the agent directory, project-level in `<cwd>/.ta/`. Changes only the provided keys (set to `null` to delete; an empty object deletes the file thereafter). Preserves other content and uses atomic writes via temporary file. Only one write happens at a time. During writes, it acquires the same file lock as pi (`<file>.lock` directory, considered stale after 10 seconds), so the terminal `ta` changing settings simultaneously does not overwrite (pi rereads within the lock and only writes back the keys it changed). Does not overwrite unreadable files. At project level, pi requests trust for projects that have not been trusted (with extensions, skills, etc.). Writing without requiring trust is treated as trusting (otherwise pi will not read). After writing, it notifies related sessions' `SettingsManager` to reload (model and reasoning level take effect for new sessions). |
| `ExtensionDataStore`(`ExtensionDataStoreImpl`) | `getExtensionData` / `setExtensionData`: data stored on the server for packages (web extensions' `pi.storage`). One file per package at `<agentDir>/extension-data/<package name>.json` (mode 0600), with serial writes to the same file. Set values to `null` to delete keys. 4 MB limit per package. When `cwd` is provided, it is data for that directory at `extension-data/directories/<dir name>-<hash>/<package name>.json`. The hash includes the execution environment, so same-name directories do not interfere when running remotely. Notifications include `cwd`. |
| `ClientToolBroker` | Client tools (`clientTools`): each is a pi tool that broadcasts `client_tool_request` on call and waits for the first client to respond via `respondClientTool`. Ends with failure if the run is aborted or the session closes. |
| `DefaultExecEnvironmentFactory` | Tools execute based on directory: `ssh://<host>/<path>` runs on that host (`RemoteHosts`); local paths run locally; when `ta.exec.url` is configured, tools run on `ta exec-server` (see @celljs/ta-exec). The environment's `cwd` is the path in that environment; all paths resolve by it. A custom `ExecEnvironmentFactory` can also be used via `rebind`. |
| `RemoteHosts` / `TaRemoteServerImpl` | `@Rpc(TaRemoteServer)`: hosts for `ssh://` directories, each with an `SshHost` (uses system `ssh` and its config; auto-installs Node.js and the server on first use), connects on first call and reconnects after disconnection. Provides `listHosts` (Hosts from `~/.ssh/config` without wildcards and known to ssh, plus from `ta.json`'s `remoteHosts`), `addHost` / `removeHost` (remember or forget a host), `resolveLocation` (expand location without path to home directory), `watch` / `answer` (when ssh needs password, confirmation, or new host, asks all pages; first response wins), `disconnect`. Pushes connection steps and changes to `TaClient.onRemoteEvent`. |
| `PortForwards` | `forwardPort`: opens ports from the host of a remote directory on localhost's `127.0.0.1` (trying to reuse the same port number), with each connection forwarded through the execution environment's `connect`. Local directories are returned as-is. |
| `PiDirectories` | Remote directories (and all directories when `ta.exec.url` is set) use shadow directories on localhost: `<agent directory>/remote/ssh/<host>/<path>`. Pi names session files by them and writes project settings there; session info then switches back to the location. Files like AGENTS.md from remote projects are read by `RemoteContextFiles` and provided to pi (see [ta-remote-ssh.md](https://github.com/cellbang/cell/blob/main/docs/design/ta-remote-ssh.md)). |

Each session loads extensions the same way as the `ta` command: pi's built-in codemode, tool search, and MCP (pi's SDK does not auto-load them; when the execution environment is not local, stdio MCP services start in the execution environment). Ta's built-in extensions, enabled built-in packages' pi extensions, and `AgentExtension` and `AgentTool` components (@celljs/ai-coding-agent).

## Configuration

```yaml
ta:
  host:
    maxSessions: 32
    idleTimeoutMs: 600000
    eventBufferBytes: 524288      # per-session event amount for recovery
    clientBacklogBytes: 8388608   # per-client backlog allowed
  exec:
    url: ''                       # address of ta exec-server (ta serve --exec); empty: local
    token: ''                     # ta serve will fill TA_EXEC_TOKEN here
  remote:
    ssh: ssh                      # ssh command for ssh:// directories; ~/.ssh/config applies normally
    sshArgs: []                   # prepended to each host, e.g. ["-F", "/path/config"]
    nodeMirror: ''                # where to download Node.js if the host lacks 18+; empty: https://nodejs.org/dist
```

When [@celljs/ta-web](https://cell.cellbang.com/ta/ta-web) is installed, the `/` path on the same port serves the Web client: GET requests for page files do not require a token (they contain no data), and all calls under `/api` require a token. When listening on localhost, both validate the `Host` header.

## Session Storage (Cloud)

`ta serve` locally uses pi's session files, relying on session locks to ensure only one process writes at a time. In the cloud there may be multiple `ta serve` replicas, any of which may take over a session. In this case, the session is stored in `TaSessionStorage`:

- **Lease + epoch**: `acquire` increments the epoch when obtaining a session. Each `write` includes the lease, and requests are rejected if the epoch is not current (`StaleLeaseError`), so nothing is written. The old holder, even if not yet aware of being taken over by another replica (`takeOver` or after lease expiration), cannot write. The expiration time only determines when others can take it without going through takeover.
- **`FileSessionStorage`**: `<id>.jsonl` (pi's format) and `<id>.lease.json` in a directory, using lock directories for atomicity. Can be used locally or on a shared filesystem, and also serves as a reference for cloud implementations (conditional database updates, compare-and-swap in KV stores) to follow.
- **`StoredSession`**: pi's `SessionManager` (in-memory mode) plus write-through to storage. Each time pi adds a record, it is written out in order, the same as pi writing to a file. Nothing is written until the first user or model message. The lease is renewed at one-third intervals. After the lease is lost, pi adding records fails (like file write failure), and `onLost` notifies the host to stop the session.

Which cloud storage to use has not yet been decided, so `TaSessionFactory` has not integrated it yet. Pi's `AgentSessionRuntime` still creates `SessionManager` by file when creating new conversations, forking, or switching sessions. When integration happens, these places will switch to `StoredSession`.

## Known Limitations

- When there are no available models (model service not signed in, no model selected), pi's error will mention the `/login` command and its documentation path in the terminal. This is changed here to `CELL_TA_NOT_SIGNED_IN` with a prompt to sign in first using `TaAuthServer`.
- The deduplication table, event log, and pending dialogs are all in memory. After service restart, dialogs become invalid (extensions receive the default value), and clients should call `getMessages` first to verify before deciding to resend.
- When executing remotely, pi's resources (`AGENTS.md`, project `.ta/` settings and skills) still read from the same paths on the host machine. Project resources on the execution machine rely on a custom ResourceLoader (not yet implemented).

<!-- https://cell.cellbang.com/ta/ta-permission-gate (ta-packages/ta-permission-gate/README.en.md) -->

# Cell - Ta Permission Gate

A pi package: allows, asks for permission on, or denies tool calls based on rules. No Cell dependency; both Ta and pi can install it:

```bash
ta install npm:@celljs/ta-permission-gate
pi install npm:@celljs/ta-permission-gate
```

Rules are written in `permissions.json`, with one global file (in the agent directory) and one per project (in `.ta/` or `.pi/`):

```json
{
  "default": "allow",
  "rules": [
    { "tool": "bash", "command": "git push*", "action": "ask" },
    { "tool": "bash", "command": "*rm -rf*", "action": "deny" },
    { "path": "*/.env*", "action": "deny" }
  ]
}
```

- The first matching rule in each file takes effect. If none match, use `default` (default is `allow`); `*` matches any characters, others are literal.
- Both files take the stricter result: a project can only tighten permissions, not loosen them; otherwise an untrusted repo could give itself permissions.
- `ask` calls `ctx.ui.confirm`. If no answer arrives within 5 minutes, it's treated as deny. Without a UI (`-p`) it's directly denied. Under `ta serve`, the dialog is sent to all connected clients.
- If a file cannot be read or has bad format, all calls are denied.

When there's no `permissions.json`, nothing is restricted, consistent with pi's default behavior.

<!-- https://cell.cellbang.com/ta/ta-protocol (ta-packages/ta-protocol/README.en.md) -->

# Cell - Ta Protocol

Protocol between `ta serve` and clients: types and constants only, with no pi or Node.js modules loaded, so it works in browsers.

- **Transport**: one WebSocket (`TA_WEBSOCKET_PATH`) with JSON-RPC 2.0 messages. Method names are `<service>/<method>`, and the server pushes `TaClient/onEvents` etc. HTTP-based calls are not offered; only workspace file bytes travel HTTP (`TA_FILES_PATH`, for images and iframes in pages to load via relative URLs).
- **Services**: `TaServer` (sessions—pi's RPC commands), `TaWorkspaceServer` (files and commands in directories), `TaTerminalServer` (terminals), `TaSettingsServer` (pi's `settings.json`), `TaPackageServer` (packages, web extensions, and package data), `TaAuthServer` (login to model services, same as pi's `/login` and `/logout`), `TaRelayServer` (paired devices via Relay, same as `ta pair`), `TaRemoteServer` (hosts for `ssh://` directories, ssh prompts, port forwarding). Capabilities outside sessions split into separate services by responsibility, not added to `TaServer`.
- **`TaServer` methods**: besides `openSession`, `closeSession`, `listSessions`, `attach`, `detach`, `respondUi`, and `respondClientTool`, the rest are pi RPC mode commands with the same name (snake_case → camelCase, see `PiCommandMethod`). The first parameter is `sessionId`, and return values match pi's; when pi adds an RPC command and `TaServer` lacks the method, this package's tests won't compile. `setWorkingDirectory` sets ta serve's working directory (`TaServerInfo.cwd`, used when clients don't specify one, persists across restarts). Session operations not in pi RPC: `forkToFile` (saves the forked session to a file, current session untouched, then open with `openSession`), `navigateTree` (same as pi's `/tree`, returns `editorText`), `fork` has an optional `position` (`at` keeps the selected item, like pi's `/clone` but optional for any item).
- **Events**: `TaEventEnvelope { sessionId, seq, event }`, where `event` is a pi JSON/RPC mode event or `extension_ui_request`. Ta adds only `ui_request_resolved`, `extension_error`, `session_replaced`, `session_closed`, and `client_tool_request` (reserved).
- **`prompt` / `steer` / `followUp`**: carry client-generated `clientMessageId`. Retrying with the same ID returns `duplicate` and doesn't re-execute. Receipt only means accepted; the round end is marked by the `agent_settled` event.
- **Locations** (`cwd`): a path is either local or on another machine in the form `ssh://<host>/<absolute-path>` (`TaLocation` parses, handles parent/child, and names).
- **Errors**: the JSON-RPC error code is `TA_RPC_ERROR_CODE`. The `data` field includes a stable `code` (`TaErrorCode`, e.g., `CELL_TA_SESSION_LOCKED`) and a one-line handling hint. When no model is available or the model service isn't signed in, the code is `CELL_TA_NOT_SIGNED_IN`; clients open the login page accordingly. `CELL_TA_CONNECTION_LOST` is client-generated: the call didn't reach ta serve, or the connection dropped before the result arrived.

<!-- https://cell.cellbang.com/ta/ta-relay (ta-packages/ta-relay/README.en.md) -->

# Cell - Ta Relay

Connect from your phone or another device to your computer's `ta serve`: both sides establish connections to Relay, which only forwards traffic. Content is end-to-end encrypted, so Relay cannot read it. This is off by default; `ta serve` only connects to Relay after you pair a device.

```text
Mobile (RelaySocket) ──wss──▶ Relay ◀──wss── ta serve (RelayHost) ──ws──▶ localhost /api/ws
          └──────── AES-256-GCM, key only at both ends ────────┘
```

## Pairing

```bash
ta pair                          # add a device, print pairing link; default Relay is https://relay.cellbang.com
ta pair https://<relay> --name phone   # use your own Relay, name the device
ta pair --list                   # list paired devices
ta pair --remove <device-id>     # unpair, takes effect immediately
```

Pairing links look like `https://<relay>/pair#v=1&h=<host-id>&d=<device-id>&k=<key>`. The key is after the `#`, so the browser won't send it to Relay. Paste the link in the Ta app to connect. You can also pair from the Web client or desktop app: click the gear menu's "Use on your phone…" to show the link as a QR code (shown once only) and list paired devices, whether ta serve is connected to Relay, and allow you to unpair (`ta serve`'s `TaRelayServer`). Devices are saved in `relay.json` in the agent directory (file mode 0600); `ta serve` automatically reads changes as they happen, no restart needed.

## Protocol

- `/v1/host/<host-id>?secret=<host-secret>`: `ta serve` connects here. Each host ID is claimed by the first host to connect with it; Relay only stores the hash of the secret.
- `/v1/connect/<host-id>`: devices connect here. Relay assigns each a channel and forwards it to the host (`{t:'open'|'data'|'close', ch, d}`).
- Handshake: the device sends first `{t:'hello', v:1, device, nonce}`; the host finds the device's key and replies `{t:'ready', nonce, proof}`. Both sides use HKDF-SHA-256 (device key, salt is both nonces) to derive one AES-256-GCM key for each direction, ensuring every connection has a different key. `proof` is the host's first encrypted message, proving it has this device's key. After that, every message is encrypted with the IV set to the message sequence number, so Relay's replay, drop, or reorder attempts all fail decryption.
- The host opens one connection per device to localhost's `/api/ws`, including the localhost token. Devices never receive or need the token.

## Deploying Relay

- Cloudflare Workers: [apps/ta-relay](https://cell.cellbang.com/ta/relay) (Durable Objects, sleep when idle).
- Your own machine: `ta relay [--host 0.0.0.0] [--port 8080]`, behind an HTTPS reverse proxy. Host ID ownership exists only in memory; after restart, the first host to connect reclaims it.

## Known Limitations

- When going through Relay, only WebSocket calls work. Local file preview in the Web client (`/api/files`) is not available.
- Device keys are long-term with no forward secrecy: if a key leaks, old traffic in recordings can be decrypted. Unpairing invalidates the key.

<!-- https://cell.cellbang.com/ta/ta-web (ta-packages/ta-web/README.en.md) -->

# Cell - Ta Web

The Web client included with `ta serve`: a Cell frontend component ([@celljs/react](https://cell.cellbang.com/packages/react)) whose state comes entirely from [@celljs/ta-client](https://cell.cellbang.com/ta/ta-client), so it shares the same session state machine as the desktop and mobile clients.

```bash
ta serve --web     # Start and open in browser, token already included
```

## Install as Application (PWA)

The Web client can be installed as an application on desktop or mobile: use the install icon in the Chrome or Edge address bar, or "Install as app" from the account menu, or "Add to Home Screen" in iOS Safari. After installation, it opens in a separate window with the Cell dinosaur icon.

- Files are in `src/browser/public/` (`manifest.webmanifest`, `sw.js`, `icons/`) and placed at the site root during build; the manifest and Service Worker only work in secure contexts: localhost (127.0.0.1 or localhost) or HTTPS. Accessing via HTTP from another machine using `--host` displays only as a web page.
- The app remembers the address (including port) and token, so `ta serve` reuses the last port and token by default (see [@celljs/ta](https://cell.cellbang.com/ta)).
- The Service Worker caches nothing under `/api`: pages come from the network and fall back to the last page on failure; hashed scripts under `/assets/` come from the cache first, and old scripts are cleared once the page has a new build. While ta serve is not running the app still opens, says "The Ta service is not running" and connects once it starts. The interface calls ta serve "the Ta service" and names the command only where the user has to run it in a terminal.

## Interface

The main layout is IDE-style: the navigation bar on the far left (with logo doubling as a sidebar toggle, pages for web extensions, and settings and account menu at the bottom), the sidebar next to it (resizable and collapsible; a row of icon tabs at the top switches between web extension sidebar views and the conversation list, with a search box and + button to the right of the tabs) containing all open sessions on the server (which can be created, created in a specified directory, or closed), the current conversation in the middle, and a collapsible panel on the right for web extension cards. On narrow screens, the navigation bar and conversation list become drawers, and the panel floats above the conversation.

Initially, the interface shows only conversations. You tell Ta what you want this page to do and display, and Ta builds it as a pi package—cards beside the conversation, a standalone page, or a new Ta command—which appears on the page immediately.

Everything new in the interface comes from **web extensions** within packages, using the same mechanism and terminology as pi extensions:

- **Packages** are pi packages. In the `pi` field of `package.json`, `extensions` are extensions for Ta (terminal and server), and `web` are extensions for this page; when not declared, modules in the `web/` directory are used. Packages can be placed in `~/.ta/agent/extensions/<name>/` or the project's `.ta/extensions/` to take effect, or installed with `ta install`.
- **Web extensions** are ES modules without import statements, with a default export of a function that the page calls with `pi`; the returned function is called on unload. The `pi` interface follows pi's ExtensionAPI naming: `ui.setWidget` (default above the input box, same as pi; `placement: 'panel'` puts it in the right workbench's card tabs), `registerView` (pages in the navigation bar, or a tab at the top of the sidebar; `location: 'panel'` is a tool in the right workbench), `registerMessageRenderer` (displays custom messages sent by pi extensions with `sendMessage`), `registerTool` (tools executed by the browser in conversations opened on the page), `registerOpener` (opens links in replies: files and their lines, directories, web pages, asked in registration order, returns true if opened), `on` (events of the current conversation), `sendUserMessage` (sends to current conversation; `/commands` execute pi extension commands), `switchSession` (displays another open session in ta serve as the current conversation), `callHost` (calls methods of this package's `pi.host`, via `callPackageHost`), `reloadExtensions` (after the extension itself installs, imports or removes packages, reload web extensions and pi extensions of the current conversation like at the end of a reply), `ui.showView` / `ui.useView` (show, view any extension's view), `ui.Composer` / `ui.Markdown` (input box and Markdown same as conversation), `ui.Dialog` (full-page modal), `ui.openEditor`'s `preview` (preview tab that opens on click, title in italics, next preview replaces it, double-click or `ui.pinEditor` pins it), `ui.setEditorDirty` (tab shows unsaved dot, confirm before close), `ui.useActiveEditor` (current tab in workbench), `ui.DiffEditor` (Monaco diff editor, side-by-side or inline, right side editable), `ui.confirm`'s `confirmLabel` / `danger`, view's `head` (its own title bar), `ui.input` / `ui.editor` (ask user for one or multiple lines of text, returns `undefined` if canceled), page's `menu` (floating … menu when the page is listed in sidebar) and `pages` (pages listed in sidebar, navigation bar no longer lists them separately), `ui.notify` (notifications in bottom right of page), `ui.confirm` (confirm before continuing, returns whether user agreed), `ui.theme`, `ui.language`, `ui.supportsWebview` (whether a view can show a site in a `<webview>`, as in Ta Desktop, rather than an iframe), `ui.debugWebview` (Ta Desktop: a command of the Chrome DevTools Protocol to the page of such a webview, limited to the page itself), `ui.desktop.browserData` (Ta Desktop on macOS and Windows: the cookies of a profile of the user's browser taken into the browser of Ta once the user says yes in a dialog of the app, and clearing that browser's data), and page services: `server` (session, pi's RPC commands), `workspace` (files and commands in directory), `terminals` (terminals), `packages` (packages) (types see `WebExtensionAPI`).
- **Make packages with natural language**: the built-in extension [@celljs/ta-extensions](https://cell.cellbang.com/ta/ta-extensions) includes the skill `ta-package` (also available in the Ta terminal) and adds an "Extensions" page in the navigation bar (create an extension in one sentence, export or import). It documents package format, the web extension interface, and validation steps. At the end of each reply in the current conversation, the page reloads web extensions: new ones load, changed ones reload, and deleted ones unload; when tools change, the conversation reopens that part in the same session file (only for conversations opened on this page); when packages change, the session reloads pi extensions. The page checks again when redisplayed (packages might change in the terminal too).
- **Stable**: each extension owns what it registers and removes it all on unload; if one extension fails to load or render, only that extension's area shows an error, without affecting the page or other extensions.

**Settings → More → Extensions** (the "Extensions" in the gear menu) lists installed extensions (each is a package with web extensions that can be removed or reloaded); **Built-in Extensions** lists packages and web extensions provided with Ta and can be toggled here:

- **My Double**: a double that can be given tasks by voice or text. The main conversation is a regular Ta session with role instructions (`appendSystemPrompt`) and five client tools (such as `start_task`); each task runs as a new session in the background and ends with a `<task_update>` report. The appearance is the dinosaur from the Cell logo (`DinoAvatar`, using the same path as `assets/logo.svg`), conveying states such as standby, listening, thinking, working, speaking, needing confirmation, done, and asleep using only eye expressions and small markers.

### Conversation and Input Box

- **Conversation flow**: continuous thinking, tool calls, and interim explanations in a turn are folded into a single line "Executed N steps": this expands while in progress, shows only recent steps, and collapses after completion (remaining expanded and marking failed steps if any); the final text is the reply. Layout is a pure function `ProcessUtil` (`util/process.ts`); each message uses a stable key and memos per message, so streaming output only redraws changed messages.
- **Input box**: Enter sends, Shift+Enter inserts a newline; during IME composition, Enter does not send. While Ta works, Enter suggests, Alt+Enter queues, Esc stops, and send and stop use the same button. `/` lists commands, `@` finds and inserts `@path` by filename (using the server's `findFiles`; the menu explains if unsupported); images can be pasted, dragged, or selected (PNG, JPEG, GIF, WebP; max 5 MB per image, max 8 per message); queued messages show above the input box and can be undone back to the box (`clearQueue`). Logic is in `ComposerUtil` (`util/composer.ts`).
- **Avatar**: `TaAvatar` is the Cell logo, and `mark` is a 1–2 character badge to distinguish agents (in web extensions it's `pi.ui.Avatar`); each reply starts with a small avatar (once per turn): during work, eye expression shows thinking, execution, or output; on the last turn when done, eyes squint with a checkmark; on error, it shows an alert badge; an empty conversation page displays a large avatar that blinks and occasionally looks at the input box. With reduced motion, everything is static.
- **Status and hints**: four levels (info, success, warning, and error), each with a fixed icon and color, with the body always in body color. By ownership, there are three types: global **connection status bar** (a capsule at the top of the main area that appears after 1 second of disconnect, showing reason, countdown, and "Retry now"; shows "Reconnected" for 2 seconds after recovery); **notices** (`TaNotices`, bottom right, top on phone; success 3s, info 4s, warning 6s, error 8s; add 4s for buttons; pause on hover or focus; merge same messages with count; max 4 notices); **inline hints** (`Callout`, staying at the place of issue, such as when a turn reply fails, an extension view errors, or a token is rejected). Operation failures (send, switch model, open conversation, etc.) uniformly use `notices.error`: server errors with `hint` put the suggestion on the second line; failures from disconnect merge into one "Did not complete: ta serve not connected" message. Operations needing user confirmation use `notices.confirm`; irreversible operations have red buttons with default focus on "Cancel".
- **Links**: all links in replies are clickable (`TaLinks`, parsed in `LinkUtil`). Web links, bare URLs in text, and `<URL>` open by default in the browser on the right workbench; Cmd/Ctrl+click (or middle button) opens in the system browser. File paths (`[text](https://github.com/cellbang/cell/blob/main/ta-packages/ta-web/src/a.ts#L10-L20)`, `src/a.ts:10:5`, `file://` address, and inline code like `src/a.ts:12` and `package.json`) are parsed relative to the conversation directory, open and locate in the workbench, and select corresponding lines and columns (syntax like VS Code: `#L10`, `#L10C5-L12C3`, `:10:5`, `:10-20`); directories (`docs/`) open in the explorer at that directory. Open actions are provided by web extensions (`registerOpener`; the built-in @celljs/ta-workspace handles files, directories, and the built-in browser). For security, following VS Code: only http(s), mailto, and paths are recognized; `javascript:`, `data:`, `command:`, etc. are plain text; rendering results are React elements, not HTML; paths are confirmed to exist on the server first, though read/write are still subject to execution environment constraints. Before opening in the system browser, a popup shows the full address with the domain highlighted (domains with similar appearance are shown in browser's punycode format); you can copy, open, or trust the domain. Localhost addresses (localhost, 127.0.0.1, and the host where ta serve runs) and **Settings → Links → Trusted Domains** (`github.com`, `*.github.com`, `localhost:3000`, `*`) skip confirmation; new windows always have `noopener,noreferrer`. In the built-in browser, URLs same-origin with the Ta page do not get `allow-same-origin` and cannot reach the page or token.
- **Account menu**: the round avatar at the foot of the navigation bar (`AccountMenu`) shows the initial of the user name on the computer of ta serve (`TaServerInfo.user`), with a yellow dot at its corner while disconnected. The menu shows the user and computer name (`host`), the connection state and version of the Ta service, "Install as app" (when the browser supports it) and sign out.

### Settings

The gear above the avatar (`ManageMenu`) is a two-level menu: Settings (⌘/Ctrl+,), Extensions, Keyboard shortcuts; Model accounts…, Open working directory…, Use on your phone…; Theme and Language expand on the right as a second level, with About Ta last. Settings is a view in the main area (`SettingsView`; it occupies the conversation and workbench when open; Esc or × closes it). The left side is a two-level directory (Interface, Ta, and More, then groups below; it follows highlight when scrolling); the right side shows group cards. The search bar at the top filters by name and description of each line:

- **Interface**: theme, reduce motion, interface language, and read aloud replies; stored in server user data (`TaSettings`), consistent across browsers and devices.
- **Ta**: Ta's own settings; reads and writes pi's `settings.json` (via the server's `getSettings` and `updateSettings`; editable keys are listed in ta-protocol's `TA_SETTINGS`): default model, thinking strength, transport, guide and queue message delivery, auto-compress and retry, code mode, skill commands, shell and command prefix, and images. At the top, switch between **User** (agent directory; affects all projects) and **Project** (`.ta/settings.json` in the current conversation directory; overrides user settings). Unset items show inherited values ("Default (…)" or "Use user setting (…)"); items set in the current level have a blue bar on the left; hover to reset. A project that is untrusted is read-only with the reason shown.
- **More**: Extensions, Built-in extensions, Keyboard shortcuts, and About (version, working directory, model accounts, phone access, and log out).

### Sign In to Model Service, Working Directory and Phone

- **Model accounts**: similar to pi's `/login` in the terminal, you can sign in with an account (OAuth, Claude, ChatGPT subscriptions) or API Key. Sign-in occurs on ta serve (`TaAuthServer`): the login page to open, device code, and key to fill are sent only to the requesting page; credentials are stored in `auth.json` on the ta serve machine, not in the browser. When no model is available (`CELL_TA_NOT_SIGNED_IN`), the page opens the login page directly instead of pi's `/login` prompt; the same applies to the desktop app on first launch.
- **Working directory**: when no directory is specified, new conversations and doubles open in ta serve's working directory. "Open working directory…" (`TaServer.setWorkingDirectory`) affects all clients and persists across restarts; already open conversations are not changed.
- **Use on your phone**: pair a device via Relay ([@celljs/ta-relay](https://cell.cellbang.com/ta/ta-relay)); the pairing link is displayed as a QR code (`util/qr-code.ts` draws it itself with no dependencies) and shown only once. Below, it lists paired devices and whether ta serve is connected to Relay. The default Relay is `https://relay.cellbang.com`.

## Structure

| | |
| --- | --- |
| `TaWorkbench` (`TaWorkbenchImpl`) | One connection and open sessions on the server; token from URL fragment or localStorage; if unreachable, probe the server first: a response means the token is wrong (back to login page); no response means ta serve is not running (keep token, show hint, and auto-retry) |
| `TaPwa` (`TaPwaImpl`) | Make the page an installable app: link the manifest and icons, register Service Worker, and provide "Install as app" in the account menu (when the browser offers an install prompt) |
| `TaWebExtensions` (`TaWebExtensionsImpl`) | Load, reload, and unload web extensions; aggregate pages, cards, message renderers, and tools they register |
| `BuiltinWebExtension` | Extension point for built-in web extensions: `AssistantWebExtension` (the double) |
| `TaChat` (`TaChatImpl`) | Current conversation: create, switch, or close; open a session with web extension tools; reload extensions after a reply; remember the last session file and new conversation directory (user level) |
| `TaAssistant` (`TaAssistantImpl`) | The double: main conversation, tasks, and client tools for task dispatch; session file and task list are user-level state, with the same double across browsers |
| `TaState` (`TaStateImpl`) | Interface state saved by level; see below "Interface State" |
| `TaSettings` (`TaSettingsImpl`) | Theme, language, read aloud, reduce motion, and toggled built-in extensions; language is switched via @celljs/widget's `LocaleManager` |
| `TaNotices` (`TaNoticesImpl`) | Page's notices and confirmations; shared by Ta and web extensions |
| `TaAppPage` | Home page registered with `@View` (`AppView`) |

The server ([@celljs/ta-host](https://cell.cellbang.com/ta/ta-host)) adds `getSettings` and `updateSettings` (Ta's settings) and three methods: `listWebExtensions`, `readWebExtension`, and `removeWebExtension`, which find web extensions the same way pi loads packages (`packages` setting and `extensions/` directory; project's only when trusted); and `reload`, which is the same as pi's `/reload`.

## Interface State

Things on the interface that should persist after refresh, grouped by "who should see it again", are saved uniformly by `TaState` (in components use `usePersisted(spec)`; `spec` specifies the key, level, initial value, and validation on read):

| Level | Where | For |
| --- | --- | --- |
| `tab` | This page's sessionStorage | Current page and sidebar tabs: two pages can each see their own |
| `device` | This browser's localStorage | Panel widths, collapse state, and whether the right workbench is open: follows the screen |
| `user` | Server's data for `@celljs/ta-web` package (`getExtensionData`); browser keeps a copy | Settings, last conversation, new conversation directory, the double's session and tasks, and workbench open tools: consistent across browsers and devices |

`user` level first uses the browser copy (no flash on first screen), then reads from the server and updates if the server value differs; changes merge and write after ~300 ms, write immediately when the page is hidden or closed, changes during disconnect are sent after reconnect, and changes from other browsers are pushed via `onExtensionData`. On read, values already changed on this page are not overwritten; between browsers, the last write wins. Old values existing only in the browser are moved to the server on first read.

State for a specific directory (expanded folders in the explorer) is saved by the web extension displaying it with `pi.storage.directory(cwd)`; the server stores it by directory (plus execution environment; with `ta serve --exec`, same-named directories on remote machines are separate) in separate files. Open files are recorded by @celljs/ta-workspace itself in `pi.storage`; loading reopens them in the background with `openEditor(editor, { preserveFocus: true })` and does not pop out the workbench.

The token is a login credential, not interface state, and is still stored by `TaWorkbench` in localStorage (after being installed as an app, you can sign in in its own window).

To add a built-in web extension, write a `@Component(BuiltinWebExtension)`. To replace the whole interface, rebind the home page with `@View({ index: true, component: MyView }, true)`.

<!-- https://cell.cellbang.com/ta/ta-workspace (ta-packages/ta-workspace/README.md) -->

# @celljs/ta-workspace

A pi package that comes with Ta: the workspace of the conversation shown, in the workbench beside it in the web client of `ta serve`, as the tools of an IDE.

| View | What it does |
| --- | --- |
| Explorer | The files of the conversation's directory, with the file icons of VS Code, the colors and letters of git (folders take the change inside them, ignored files are dimmed) and indent guides; it follows the tab shown. A click opens a file as a preview tab (the next preview takes its place), a double click keeps it: Markdown, HTML, images, videos, sounds and PDFs as a preview, the rest in Monaco (`pi.ui.CodeEditor`), saved with Ctrl+S or Cmd+S. New file and folder (`a/b.ts` makes the folders), rename and delete in place, with the checks of VS Code on names; a context menu with copy path and relative path, find in folder, upload files or a folder, and download (a folder as a zip made in the page); in Ta Desktop, reveal in Finder (File Explorer on Windows, the file manager on Linux) for directories of this machine (`pi.ui.desktop`). Drag an item onto a folder to move it there (a closed folder opens while it is held over it), files or folders of the system onto the tree to upload them, and an item onto the message box (an `@` reference) or a terminal (its path) (`pi.ui.fileDrag`); the keys of a tree (arrows, Home/End, F2 or Enter on a Mac, Delete) |
| Open files | The tabs of files and changes this package opened, the one shown marked; close, close others, close below, reveal in the explorer |
| Search | Text in the files (ripgrep, git grep or grep, whichever the machine has): match case, whole word, a regular expression (its error shown), files to include and to exclude (globs separated by commas, a folder takes all inside it); each match of a line is a result, which opens the file selected on it. Replace one, in a file or all (with `$1` for a group), the change shown on each result; dismiss results (a file or a folder); collapse and expand all; the results as a list or a tree of folders |
| Source control | The branch with what it is ahead and behind, a box for the commit message (Ctrl+Enter or Cmd+Enter; with nothing staged it offers to stage all), merge changes, staged changes and changes, as a list or a tree; stage, unstage and discard a file or a group (discarding asks; for an untracked file it deletes), pull, push and fetch. A change opens in Monaco's diff editor, side by side or inline, the unchanged lines folded; a change not staged can be edited there and saved |
| Terminal | Shells on the machine of the session, in one tab; the first opens with it; they survive a dropped connection for 30 s. Files dragged from the explorer are typed as their paths, quoted for the shell |
| Browser | A page in its tab, such as the dev server the agent started: back, forward, reload and the address in one bar, a line while the page loads; a start page with the addresses opened lately (remove one with its ×), or the ports dev servers take when there are none yet. A page of the origin of Ta itself runs without `allow-same-origin`, so it cannot reach the page or its token. In a directory of another machine (`ssh://`), a page of its `localhost` is that machine's: its port is opened on the machine of `ta serve` (`pi.remote.forwardPort`), and the bar keeps the address as typed. In Ta Desktop (`pi.ui.supportsWebview`) the page is a `<webview>` instead of a frame: sites cannot refuse it, signing in works and stays (a partition of its own), back and forward follow the page, the bar shows its title and icon and stops a load, a failed load or a crashed page says so with a retry, and the context menu, browser shortcuts and DevTools are the app's. There the agent works the same page with the `browser` tool (`pi.ui.debugWebview`): navigate, back, forward, reload; a snapshot of the accessibility tree whose elements carry refs; click, type, press, scroll; a screenshot (a data URL for codemode's `image()`); evaluate, wait, and any command of the DevTools protocol on the page. Refs hold for the page of the last snapshot only. The view comes up while the agent works it and the bar says so; text goes in without the keyboard focus, and a click or a key gives the focus back to where the user was typing. The start page offers to import sign-ins (`pi.ui.desktop.browserData`, macOS and Windows): the user picks a profile of Chrome, Edge, Brave, Arc, Vivaldi or Chromium, says yes in a dialog of the app, and its cookies come over; passwords and history do not. The same dialog clears the data of the browser |

Each view is a `panel` view of its web extension, opened from the `+` of the workbench or its empty state (`pi.web` of `package.json`); the work runs on the server through `pi.workspace` (`listDirectory`, `readFile`, `writeFile`, `uploadFile`, `fileUrl`, `runCommand`, …) and `pi.terminals`, in the execution environment of the directory, so a remote `ta exec-server` works the same. Search, source control and the changes to files are this package's: it runs `rg` (or `git grep`, or `grep`), `git`, `mkdir`, `mv -n` and `rm` with `runCommand` and reads their output; paths go to git as `:(literal)` pathspecs. Paths may not leave the directory. What the agent changes with its tools shows at once.

Files open in Monaco, which the page brings (`pi.ui.CodeEditor`, bundled with Ta, no network); Markdown, HTML, SVG open as a preview first, with Edit beside Preview. Previews load the file from `TaWorkspaceServer.fileUrl`: a page runs sandboxed in an origin of its own, Markdown (rendered with marked, bundled in) runs no scripts, and both load the files beside them with relative URLs. Diffs open in Monaco's diff editor (`pi.ui.DiffEditor`), terminals are xterm.js, as in VS Code (`pi.ui.createTerminal`: drawn with WebGL, in the theme of the page; Cmd or Ctrl + click opens the URLs and the paths of files they print, at the line a compiler or grep names). The file icons are the Seti icons VS Code shows by default (font and map from `extensions/theme-seti` of microsoft/vscode, MIT; `bun scripts/seti.ts` writes them again into `web-src/util/seti*.ts`). With `script` on the server a shell gets a pseudo-terminal; without it, it runs on pipes and the server echoes and edits the line.

Links of replies open here (`pi.registerOpener`): a file as its tab, with the lines the link names selected (`src/a.ts#L10-L20`, `src/a.ts:10:5`), even a file open with changes, which keeps them; a directory in the explorer, which switches to it; a page in the browser. Cmd or Ctrl + click opens a page in the browser of the system instead, which Ta does itself.

Turn it off in Settings → Packages.

## Development

```sh
bun run build   # tsc -b, then bun build web-src/index.tsx → web/index.js (one module, no imports)
bun run test
```

The web extension gets React from the page (`web-src/react.ts`) and icons from `pi.ui.icons`: it imports nothing at run time. To try it with an installed Ta, link the package into `~/.ta/agent/extensions/`.