@moostjs/event-cli 0.5.33 → 0.6.0

package/skills/moostjs-event-cli/advanced.md

@@ -0,0 +1,202 @@
+# Advanced — @moostjs/event-cli
+
+> Manual adapter setup, Wooks composables, DI scopes, multi-adapter patterns, and cliKind.
+
+## Concepts
+
+`CliApp` handles the common case. For advanced scenarios — sharing a Moost instance across adapters, using Wooks composables directly, or fine-tuning DI — use `MoostCli` as a standalone adapter.
+
+Wooks composables are functions that access the current CLI event context (via AsyncLocalStorage). They work anywhere in the handler call chain — in handlers, services, or interceptors.
+
+## API Reference
+
+### `MoostCli`
+
+Low-level CLI adapter class implementing `TMoostAdapter<TCliHandlerMeta>`.
+
+Constructor options (`TMoostCliOpts`):
+- `wooksCli?: WooksCli | TWooksCliOptions` — a WooksCli instance or configuration options
+- `debug?: boolean` — enable internal logging (default: `false`)
+- `globalCliOptions?: { keys: string[]; description?: string; type?: TFunction }[]` — options shown in help for every command
+
+```ts
+import { MoostCli, cliHelpInterceptor } from '@moostjs/event-cli'
+import { Moost } from 'moost'
+
+const app = new Moost()
+
+app.applyGlobalInterceptors(
+  cliHelpInterceptor({ colors: true, lookupLevel: 3 }),
+)
+
+app.registerControllers(AppController)
+
+app.adapter(new MoostCli({
+  wooksCli: {
+    cliHelp: { name: 'my-cli' },
+  },
+  globalCliOptions: [
+    { keys: ['help'], description: 'Display instructions for the command.' },
+  ],
+}))
+
+void app.init()
+```
+
+### When to use MoostCli vs CliApp
+
+| Use case | Recommendation |
+|----------|---------------|
+| Standard CLI app | `CliApp` — less boilerplate |
+| Pre-configured WooksCli instance | `MoostCli` — pass your own instance |
+| Multiple adapters (CLI + HTTP) | `MoostCli` — attach to existing Moost instance |
+| Custom error handling on WooksCli | `MoostCli` — configure `wooksCli.onError` |
+
+### `cliKind`
+
+Event type identifier for CLI events, re-exported from `@wooksjs/event-cli`. Useful when writing adapters or composables that distinguish event types.
+
+```ts
+import { cliKind } from '@moostjs/event-cli'
+```
+
+## Wooks composables
+
+These are from `@wooksjs/event-cli` and `@wooksjs/event-core`. They work inside any handler or service during a CLI event.
+
+### `useCliOption(name: string)`
+
+Read a single option value. This is what `@CliOption()` uses under the hood.
+
+```ts
+import { useCliOption } from '@wooksjs/event-cli'
+
+@Cli('build')
+build() {
+  const verbose = useCliOption('verbose')
+  if (verbose) console.log('Verbose mode on')
+  return 'Building...'
+}
+```
+
+### `useCliOptions()`
+
+Read all parsed CLI options at once.
+
+```ts
+import { useCliOptions } from '@wooksjs/event-cli'
+
+@Cli('build')
+build() {
+  const opts = useCliOptions()
+  // opts: { verbose: true, target: 'production', ... }
+  return `Building with ${JSON.stringify(opts)}`
+}
+```
+
+### `useRouteParams()`
+
+Read positional arguments. This is what `@Param()` uses under the hood.
+
+```ts
+import { useRouteParams } from '@wooksjs/event-core'
+
+@Cli('deploy/:env')
+deploy() {
+  const params = useRouteParams()
+  return `Deploying to ${params.get('env')}`
+}
+```
+
+### `useCliHelp()`
+
+Access the help renderer programmatically.
+
+```ts
+import { useCliHelp } from '@wooksjs/event-cli'
+
+@Cli('info')
+info() {
+  const { print } = useCliHelp()
+  print(true) // print help with colors
+}
+```
+
+## Common Patterns
+
+### Pattern: Multi-adapter CLI + HTTP
+
+A single Moost instance serving both CLI commands and HTTP routes:
+
+```ts
+import { Cli, Controller, Param } from '@moostjs/event-cli'
+import { Get } from '@moostjs/event-http'
+
+@Controller('health')
+export class HealthController {
+  @Cli('check')
+  @Get('check')
+  check() {
+    return { status: 'ok', uptime: process.uptime() }
+  }
+}
+```
+
+Wire up both adapters:
+
+```ts
+import { MoostCli } from '@moostjs/event-cli'
+import { MoostHttp } from '@moostjs/event-http'
+import { Moost } from 'moost'
+
+const app = new Moost()
+app.registerControllers(HealthController)
+
+app.adapter(new MoostCli())
+app.adapter(new MoostHttp()).listen(3000)
+
+void app.init()
+```
+
+Now `my-cli health check` and `GET /health/check` both invoke the same handler.
+
+### Pattern: DI scopes in CLI
+
+```ts
+import { Injectable } from 'moost'
+
+@Injectable('SINGLETON')
+export class ConfigService {
+  readonly env = process.env.NODE_ENV ?? 'development'
+}
+
+@Injectable('FOR_EVENT')
+export class CommandState {
+  startedAt = Date.now()
+}
+```
+
+- `SINGLETON` — one instance for the app lifetime (shared config, DB connections)
+- `FOR_EVENT` — new instance per CLI command execution (command-specific state)
+
+Controllers default to `SINGLETON` scope, which is correct for most CLI apps.
+
+## Integration
+
+- Wooks composables (`useCliOption`, `useCliOptions`, etc.) are imported from `@wooksjs/event-cli`
+- Route param composables (`useRouteParams`) come from `@wooksjs/event-core`
+- DI decorators (`@Injectable`, `@Inject`, `@Provide`) come from `moost`
+- HTTP decorators (`@Get`, `@Post`, etc.) come from `@moostjs/event-http`
+
+## Best Practices
+
+- Use `MoostCli` only when `CliApp` isn't flexible enough
+- When `debug` is `false` (default), DI container logging is suppressed for clean terminal output
+- In multi-adapter setups, decorate shared methods with both `@Cli()` and `@Get()`/`@Post()`
+- Composables work in interceptors and services too — not just handlers
+
+## Gotchas
+
+- `MoostCli` calls `app.init()` — don't call `init()` yourself after attaching the adapter in `CliApp.start()`
+- Wooks composables only work inside an active event context (during handler execution)
+- When using a custom `WooksCli` instance with `MoostCli`, the `onNotFound` callback is overridden by the adapter

