@moostjs/event-cli 0.5.32 → 0.6.0

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

@@ -0,0 +1,160 @@
+# Help system — @moostjs/event-cli
+
+> Auto-generated help output, help interceptor configuration, and unknown command handling.
+
+## Concepts
+
+Moost CLI auto-generates `--help` output from decorator metadata: `@Description()` on methods and parameters, `@CliExample()` for usage patterns, `@Value()` for sample values, and `@CliGlobalOption()` for global flags. The help system is powered by `cliHelpInterceptor`, which intercepts `--help` flags and renders formatted help.
+
+## API Reference
+
+### `cliHelpInterceptor(opts?)`
+
+Factory function that returns a before-interceptor at `BEFORE_ALL` priority. Intercepts commands with `--help` and prints help output.
+
+Options:
+- `helpOptions?: string[]` — flag names that trigger help (default: `['help']`)
+- `colors?: boolean` — enable colored output
+- `lookupLevel?: number` — depth for "did you mean?" fuzzy matching on unknown commands
+
+```ts
+import { cliHelpInterceptor } from '@moostjs/event-cli'
+import { Moost } from 'moost'
+
+const app = new Moost()
+app.applyGlobalInterceptors(
+  cliHelpInterceptor({
+    helpOptions: ['help', 'h'],
+    colors: true,
+    lookupLevel: 3,
+  }),
+)
+```
+
+### `@CliHelpInterceptor(opts?)`
+
+Decorator form of `cliHelpInterceptor`. Apply to a controller or method to scope help behavior:
+
+```ts
+import { CliHelpInterceptor } from '@moostjs/event-cli'
+
+@CliHelpInterceptor({ colors: true, lookupLevel: 3 })
+@Controller()
+export class AppController {
+  @Cli('deploy')
+  deploy() { return 'Deploying...' }
+}
+```
+
+### `useHelp(opts)` on CliApp
+
+The simplest way to enable help. Calls `cliHelpInterceptor` internally:
+
+```ts
+new CliApp()
+  .controllers(AppController)
+  .useHelp({
+    name: 'my-cli',       // shown in usage: "$ my-cli ..."
+    title: 'My CLI Tool', // title at top of help
+    colors: true,          // colored output (default: true)
+    lookupLevel: 3,        // fuzzy lookup depth (default: 3)
+    maxWidth: 80,          // max help output width
+    maxLeft: 30,           // max left column width
+    mark: '>',             // prefix marker for sections
+  })
+  .start()
+```
+
+### Help options reference
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `name` | — | CLI app name shown in usage examples |
+| `title` | — | Title displayed at the top of help |
+| `colors` | `true` | Enable colored terminal output |
+| `lookupLevel` | `3` | Depth for "did you mean?" suggestions |
+| `maxWidth` | — | Maximum width of help output |
+| `maxLeft` | — | Maximum width of the left column |
+| `mark` | — | Prefix marker for help sections |
+
+## Common Patterns
+
+### Pattern: Full help setup with CliApp
+
+```ts
+new CliApp()
+  .controllers(AppController)
+  .useHelp({ name: 'my-cli' })
+  .useOptions([
+    { keys: ['help'], description: 'Display instructions for the command.' },
+    { keys: ['verbose', 'v'], description: 'Enable verbose output.' },
+  ])
+  .start()
+```
+
+### Pattern: Documenting a command
+
+```ts
+@Description('Deploy application to a target environment')
+@Cli('deploy/:env')
+@CliExample('deploy dev -p my-app', 'Deploy "my-app" to development')
+@CliExample('deploy prod -p my-app --verbose', 'Deploy with verbose logging')
+deploy(
+  @Description('Environment')
+  @Param('env')
+  env: string,
+
+  @Description('Project name')
+  @CliOption('project', 'p')
+  @Value('<my-app>')
+  project: string,
+) {
+  return `Deploying ${project} to ${env}`
+}
+```
+
+Running `my-cli deploy --help` produces:
+```
+DESCRIPTION
+  Deploy application to a target environment
+
+USAGE
+  $ my-cli deploy <env>
+
+ARGUMENTS
+  <env>                   - Environment
+
+OPTIONS
+  --help                  - Display instructions for the command.
+  -p, --project <my-app>  - Project name
+
+EXAMPLES
+  # Deploy "my-app" to development
+  $ my-cli deploy dev -p my-app
+  # Deploy with verbose logging
+  $ my-cli deploy prod -p my-app --verbose
+```
+
+### Pattern: Unknown command handling
+
+When `lookupLevel` is set, typing a wrong command triggers suggestions:
+
+```bash
+$ my-cli depoly
+Did you mean "deploy"?
+```
+
+## Integration
+
+- `@Description()` on methods fills the DESCRIPTION section
+- `@Description()` on parameters fills ARGUMENTS and OPTIONS sections
+- `@CliExample()` fills the EXAMPLES section
+- `@Value()` shows sample values next to options
+- `@CliGlobalOption()` adds options to every command's help in that controller
+
+## Best Practices
+
+- Always call `.useHelp({ name: 'my-cli' })` — the name makes usage examples clear
+- Add `@Description()` to every command and parameter — it's the primary documentation
+- Use `@CliExample()` for non-obvious usage patterns
+- Set `lookupLevel: 3` for helpful "did you mean?" suggestions

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

