@wooksjs/event-cli 0.6.2 → 0.6.4

package/README.md

@@ -44,3 +44,27 @@ app.run()
 ## Documentation
 
 To check out docs, visit [wooks.moost.org](https://wooks.moost.org/cliapp/).
+
+## AI Agent Skills
+
+This package ships with structured skill files for AI coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx @wooksjs/event-cli setup-skills
+
+# Global (available across all your projects)
+npx @wooksjs/event-cli setup-skills --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx @wooksjs/event-cli setup-skills --postinstall"
+  }
+}
+```
+
+This ensures the skill files are refreshed whenever dependencies are installed, without needing a separate command.

package/dist/index.cjs

@@ -27,6 +27,7 @@ const wooks = __toESM(require("wooks"));
 const __wooksjs_event_core = __toESM(require("@wooksjs/event-core"));
 
 //#region packages/event-cli/src/event-cli.ts
+/** Creates a new async event context for a CLI command invocation. */
 function createCliContext(data, options) {
 	return (0, __wooksjs_event_core.createAsyncEventContext)({
 		event: {
@@ -47,7 +48,9 @@ function useCliContext() {
 
 //#endregion
 //#region packages/event-cli/src/cli-adapter.ts
+/** Shortcut mappings for CLI event methods. */
 const cliShortcuts = { cli: "CLI" };
+/** Wooks adapter for building CLI applications with command routing and help generation. */
 var WooksCli = class extends wooks.WooksAdapterBase {
 	logger;
 	cliHelp;
@@ -213,10 +216,16 @@ var WooksCli = class extends wooks.WooksAdapterBase {
 	}
 };
 /**
-* Factory for WooksCli App
-* @param opts TWooksCliOptions
-* @param wooks Wooks | WooksAdapterBase
-* @returns WooksCli
+* Creates a new WooksCli application instance.
+* @param opts - CLI adapter configuration options
+* @param wooks - Optional existing Wooks or adapter instance to attach to
+* @returns A new WooksCli instance
+* @example
+* ```ts
+* const app = createCliApp()
+* app.cli('greet/:name', () => `Hello, ${useRouteParams().get('name')}!`)
+* app.run()
+* ```
 */
 function createCliApp(opts, wooks$1) {
 	return new WooksCli(opts, wooks$1);
@@ -243,6 +252,13 @@ function useCliOptions() {
 *
 * @param name name of the option
 * @returns value of a CLI option
+* @example
+* ```ts
+* const verbose = useCliOption('verbose')
+* if (verbose) {
+*   console.log('Verbose mode enabled')
+* }
+* ```
 */
 function useCliOption(name) {
 	try {
@@ -251,7 +267,7 @@ function useCliOption(name) {
 		if (opt) {
 			for (const key of opt.keys) if (useCliOptions()[key]) return useCliOptions()[key];
 		}
-	} catch (error) {}
+	} catch {}
 	return useCliOptions()[name];
 }
 
@@ -357,7 +373,7 @@ function useCommandLookupHelp(lookupDepth = 3) {
 			break;
 		} catch (error) {
 			const variants = cliHelp.lookup(pathParams);
-			if (variants.length > 0) throw new Error(`Wrong command, did you mean:\n${variants.slice(0, 7).map((c) => `  $ ${cmd} ${c.main.command}`).join("\n")}`);
+			if (variants.length > 0) throw new Error(`Wrong command, did you mean:\n${variants.slice(0, 7).map((c) => `  $ ${cmd} ${c.main.command}`).join("\n")}`, { cause: error });
 		}
 	}
 	if (data) {

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 import * as wooks from 'wooks';
 import { TWooksHandler, TWooksOptions, WooksAdapterBase, Wooks } from 'wooks';
 import * as _prostojs_cli_help from '@prostojs/cli-help';
-import { CliHelpRenderer, TCliHelpOptions, TCliEntry } from '@prostojs/cli-help';
+import { CliHelpRenderer, TCliEntry, TCliHelpOptions } from '@prostojs/cli-help';
 import { TConsoleBase } from '@prostojs/logger';
 import * as _wooksjs_event_core from '@wooksjs/event-core';
 import { TEventOptions, TEmpty } from '@wooksjs/event-core';
 import minimist from 'minimist';
 import { TProstoRouterPathHandle } from '@prostojs/router';
 
+/** Event data describing a CLI command invocation. */
 interface TCliEventData {
     argv: string[];
     pathParams: string[];
@@ -16,9 +17,11 @@ interface TCliEventData {
     type: 'CLI';
     cliHelp: TCliHelpRenderer;
 }
+/** Context store for CLI events, holding parsed flags. */
 interface TCliContextStore {
     flags?: Record<string, boolean | string>;
 }
+/** Custom data attached to CLI help entries for handler resolution. */
 interface TCliHelpCustom {
     handler: TWooksHandler<any>;
     /**
@@ -29,11 +32,14 @@ interface TCliHelpCustom {
      */
     cb?: <T>(path: string, aliasType: number, route?: TProstoRouterPathHandle<T>) => void;
 }
+/** CLI help renderer type parameterized with custom help data. */
 type TCliHelpRenderer = CliHelpRenderer<TCliHelpCustom>;
 
+/** Shortcut mappings for CLI event methods. */
 declare const cliShortcuts: {
     cli: string;
 };
+/** Configuration options for the WooksCli adapter. */
 interface TWooksCliOptions {
     onError?: (e: Error) => void;
     onNotFound?: TWooksHandler;
@@ -43,10 +49,12 @@ interface TWooksCliOptions {
     cliHelp?: TCliHelpRenderer | TCliHelpOptions;
     router?: TWooksOptions['router'];
 }
+/** Entry definition for registering a CLI command with its handler and help metadata. */
 interface TWooksCliEntry<T> extends Omit<TCliEntry<TWooksHandler<T>>, 'custom' | 'command'> {
     onRegister?: TCliHelpCustom['cb'];
     handler: TWooksHandler<T>;
 }
+/** Wooks adapter for building CLI applications with command routing and help generation. */
 declare class WooksCli extends WooksAdapterBase {
     protected opts?: TWooksCliOptions | undefined;
     protected logger: TConsoleBase;
@@ -112,10 +120,16 @@ declare class WooksCli extends WooksAdapterBase {
     protected error(e: string | Error): void;
 }
 /**
- * Factory for WooksCli App
- * @param opts TWooksCliOptions
- * @param wooks Wooks | WooksAdapterBase
- * @returns WooksCli
+ * Creates a new WooksCli application instance.
+ * @param opts - CLI adapter configuration options
+ * @param wooks - Optional existing Wooks or adapter instance to attach to
+ * @returns A new WooksCli instance
+ * @example
+ * ```ts
+ * const app = createCliApp()
+ * app.cli('greet/:name', () => `Hello, ${useRouteParams().get('name')}!`)
+ * app.run()
+ * ```
  */
 declare function createCliApp(opts?: TWooksCliOptions, wooks?: Wooks | WooksAdapterBase): WooksCli;
 
@@ -208,9 +222,17 @@ declare function useCliOptions(): Record<string, string | boolean>;
  *
  * @param name name of the option
  * @returns value of a CLI option
+ * @example
+ * ```ts
+ * const verbose = useCliOption('verbose')
+ * if (verbose) {
+ *   console.log('Verbose mode enabled')
+ * }
+ * ```
  */
 declare function useCliOption(name: string): string | boolean;
 
+/** Creates a new async event context for a CLI command invocation. */
 declare function createCliContext(data: Omit<TCliEventData, 'type'>, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
 /**
  * Wrapper on top of useEventContext that provides
@@ -219,4 +241,5 @@ declare function createCliContext(data: Omit<TCliEventData, 'type'>, options: TE
  */
 declare function useCliContext<T extends TEmpty>(): _wooksjs_event_core.TCtxHelpers<TCliContextStore & T & _wooksjs_event_core.TGenericContextStore<TCliEventData>>;
 
-export { type TCliContextStore, type TCliEventData, type TCliHelpCustom, type TCliHelpRenderer, type TWooksCliEntry, type TWooksCliOptions, WooksCli, cliShortcuts, createCliApp, createCliContext, useAutoHelp, useCliContext, useCliHelp, useCliOption, useCliOptions, useCommandLookupHelp };
+export { WooksCli, cliShortcuts, createCliApp, createCliContext, useAutoHelp, useCliContext, useCliHelp, useCliOption, useCliOptions, useCommandLookupHelp };
+export type { TCliContextStore, TCliEventData, TCliHelpCustom, TCliHelpRenderer, TWooksCliEntry, TWooksCliOptions };

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { WooksAdapterBase } from "wooks";
 import { createAsyncEventContext, useAsyncEventContext } from "@wooksjs/event-core";
 
 //#region packages/event-cli/src/event-cli.ts
+/** Creates a new async event context for a CLI command invocation. */
 function createCliContext(data, options) {
 	return createAsyncEventContext({
 		event: {
@@ -24,7 +25,9 @@ function useCliContext() {
 
 //#endregion
 //#region packages/event-cli/src/cli-adapter.ts
+/** Shortcut mappings for CLI event methods. */
 const cliShortcuts = { cli: "CLI" };
+/** Wooks adapter for building CLI applications with command routing and help generation. */
 var WooksCli = class extends WooksAdapterBase {
 	logger;
 	cliHelp;
@@ -190,10 +193,16 @@ var WooksCli = class extends WooksAdapterBase {
 	}
 };
 /**
-* Factory for WooksCli App
-* @param opts TWooksCliOptions
-* @param wooks Wooks | WooksAdapterBase
-* @returns WooksCli
+* Creates a new WooksCli application instance.
+* @param opts - CLI adapter configuration options
+* @param wooks - Optional existing Wooks or adapter instance to attach to
+* @returns A new WooksCli instance
+* @example
+* ```ts
+* const app = createCliApp()
+* app.cli('greet/:name', () => `Hello, ${useRouteParams().get('name')}!`)
+* app.run()
+* ```
 */
 function createCliApp(opts, wooks) {
 	return new WooksCli(opts, wooks);
@@ -220,6 +229,13 @@ function useCliOptions() {
 *
 * @param name name of the option
 * @returns value of a CLI option
+* @example
+* ```ts
+* const verbose = useCliOption('verbose')
+* if (verbose) {
+*   console.log('Verbose mode enabled')
+* }
+* ```
 */
 function useCliOption(name) {
 	try {
@@ -228,7 +244,7 @@ function useCliOption(name) {
 		if (opt) {
 			for (const key of opt.keys) if (useCliOptions()[key]) return useCliOptions()[key];
 		}
-	} catch (error) {}
+	} catch {}
 	return useCliOptions()[name];
 }
 
@@ -334,7 +350,7 @@ function useCommandLookupHelp(lookupDepth = 3) {
 			break;
 		} catch (error) {
 			const variants = cliHelp.lookup(pathParams);
-			if (variants.length > 0) throw new Error(`Wrong command, did you mean:\n${variants.slice(0, 7).map((c) => `  $ ${cmd} ${c.main.command}`).join("\n")}`);
+			if (variants.length > 0) throw new Error(`Wrong command, did you mean:\n${variants.slice(0, 7).map((c) => `  $ ${cmd} ${c.main.command}`).join("\n")}`, { cause: error });
 		}
 	}
 	if (data) {

package/package.json

@@ -1,48 +1,48 @@
 {
   "name": "@wooksjs/event-cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "@wooksjs/event-cli",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
-    }
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/wooksjs/wooksjs.git",
-    "directory": "packages/event-cli"
-  },
   "keywords": [
-    "http",
-    "wooks",
+    "api",
+    "app",
     "composables",
-    "web",
     "framework",
-    "app",
-    "api",
+    "http",
+    "prostojs",
     "rest",
     "restful",
-    "prostojs"
+    "web",
+    "wooks"
   ],
-  "author": "Artem Maltsev",
-  "license": "MIT",
+  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-cli#readme",
   "bugs": {
     "url": "https://github.com/wooksjs/wooksjs/issues"
   },
-  "peerDependencies": {
-    "@prostojs/logger": "^0.4.3",
-    "@prostojs/router": "^0.2.1",
-    "@wooksjs/event-core": "^0.6.2",
-    "wooks": "^0.6.2"
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wooksjs/wooksjs.git",
+    "directory": "packages/event-cli"
+  },
+  "bin": {
+    "setup-skills": "scripts/setup-skills.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    }
   },
   "dependencies": {
     "@prostojs/cli-help": "^0.0.11",
@@ -50,11 +50,20 @@
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@wooksjs/event-core": "^0.6.4",
+    "wooks": "^0.6.4"
+  },
+  "peerDependencies": {
+    "@prostojs/logger": "^0.4.3",
+    "@prostojs/router": "^0.2.1",
+    "wooks": "^0.6.4",
+    "@wooksjs/event-core": "^0.6.4"
   },
-  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-cli#readme",
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs"
+    "build": "rolldown -c ../../rolldown.config.mjs",
+    "postinstall": "node scripts/setup-skills.js",
+    "setup-skills": "node scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

@@ -0,0 +1,77 @@
+#!/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

@@ -0,0 +1,35 @@
+---
+name: wooksjs-event-cli
+description: Wooks CLI framework — composable, command-line application framework for Node.js. Load when building CLI apps with wooks; defining CLI commands or using the wooks router for command routing; using CLI composables (useCliOptions, useCliOption, useCliHelp, useAutoHelp, useCommandLookupHelp, useRouteParams); creating custom event context composables; working with @wooksjs/event-core context store (init, get, set, hook); parsing CLI flags and options; generating command help and usage text; handling unknown commands; building multi-command CLI tools.
+---
+
+# @wooksjs/event-cli
+
+A composable CLI framework for Node.js built on async context (AsyncLocalStorage). Instead of imperative argument parsing libraries, you call composable functions (`useCliOptions()`, `useCliHelp()`, etc.) anywhere in your command handler — flags are parsed on demand and cached per invocation.
+
+## 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... |
+|--------|------|------------|
+| Event context (core machinery) | [event-core.md](event-core.md) | Understanding the context store API (`init`/`get`/`set`/`hook`), creating custom composables, lazy evaluation and caching, building your own `use*()` functions |
+| CLI app setup | [core.md](core.md) | Creating a CLI app, running commands, `createCliApp`, `app.run()`, error handling, unknown command handling, sharing routers, testing |
+| Commands & help | [commands.md](commands.md) | Defining commands with `app.cli()`, command syntax (args, aliases, options, examples), help generation (`useCliHelp`, `useAutoHelp`, `useCommandLookupHelp`), accessing flags (`useCliOptions`, `useCliOption`), route params in CLI |
+
+## Quick reference
+
+```ts
+import { useRouteParams } from '@wooksjs/event-core'
+import { createCliApp, useCliOptions } from '@wooksjs/event-cli'
+
+const app = createCliApp()
+app.cli('greet/:name', () => {
+  const { get } = useRouteParams<{ name: string }>()
+  const flags = useCliOptions()
+  return `Hello, ${get('name')}!`
+})
+app.run()
+```
+
+Key composables: `useCliOptions()`, `useCliOption(name)`, `useCliHelp()`, `useAutoHelp()`, `useCommandLookupHelp()`, `useRouteParams()`, `useEventId()`, `useEventLogger()`.