@wolfstar/cli 2.1.0-next-20261001111011 → 2.2.0

package/README.md

@@ -1,304 +1,304 @@
-<div align="center">
-
-# @wolfstar/cli
-
-**The `stars` command line interface for [`@wolfstar/http-framework`](../http-framework) projects.**
-
-[![GitHub](https://img.shields.io/github/license/wolfstar-project/stars-components)](https://github.com/wolfstar-project/stars-components/blob/main/LICENSE)
-[![npm](https://img.shields.io/npm/v/@wolfstar/cli?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/@wolfstar/cli)
-
-</div>
-
-## Description
-
-`stars` is a small, fast CLI that owns the developer workflow of a bot built with `@wolfstar/http-framework`. Like
-Nuxt splits `nuxt.config`/`defineNuxtConfig` (owned by `@nuxt/schema`, which both `nuxt` and the separate `@nuxt/cli`
-package depend on) from `nuxi`, the typed `stars.config.*` schema and loader live in their own package,
-[`@wolfstar/schema`](../schema), which both [`@wolfstar/http-framework`](../http-framework) (re-exported
-as `@wolfstar/http-framework/config`) and this package depend on — this package only consumes it to drive its
-commands. `@wolfstar/http-framework` also depends on this package and exposes it as its own `stars` binary (the way
-`nuxt` exposes `nuxi`'s), so installing it is enough to get `stars` without a separate `@wolfstar/cli` install; this
-package has no install-time dependency on `@wolfstar/http-framework` in return, the same way `@nuxt/cli` has none on
-`nuxt` — its own commands:
-
-- `stars dev` builds the project, starts the bot, restarts it on changes and shows what is happening in an interactive terminal UI (or plain logs).
-- `stars build` runs the configured build tool once.
-- `stars info` prints the resolved configuration and environment (`--json` for scripts).
-- `stars codegen` runs the configured code generators (`--check` for CI).
-- `stars prepare` generates `.stars/tsconfig.json` and the auto imports declaration file (`--check` for CI).
-- `stars commands` inspects and cleans the application commands Discord has deployed.
-
-Everything is driven by a typed `stars.config.ts` file.
-
-## Installation
-
-```sh
-pnpm add -D @wolfstar/cli
-```
-
-Installing [`@wolfstar/http-framework`](../http-framework) already gives a project the `stars` binary, so this
-explicit install is only needed to depend on this package directly — for its programmatic exports (`loadStarsConfig`,
-diagnostics), or to pin its version independently of the framework's.
-
-Projects scaffolded with [`@wolfstar/create-http-framework`](../create-http-framework) come with `@wolfstar/cli`, a `stars.config.ts` file and `dev`/`build` scripts already wired up.
-
-## Configuration
-
-`stars.config.{ts,mts,cts,js,mjs,cjs}` is defined and loaded by [`@wolfstar/http-framework`](../http-framework#project-configuration-starsconfig), not by this package — see its README for the full option reference (`root`, `entry`, `build`, `dev`, `codegen`) and the `defineConfig` helper. `stars` looks for it in the working directory (`--config <file>` overrides it, `--cwd <dir>` changes the working directory) and passes `ConfigError`s from the framework through as exit code `2`, with the offending option path and a hint printed to the terminal.
-
-```ts
-// stars.config.ts
-import { defineConfig } from '@wolfstar/http-framework/config';
-
-export default defineConfig({});
-```
-
-`stars dev`'s URL needs no configuration either — it is detected from `HTTP_PORT` (env var, `src/.env*`/`.env*`, or `dev.env`) or `3000`, the same way Vite's and Nuxt's dev servers do, and `localhost` is swapped for `127.0.0.1` at runtime if that is what is actually reachable. Set `dev.url` only to override it.
-
-The resolved configuration is also available programmatically, exactly as the commands see it (re-exported from this package for convenience, or import it directly from `@wolfstar/http-framework/config`):
-
-```ts
-import { loadStarsConfig } from '@wolfstar/cli';
-
-const config = await loadStarsConfig({ cwd: process.cwd() });
-console.log(config.entry, config.build.output);
-```
-
-## Commands
-
-```sh
-stars dev [--no-tui] [--config <file>] [--cwd <dir>]
-stars build [--config <file>] [--cwd <dir>]
-stars info [--json] [--config <file>] [--cwd <dir>]
-stars codegen [--check] [--json] [--config <file>] [--cwd <dir>]
-stars prepare [--check] [--json] [--config <file>] [--cwd <dir>]
-stars commands [list|clean] [--guild <id>] [--name <name>] [--yes] [--json]
-stars --help | --version
-```
-
-### `stars dev`
-
-Watches the sources through the configured build tool (`tsdown` programmatically, configured from your `stars.config`, `tsc -b --watch`, or a plain file watcher for JavaScript projects), starts the bot after the first successful build and restarts it after every following one. Failed builds keep the previous process running and wait for the next change; a crashed bot waits for the next change or a manual restart.
-
-The bot runs as a child `node` process with `STARS_DEV=1` and `NODE_ENV=development` in its environment. Because `stars dev` already restarts the whole process, leave the framework's own `hmr` option disabled while using it.
-
-**Interactive UI** (default on a TTY): a bottom-aligned panel following the layout and keyboard conventions of
-[Nuxt CLI's dev TUI](https://github.com/nuxt/cli/tree/b4b366eafdd9ac4d5b81b6ae7dadda35364252c9/packages/nuxt-cli/src/dev/tui).
-The normal screen shows a Stars wordmark, aligned URLs, a 20-cell progress bar with elapsed time, status and
-shortcuts. The percentage follows actual build milestones, not a timer: it can stay still while a compiler phase
-runs. Once ready, the bar gives way to diagnostics and the header reports the load time.
-
-Application output (including its banner), build-plugin output and diagnostics stay in the bounded log history and
-`.stars/dev.log`. tsdown's entry list and output-size table are suppressed. Only log/help/info overlays enter the
-alternate screen; closing them restores the panel without duplicating output in scrollback. Error stack frames do
-not count as individual errors. `READY` reports process state unless `dev.health` is configured; it does not certify
-that every application plugin loaded successfully. Logged errors switch the badge to `ERROR`.
-
-| Key            | Action                                                       |
-| -------------- | ------------------------------------------------------------ |
-| `r` / `Ctrl+R` | restart the bot                                              |
-| `o`            | open the local URL in a browser                              |
-| `t`            | toggle a public `cloudflared` tunnel                         |
-| `i`            | show project, versions, URLs, health, types and session info |
-| `T`            | pick a colour theme (see **Themes** below)                   |
-| `l`            | browse logs                                                  |
-| `e`            | select the last error with its surrounding context           |
-| `c` / `Ctrl+L` | clear log history                                            |
-| `h` / `?`      | show keyboard shortcuts                                      |
-| `q` / `Ctrl+D` | quit; confirm with `y` while a build/restart is in flight    |
-| `Ctrl+C`       | quit immediately from any view                               |
-
-In the log view: arrows or `j/k` select, `PgUp/PgDn` move a page, `g/G` go to the beginning/follow the tail,
-`e/w/a` filter errors/warnings/all, `c/b/r` toggle CLI/build/runtime sources, `/` searches, `x` clears, and
-`Enter`/`y` copies the selected line on terminals supporting OSC 52 clipboard writes. `q`, `Esc` or the view's
-own shortcut closes an overlay rather than quitting the session. Nuxt-specific request and page-route inspectors
-are not exposed: the bot supervisor does not receive those runtime events.
-
-Replace the default wordmark in `stars.config.ts` (up to four lines are displayed, clipped to the terminal width):
-
-```ts
-export default defineConfig({
-	dev: { banner: ['★ STARYL', 'Twitch notifications'] }
-});
-```
-
-`dev.banner` also accepts a string containing newlines, or `false` to hide the wordmark. Omit it for Stars branding.
-For the application's standalone banner outside the TUI, use `createStarsBanner` from `@wolfstar/start-banner`.
-
-**Themes.** Press `T` to pick a colour theme, like Claude Code's `/theme`: arrows preview it live, `Enter` keeps and saves
-it, `Esc` restores the previous one. Available themes are `auto` (follows the terminal background through
-`COLORFGBG`, dark when unknown), `dark`, `light`, `dark-daltonized` and `light-daltonized` (blue/orange instead of
-green/red, for colour-blind users), and `dark-ansi` and `light-ansi` (only the 16 ANSI colours, so your terminal
-palette decides). The theme resolves as `--theme <name>` › `STARS_THEME` › the saved choice › `auto`. It is saved in
-`preferences.json` under `$STARS_CONFIG_DIR`, `$XDG_CONFIG_HOME/stars`, `%APPDATA%\stars` or `~/.config/stars`.
-`NO_COLOR` still disables colour altogether.
-
-**Plain mode** prints prefixed lines instead and is selected by `--no-tui`, `STARS_TUI=plain`, redirected input/output,
-CI, `TERM=dumb`, or terminals smaller than 40×10. `STARS_TUI=1` overrides CI/size checks, never redirected streams or
-a dumb terminal. Both modes honour `NO_COLOR`/`FORCE_COLOR`; `STARS_REDUCED_MOTION=1` freezes the logo/spinner but
-keeps the elapsed clock. Both stop the bot cleanly on `SIGINT`/`SIGTERM`. `SIGUSR2` restarts the bot (not on Windows).
-
-### `stars commands`
-
-Lists what Discord currently has deployed, which is not necessarily what the project registers today: renamed and
-removed commands stay until something deletes them.
-
-```sh
-stars commands list                 # global commands
-stars commands list --guild 1234    # a guild's commands
-stars commands clean                # wizard: pick from a checklist, then confirm
-stars commands clean --name ping    # delete one, asking first
-stars commands clean --guild 1234 --yes
-```
-
-It reads `DISCORD_TOKEN` and `DISCORD_APPLICATION_ID` (or `APPLICATION_ID`) from the environment or the project's
-`.env`, the same place the bot reads them from. `clean` deletes deployed commands, so on a terminal it opens a wizard —
-a checklist of what is deployed, then a confirmation — and refuses to run without `--yes` (or `--name`) anywhere
-else.
-
-### Type checking, tunnel and logs
-
-Three `dev` options round out the dev loop (all documented in
-[`@wolfstar/http-framework`](../http-framework#project-configuration-starsconfig)):
-
-- `dev.typecheck: true` runs a type checker next to the bot and reports type errors on the UI's `tsc` channel,
-  without ever blocking a build or a restart — useful when building with `tsdown`, which does not type-check.
-  `dev.typecheck.checker` picks which one: `tsc` (the project's TypeScript, watch mode), `golar` (`golar tsc`, watch
-  mode), `tsz` (the tsc-compatible checker, re-run after every build since it has no watch mode), or `auto` — the
-  default, which uses `golar` when the project depends on it and `tsc` otherwise.
-- Pressing `t` opens and closes a `cloudflared` quick tunnel without configuration. `dev.tunnel: true` opens it at startup so Discord can reach the bot's interactions endpoint from the
-  internet; a string is an https URL you already serve, which the CLI only probes. `dev.tunnel.updateEndpoint` writes
-  the URL to the Discord application, and is opt-in because it edits a live application.
-- `dev.logFile` (default `.stars/dev.log`) mirrors the session's logs to disk, so a run can be read back after the
-  terminal UI is gone. Set it to `false` to disable it.
-
-### The build
-
-`tsdown` is configured from `stars.config`, and a base project configures nothing: the entry's directory, one output
-file per source file, ESM on Node, `build.outDir`, the tsconfig (`src/tsconfig.json` or `tsconfig.json`), the
-extension `build.output` implies, sourcemaps, unbundled dependencies, Nuxt's `~`/`@`/`~~`/`@@` alias prefixes and
-the auto imports plugin, and copying `src/locales` to `dist/locales` are all filled in
-(the [framework README](../http-framework#the-build-tsdown) lists every default). The `tsdown` block is for what they
-cannot know:
-
-Every `@wolfstar/plugin-*` package listed in the project's `dependencies` or `optionalDependencies` is activated
-automatically in bundler builds. `stars` injects its `/register` side-effect entrypoint before the application entry,
-so projects do not need to maintain bare imports such as `import '@wolfstar/plugin-i18next/register'`. Packages used
-only for development are intentionally not activated from `devDependencies`.
-
-```typescript
-export default defineConfig({
-	tsdown: { dts: true }
-});
-```
-
-With `future.compatibilityVersion: 3` (end-of-life) an existing `tsdown.config.*` still drives the build and the block
-is merged over it (values from `stars.config` win, `plugins` are appended); from `4` on the block is the whole
-configuration. The
-`vite` block works the same way for `build.tool: 'vite'`. `stars info` shows which file the build is configured from
-and which options the block sets.
-
-### Compatibility version
-
-`future.compatibilityVersion` selects the legacy or current defaults, the way Nuxt's own compatibility setting does (see the
-[framework README](../http-framework#compatibility-version) for the full reference):
-
-| Version       | What it changes                                                                                                               |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `3` (EOL)     | Legacy behaviour: a `tsdown.config.*` drives the build, auto imports off unless asked for; prints `COMPATIBILITY_VERSION_EOL` |
-| `4`           | `tsdown` configured from `stars.config` alone, auto imports on and wired in, `'auto'` picks `tsdown` for TypeScript           |
-| `5` (default) | Everything in `4`, plus `env` registered automatically when the project depends on `@wolfstar/env-utilities`                  |
-
-### Environment and hooks
-
-`env` mirrors the options of `setup()` from `@wolfstar/env-utilities`: `stars` calls it with them as the first import
-of the built entry, before plugin registrations and the bot's own modules. tsdown, Vite and Nitro builds get it
-through the entry transform; with `build.tool: 'tsc'` or `'none'` only `stars dev` preloads it (`node --import`).
-Nitro leaves it off unless `env` is set explicitly.
-
-```typescript
-export default defineConfig({
-	env: { prefix: 'BOT_' },
-	hooks: {
-		'env:options'(options) {
-			if (process.env.CI) options.path = '.env.ci';
-		},
-		build: { done: (outcome) => void (outcome.ok || console.error(outcome.message)) }
-	}
-});
-```
-
-`hooks` are CLI lifecycle hooks run with [`hookable`](https://github.com/unjs/hookable): `config:resolved`,
-`env:options`, `prepare:before`/`prepare:done`, `builder:created`, `tsdown:options`, `build:before`/`build:done`,
-`dev:start`/`dev:restart`/`dev:close`. They run in the CLI process, never in the bot, in the same order in `stars build` and
-`stars dev` (see the framework README for how `stars dev` awaits them). `stars info` lists the env
-options and the registered hooks. See the [framework README](../http-framework#environment-env) for the full
-reference.
-
-### Experimental flags
-
-`experimental` in `stars.config.*` turns on work that is still landing (see the
-[framework README](../http-framework#experimental-flags) for the full reference):
-
-| Flag                 | What it changes                                                                                                           |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `enableVite`         | Builds through the project's own `vite` (and allows `build.tool: 'vite'`) instead of `tsdown`                             |
-| `enableExternalVite` | The project runs Vite itself; `stars dev` only watches the build output and restarts the bot                              |
-| `enableNitro`        | Builds through [Nitro](https://nitro.build) (itself a Vite plugin) instead of `node:http`, deployable to any Nitro preset |
-
-`stars info` prints which flags are on.
-
-### Exit codes
-
-| Code  | Meaning                                              |
-| ----- | ---------------------------------------------------- |
-| `0`   | success                                              |
-| `1`   | generic error (including `codegen --check` failures) |
-| `2`   | invalid or missing configuration                     |
-| `3`   | build failed                                         |
-| `130` | interrupted with `SIGINT`                            |
-| `143` | terminated with `SIGTERM`/`SIGHUP`                   |
-
-### Generated TypeScript configuration
-
-The generated compiler options combine `@sapphire/ts-config`, `@sapphire/ts-config/extra-strict`, and
-`@sapphire/ts-config/decorators`. The CLI loads these presets and writes their options directly into the file,
-so consumers do not need to install Sapphire. This enables strict checks, explicit overrides, and legacy decorators
-with metadata. Stars targets ES2022, skips dependency declaration checks, and stores incremental build information
-inside `.stars/`. Tsdown and Vite use `ESNext`/`Bundler` with `noEmit`; tsc retains Sapphire's Node16 emit settings.
-Project compiler options can override these defaults.
-
-Bundler builds also follow [Nitro's TypeScript configuration](https://github.com/nitrojs/nitro/blob/main/lib/tsconfig.json):
-forced module detection, isolated modules, verbatim module syntax, JavaScript sources, `.ts` import extensions,
-package.json imports, and ESNext/DOM libraries. Use `import type` and `export type` for type-only dependencies.
-These options apply to tsdown and Vite; tsc keeps its emit-compatible settings. Sapphire's decorator options and
-the ES2022 target remain in effect. This does not enable Stars' experimental Nitro runtime integration.
-
-Run `stars prepare` and extend the generated config from your project's `tsconfig.json`:
-
-```json
-{
-	"extends": "./.stars/tsconfig.json"
-}
-```
-
-New tsdown projects already extend this file and run `stars prepare` through `postinstall`.
-Keep your existing compiler options alongside `extends`. `stars dev` and `stars build` also regenerate this file.
-For tsdown builds, `@/` and `~/` resolve to the entry file's directory (normally `src/`), while `@@/` and `~~/`
-resolve to the project root. Filesystem aliases in `stars.config.ts`'s `tsdown.alias` are included too, with custom
-values taking precedence. Legacy builds using a separate tsdown config only include aliases declared in
-`stars.config.ts`. Other build tools do not get tsdown aliases, since TypeScript alone does not rewrite imports.
-
-The generated config includes source files and the auto imports declaration, including a custom `imports.dts`
-location. Explicit `include` or `compilerOptions.paths` in your own tsconfig replace the inherited values;
-remove manually duplicated paths to use the generated aliases. Generation works with `imports: false` too.
-Use `stars prepare --check` to check both generated files without writing them. Do not edit `.stars/tsconfig.json`
-by hand; keep `.stars/` ignored by Git and run `stars prepare` after installing dependencies on a fresh checkout.
-
-## Server integrations
-
-`@wolfstar/vite-server` and `@wolfstar/nitro-server` provide the Vite and Nitro builders. The CLI loads the
-selected integration lazily, passes the resolved `stars.config` and supplies project dependency loading and
-plugin registration through `BuilderContext` from `@wolfstar/schema`. Neither server package depends on the CLI
-or framework. Existing experimental flags, presets, output directories and `stars dev`/`stars build` commands
-are unchanged; install Vite/Nitro in the consuming project as before.
+<div align="center">
+
+# @wolfstar/cli
+
+**The `stars` command line interface for [`@wolfstar/http-framework`](../http-framework) projects.**
+
+[![GitHub](https://img.shields.io/github/license/wolfstar-project/stars-components)](https://github.com/wolfstar-project/stars-components/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/@wolfstar/cli?color=crimson&logo=npm&style=flat-square)](https://www.npmjs.com/package/@wolfstar/cli)
+
+</div>
+
+## Description
+
+`stars` is a small, fast CLI that owns the developer workflow of a bot built with `@wolfstar/http-framework`. Like
+Nuxt splits `nuxt.config`/`defineNuxtConfig` (owned by `@nuxt/schema`, which both `nuxt` and the separate `@nuxt/cli`
+package depend on) from `nuxi`, the typed `stars.config.*` schema and loader live in their own package,
+[`@wolfstar/schema`](../schema), which both [`@wolfstar/http-framework`](../http-framework) (re-exported
+as `@wolfstar/http-framework/config`) and this package depend on — this package only consumes it to drive its
+commands. `@wolfstar/http-framework` also depends on this package and exposes it as its own `stars` binary (the way
+`nuxt` exposes `nuxi`'s), so installing it is enough to get `stars` without a separate `@wolfstar/cli` install; this
+package has no install-time dependency on `@wolfstar/http-framework` in return, the same way `@nuxt/cli` has none on
+`nuxt` — its own commands:
+
+- `stars dev` builds the project, starts the bot, restarts it on changes and shows what is happening in an interactive terminal UI (or plain logs).
+- `stars build` runs the configured build tool once.
+- `stars info` prints the resolved configuration and environment (`--json` for scripts).
+- `stars codegen` runs the configured code generators (`--check` for CI).
+- `stars prepare` generates `.stars/tsconfig.json` and the auto imports declaration file (`--check` for CI).
+- `stars commands` inspects and cleans the application commands Discord has deployed.
+
+Everything is driven by a typed `stars.config.ts` file.
+
+## Installation
+
+```sh
+pnpm add -D @wolfstar/cli
+```
+
+Installing [`@wolfstar/http-framework`](../http-framework) already gives a project the `stars` binary, so this
+explicit install is only needed to depend on this package directly — for its programmatic exports (`loadStarsConfig`,
+diagnostics), or to pin its version independently of the framework's.
+
+Projects scaffolded with [`@wolfstar/create-http-framework`](../create-http-framework) come with `@wolfstar/cli`, a `stars.config.ts` file and `dev`/`build` scripts already wired up.
+
+## Configuration
+
+`stars.config.{ts,mts,cts,js,mjs,cjs}` is defined and loaded by [`@wolfstar/http-framework`](../http-framework#project-configuration-starsconfig), not by this package — see its README for the full option reference (`root`, `entry`, `build`, `dev`, `codegen`) and the `defineConfig` helper. `stars` looks for it in the working directory (`--config <file>` overrides it, `--cwd <dir>` changes the working directory) and passes `ConfigError`s from the framework through as exit code `2`, with the offending option path and a hint printed to the terminal.
+
+```ts
+// stars.config.ts
+import { defineConfig } from '@wolfstar/http-framework/config';
+
+export default defineConfig({});
+```
+
+`stars dev`'s URL needs no configuration either — it is detected from `HTTP_PORT` (env var, `src/.env*`/`.env*`, or `dev.env`) or `3000`, the same way Vite's and Nuxt's dev servers do, and `localhost` is swapped for `127.0.0.1` at runtime if that is what is actually reachable. Set `dev.url` only to override it.
+
+The resolved configuration is also available programmatically, exactly as the commands see it (re-exported from this package for convenience, or import it directly from `@wolfstar/http-framework/config`):
+
+```ts
+import { loadStarsConfig } from '@wolfstar/cli';
+
+const config = await loadStarsConfig({ cwd: process.cwd() });
+console.log(config.entry, config.build.output);
+```
+
+## Commands
+
+```sh
+stars dev [--no-tui] [--config <file>] [--cwd <dir>]
+stars build [--config <file>] [--cwd <dir>]
+stars info [--json] [--config <file>] [--cwd <dir>]
+stars codegen [--check] [--json] [--config <file>] [--cwd <dir>]
+stars prepare [--check] [--json] [--config <file>] [--cwd <dir>]
+stars commands [list|clean] [--guild <id>] [--name <name>] [--yes] [--json]
+stars --help | --version
+```
+
+### `stars dev`
+
+Watches the sources through the configured build tool (`tsdown` programmatically, configured from your `stars.config`, `tsc -b --watch`, or a plain file watcher for JavaScript projects), starts the bot after the first successful build and restarts it after every following one. Failed builds keep the previous process running and wait for the next change; a crashed bot waits for the next change or a manual restart.
+
+The bot runs as a child `node` process with `STARS_DEV=1` and `NODE_ENV=development` in its environment. Because `stars dev` already restarts the whole process, leave the framework's own `hmr` option disabled while using it.
+
+**Interactive UI** (default on a TTY): a bottom-aligned panel following the layout and keyboard conventions of
+[Nuxt CLI's dev TUI](https://github.com/nuxt/cli/tree/b4b366eafdd9ac4d5b81b6ae7dadda35364252c9/packages/nuxt-cli/src/dev/tui).
+The normal screen shows a Stars wordmark, aligned URLs, a 20-cell progress bar with elapsed time, status and
+shortcuts. The percentage follows actual build milestones, not a timer: it can stay still while a compiler phase
+runs. Once ready, the bar gives way to diagnostics and the header reports the load time.
+
+Application output (including its banner), build-plugin output and diagnostics stay in the bounded log history and
+`.stars/dev.log`. tsdown's entry list and output-size table are suppressed. Only log/help/info overlays enter the
+alternate screen; closing them restores the panel without duplicating output in scrollback. Error stack frames do
+not count as individual errors. `READY` reports process state unless `dev.health` is configured; it does not certify
+that every application plugin loaded successfully. Logged errors switch the badge to `ERROR`.
+
+| Key            | Action                                                       |
+| -------------- | ------------------------------------------------------------ |
+| `r` / `Ctrl+R` | restart the bot                                              |
+| `o`            | open the local URL in a browser                              |
+| `t`            | toggle a public `cloudflared` tunnel                         |
+| `i`            | show project, versions, URLs, health, types and session info |
+| `T`            | pick a colour theme (see **Themes** below)                   |
+| `l`            | browse logs                                                  |
+| `e`            | select the last error with its surrounding context           |
+| `c` / `Ctrl+L` | clear log history                                            |
+| `h` / `?`      | show keyboard shortcuts                                      |
+| `q` / `Ctrl+D` | quit; confirm with `y` while a build/restart is in flight    |
+| `Ctrl+C`       | quit immediately from any view                               |
+
+In the log view: arrows or `j/k` select, `PgUp/PgDn` move a page, `g/G` go to the beginning/follow the tail,
+`e/w/a` filter errors/warnings/all, `c/b/r` toggle CLI/build/runtime sources, `/` searches, `x` clears, and
+`Enter`/`y` copies the selected line on terminals supporting OSC 52 clipboard writes. `q`, `Esc` or the view's
+own shortcut closes an overlay rather than quitting the session. Nuxt-specific request and page-route inspectors
+are not exposed: the bot supervisor does not receive those runtime events.
+
+Replace the default wordmark in `stars.config.ts` (up to four lines are displayed, clipped to the terminal width):
+
+```ts
+export default defineConfig({
+	dev: { banner: ['★ STARYL', 'Twitch notifications'] }
+});
+```
+
+`dev.banner` also accepts a string containing newlines, or `false` to hide the wordmark. Omit it for Stars branding.
+For the application's standalone banner outside the TUI, use `createStarsBanner` from `@wolfstar/start-banner`.
+
+**Themes.** Press `T` to pick a colour theme, like Claude Code's `/theme`: arrows preview it live, `Enter` keeps and saves
+it, `Esc` restores the previous one. Available themes are `auto` (follows the terminal background through
+`COLORFGBG`, dark when unknown), `dark`, `light`, `dark-daltonized` and `light-daltonized` (blue/orange instead of
+green/red, for colour-blind users), and `dark-ansi` and `light-ansi` (only the 16 ANSI colours, so your terminal
+palette decides). The theme resolves as `--theme <name>` › `STARS_THEME` › the saved choice › `auto`. It is saved in
+`preferences.json` under `$STARS_CONFIG_DIR`, `$XDG_CONFIG_HOME/stars`, `%APPDATA%\stars` or `~/.config/stars`.
+`NO_COLOR` still disables colour altogether.
+
+**Plain mode** prints prefixed lines instead and is selected by `--no-tui`, `STARS_TUI=plain`, redirected input/output,
+CI, `TERM=dumb`, or terminals smaller than 40×10. `STARS_TUI=1` overrides CI/size checks, never redirected streams or
+a dumb terminal. Both modes honour `NO_COLOR`/`FORCE_COLOR`; `STARS_REDUCED_MOTION=1` freezes the logo/spinner but
+keeps the elapsed clock. Both stop the bot cleanly on `SIGINT`/`SIGTERM`. `SIGUSR2` restarts the bot (not on Windows).
+
+### `stars commands`
+
+Lists what Discord currently has deployed, which is not necessarily what the project registers today: renamed and
+removed commands stay until something deletes them.
+
+```sh
+stars commands list                 # global commands
+stars commands list --guild 1234    # a guild's commands
+stars commands clean                # wizard: pick from a checklist, then confirm
+stars commands clean --name ping    # delete one, asking first
+stars commands clean --guild 1234 --yes
+```
+
+It reads `DISCORD_TOKEN` and `DISCORD_APPLICATION_ID` (or `APPLICATION_ID`) from the environment or the project's
+`.env`, the same place the bot reads them from. `clean` deletes deployed commands, so on a terminal it opens a wizard —
+a checklist of what is deployed, then a confirmation — and refuses to run without `--yes` (or `--name`) anywhere
+else.
+
+### Type checking, tunnel and logs
+
+Three `dev` options round out the dev loop (all documented in
+[`@wolfstar/http-framework`](../http-framework#project-configuration-starsconfig)):
+
+- `dev.typecheck: true` runs a type checker next to the bot and reports type errors on the UI's `tsc` channel,
+  without ever blocking a build or a restart — useful when building with `tsdown`, which does not type-check.
+  `dev.typecheck.checker` picks which one: `tsc` (the project's TypeScript, watch mode), `golar` (`golar tsc`, watch
+  mode), `tsz` (the tsc-compatible checker, re-run after every build since it has no watch mode), or `auto` — the
+  default, which uses `golar` when the project depends on it and `tsc` otherwise.
+- Pressing `t` opens and closes a `cloudflared` quick tunnel without configuration. `dev.tunnel: true` opens it at startup so Discord can reach the bot's interactions endpoint from the
+  internet; a string is an https URL you already serve, which the CLI only probes. `dev.tunnel.updateEndpoint` writes
+  the URL to the Discord application, and is opt-in because it edits a live application.
+- `dev.logFile` (default `.stars/dev.log`) mirrors the session's logs to disk, so a run can be read back after the
+  terminal UI is gone. Set it to `false` to disable it.
+
+### The build
+
+`tsdown` is configured from `stars.config`, and a base project configures nothing: the entry's directory, one output
+file per source file, ESM on Node, `build.outDir`, the tsconfig (`src/tsconfig.json` or `tsconfig.json`), the
+extension `build.output` implies, sourcemaps, unbundled dependencies, Nuxt's `~`/`@`/`~~`/`@@` alias prefixes and
+the auto imports plugin, and copying `src/locales` to `dist/locales` are all filled in
+(the [framework README](../http-framework#the-build-tsdown) lists every default). The `tsdown` block is for what they
+cannot know:
+
+Every `@wolfstar/plugin-*` package listed in the project's `dependencies` or `optionalDependencies` is activated
+automatically in bundler builds. `stars` injects its `/register` side-effect entrypoint before the application entry,
+so projects do not need to maintain bare imports such as `import '@wolfstar/plugin-i18next/register'`. Packages used
+only for development are intentionally not activated from `devDependencies`.
+
+```typescript
+export default defineConfig({
+	tsdown: { dts: true }
+});
+```
+
+With `future.compatibilityVersion: 3` (end-of-life) an existing `tsdown.config.*` still drives the build and the block
+is merged over it (values from `stars.config` win, `plugins` are appended); from `4` on the block is the whole
+configuration. The
+`vite` block works the same way for `build.tool: 'vite'`. `stars info` shows which file the build is configured from
+and which options the block sets.
+
+### Compatibility version
+
+`future.compatibilityVersion` selects the legacy or current defaults, the way Nuxt's own compatibility setting does (see the
+[framework README](../http-framework#compatibility-version) for the full reference):
+
+| Version       | What it changes                                                                                                               |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `3` (EOL)     | Legacy behaviour: a `tsdown.config.*` drives the build, auto imports off unless asked for; prints `COMPATIBILITY_VERSION_EOL` |
+| `4`           | `tsdown` configured from `stars.config` alone, auto imports on and wired in, `'auto'` picks `tsdown` for TypeScript           |
+| `5` (default) | Everything in `4`, plus `env` registered automatically when the project depends on `@wolfstar/env-utilities`                  |
+
+### Environment and hooks
+
+`env` mirrors the options of `setup()` from `@wolfstar/env-utilities`: `stars` calls it with them as the first import
+of the built entry, before plugin registrations and the bot's own modules. tsdown, Vite and Nitro builds get it
+through the entry transform; with `build.tool: 'tsc'` or `'none'` only `stars dev` preloads it (`node --import`).
+Nitro leaves it off unless `env` is set explicitly.
+
+```typescript
+export default defineConfig({
+	env: { prefix: 'BOT_' },
+	hooks: {
+		'env:options'(options) {
+			if (process.env.CI) options.path = '.env.ci';
+		},
+		build: { done: (outcome) => void (outcome.ok || console.error(outcome.message)) }
+	}
+});
+```
+
+`hooks` are CLI lifecycle hooks run with [`hookable`](https://github.com/unjs/hookable): `config:resolved`,
+`env:options`, `prepare:before`/`prepare:done`, `builder:created`, `tsdown:options`, `build:before`/`build:done`,
+`dev:start`/`dev:restart`/`dev:close`. They run in the CLI process, never in the bot, in the same order in `stars build` and
+`stars dev` (see the framework README for how `stars dev` awaits them). `stars info` lists the env
+options and the registered hooks. See the [framework README](../http-framework#environment-env) for the full
+reference.
+
+### Experimental flags
+
+`experimental` in `stars.config.*` turns on work that is still landing (see the
+[framework README](../http-framework#experimental-flags) for the full reference):
+
+| Flag                 | What it changes                                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `enableVite`         | Builds through the project's own `vite` (and allows `build.tool: 'vite'`) instead of `tsdown`                             |
+| `enableExternalVite` | The project runs Vite itself; `stars dev` only watches the build output and restarts the bot                              |
+| `enableNitro`        | Builds through [Nitro](https://nitro.build) (itself a Vite plugin) instead of `node:http`, deployable to any Nitro preset |
+
+`stars info` prints which flags are on.
+
+### Exit codes
+
+| Code  | Meaning                                              |
+| ----- | ---------------------------------------------------- |
+| `0`   | success                                              |
+| `1`   | generic error (including `codegen --check` failures) |
+| `2`   | invalid or missing configuration                     |
+| `3`   | build failed                                         |
+| `130` | interrupted with `SIGINT`                            |
+| `143` | terminated with `SIGTERM`/`SIGHUP`                   |
+
+### Generated TypeScript configuration
+
+The generated compiler options combine `@sapphire/ts-config`, `@sapphire/ts-config/extra-strict`, and
+`@sapphire/ts-config/decorators`. The CLI loads these presets and writes their options directly into the file,
+so consumers do not need to install Sapphire. This enables strict checks, explicit overrides, and legacy decorators
+with metadata. Stars targets ES2022, skips dependency declaration checks, and stores incremental build information
+inside `.stars/`. Tsdown and Vite use `ESNext`/`Bundler` with `noEmit`; tsc retains Sapphire's Node16 emit settings.
+Project compiler options can override these defaults.
+
+Bundler builds also follow [Nitro's TypeScript configuration](https://github.com/nitrojs/nitro/blob/main/lib/tsconfig.json):
+forced module detection, isolated modules, verbatim module syntax, JavaScript sources, `.ts` import extensions,
+package.json imports, and ESNext/DOM libraries. Use `import type` and `export type` for type-only dependencies.
+These options apply to tsdown and Vite; tsc keeps its emit-compatible settings. Sapphire's decorator options and
+the ES2022 target remain in effect. This does not enable Stars' experimental Nitro runtime integration.
+
+Run `stars prepare` and extend the generated config from your project's `tsconfig.json`:
+
+```json
+{
+	"extends": "./.stars/tsconfig.json"
+}
+```
+
+New tsdown projects already extend this file and run `stars prepare` through `postinstall`.
+Keep your existing compiler options alongside `extends`. `stars dev` and `stars build` also regenerate this file.
+For tsdown builds, `@/` and `~/` resolve to the entry file's directory (normally `src/`), while `@@/` and `~~/`
+resolve to the project root. Filesystem aliases in `stars.config.ts`'s `tsdown.alias` are included too, with custom
+values taking precedence. Legacy builds using a separate tsdown config only include aliases declared in
+`stars.config.ts`. Other build tools do not get tsdown aliases, since TypeScript alone does not rewrite imports.
+
+The generated config includes source files and the auto imports declaration, including a custom `imports.dts`
+location. Explicit `include` or `compilerOptions.paths` in your own tsconfig replace the inherited values;
+remove manually duplicated paths to use the generated aliases. Generation works with `imports: false` too.
+Use `stars prepare --check` to check both generated files without writing them. Do not edit `.stars/tsconfig.json`
+by hand; keep `.stars/` ignored by Git and run `stars prepare` after installing dependencies on a fresh checkout.
+
+## Server integrations
+
+`@wolfstar/vite-server` and `@wolfstar/nitro-server` provide the Vite and Nitro builders. The CLI loads the
+selected integration lazily, passes the resolved `stars.config` and supplies project dependency loading and
+plugin registration through `BuilderContext` from `@wolfstar/schema`. Neither server package depends on the CLI
+or framework. Existing experimental flags, presets, output directories and `stars dev`/`stars build` commands
+are unchanged; install Vite/Nitro in the consuming project as before.