package/skills/moostjs-event-cli/commands.md

@@ -0,0 +1,152 @@
+# Commands — @moostjs/event-cli
+
+> Defining CLI commands, command paths, positional arguments, aliases, and examples.
+
+## Concepts
+
+Every CLI command is a method decorated with `@Cli()`. The decorator argument defines the command path — the words a user types to invoke it. Command paths support positional arguments (`:param` segments), space or slash separation, and escaped colons.
+
+## API Reference
+
+### `@Cli(path?: string)`
+
+Method decorator. Registers the method as a CLI command handler.
+
+- `path` — command path with segments separated by spaces or `/`. Segments starting with `:` are positional arguments. If omitted, the method name is used as the command.
+
+```ts
+import { Cli, Controller } from '@moostjs/event-cli'
+
+@Controller()
+export class AppController {
+  @Cli('deploy/:env')
+  deploy(@Param('env') env: string) {
+    return `Deploying to ${env}...`
+  }
+}
+```
+
+### `@CliAlias(alias: string)`
+
+Method decorator. Defines an alternative name for a command. Stack multiple decorators for multiple aliases.
+
+```ts
+import { Cli, CliAlias, Controller, Param } from '@moostjs/event-cli'
+
+@Controller()
+export class AppController {
+  @Cli('install/:package')
+  @CliAlias('i/:package')
+  @CliAlias('add/:package')
+  install(@Param('package') pkg: string) {
+    return `Installing ${pkg}...`
+  }
+}
+```
+
+All three invoke the same handler:
+```bash
+my-cli install lodash
+my-cli i lodash
+my-cli add lodash
+```
+
+### `@CliExample(cmd: string, description?: string)`
+
+Method decorator. Adds a usage example displayed in `--help` output. Stack multiple decorators for multiple examples.
+
+```ts
+import { Cli, CliExample, Controller } from '@moostjs/event-cli'
+
+@Controller()
+export class DeployController {
+  @Cli('deploy/:env')
+  @CliExample('deploy dev -p my-app', 'Deploy to development')
+  @CliExample('deploy prod --verbose', 'Deploy with verbose logging')
+  deploy(@Param('env') env: string) {
+    return `Deploying to ${env}`
+  }
+}
+```
+
+### `@Param(name: string)`
+
+Parameter decorator (re-exported from `moost`). Extracts a positional argument from a `:name` segment in the command path.
+
+```ts
+@Cli('copy/:source/:dest')
+copy(
+  @Param('source') source: string,
+  @Param('dest') dest: string,
+) {
+  return `Copying ${source} to ${dest}`
+}
+```
+
+```bash
+my-cli copy fileA.txt fileB.txt
+```
+
+## Common Patterns
+
+### Pattern: Space-separated vs slash-separated paths
+
+Both notations are equivalent. The user always types space-separated words:
+
+```ts
+// These are identical:
+@Cli('config set')
+@Cli('config/set')
+```
+
+```bash
+my-cli config set
+```
+
+### Pattern: Default path from method name
+
+When `@Cli()` is called without arguments, the method name becomes the command:
+
+```ts
+@Cli()
+status() {
+  return 'All systems operational'
+}
+```
+
+```bash
+my-cli status
+```
+
+### Pattern: Escaped colons
+
+If a command contains a literal colon (like `build:dev`), escape it:
+
+```ts
+@Cli('build\\:dev')
+buildDev() {
+  return 'Building for dev...'
+}
+```
+
+```bash
+my-cli build:dev
+```
+
+### Pattern: Return values
+
+Whatever a handler returns is printed to stdout. Return a string for plain text, or an object/array for JSON:
+
+```ts
+@Cli('info')
+info() {
+  return { name: 'my-app', version: '1.0.0' }
+}
+```
+
+## Gotchas
+
+- Command paths with `:` that are NOT parameters must be escaped with `\\:` (e.g. `'build\\:dev'`)
+- Space-separated and slash-separated paths are equivalent internally — `'config set'` becomes `'config/set'`
+- If you omit the path in `@Cli()`, the method name is used as the command name
+- Multiple `@Cli()` decorators on the same method register multiple commands pointing to the same handler

