@moostjs/event-ws 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import * as moost from 'moost';
+import { TMoostAdapter, Moost, TConsoleBase, TMoostAdapterOptions } from 'moost';
+export { Controller, Description, Intercept, Param, TInterceptorPriority, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor } from 'moost';
+import { WooksWs, TWooksWsOptions } from '@wooksjs/event-ws';
+export { TTestWsConnectionContext, TTestWsMessageContext, TWooksWsOptions, WooksWs, WsBroadcastOptions, WsBroadcastTransport, WsClientMessage, WsConnection, WsError, WsPushMessage, WsReplyMessage, WsRoomManager, WsServerAdapter, WsSocket, currentConnection, prepareTestWsConnectionContext, prepareTestWsMessageContext, useWsConnection, useWsMessage, useWsRooms, useWsServer, wsConnectionKind, wsMessageKind } from '@wooksjs/event-ws';
+
+/**
+ * ## Define WebSocket Message Handler
+ * ### @MethodDecorator
+ *
+ * Registers a handler for routed WebSocket messages.
+ * The event and path correspond to the WsClientMessage protocol fields.
+ *
+ * @param event - message event type (e.g. "message", "rpc", "subscribe")
+ * @param path - route path with optional params (e.g. "/chat/rooms/:roomId")
+ */
+declare function Message(event: string, path?: string): MethodDecorator;
+/**
+ * ## Define WebSocket Connection Handler
+ * ### @MethodDecorator
+ *
+ * Registers a handler that runs when a new WebSocket connection is established.
+ * Runs inside the connection context. Throwing or rejecting closes the connection.
+ */
+declare function Connect(): MethodDecorator;
+/**
+ * ## Define WebSocket Disconnection Handler
+ * ### @MethodDecorator
+ *
+ * Registers a handler that runs when a WebSocket connection closes.
+ */
+declare function Disconnect(): MethodDecorator;
+
+/**
+ * Get the parsed WebSocket message payload.
+ * Only available in message handlers (@Message).
+ * @decorator
+ * @paramType T
+ */
+declare function MessageData(): ParameterDecorator & PropertyDecorator;
+/**
+ * Get the raw WebSocket message (Buffer or string before parsing).
+ * Only available in message handlers (@Message).
+ * @decorator
+ * @paramType Buffer | string
+ */
+declare function RawMessage(): ParameterDecorator & PropertyDecorator;
+/**
+ * Get the WebSocket message correlation ID.
+ * Only available in message handlers (@Message).
+ * @decorator
+ * @paramType string | number | undefined
+ */
+declare function MessageId(): ParameterDecorator & PropertyDecorator;
+/**
+ * Get the WebSocket message event type.
+ * Only available in message handlers (@Message).
+ * @decorator
+ * @paramType string
+ */
+declare function MessageType(): ParameterDecorator & PropertyDecorator;
+/**
+ * Get the WebSocket message path.
+ * Only available in message handlers (@Message).
+ * @decorator
+ * @paramType string
+ */
+declare function MessagePath(): ParameterDecorator & PropertyDecorator;
+/**
+ * Get the WebSocket connection ID (UUID).
+ * Available in all WS handlers (@Message, @Connect, @Disconnect).
+ * @decorator
+ * @paramType string
+ */
+declare function ConnectionId(): ParameterDecorator & PropertyDecorator;
+
+/** Handler metadata for routed WebSocket message events. */
+interface TWsMessageHandlerMeta {
+    event: string;
+    path: string;
+}
+/** Handler metadata for WebSocket connection events. */
+interface TWsConnectHandlerMeta {
+}
+/** Union of all WebSocket handler metadata types. */
+type TWsHandlerMeta = TWsMessageHandlerMeta | TWsConnectHandlerMeta;
+/** Configuration options for the MoostWs adapter. */
+interface TMoostWsOpts {
+    /**
+     * WooksWs options or instance
+     */
+    wooksWs?: WooksWs | TWooksWsOptions;
+}
+/**
+ * ## Moost WebSocket Adapter
+ *
+ * Moost Adapter for WebSocket events, wrapping @wooksjs/event-ws.
+ * Supports standalone and HTTP-integrated modes.
+ *
+ * ### HTTP-integrated mode (recommended)
+ * ```ts
+ * |  import { MoostHttp, Upgrade } from '@moostjs/event-http'
+ * |  import { MoostWs, Message, MessageData } from '@moostjs/event-ws'
+ * |  import { Moost, Param, Controller, Injectable } from 'moost'
+ * |
+ * |  @Controller()
+ * |  class AppController {
+ * |      constructor(private ws: WooksWs) {}
+ * |
+ * |      @Upgrade('/ws')
+ * |      handleUpgrade() { return this.ws.upgrade() }
+ * |  }
+ * |
+ * |  @Controller('chat')
+ * |  class ChatController {
+ * |      @Message('message', 'rooms/:roomId')
+ * |      onMessage(@Param('roomId') roomId: string, @MessageData() data: unknown) {
+ * |          return { received: true, roomId }
+ * |      }
+ * |  }
+ * |
+ * |  const app = new Moost()
+ * |  const http = new MoostHttp()
+ * |  const ws = new MoostWs({ httpApp: http.getHttpApp() })
+ * |  app.adapter(http)
+ * |  app.adapter(ws)
+ * |  app.registerControllers(AppController, ChatController)
+ * |  http.listen(3000)
+ * |  app.init()
+ * ```
+ */
+declare class MoostWs implements TMoostAdapter<TWsHandlerMeta> {
+    protected opts?: (TMoostWsOpts & {
+        /**
+         * WooksHttp instance or an adapter with getHttpApp() for HTTP-integrated mode.
+         * When provided, the WS adapter shares the HTTP server.
+         * Use @Upgrade() decorator on a handler method to register the upgrade route.
+         */
+        httpApp?: {
+            getHttpApp(): unknown;
+        } | object;
+    }) | undefined;
+    readonly name = "ws";
+    protected wsApp: WooksWs;
+    constructor(opts?: (TMoostWsOpts & {
+        /**
+         * WooksHttp instance or an adapter with getHttpApp() for HTTP-integrated mode.
+         * When provided, the WS adapter shares the HTTP server.
+         * Use @Upgrade() decorator on a handler method to register the upgrade route.
+         */
+        httpApp?: {
+            getHttpApp(): unknown;
+        } | object;
+    }) | undefined);
+    getWsApp(): WooksWs;
+    /**
+     * Start a standalone WebSocket server (without HTTP integration).
+     */
+    listen(port: number, hostname?: string): Promise<void>;
+    /**
+     * Stop the server, close all connections, clean up heartbeat.
+     */
+    close(): void;
+    protected moost?: Moost;
+    onInit(moost: Moost): void;
+    getProvideRegistry(): moost.TProvideRegistry;
+    getLogger(): TConsoleBase;
+    bindHandler<T extends object = object>(opts: TMoostAdapterOptions<TWsHandlerMeta, T>): void;
+    protected bindMessageHandler<T extends object>(opts: TMoostAdapterOptions<TWsHandlerMeta, T>, handler: TWsMessageHandlerMeta & {
+        type: string;
+    }): void;
+    protected bindConnectHandler<T extends object>(opts: TMoostAdapterOptions<TWsHandlerMeta, T>): void;
+    protected bindDisconnectHandler<T extends object>(opts: TMoostAdapterOptions<TWsHandlerMeta, T>): void;
+}
+
+interface TWsAppOptions {
+    /**
+     * WooksWs configuration options
+     */
+    ws?: TWooksWsOptions;
+}
+/**
+ * Quick WS App factory class.
+ *
+ * Use this class to quickly build a standalone WebSocket application
+ * with controllers. It extends the Moost class and wraps MoostWs initialization.
+ *
+ * @example
+ * ```typescript
+ * import { WsApp } from '@moostjs/event-ws'
+ * import { ChatController } from './chat.controller.ts'
+ *
+ * new WsApp()
+ *   .controllers(ChatController)
+ *   .start(3000)
+ * ```
+ */
+declare class WsApp extends Moost {
+    protected _wsOpts?: TWsAppOptions;
+    protected _wsAdapter?: MoostWs;
+    /**
+     * Registers one or more WS controllers.
+     *
+     * (Shortcut for `registerControllers` method.)
+     */
+    controllers(...controllers: (object | Function | [string, object | Function])[]): this;
+    /**
+     * Configures the WS options.
+     */
+    useWsOptions(wsOpts: TWsAppOptions): this;
+    /**
+     * Returns the underlying MoostWs adapter instance.
+     */
+    getWsAdapter(): MoostWs | undefined;
+    /**
+     * Starts the standalone WebSocket application.
+     *
+     * @param port - Port to listen on
+     * @param hostname - Optional hostname
+     */
+    start(port: number, hostname?: string): Promise<void>;
+}
+
+export { Connect, ConnectionId, Disconnect, Message, MessageData, MessageId, MessagePath, MessageType, MoostWs, RawMessage, WsApp };
+export type { TMoostWsOpts, TWsConnectHandlerMeta, TWsHandlerMeta, TWsMessageHandlerMeta };

