@moostjs/event-cli 0.6.6 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-cli",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "@moostjs/event-cli",
   "keywords": [
     "composables",
@@ -21,13 +21,8 @@
     "url": "git+https://github.com/moostjs/moostjs.git",
     "directory": "packages/event-cli"
   },
-  "bin": {
-    "moostjs-event-cli-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
@@ -43,19 +38,18 @@
     }
   },
   "dependencies": {
-    "@wooksjs/event-cli": "^0.7.8"
+    "@wooksjs/event-cli": "^0.7.9"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@wooksjs/event-core": "^0.7.8",
-    "wooks": "^0.7.8",
-    "moost": "^0.6.6"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9",
+    "moost": "^0.6.7"
   },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "test": "vitest"
   }
 }

package/scripts/setup-skills.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'moostjs-event-cli'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

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

@@ -1,38 +0,0 @@
----
-name: moostjs-event-cli
-description: Use this skill when working with @moostjs/event-cli — to build CLI applications with CliApp or MoostCli, define commands with @Cli(), parse flags and options with @CliOption(), organize commands into controllers with @Controller() and @ImportController(), generate auto-help with cliHelpInterceptor() and @CliHelpInterceptor, define command aliases with @CliAlias(), add usage examples with @CliExample(), set global options with @CliGlobalOption(), use composables like useCliOption()/useCliOptions()/useCliHelp(), combine CLI with HTTP via multi-adapter setup, or access cliKind for event type identification.
----
-
-# @moostjs/event-cli
-
-Moost adapter for building decorator-driven CLI applications. Wraps `@wooksjs/event-cli` and integrates with Moost's DI, interceptors, and pipes.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain | File | Load when... |
-|--------|------|------------|
-| Core concepts & setup | [core.md](core.md) | Starting a new project, understanding the mental model, installing the package |
-| Commands | [commands.md](commands.md) | Defining commands with @Cli(), command paths, positional arguments, aliases, examples |
-| Options & arguments | [options.md](options.md) | Adding flags with @CliOption(), boolean options, @Description, @Optional, @Value, @CliGlobalOption |
-| Controllers | [controllers.md](controllers.md) | Organizing commands into groups, nesting with @ImportController, path composition |
-| Help system | [help.md](help.md) | Configuring auto-help, cliHelpInterceptor, @CliHelpInterceptor, unknown command handling |
-| Interceptors | [interceptors.md](interceptors.md) | Adding guards, error handlers, timing, cross-cutting CLI logic |
-| Advanced | [advanced.md](advanced.md) | Manual MoostCli setup, Wooks composables, DI scopes, multi-adapter CLI+HTTP, cliKind |
-
-## Quick reference
-
-```ts
-// Most common imports
-import { CliApp, Cli, CliOption, CliAlias, CliExample, CliGlobalOption } from '@moostjs/event-cli'
-import { Controller, Param, Description, Optional, Intercept } from '@moostjs/event-cli'
-import { cliHelpInterceptor, CliHelpInterceptor } from '@moostjs/event-cli'
-import { MoostCli, cliKind } from '@moostjs/event-cli'
-
-// Minimal app
-new CliApp()
-  .controllers(AppController)
-  .useHelp({ name: 'my-cli' })
-  .start()
-```

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

@@ -1,202 +0,0 @@
-# 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

@@ -1,152 +0,0 @@
-# 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

@@ -1,142 +0,0 @@
-# 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

@@ -1,114 +0,0 @@
-# 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`

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

@@ -1,160 +0,0 @@
-# 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

@@ -1,160 +0,0 @@
-# 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

@@ -1,180 +0,0 @@
-# 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`