@@ -0,0 +1,160 @@
+# Interceptors — @moostjs/event-cli
+
+> Guards, error handlers, timing, and cross-cutting CLI logic.
+
+## Concepts
+
+Interceptors wrap command execution with cross-cutting logic. They have three lifecycle hooks: `before`, `after`, and `error`. Each runs at a configurable priority level. They work identically to Moost interceptors but are applied in a CLI context.
+
+Use the `define*` helpers from `moost` (re-exported by `@moostjs/event-cli`) to create functional interceptors.
+
+## API Reference
+
+### `defineBeforeInterceptor(fn, priority?)`
+
+Creates an interceptor that runs before the handler. Call `reply(value)` to short-circuit and skip the handler.
+
+```ts
+import { defineBeforeInterceptor, TInterceptorPriority } from '@moostjs/event-cli'
+
+const guard = defineBeforeInterceptor((reply) => {
+  if (!process.env.CI_TOKEN) {
+    console.error('Error: CI_TOKEN required')
+    process.exit(1)
+  }
+}, TInterceptorPriority.GUARD)
+```
+
+### `defineAfterInterceptor(fn, priority?)`
+
+Creates an interceptor that runs after the handler. Receives the response.
+
+```ts
+import { defineAfterInterceptor } from '@moostjs/event-cli'
+
+const logger = defineAfterInterceptor((response) => {
+  console.log('Command returned:', response)
+})
+```
+
+### `defineErrorInterceptor(fn, priority?)`
+
+Creates an interceptor that runs on error. Call `reply(value)` to recover.
+
+```ts
+import { defineErrorInterceptor, TInterceptorPriority } from '@moostjs/event-cli'
+
+const errorHandler = defineErrorInterceptor((error, reply) => {
+  console.error(`Error: ${error.message}`)
+  reply('')
+}, TInterceptorPriority.CATCH_ERROR)
+```
+
+### `defineInterceptor(hooks, priority?)`
+
+Combines all hooks in one interceptor:
+
+```ts
+import { defineInterceptor, TInterceptorPriority } from '@moostjs/event-cli'
+
+const myInterceptor = defineInterceptor({
+  before(reply) { /* ... */ },
+  after(response, reply) { /* ... */ },
+  error(error, reply) { /* ... */ },
+}, TInterceptorPriority.INTERCEPTOR)
+```
+
+### Priority levels
+
+| Priority | Value | Typical use |
+|----------|-------|-------------|
+| `BEFORE_ALL` | 0 | Help interceptor, early logging |
+| `BEFORE_GUARD` | 1 | Setup before guards |
+| `GUARD` | 2 | Permission checks, env validation |
+| `AFTER_GUARD` | 3 | Post-auth setup |
+| `INTERCEPTOR` | 4 | General-purpose (default) |
+| `CATCH_ERROR` | 5 | Error formatting |
+| `AFTER_ALL` | 6 | Timing, cleanup |
+
+## Common Patterns
+
+### Pattern: CLI guard
+
+```ts
+import { Cli, Controller, Intercept } from '@moostjs/event-cli'
+import { defineBeforeInterceptor, TInterceptorPriority } from '@moostjs/event-cli'
+
+const requireEnvGuard = defineBeforeInterceptor(() => {
+  if (!process.env.CI_TOKEN) {
+    console.error('Error: CI_TOKEN environment variable is required')
+    process.exit(1)
+  }
+}, TInterceptorPriority.GUARD)
+
+@Controller()
+export class DeployController {
+  @Intercept(requireEnvGuard)
+  @Cli('deploy/:env')
+  deploy(@Param('env') env: string) {
+    return `Deploying to ${env}...`
+  }
+}
+```
+
+### Pattern: Global error handler
+
+```ts
+const cliErrorHandler = defineErrorInterceptor((error, reply) => {
+  console.error(`Error: ${error.message}`)
+  reply('')
+}, TInterceptorPriority.CATCH_ERROR)
+
+const app = new CliApp()
+app.applyGlobalInterceptors(cliErrorHandler)
+app.controllers(AppController)
+app.useHelp({ name: 'my-cli' })
+app.start()
+```
+
+### Pattern: Timing interceptor
+
+Class-based with `FOR_EVENT` scope (fresh instance per command):
+
+```ts
+import { Interceptor, Before, After, TInterceptorPriority } from 'moost'
+
+@Interceptor(TInterceptorPriority.BEFORE_ALL, 'FOR_EVENT')
+class TimingInterceptor {
+  private start = 0
+
+  @Before()
+  recordStart() { this.start = performance.now() }
+
+  @After()
+  logDuration() {
+    const ms = (performance.now() - this.start).toFixed(1)
+    console.log(`Completed in ${ms}ms`)
+  }
+}
+```
+
+## Applying interceptors
+
+| Scope | How |
+|-------|-----|
+| Single command | `@Intercept(fn)` on the method |
+| All commands in a controller | `@Intercept(fn)` on the class |
+| Every command in the app | `app.applyGlobalInterceptors(fn)` |
+
+## Best Practices
+
+- Use `GUARD` priority for permission/env checks that should block execution
+- Use `CATCH_ERROR` for terminal-friendly error formatting
+- Apply error handlers globally so every command benefits
+- Use `FOR_EVENT` scope for class-based interceptors that track per-command state (like timing)
+
+## Gotchas
+
+- Interceptors run in priority order (lower numbers first), not registration order
+- `reply(value)` in a before-interceptor skips the handler entirely — the value becomes the response
+- The help interceptor runs at `BEFORE_ALL` — it runs before guards

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

