tsed-cli

# Scaffold and generate with the Ts.ED CLI Generate boilerplate with the CLI so file names, directories and class names match the project preferences. Hand-write a file only when no template fits. References, loaded on demand: - [Template ids, output paths and extra properties](references/templates.md) - [Init options, feature values and command flags](references/init-options.md) ## 1. Read the project preferences first Preferences live under the `tsed` key of the application's `package.json`, for example `"tsed": {"convention": "conv_default", "architecture": "arc_default", "platform": "express", "runtime": "node", "packageManager": "npm"}`. | Key | Values | Effect | | ---------------- | ----------------------------------------------------- | -------------------------------------------------------------------- | | `convention` | `conv_default`, `angular` | File name: `ProductController.ts` vs `product.controller.ts` | | `architecture` | `arc_default`, `feature` | `src/controllers/...` vs a folder taken from the name (`users/User`) | | `platform` | `express`, `koa`, `fastify` | Adapter package to import | | `runtime` | `node`, `vite`, `bun`, `bun-vite`, `babel`, `webpack` | Dev/build scripts | | `packageManager` | `npm`, `yarn`, `yarn_berry`, `pnpm`, `bun` | Install command | 1. Read these values before creating or renaming any file, even by hand. 2. The exported class name is PascalCase with the type suffix in both conventions (`ProductController`); only the file name changes. 3. A missing `tsed.packageManager` means the project is not initialized for the CLI. Do not generate; go to section 3 or ask the user. 4. Use the project's package manager for every install or script command. ## 2. Choose the channel 1. If an MCP server named `tsed` is connected (tools `set-workspace`, `generate-file`, ...), use section 3. 2. Otherwise use the shell (section 4). Prefer the locally installed binary: `npx tsed ...` inside a project that has `@tsed/cli` in `devDependencies`. 3. To offer the MCP server to the user, give this exact declaration. Node.js >= 22 is required. ```json { "mcpServers": { "tsed": { "command": "npx", "args": ["-y", "-p", "@tsed/cli", "tsed", "mcp"] } } } ``` - stdio is the default transport. `tsed mcp --http` serves streamable HTTP on `POST /mcp`, port `PORT` (default `3000`). - Do not write `npx -y @tsed/cli mcp`: it fails on a first install because the package name is not the binary name. - Do not reference a `tsed-mcp` binary. It does not exist. ## 3. MCP flow 1. Call `set-workspace` with `{cwd}` (absolute path preferred). It resolves the nearest `package.json` and returns `cwd`, `pkg` and `preferences`. 2. Read resource `tsed://project/info` and check `isInitialized`. `preferences` there omits `architecture`; read it from `pkg.tsed.architecture`. 3. Not initialized, new project wanted: 1. Read resource `tsed://init/options` (`instructions` plus the JSON `schema`). 2. Ask the user for platform, architecture, convention, features, runtime and package manager. Show labels, send enum values. 3. Call `init-project` with `{cwd, platform, architecture, convention, features, runtime, packageManager, projectName?, tsedVersion?}`. 4. Initialized, new file wanted: 1. `list-templates` with an optional `{search}` to find the template id. 2. `get-template` with `{id}` to read the extra properties schema. 3. `generate-file` with `{id, name, properties}`. Example: `{"id": "controller", "name": "Product", "properties": {"route": "/products", "directory": "rest"}}`. 4. Read `files` and `symbolPath` from the result, then edit the generated file. 5. Resource `tsed://server/info` reports the CLI version and whether the workspace is a project; use it for diagnostics. | Error code | Returned by | Fix | | ------------------------------- | ------------------------------- | --------------------------------------------------------------------- | | `E_CWD_NOT_FOUND` | `set-workspace` | Confirm the folder with the user, then `init-project` with that `cwd` | | `E_CWD_NOT_SET` | `generate-file` | Call `set-workspace` first | | `E_PROJECT_NOT_INITIALIZED` | `generate-file` | Wrong workspace, or run `init-project` | | `E_PROJECT_ALREADY_INITIALIZED` | `init-project` | Use `generate-file`, or pick another folder | | `E_TEMPLATE_UNKNOWN` | `get-template`, `generate-file` | Take the id from `list-templates` | | `E_ARGS_INVALID` | `generate-file` | Re-read `get-template`; fix `properties` (`details.errors`) | Do not call `init-project` without the user's choices. Do not retry a failed tool call with the same arguments. ## 4. Shell fallback Global options on every command: `-r, --root-dir <path>`, `--verbose`. Run commands non-interactively; an agent cannot answer prompts. ```sh # New project (asks nothing with --skip-prompt) npx -p @tsed/cli tsed init my-api --skip-prompt --platform express --arch arc_default \ --convention conv_default --runtime node --package-manager npm \ --features doc doc:swagger testing testing:vitest linter linter:oxlint # Generate: tsed generate|g [type] [name] npx tsed g controller Product --route /products --directory rest npx tsed g middleware Auth --middleware-position before npx tsed g decorator Roles --template-type endpoint npx tsed template my-template --from new # scaffold .templates/my-template.template.ts npx tsed add @tsed/cli-plugin-prisma # install a CLI plugin npx tsed run <command> # run a command from src/bin/index.ts npx tsed update # interactive version picker npx tsed dev # Vite runtimes only: watch src/index.ts npx tsed build # Vite runtimes only: vite build ``` 1. Pass both `type` and `name`, plus the template's options, or `generate` opens a prompt. 2. `tsed update` always prompts for the target version. Ask the user to run it, or edit the `@tsed/*` versions in `package.json` and install. 3. `tsed dev` and `tsed build` exist only for the `vite` and `bun-vite` runtimes and need `vite.config.ts`. For other runtimes use the `package.json` scripts written by `tsed init`. 4. `tsed init-options` prints the init JSON schema; use it when the feature list in the reference may be outdated. ## 5. Custom templates 1. Scaffold with `tsed template <name> --from new` (without `--from` the command prompts). The file lands in `.templates/<name>.template.ts`. 2. Every `.ts` file under `.templates/` is loaded at startup; a custom template replaces a built-in one with the same `id` and is labelled `(custom)`. 3. Shape: ```ts import {defineTemplate} from "@tsed/cli"; import {s} from "@tsed/schema"; export default defineTemplate({ id: "use-case", label: "Use case", description: "Create an application use case in src/use-cases.", fileName: "{{symbolName}}.use-case", outputDir: "{{srcDir}}/use-cases", schema: s.object({entity: s.string().description("Entity handled by the use case")}), render(symbolName, context) { return `import {Injectable} from "@tsed/di";\n\n@Injectable()\nexport class ${symbolName} {}\n`; } }); ``` 4. Options: `id`, `label`, `outputDir` and `render` are required; `description`, `fileName`, `ext` (default `ts`, `null` for none), `hidden`, `preserveCase`, `preserveDirectory`, `schema`, `prompts`, `hooks`, `type` are optional. `render()` returns the file content, or `undefined` to skip the file. 5. `schema` is what `get-template` returns and what `generate-file` validates `properties` against. Always declare it for templates used by agents. 6. Check for an existing `.templates/` directory before generating: the project may override `controller`, `service`, etc. Depth: `https://cli.tsed.dev/llms.txt`. ## Pitfalls - The CLI docs show `tsed generate service --name Logger` and `tsed generate template`. Both are wrong: the name is the second positional argument, and the command is `tsed template`. - `--features` is variadic: separate values with spaces, and use full values (`doc:swagger`, `orm:prisma`), not `swagger` or `prisma`. - `list-templates` returns every visible template when `search` matches nothing. Check the returned ids instead of assuming a match. - Hidden templates (project files such as `server`, `vitest.config`) are not listed but are accepted by `get-template` and `generate-file`. Do not regenerate them in an existing project. - A `name` equal to `prisma` forces the `prisma.service` template. - With `architecture: "feature"`, the base directory (`controllers`, `services`) is dropped; put the feature folder in the name: `users/User`. - `passportjs` is offered only when the platform is `express`. - Generated code is a starting point. Read the sibling skill for the file type (`tsed-controllers`, `tsed-di`, `tsed-middlewares`, `tsed-models`, `tsed-exceptions`, `tsed-testing`) before filling it in. ## Checklist - `package.json` `tsed` preferences read before any file was created. - Generator used (MCP `generate-file` or `tsed generate`) for every file type that has a template. - Init options confirmed by the user before `init-project` or `tsed init`. - Generated paths taken from the tool output, not assumed. - MCP declaration, if suggested, uses `npx -y -p @tsed/cli tsed mcp`. - No interactive command left waiting for input.