package/skills/moostjs-event-cli/controllers.md

@@ -0,0 +1,142 @@
+# Controllers — @moostjs/event-cli
+
+> Organizing commands into logical groups with prefixes and nesting.
+
+## Concepts
+
+Controllers group related commands under a shared prefix, creating natural command hierarchies like `git remote add` or `docker compose up`. A controller is a class with `@Controller(prefix?)`. The prefix is prepended to all command paths inside it.
+
+Controllers can be nested via `@ImportController()` — the child's prefix appends to the parent's, building multi-level command trees.
+
+## API Reference
+
+### `@Controller(prefix?: string)`
+
+Class decorator (re-exported from `moost`). Marks a class as a CLI controller. The optional `prefix` sets a command prefix for all methods inside.
+
+```ts
+import { Cli, Controller, Param } from '@moostjs/event-cli'
+
+@Controller('user')
+export class UserController {
+  @Cli('create/:name')
+  create(@Param('name') name: string) {
+    return `Created user: ${name}`
+  }
+
+  @Cli('delete/:name')
+  delete(@Param('name') name: string) {
+    return `Deleted user: ${name}`
+  }
+}
+```
+
+```bash
+my-cli user create Alice
+my-cli user delete Bob
+```
+
+Without a prefix (`@Controller()`), commands are registered at the root level.
+
+### `@ImportController(ctrl: Function)`
+
+Class decorator (from `moost`). Nests a child controller inside the parent. The child's prefix appends to the parent's. Register only the top-level controller — imported children are registered automatically.
+
+```ts
+import { Cli, Controller, Param } from '@moostjs/event-cli'
+import { ImportController } from 'moost'
+
+@Controller('view')
+export class ViewCommand {
+  @Cli(':id')
+  view(@Param('id') id: string) {
+    return `Viewing profile ${id}`
+  }
+}
+
+@Controller('profile')
+@ImportController(ViewCommand)
+export class ProfileController {
+  @Cli('list')
+  list() {
+    return 'Listing profiles...'
+  }
+}
+```
+
+```bash
+my-cli profile list          # ProfileController.list()
+my-cli profile view 42       # ViewCommand.view("42")
+```
+
+## Common Patterns
+
+### Pattern: Registering controllers
+
+With `CliApp`:
+```ts
+new CliApp()
+  .controllers(UserController, ConfigController)
+  .useHelp({ name: 'my-cli' })
+  .start()
+```
+
+With standard Moost:
+```ts
+const app = new Moost()
+app.registerControllers(UserController, ConfigController)
+```
+
+### Pattern: Multi-level nesting
+
+```ts
+@Controller('add')
+class RemoteAddController {
+  @Cli(':name/:url')
+  add(@Param('name') name: string, @Param('url') url: string) {
+    return `Adding remote ${name} -> ${url}`
+  }
+}
+
+@Controller('remote')
+@ImportController(RemoteAddController)
+class RemoteController {
+  @Cli('list')
+  list() { return 'Listing remotes...' }
+}
+
+@Controller()
+@ImportController(RemoteController)
+class GitController {
+  @Cli('status')
+  status() { return 'On branch main' }
+}
+```
+
+```bash
+my-cli status                        # GitController
+my-cli remote list                   # RemoteController
+my-cli remote add origin git@...     # RemoteAddController
+```
+
+## Path composition
+
+The final command path is: **controller prefix** + **child prefix** + **@Cli() path**.
+
+| Parent prefix | Child prefix | `@Cli()` path | Final command |
+|--------------|-------------|---------------|---------------|
+| `''` (root) | — | `status` | `status` |
+| `remote` | — | `list` | `remote list` |
+| `remote` | `add` | `:name/:url` | `remote add :name :url` |
+
+## Best Practices
+
+- Use `@Controller(prefix)` to create command namespaces — `user`, `config`, `remote`
+- Only register top-level controllers with `.controllers()` — nested children auto-register
+- Keep nesting to 2-3 levels max for usability
+- Use `@Controller()` (no prefix) for root-level commands
+
+## Gotchas
+
+- Registering a child controller directly AND via `@ImportController` can cause duplicate command registrations
+- The controller prefix uses the same space/slash equivalence as command paths