@@ -0,0 +1,180 @@
+# Options & arguments — @moostjs/event-cli
+
+> CLI flags, boolean options, optional parameters, descriptions, sample values, and global options.
+
+## Concepts
+
+CLI commands accept two kinds of input:
+- **Positional arguments** — extracted from `:param` segments in the command path via `@Param()`
+- **Option flags** — bound to `--flag`/`-f` style switches via `@CliOption()`
+
+Additional decorators control documentation and behavior: `@Description()`, `@Optional()`, `@Value()`, and `@CliGlobalOption()`.
+
+## API Reference
+
+### `@CliOption(...keys: string[])`
+
+Parameter decorator. Binds the parameter to one or more CLI flags. Long names (2+ chars) become `--flag`, single chars become `-f`.
+
+Under the hood, this calls `useCliOption(keys[0])` from `@wooksjs/event-cli` via a `@Resolve()` pipe.
+
+```ts
+import { Cli, CliOption, Controller, Description, Param } from '@moostjs/event-cli'
+
+@Controller()
+export class DeployController {
+  @Cli('deploy/:env')
+  deploy(
+    @Param('env') env: string,
+
+    @Description('Project name')
+    @CliOption('project', 'p')
+    project: string,
+
+    @Description('Enable verbose logging')
+    @CliOption('verbose', 'v')
+    verbose: boolean,
+  ) {
+    if (verbose) console.log(`Project: ${project}, env: ${env}`)
+    return `Deploying ${project} to ${env}`
+  }
+}
+```
+
+```bash
+my-cli deploy production --project my-app --verbose
+my-cli deploy production -p my-app -v          # same thing
+```
+
+### `@CliGlobalOption(option: { keys: string[]; description?: string; value?: string })`
+
+Class decorator. Declares an option that appears in help output for every command in the controller.
+
+```ts
+import { Cli, CliGlobalOption, Controller } from '@moostjs/event-cli'
+
+@Controller('build')
+@CliGlobalOption({
+  keys: ['verbose', 'v'],
+  description: 'Enable verbose logging',
+})
+export class BuildController {
+  @Cli('dev')
+  buildDev() { return 'Building for dev...' }
+
+  @Cli('prod')
+  buildProd() { return 'Building for prod...' }
+}
+```
+
+### `@Description(text: string)`
+
+Parameter or method decorator (re-exported from `moost`). Documents the parameter or command for help output.
+
+```ts
+@Description('Deploy the application to a target environment')
+@Cli('deploy/:env')
+deploy(
+  @Description('Target environment (production, staging, dev)')
+  @Param('env')
+  env: string,
+) {
+  return `Deploying to ${env}...`
+}
+```
+
+### `@Optional()`
+
+Parameter decorator (re-exported from `moost`). Marks a parameter as not required. Integrates with the help system.
+
+```ts
+@Cli('build')
+build(
+  @Description('Output directory')
+  @CliOption('out', 'o')
+  @Optional()
+  outDir: string,
+) {
+  return `Output: ${outDir ?? './dist'}`
+}
+```
+
+### `@Value(sample: string)`
+
+Parameter decorator (from `moost`). Shows a placeholder in help output. Does NOT set a default value.
+
+```ts
+import { Value } from 'moost'
+
+@Cli('test/:config')
+test(
+  @Description('Target environment')
+  @CliOption('target', 't')
+  @Value('<staging>')
+  target: string,
+) {
+  return `Testing in ${target}`
+}
+```
+
+In help: `--target <staging>`.
+
+## Common Patterns
+
+### Pattern: Boolean flags
+
+When a parameter has type `boolean`, Moost automatically registers it as a boolean flag (no value expected — presence means `true`):
+
+```ts
+@Cli('build')
+build(
+  @CliOption('watch', 'w') watch: boolean,
+  @CliOption('minify', 'm') minify: boolean,
+) {
+  return `watch=${watch}, minify=${minify}`
+}
+```
+
+```bash
+my-cli build --watch --minify    # watch=true, minify=true
+my-cli build -wm                 # combined short flags
+my-cli build                     # watch=undefined, minify=undefined
+```
+
+### Pattern: Global options via CliApp
+
+```ts
+new CliApp()
+  .controllers(AppController)
+  .useHelp({ name: 'my-cli' })
+  .useOptions([
+    { keys: ['help'], description: 'Display instructions for the command.' },
+    { keys: ['verbose', 'v'], description: 'Enable verbose output.' },
+  ])
+  .start()
+```
+
+## Decorator summary
+
+| Decorator | Applies to | Purpose |
+|-----------|-----------|---------|
+| `@Param('name')` | parameter | Extract positional argument from `:name` in path |
+| `@CliOption('key', 'k')` | parameter | Bind to `--key` / `-k` flag |
+| `@CliGlobalOption({...})` | class | Global option shown in all commands' help |
+| `@Description('...')` | parameter, method | Document for help output |
+| `@Optional()` | parameter | Mark as not required |
+| `@Value('...')` | parameter | Show sample value in help |
+
+## Best Practices
+
+- Always add `@Description()` to options and arguments — it drives `--help` output
+- Use short aliases (single char) for frequently-used flags: `@CliOption('verbose', 'v')`
+- Type boolean flags as `boolean` so they don't expect a value argument
+- Use `@Value()` for non-obvious option formats (e.g., `@Value('<host:port>')`)
+
+## Gotchas
+
+- `@Optional()` does not provide a default value — it only marks the parameter as optional. Use `??` in your code for defaults
+- `@Value()` is purely cosmetic for help display — it does NOT set a default value
+- Without `@Optional()`, a missing flag results in `undefined` (not an error)
+- Boolean flags that are absent yield `undefined`, not `false`