@moostjs/event-cli 0.5.33 → 0.6.0

package/README.md

@@ -29,13 +29,35 @@ You can also provide a name for your project:
 npm create moost my-cli-app -- --cli
 ```
 
-This command will initiate a setup tool that will guide you through the project initialization process. It will prompt you to make certain choices such as:
+This command will initiate a setup tool that will guide you through the project initialization process. It will prompt you to configure:
 
-- Whether you want to integrate eslint and prettier.
-- Which bundler you prefer to use: esbuild or rollup.
+- Project and package name.
+- Whether to add do-me-lint (smart eslint installer).
 
 ## [Official Documentation](https://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 moostjs-event-cli-skill
+
+# Global (available across all your projects)
+npx moostjs-event-cli-skill --global
+```
+
+To keep skills automatically up-to-date, add a postinstall script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "moostjs-event-cli-skill --postinstall"
+  }
+}
+```
+
 ## Contributing
 
 We are excited to welcome contributors who are passionate about improving Moostjs. No matter your level of experience, your unique perspective and skills can make valuable contributions to our growing community.

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const moost = __toESM(require("moost"));
 const __wooksjs_event_cli = __toESM(require("@wooksjs/event-cli"));
+const __wooksjs_event_core = __toESM(require("@wooksjs/event-core"));
 
 //#region packages/event-cli/src/meta-types.ts
 function getCliMate() {
@@ -47,7 +48,7 @@ function getCliMate() {
 * @returns
 */ function Cli(path) {
 	return getCliMate().decorate("handlers", {
-		path: path?.replace(/\s+/g, "/"),
+		path: path?.replaceAll(/\s+/g, "/"),
 		type: "CLI"
 	}, true);
 }
@@ -164,7 +165,7 @@ const CONTEXT_TYPE = "CLI";
 * ```
 */ var MoostCli = class {
 	async onNotFound() {
-		const pathParams = (0, __wooksjs_event_cli.useCliContext)().store("event").get("pathParams") || [];
+		const pathParams = (0, __wooksjs_event_core.current)().get(__wooksjs_event_cli.cliKind.keys.pathParams) || [];
 		const response = await (0, moost.defineMoostEventHandler)({
 			loggerTitle: LOGGER_TITLE,
 			getIterceptorHandler: () => this.moost?.getGlobalInterceptorHandler(),
@@ -187,8 +188,8 @@ const CONTEXT_TYPE = "CLI";
 		for (const handler of opts.handlers) {
 			if (handler.type !== "CLI") continue;
 			const path = typeof handler.path === "string" ? handler.path : typeof opts.method === "string" ? opts.method : "";
-			const prefix = opts.prefix.replace(/\s+/g, "/") || "";
-			const makePath = (p) => `${prefix}/${p}`.replace(/\/\/+/g, "/").replace(/\/\\:/g, "\\:").replace(/^\/+/g, "");
+			const prefix = opts.prefix.replaceAll(/\s+/g, "/") || "";
+			const makePath = (p) => `${prefix}/${p}`.replaceAll(/\/\/+/g, "/").replaceAll(/\/\\:/g, "\\:").replaceAll(/^\/+/g, "");
 			const targetPath = makePath(path);
 			fn = (0, moost.defineMoostEventHandler)({
 				contextType: CONTEXT_TYPE,
@@ -196,6 +197,7 @@ const CONTEXT_TYPE = "CLI";
 				getIterceptorHandler: opts.getIterceptorHandler,
 				getControllerInstance: opts.getInstance,
 				controllerMethod: opts.method,
+				controllerName: opts.controllerName,
 				resolveArgs: opts.resolveArgs,
 				logErrors: this.opts?.debug,
 				targetPath,
@@ -285,10 +287,13 @@ const aliasTypes = [
 * new Moost().applyGlobalInterceptors(cliHelpInterceptor({ colors: true }))
 * ```
 * @param opts {} { helpOptions: ['help', 'h'], colors: true } cli options to invoke help renderer
-* @returns TInterceptorFn
-*/ const cliHelpInterceptor = (opts) => (0, moost.defineInterceptorFn)(() => {
+* @returns TInterceptorDef
+*/ const cliHelpInterceptor = (opts) => (0, moost.defineBeforeInterceptor)((reply) => {
 	try {
-		if ((0, __wooksjs_event_cli.useAutoHelp)(opts?.helpOptions, opts?.colors)) return "";
+		if ((0, __wooksjs_event_cli.useAutoHelp)(opts?.helpOptions, opts?.colors)) {
+			reply("");
+			return;
+		}
 	} catch (error) {}
 	if (opts?.lookupLevel) {
 		const { getMethod } = (0, moost.useControllerContext)();
@@ -453,9 +458,27 @@ Object.defineProperty(exports, 'Param', {
   }
 });
 exports.cliHelpInterceptor = cliHelpInterceptor;
-Object.defineProperty(exports, 'useCliContext', {
+Object.defineProperty(exports, 'cliKind', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_cli.cliKind;
+  }
+});
+Object.defineProperty(exports, 'defineAfterInterceptor', {
+  enumerable: true,
+  get: function () {
+    return moost.defineAfterInterceptor;
+  }
+});
+Object.defineProperty(exports, 'defineBeforeInterceptor', {
+  enumerable: true,
+  get: function () {
+    return moost.defineBeforeInterceptor;
+  }
+});
+Object.defineProperty(exports, 'defineInterceptor', {
   enumerable: true,
   get: function () {
-    return __wooksjs_event_cli.useCliContext;
+    return moost.defineInterceptor;
   }
 });

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { WooksCli, TWooksCliOptions } from '@wooksjs/event-cli';
-export { useCliContext } from '@wooksjs/event-cli';
+export { cliKind } from '@wooksjs/event-cli';
 import * as moost from 'moost';
-import { TMoostAdapter, Moost, TMoostAdapterOptions } from 'moost';
-export { Controller, Description, Intercept, Optional, Param, TInterceptorPriority, defineInterceptorFn } from 'moost';
+import { TFunction, TMoostAdapter, Moost, TMoostAdapterOptions } from 'moost';
+export { Controller, Description, Intercept, Optional, Param, TInterceptorPriority, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor } from 'moost';
 
 /**
  * ## Define CLI Command
@@ -74,11 +74,11 @@ declare function CliGlobalOption(option: {
     value?: string;
 }): ClassDecorator;
 
-type TFunction = Function;
-
+/** Handler metadata for CLI events, carrying the command path. */
 interface TCliHandlerMeta {
     path: string;
 }
+/** Configuration options for the MoostCli adapter. */
 interface TMoostCliOpts {
     /**
      * WooksCli options or instance
@@ -91,11 +91,11 @@ interface TMoostCliOpts {
     /**
      * Array of cli options applicable to every cli command
      */
-    globalCliOptions?: Array<{
+    globalCliOptions?: {
         keys: string[];
         description?: string;
         type?: TFunction;
-    }>;
+    }[];
 }
 /**
  * ## Moost Cli Adapter
@@ -149,7 +149,7 @@ declare class MoostCli implements TMoostAdapter<TCliHandlerMeta> {
  * new Moost().applyGlobalInterceptors(cliHelpInterceptor({ colors: true }))
  * ```
  * @param opts {} { helpOptions: ['help', 'h'], colors: true } cli options to invoke help renderer
- * @returns TInterceptorFn
+ * @returns TInterceptorDef
  */
 declare const cliHelpInterceptor: (opts?: {
     /**
@@ -167,7 +167,7 @@ declare const cliHelpInterceptor: (opts?: {
      * Enable lookup for a command
      */
     lookupLevel?: number;
-}) => moost.TInterceptorFn;
+}) => moost.TInterceptorDef;
 /**
  * ## @Decorator
  * ### Interceptor Factory for CliHelpRenderer
@@ -191,7 +191,7 @@ declare const cliHelpInterceptor: (opts?: {
  */
 declare const CliHelpInterceptor: (...opts: Parameters<typeof cliHelpInterceptor>) => ClassDecorator & MethodDecorator;
 
-type THelpOptions = {
+interface THelpOptions {
     name?: string;
     title?: string;
     maxWidth?: number;
@@ -199,7 +199,7 @@ type THelpOptions = {
     mark?: string;
     colors?: boolean;
     lookupLevel?: number;
-};
+}
 /**
  * Quick CLI App factory class.
  *
@@ -229,7 +229,7 @@ declare class CliApp extends Moost {
      *   Each controller can be an object, a class, or a tuple with a name and the controller.
      * @returns {this} The CliApp instance for method chaining.
      */
-    controllers(...controllers: Array<object | Function | [string, object | Function]>): this;
+    controllers(...controllers: (object | Function | [string, object | Function])[]): this;
     /**
      * Configures the CLI help options.
      *

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { Controller, Description, Intercept, Intercept as Intercept$1, Moost, Optional, Param, Resolve, TInterceptorPriority, defineInterceptorFn, defineMoostEventHandler, getMoostMate, setInfactLoggingOptions, useControllerContext } from "moost";
-import { WooksCli, createCliApp, useAutoHelp, useCliContext, useCliContext as useCliContext$1, useCliOption, useCommandLookupHelp } from "@wooksjs/event-cli";
+import { Controller, Description, Intercept, Intercept as Intercept$1, Moost, Optional, Param, Resolve, TInterceptorPriority, defineAfterInterceptor, defineBeforeInterceptor, defineBeforeInterceptor as defineBeforeInterceptor$1, defineInterceptor, defineMoostEventHandler, getMoostMate, setInfactLoggingOptions, useControllerContext } from "moost";
+import { WooksCli, cliKind, cliKind as cliKind$1, createCliApp, useAutoHelp, useCliOption, useCommandLookupHelp } from "@wooksjs/event-cli";
+import { current } from "@wooksjs/event-core";
 
 //#region packages/event-cli/src/meta-types.ts
 function getCliMate() {
@@ -24,7 +25,7 @@ function getCliMate() {
 * @returns
 */ function Cli(path) {
 	return getCliMate().decorate("handlers", {
-		path: path?.replace(/\s+/g, "/"),
+		path: path?.replaceAll(/\s+/g, "/"),
 		type: "CLI"
 	}, true);
 }
@@ -141,7 +142,7 @@ const CONTEXT_TYPE = "CLI";
 * ```
 */ var MoostCli = class {
 	async onNotFound() {
-		const pathParams = useCliContext$1().store("event").get("pathParams") || [];
+		const pathParams = current().get(cliKind$1.keys.pathParams) || [];
 		const response = await defineMoostEventHandler({
 			loggerTitle: LOGGER_TITLE,
 			getIterceptorHandler: () => this.moost?.getGlobalInterceptorHandler(),
@@ -164,8 +165,8 @@ const CONTEXT_TYPE = "CLI";
 		for (const handler of opts.handlers) {
 			if (handler.type !== "CLI") continue;
 			const path = typeof handler.path === "string" ? handler.path : typeof opts.method === "string" ? opts.method : "";
-			const prefix = opts.prefix.replace(/\s+/g, "/") || "";
-			const makePath = (p) => `${prefix}/${p}`.replace(/\/\/+/g, "/").replace(/\/\\:/g, "\\:").replace(/^\/+/g, "");
+			const prefix = opts.prefix.replaceAll(/\s+/g, "/") || "";
+			const makePath = (p) => `${prefix}/${p}`.replaceAll(/\/\/+/g, "/").replaceAll(/\/\\:/g, "\\:").replaceAll(/^\/+/g, "");
 			const targetPath = makePath(path);
 			fn = defineMoostEventHandler({
 				contextType: CONTEXT_TYPE,
@@ -173,6 +174,7 @@ const CONTEXT_TYPE = "CLI";
 				getIterceptorHandler: opts.getIterceptorHandler,
 				getControllerInstance: opts.getInstance,
 				controllerMethod: opts.method,
+				controllerName: opts.controllerName,
 				resolveArgs: opts.resolveArgs,
 				logErrors: this.opts?.debug,
 				targetPath,
@@ -262,10 +264,13 @@ const aliasTypes = [
 * new Moost().applyGlobalInterceptors(cliHelpInterceptor({ colors: true }))
 * ```
 * @param opts {} { helpOptions: ['help', 'h'], colors: true } cli options to invoke help renderer
-* @returns TInterceptorFn
-*/ const cliHelpInterceptor = (opts) => defineInterceptorFn(() => {
+* @returns TInterceptorDef
+*/ const cliHelpInterceptor = (opts) => defineBeforeInterceptor$1((reply) => {
 	try {
-		if (useAutoHelp(opts?.helpOptions, opts?.colors)) return "";
+		if (useAutoHelp(opts?.helpOptions, opts?.colors)) {
+			reply("");
+			return;
+		}
 	} catch (error) {}
 	if (opts?.lookupLevel) {
 		const { getMethod } = useControllerContext();
@@ -391,4 +396,4 @@ function _define_property(obj, key, value) {
 };
 
 //#endregion
-export { Cli, CliAlias, CliApp, CliExample, CliGlobalOption, CliHelpInterceptor, CliOption, Controller, Description, Intercept, MoostCli, Optional, Param, cliHelpInterceptor, useCliContext };
+export { Cli, CliAlias, CliApp, CliExample, CliGlobalOption, CliHelpInterceptor, CliOption, Controller, Description, Intercept, MoostCli, Optional, Param, cliHelpInterceptor, cliKind, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor };

package/package.json

@@ -1,12 +1,39 @@
 {
   "name": "@moostjs/event-cli",
-  "version": "0.5.33",
+  "version": "0.6.0",
   "description": "@moostjs/event-cli",
+  "keywords": [
+    "composables",
+    "framework",
+    "moost",
+    "moostjs",
+    "prostojs",
+    "wooksjs"
+  ],
+  "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/event-cli#readme",
+  "bugs": {
+    "url": "https://github.com/moostjs/moostjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "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"
+  ],
+  "type": "module",
+  "sideEffects": false,
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "type": "module",
-  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -15,41 +42,20 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/moostjs/moostjs.git",
-    "directory": "packages/event-cli"
-  },
-  "keywords": [
-    "moost",
-    "moostjs",
-    "composables",
-    "framework",
-    "wooksjs",
-    "prostojs"
-  ],
-  "author": "Artem Maltsev",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/moostjs/moostjs/issues"
-  },
-  "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/event-cli#readme",
-  "peerDependencies": {
-    "@wooksjs/event-core": "^0.6.2",
-    "wooks": "^0.6.2",
-    "moost": "^0.5.33"
-  },
   "dependencies": {
-    "@wooksjs/event-cli": "^0.6.2"
+    "@wooksjs/event-cli": "^0.7.3"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
+  "peerDependencies": {
+    "@wooksjs/event-core": "^0.7.3",
+    "wooks": "^0.7.3",
+    "moost": "^0.6.0"
+  },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest"
+    "test": "vitest",
+    "setup-skills": "node ./scripts/setup-skills.js"
   }
 }

package/scripts/setup-skills.js

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

@@ -0,0 +1,38 @@
+---
+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()
+```