package/skills/moostjs-event-cli/core.md

@@ -0,0 +1,114 @@
+# Core concepts & setup — @moostjs/event-cli
+
+> Installation, project scaffolding, and the mental model for building CLI apps with Moost.
+
+## Concepts
+
+`@moostjs/event-cli` is a Moost adapter that turns decorated TypeScript classes into CLI applications. It wraps `@wooksjs/event-cli` (the Wooks CLI engine) and integrates with Moost's decorator-driven DI, interceptors, and pipes.
+
+The core mental model:
+- **Commands** are methods decorated with `@Cli('path')` inside controller classes
+- **Controllers** group commands under shared prefixes (like `git remote add`)
+- **Options** are method parameters decorated with `@CliOption('flag')`
+- **Arguments** are extracted from `:param` segments in command paths via `@Param('name')`
+- **CliApp** is a convenience class that wires everything together with one fluent API
+
+## Installation
+
+```bash
+npm install @moostjs/event-cli moost @wooksjs/event-core wooks
+# or
+pnpm add @moostjs/event-cli moost @wooksjs/event-core wooks
+```
+
+Peer dependencies: `moost`, `@wooksjs/event-core`, `wooks`.
+
+## Project scaffolding
+
+```bash
+npm create moost -- --cli
+# or with a name:
+npm create moost my-cli -- --cli
+```
+
+Creates:
+```
+my-cli/
+├── src/
+│   ├── controllers/
+│   │   └── app.controller.ts
+│   ├── main.ts
+│   └── bin.ts
+├── package.json
+└── tsconfig.json
+```
+
+## CliApp — quick setup
+
+`CliApp` extends `Moost` and provides a fluent API for the common case:
+
+```ts
+import { CliApp } from '@moostjs/event-cli'
+import { AppController } from './controllers/app.controller'
+
+new CliApp()
+  .controllers(AppController)       // register controller classes
+  .useHelp({ name: 'my-cli' })     // enable --help with app name
+  .useOptions([                     // global options shown in all commands
+    { keys: ['help'], description: 'Display instructions for the command.' },
+  ])
+  .start()                          // wire adapters + interceptors, call init()
+```
+
+### `CliApp` methods
+
+| Method | Description |
+|--------|-------------|
+| `.controllers(...ctrls)` | Register one or more controller classes (shortcut for `registerControllers`) |
+| `.useHelp(opts)` | Configure the help system (name, title, colors, lookupLevel, maxWidth, maxLeft, mark) |
+| `.useOptions(opts)` | Set global CLI options that appear in every command's help |
+| `.start()` | Creates `MoostCli`, attaches adapter, applies help interceptor, calls `init()` |
+
+## Exports
+
+All imports come from `'@moostjs/event-cli'`:
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `CliApp` | class | Quick-setup CLI application factory |
+| `MoostCli` | class | Low-level adapter (implements `TMoostAdapter`) |
+| `Cli` | decorator | Define a CLI command on a method |
+| `CliAlias` | decorator | Add an alias for a command |
+| `CliExample` | decorator | Add a usage example for help output |
+| `CliOption` | decorator | Bind a parameter to a `--flag` |
+| `CliGlobalOption` | decorator | Define a global option on a controller class |
+| `cliHelpInterceptor` | function | Factory for the help interceptor |
+| `CliHelpInterceptor` | decorator | Decorator form of the help interceptor |
+| `cliKind` | object | Event type identifier for CLI events |
+| `Controller` | decorator | Re-exported from `moost` |
+| `Param` | decorator | Re-exported from `moost` |
+| `Intercept` | decorator | Re-exported from `moost` |
+| `Description` | decorator | Re-exported from `moost` |
+| `Optional` | decorator | Re-exported from `moost` |
+| `defineBeforeInterceptor` | function | Re-exported from `moost` |
+| `defineAfterInterceptor` | function | Re-exported from `moost` |
+| `defineInterceptor` | function | Re-exported from `moost` |
+| `TInterceptorPriority` | type | Re-exported from `moost` |
+
+## Running the app
+
+```bash
+# Development
+npx tsx src/bin.ts greet World
+
+# Production (after compiling)
+node dist/bin.js greet World
+```
+
+The return value of a command handler is printed to stdout.
+
+## Best Practices
+
+- Use `CliApp` for standard CLI apps; use `MoostCli` only when you need full control or multi-adapter setups
+- Keep `tsconfig.json` with `"experimentalDecorators": true` and `"emitDecoratorMetadata": true`
+- Register only top-level controllers — nested children are auto-registered via `@ImportController`