package/dist/index.mjs

@@ -0,0 +1,298 @@
+import { Controller, Description, Intercept, Moost, Param, Resolve, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor, defineMoostEventHandler, getMoostMate } from "moost";
+import { WooksWs, WooksWs as WooksWs$1, WsError, WsRoomManager, createWsApp, currentConnection, prepareTestWsConnectionContext, prepareTestWsMessageContext, useWsConnection, useWsConnection as useWsConnection$1, useWsMessage, useWsMessage as useWsMessage$1, useWsRooms, useWsServer, wsConnectionKind, wsMessageKind } from "@wooksjs/event-ws";
+import { createProvideRegistry } from "@prostojs/infact";
+
+//#region packages/event-ws/src/decorators/ws-method.decorator.ts
+/**
+* ## Define WebSocket Message Handler
+* ### @MethodDecorator
+*
+* Registers a handler for routed WebSocket messages.
+* The event and path correspond to the WsClientMessage protocol fields.
+*
+* @param event - message event type (e.g. "message", "rpc", "subscribe")
+* @param path - route path with optional params (e.g. "/chat/rooms/:roomId")
+*/ function Message(event, path) {
+	return getMoostMate().decorate("handlers", {
+		event,
+		path,
+		type: "WS_MESSAGE"
+	}, true);
+}
+/**
+* ## Define WebSocket Connection Handler
+* ### @MethodDecorator
+*
+* Registers a handler that runs when a new WebSocket connection is established.
+* Runs inside the connection context. Throwing or rejecting closes the connection.
+*/ function Connect() {
+	return getMoostMate().decorate("handlers", { type: "WS_CONNECT" }, true);
+}
+/**
+* ## Define WebSocket Disconnection Handler
+* ### @MethodDecorator
+*
+* Registers a handler that runs when a WebSocket connection closes.
+*/ function Disconnect() {
+	return getMoostMate().decorate("handlers", { type: "WS_DISCONNECT" }, true);
+}
+
+//#endregion
+//#region packages/event-ws/src/decorators/resolve.decorator.ts
+/**
+* Get the parsed WebSocket message payload.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType T
+*/ function MessageData() {
+	return Resolve(() => useWsMessage$1().data, "ws_data");
+}
+/**
+* Get the raw WebSocket message (Buffer or string before parsing).
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType Buffer | string
+*/ function RawMessage() {
+	return Resolve(() => useWsMessage$1().raw, "ws_raw");
+}
+/**
+* Get the WebSocket message correlation ID.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string | number | undefined
+*/ function MessageId() {
+	return Resolve(() => useWsMessage$1().id, "ws_message_id");
+}
+/**
+* Get the WebSocket message event type.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string
+*/ function MessageType() {
+	return Resolve(() => useWsMessage$1().event, "ws_event");
+}
+/**
+* Get the WebSocket message path.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string
+*/ function MessagePath() {
+	return Resolve(() => useWsMessage$1().path, "ws_path");
+}
+/**
+* Get the WebSocket connection ID (UUID).
+* Available in all WS handlers (@Message, @Connect, @Disconnect).
+* @decorator
+* @paramType string
+*/ function ConnectionId() {
+	return Resolve(() => useWsConnection$1().id, "ws_connection_id");
+}
+
+//#endregion
+//#region packages/event-ws/src/event-ws.ts
+function _define_property$1(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+const LOGGER_TITLE = "moost-ws";
+/**
+* ## Moost WebSocket Adapter
+*
+* Moost Adapter for WebSocket events, wrapping @wooksjs/event-ws.
+* Supports standalone and HTTP-integrated modes.
+*
+* ### HTTP-integrated mode (recommended)
+* ```ts
+* |  import { MoostHttp, Upgrade } from '@moostjs/event-http'
+* |  import { MoostWs, Message, MessageData } from '@moostjs/event-ws'
+* |  import { Moost, Param, Controller, Injectable } from 'moost'
+* |
+* |  @Controller()
+* |  class AppController {
+* |      constructor(private ws: WooksWs) {}
+* |
+* |      @Upgrade('/ws')
+* |      handleUpgrade() { return this.ws.upgrade() }
+* |  }
+* |
+* |  @Controller('chat')
+* |  class ChatController {
+* |      @Message('message', 'rooms/:roomId')
+* |      onMessage(@Param('roomId') roomId: string, @MessageData() data: unknown) {
+* |          return { received: true, roomId }
+* |      }
+* |  }
+* |
+* |  const app = new Moost()
+* |  const http = new MoostHttp()
+* |  const ws = new MoostWs({ httpApp: http.getHttpApp() })
+* |  app.adapter(http)
+* |  app.adapter(ws)
+* |  app.registerControllers(AppController, ChatController)
+* |  http.listen(3000)
+* |  app.init()
+* ```
+*/ var MoostWs = class MoostWs {
+	getWsApp() {
+		return this.wsApp;
+	}
+	/**
+	* Start a standalone WebSocket server (without HTTP integration).
+	*/ listen(port, hostname) {
+		return this.wsApp.listen(port, hostname);
+	}
+	/**
+	* Stop the server, close all connections, clean up heartbeat.
+	*/ close() {
+		return this.wsApp.close();
+	}
+	onInit(moost) {
+		this.moost = moost;
+	}
+	getProvideRegistry() {
+		return createProvideRegistry([MoostWs, () => this], ["MoostWs", () => this], [WooksWs$1, () => this.getWsApp()], ["WooksWs", () => this.getWsApp()]);
+	}
+	getLogger() {
+		return this.wsApp.getLogger("[moost-ws]");
+	}
+	bindHandler(opts) {
+		for (const handler of opts.handlers) if (handler.type === "WS_MESSAGE") this.bindMessageHandler(opts, handler);
+		else if (handler.type === "WS_CONNECT") this.bindConnectHandler(opts);
+		else if (handler.type === "WS_DISCONNECT") this.bindDisconnectHandler(opts);
+	}
+	bindMessageHandler(opts, handler) {
+		const event = handler.event;
+		const path = typeof handler.path === "string" ? handler.path : typeof opts.method === "string" ? opts.method : "";
+		const targetPath = `${`${opts.prefix || ""}/${path}`.replaceAll(/\/\/+/g, "/")}`;
+		const fn = defineMoostEventHandler({
+			contextType: "WS_MESSAGE",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			controllerName: opts.controllerName,
+			resolveArgs: opts.resolveArgs,
+			targetPath,
+			handlerType: handler.type
+		});
+		this.wsApp.onMessage(event, targetPath, fn);
+		opts.logHandler(`(ws:${event})${targetPath}`);
+		opts.register(handler, targetPath, []);
+	}
+	bindConnectHandler(opts) {
+		const fn = defineMoostEventHandler({
+			contextType: "WS_CONNECT",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			resolveArgs: opts.resolveArgs,
+			targetPath: "__ws_connect__",
+			handlerType: "WS_CONNECT"
+		});
+		this.wsApp.onConnect(fn);
+		opts.logHandler(`(ws:connect)`);
+		opts.register({ type: "WS_CONNECT" }, "__ws_connect__", []);
+	}
+	bindDisconnectHandler(opts) {
+		const fn = defineMoostEventHandler({
+			contextType: "WS_DISCONNECT",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			resolveArgs: opts.resolveArgs,
+			targetPath: "__ws_disconnect__",
+			handlerType: "WS_DISCONNECT"
+		});
+		this.wsApp.onDisconnect(fn);
+		opts.logHandler(`(ws:disconnect)`);
+		opts.register({ type: "WS_DISCONNECT" }, "__ws_disconnect__", []);
+	}
+	constructor(opts) {
+		_define_property$1(this, "opts", void 0);
+		_define_property$1(this, "name", void 0);
+		_define_property$1(this, "wsApp", void 0);
+		_define_property$1(this, "moost", void 0);
+		this.opts = opts;
+		this.name = "ws";
+		const wsOpts = opts?.wooksWs;
+		if (wsOpts && wsOpts instanceof WooksWs$1) this.wsApp = wsOpts;
+		else {
+			const httpApp = opts?.httpApp && "getHttpApp" in opts.httpApp ? opts.httpApp.getHttpApp() : opts?.httpApp;
+			if (httpApp) this.wsApp = createWsApp(httpApp, wsOpts || {});
+			else this.wsApp = createWsApp(wsOpts || {});
+		}
+	}
+};
+
+//#endregion
+//#region packages/event-ws/src/quick-ws.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+/**
+* Quick WS App factory class.
+*
+* Use this class to quickly build a standalone WebSocket application
+* with controllers. It extends the Moost class and wraps MoostWs initialization.
+*
+* @example
+* ```typescript
+* import { WsApp } from '@moostjs/event-ws'
+* import { ChatController } from './chat.controller.ts'
+*
+* new WsApp()
+*   .controllers(ChatController)
+*   .start(3000)
+* ```
+*/ var WsApp = class extends Moost {
+	/**
+	* Registers one or more WS controllers.
+	*
+	* (Shortcut for `registerControllers` method.)
+	*/ controllers(...controllers) {
+		return this.registerControllers(...controllers);
+	}
+	/**
+	* Configures the WS options.
+	*/ useWsOptions(wsOpts) {
+		this._wsOpts = wsOpts;
+		return this;
+	}
+	/**
+	* Returns the underlying MoostWs adapter instance.
+	*/ getWsAdapter() {
+		return this._wsAdapter;
+	}
+	/**
+	* Starts the standalone WebSocket application.
+	*
+	* @param port - Port to listen on
+	* @param hostname - Optional hostname
+	*/ async start(port, hostname) {
+		this._wsAdapter = new MoostWs({ wooksWs: this._wsOpts?.ws });
+		this.adapter(this._wsAdapter);
+		await this.init();
+		return this._wsAdapter.listen(port, hostname);
+	}
+	constructor(...args) {
+		super(...args), _define_property(this, "_wsOpts", void 0), _define_property(this, "_wsAdapter", void 0);
+	}
+};
+
+//#endregion
+export { Connect, ConnectionId, Controller, Description, Disconnect, Intercept, Message, MessageData, MessageId, MessagePath, MessageType, MoostWs, Param, RawMessage, WooksWs, WsApp, WsError, WsRoomManager, currentConnection, defineAfterInterceptor, defineBeforeInterceptor, defineInterceptor, prepareTestWsConnectionContext, prepareTestWsMessageContext, useWsConnection, useWsMessage, useWsRooms, useWsServer, wsConnectionKind, wsMessageKind };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@moostjs/event-ws",
+  "version": "0.6.0",
+  "description": "@moostjs/event-ws",
+  "keywords": [
+    "composables",
+    "framework",
+    "moost",
+    "moostjs",
+    "prostojs",
+    "websocket",
+    "wooksjs"
+  ],
+  "homepage": "https://github.com/moostjs/moostjs/tree/main/packages/event-ws#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-ws"
+  },
+  "bin": {
+    "moostjs-event-ws-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",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@wooksjs/event-ws": "^0.7.3"
+  },
+  "devDependencies": {
+    "vitest": "3.2.4"
+  },
+  "peerDependencies": {
+    "@prostojs/infact": "^0.4.1",
+    "@wooksjs/event-core": "^0.7.3",
+    "moost": "^0.6.0"
+  },
+  "scripts": {
+    "pub": "pnpm publish --access public",
+    "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-ws'
+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.`)
+}