@wooksjs/event-cli 0.7.8 → 0.7.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-cli",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "description": "@wooksjs/event-cli",
   "keywords": [
     "api",
@@ -25,13 +25,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-cli"
   },
-  "bin": {
-    "wooksjs-event-cli-skill": "scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -52,17 +47,16 @@
     "@types/minimist": "^1.2.5",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "wooks": "^0.7.8",
-    "@wooksjs/event-core": "^0.7.8"
+    "@wooksjs/event-core": "^0.7.10",
+    "wooks": "^0.7.10"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
     "@prostojs/router": "^0.3.3",
-    "wooks": "^0.7.8",
-    "@wooksjs/event-core": "^0.7.8"
+    "@wooksjs/event-core": "^0.7.10",
+    "wooks": "^0.7.10"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const os = require('os')
-
-const SKILL_NAME = 'wooksjs-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/wooksjs-event-cli/SKILL.md

@@ -1,31 +0,0 @@
----
-name: wooksjs-event-cli
-description: Use this skill when working with @wooksjs/event-cli — to build CLI applications with createCliApp(), register commands with app.cli(), parse flags and options with useCliOptions()/useCliOption(), generate auto-help with useCliHelp()/useAutoHelp(), handle unknown commands with useCommandLookupHelp(), define command aliases/args/options metadata, or run CLI commands programmatically with app.run().
----
-
-# @wooksjs/event-cli
-
-CLI adapter for Wooks. Build command-line applications with the same composable architecture as Wooks HTTP — routed commands, typed options, auto-generated help, and per-invocation context.
-
-## 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 setup & routing | [core.md](core.md)         | Creating a CLI app, registering commands, running commands, understanding the architecture                                  |
-| Commands & help      | [commands.md](commands.md) | Command registration with options/args/aliases, help generation, composables (`useCliOptions`, `useCliHelp`, `useAutoHelp`) |
-
-## Quick reference
-
-```ts
-import { createCliApp } from '@wooksjs/event-cli'
-import { useRouteParams, useLogger } from '@wooksjs/event-cli'
-import {
-  useCliOptions,
-  useCliOption,
-  useCliHelp,
-  useAutoHelp,
-  useCommandLookupHelp,
-} from '@wooksjs/event-cli'
-```

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

@@ -1,222 +0,0 @@
-# Commands & help — @wooksjs/event-cli
-
-> Command registration with options/args/aliases, help generation, and CLI composables.
-
-## Concepts
-
-Commands can be registered with rich metadata (description, options, args, aliases, examples) that drives auto-generated help output. The help system is powered by `@prostojs/cli-help`.
-
-CLI composables (`useCliOptions`, `useCliOption`, `useCliHelp`, `useAutoHelp`) provide access to parsed flags and help rendering from within handlers.
-
-## API Reference
-
-### Command registration with options
-
-```ts
-app.cli('deploy/:env', {
-  description: 'Deploy the application to the specified environment',
-  args: {
-    env: 'Target environment (staging, production)',
-  },
-  options: [
-    { keys: ['verbose', 'v'], description: 'Enable verbose output' },
-    { keys: ['dry-run', 'd'], description: 'Run without making changes' },
-    { keys: ['config', 'c'], description: 'Path to config file', value: 'path' },
-  ],
-  aliases: ['dep'],
-  examples: [
-    {
-      description: 'Deploy to production with verbose output',
-      cmd: 'production --verbose',
-    },
-  ],
-  handler: () => {
-    const { params } = useRouteParams<{ env: string }>()
-    const verbose = useCliOption('verbose')
-    return `Deploying to ${params.env}${verbose ? ' (verbose)' : ''}`
-  },
-})
-```
-
-**`TWooksCliEntry<T>` fields:**
-
-| Field         | Type                                | Description                                              |
-| ------------- | ----------------------------------- | -------------------------------------------------------- |
-| `handler`     | `TWooksHandler<T>`                  | The command handler function                             |
-| `description` | `string`                            | Command description for help                             |
-| `args`        | `Record<string, string>`            | Argument descriptions (auto-populated from route params) |
-| `options`     | `TCliOption[]`                      | Flag/option definitions                                  |
-| `aliases`     | `string[]`                          | Alternative command names                                |
-| `examples`    | `TCliExample[]`                     | Usage examples                                           |
-| `onRegister`  | `(path, aliasType, route?) => void` | Callback when command/alias is registered                |
-
-**Option definition:**
-
-```ts
-{ keys: ['verbose', 'v'], description: 'Enable verbose output' }
-{ keys: ['config', 'c'], description: 'Config file path', value: 'file' }
-```
-
-- `keys`: Array of flag names (first is primary, rest are aliases)
-- `description`: Help text
-- `value`: If present, the option expects a value (shown in help as `--config <file>`)
-
-### `useCliOptions(): Record<string, boolean | string>`
-
-Returns all parsed CLI flags (via `minimist`). Includes positional args in `_`.
-
-```ts
-import { useCliOptions } from '@wooksjs/event-cli'
-
-app.cli('build', () => {
-  const opts = useCliOptions()
-  // For: $ mycli build --verbose --target=production
-  // opts = { _: ['build'], verbose: true, target: 'production' }
-})
-```
-
-### `useCliOption(name: string): boolean | string | undefined`
-
-Returns a single option value, resolving aliases from the command's option definitions.
-
-```ts
-import { useCliOption } from '@wooksjs/event-cli'
-
-app.cli('deploy', {
-  options: [{ keys: ['verbose', 'v'], description: 'Verbose output' }],
-  handler: () => {
-    const verbose = useCliOption('verbose')
-    // Returns true for both --verbose and -v
-  },
-})
-```
-
-### `useCliHelp()`
-
-Provides access to the help renderer for the current command.
-
-```ts
-import { useCliHelp } from '@wooksjs/event-cli'
-
-const { print, render, getEntry, getCliHelp } = useCliHelp()
-```
-
-| Method                        | Description                                |
-| ----------------------------- | ------------------------------------------ |
-| `print(withColors?)`          | Print help to stdout                       |
-| `render(width?, withColors?)` | Render help as string                      |
-| `getEntry()`                  | Get the help entry for the current command |
-| `getCliHelp()`                | Get the full `CliHelpRenderer` instance    |
-
-### `useAutoHelp(keys?, colors?)`
-
-Checks if `--help` (or custom flag) was passed; if so, prints help and returns `true`.
-
-```ts
-import { useAutoHelp } from '@wooksjs/event-cli'
-
-app.cli('build', {
-  description: 'Build the project',
-  handler: () => {
-    if (useAutoHelp()) return // prints help and returns true for --help
-    return 'Building...'
-  },
-})
-
-// Custom trigger flags
-app.cli('test', {
-  handler: () => {
-    if (useAutoHelp(['help', 'h'], false)) return // -h, --help, no colors
-  },
-})
-```
-
-**Parameters:**
-
-- `keys` (default: `['help']`) — option names that trigger help
-- `colors` (default: `true`) — whether to use ANSI colors
-
-### `useCommandLookupHelp(lookupDepth?)`
-
-Provides "did you mean?" suggestions for unknown commands. Best used in `onUnknownCommand`:
-
-```ts
-import { createCliApp } from '@wooksjs/event-cli'
-import { useCommandLookupHelp } from '@wooksjs/event-cli'
-
-const app = createCliApp({
-  onUnknownCommand: (params, raiseError) => {
-    useCommandLookupHelp() // throws with suggestions if found
-    raiseError() // fallback: standard "unknown command" error
-  },
-})
-```
-
-For a command like `run test:drive dir`, it searches backwards:
-
-1. `run test:drive dir` (depth 0)
-2. `run test:drive` (depth 1)
-3. `run test` (depth 2)
-4. `run` (depth 3)
-
-If a match has children, it suggests them. If a match expects args, it says which args are expected.
-
-## Common Patterns
-
-### Pattern: Auto-help with exit
-
-```ts
-app.cli('serve', {
-  description: 'Start the development server',
-  options: [{ keys: ['port', 'p'], description: 'Port number', value: 'number' }],
-  handler: () => {
-    if (useAutoHelp()) process.exit(0)
-    const port = useCliOption('port') || '3000'
-    return `Server running on port ${port}`
-  },
-})
-```
-
-### Pattern: Boolean and value flags
-
-```ts
-app.cli('build', {
-  options: [
-    { keys: ['watch', 'w'], description: 'Watch mode' }, // boolean
-    { keys: ['output', 'o'], description: 'Output dir', value: 'path' }, // value
-  ],
-  handler: () => {
-    const watch = useCliOption('watch') // true | undefined
-    const output = useCliOption('output') // 'dist' | undefined
-  },
-})
-```
-
-### Pattern: Shared CLI and HTTP adapters
-
-Both adapters can share the same `Wooks` instance:
-
-```ts
-import { createCliApp } from '@wooksjs/event-cli'
-import { createHttpApp } from '@wooksjs/event-http'
-
-const httpApp = createHttpApp()
-const cliApp = createCliApp({}, httpApp)
-
-// CLI commands and HTTP routes share the same router
-cliApp.cli('start', () => httpApp.listen(3000))
-```
-
-## Best Practices
-
-- Always provide `description` and `options` for production CLI tools — it powers `--help`
-- Use `useAutoHelp()` at the top of every command handler
-- Use `useCommandLookupHelp()` in `onUnknownCommand` for better UX
-- Use aliases for common abbreviations: `aliases: ['dep']` for `deploy`
-
-## Gotchas
-
-- `useCliOptions()` returns the raw `minimist` output — `_` contains positional args, everything else is flags
-- `useCliOption(name)` resolves aliases from the option definitions — `useCliOptions()[name]` does not
-- Help is auto-registered from `app.cli()` metadata — no separate help registration needed
-- Colons in command names must be escaped: `'use\\:dev'` for command `use:dev`

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

@@ -1,136 +0,0 @@
-# Core setup & routing — @wooksjs/event-cli
-
-> Creating a CLI app, registering commands, running them, and architecture overview.
-
-## Concepts
-
-`@wooksjs/event-cli` wraps command-line argument parsing with Wooks' composable architecture. Each command invocation gets its own `EventContext`, and handlers are plain functions. Command routing uses the same `@prostojs/router` as the HTTP adapter — supporting parameters, optional params, wildcards, and aliases.
-
-Arguments are parsed with `minimist`. Help text is generated automatically from command metadata via `@prostojs/cli-help`.
-
-## Installation
-
-```bash
-pnpm add @wooksjs/event-cli
-```
-
-Peer dependencies: `@wooksjs/event-core`, `wooks`, `@prostojs/router`, `@prostojs/logger`.
-
-## API Reference
-
-### `createCliApp(opts?): WooksCli`
-
-Creates a CLI application instance.
-
-```ts
-import { createCliApp } from '@wooksjs/event-cli'
-
-const app = createCliApp()
-
-app.cli('greet/:name', () => {
-  const { params } = useRouteParams<{ name: string }>()
-  return `Hello, ${params.name}!`
-})
-
-app.run() // processes process.argv
-```
-
-**Options (`TWooksCliOptions`):**
-
-| Option             | Type                                  | Description                                               |
-| ------------------ | ------------------------------------- | --------------------------------------------------------- |
-| `logger`           | `TConsoleBase`                        | Custom logger                                             |
-| `onError`          | `(e: Error) => void`                  | Custom error handler (default: print + `process.exit(1)`) |
-| `onNotFound`       | `TWooksHandler`                       | Handler for unknown commands                              |
-| `onUnknownCommand` | `(params, raiseError) => unknown`     | Callback before "unknown command" error                   |
-| `cliHelp`          | `TCliHelpRenderer \| TCliHelpOptions` | Help renderer or options                                  |
-| `router`           | router options                        | Custom router configuration                               |
-
-### `app.cli(path, handler | options)`
-
-Register a CLI command. Path segments can use `/` or space as separators.
-
-```ts
-// Simple handler
-app.cli('build/:target', () => {
-  const { params } = useRouteParams<{ target: string }>()
-  return `Building ${params.target}...`
-})
-
-// Equivalent paths:
-app.cli('deploy staging', handler)
-app.cli('deploy/staging', handler)
-```
-
-### `app.run(argv?, minimistOpts?)`
-
-Start command processing. Defaults to `process.argv.slice(2)`.
-
-```ts
-// Use process.argv
-await app.run()
-
-// Override argv
-await app.run(['build', 'production', '--verbose'])
-
-// With minimist options
-await app.run(['cmd', '-cA'], { boolean: ['A'] })
-```
-
-Returns the handler's return value, or an `Error` if the command fails.
-
-## Command routing
-
-Routes use the same `@prostojs/router` as HTTP. Command path segments become route segments:
-
-```ts
-// Static command
-app.cli('init', handler) // $ mycli init
-
-// With parameter
-app.cli('build/:target', handler) // $ mycli build production
-
-// Optional parameter
-app.cli('test/:suite?', handler) // $ mycli test        (suite = undefined)
-// $ mycli test unit   (suite = 'unit')
-
-// Multi-segment
-app.cli('deploy staging setup', handler) // $ mycli deploy staging setup
-```
-
-Route params accessed via `useRouteParams()`:
-
-```ts
-import { useRouteParams } from '@wooksjs/event-cli'
-
-app.cli('generate/:type/:name', () => {
-  const { params } = useRouteParams<{ type: string; name: string }>()
-  return `Generating ${params.type}: ${params.name}`
-})
-```
-
-## Response handling
-
-Handler return values are printed to stdout:
-
-| Return type | Behavior                                          |
-| ----------- | ------------------------------------------------- |
-| `string`    | `console.log(value)`                              |
-| `array`     | Each item logged (strings as-is, objects as JSON) |
-| `object`    | `console.log(JSON.stringify(value, null, '  '))`  |
-| `Error`     | Passed to `onError` handler                       |
-| `undefined` | Nothing printed                                   |
-
-## Best Practices
-
-- Use `useRouteParams()` for positional arguments and `useCliOptions()` for flags
-- Prefer the options object form of `app.cli()` to get auto-generated help
-- Use `onUnknownCommand` with `useCommandLookupHelp()` for "did you mean?" suggestions
-- Command paths with spaces and `/` are equivalent — use whichever is more readable
-
-## Gotchas
-
-- `app.run()` is async — always `await` it
-- Default error handling calls `process.exit(1)` — override with `onError` for testing
-- Colons in command names need escaping: `app.cli('use\\:dev', handler)` for `$ mycli use:dev`
-- `minimist` treats `--no-flag` as `flag: false` when the flag is in `boolean` array