@ashdev/codex-plugin-sdk 1.0.0

package/README.md

@@ -0,0 +1,260 @@
+# @ashdev/codex-plugin-sdk
+
+Official SDK for building Codex plugins. Provides type-safe interfaces, utilities, and a server framework for communicating with Codex via JSON-RPC over stdio.
+
+## Installation
+
+```bash
+npm install @ashdev/codex-plugin-sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  createMetadataPlugin,
+  type MetadataContentType,
+  type MetadataProvider,
+  type PluginManifest,
+} from "@ashdev/codex-plugin-sdk";
+
+// Define your plugin manifest
+const manifest = {
+  name: "metadata-my-plugin",
+  displayName: "My Plugin",
+  version: "1.0.0",
+  description: "A custom metadata provider",
+  author: "Your Name",
+  protocolVersion: "1.0",
+  capabilities: {
+    metadataProvider: ["series"] as MetadataContentType[],
+  },
+} as const satisfies PluginManifest & {
+  capabilities: { metadataProvider: MetadataContentType[] };
+};
+
+// Implement the MetadataProvider interface
+const provider: MetadataProvider = {
+  async search(params) {
+    // Search your data source
+    return {
+      results: [
+        {
+          externalId: "123",
+          title: "Example Series",
+          alternateTitles: [],
+          relevanceScore: 0.95,
+          preview: {
+            status: "ongoing",
+            genres: ["Action", "Adventure"],
+          },
+        },
+      ],
+    };
+  },
+
+  async get(params) {
+    // Fetch full metadata
+    return {
+      externalId: params.externalId,
+      externalUrl: `https://example.com/series/${params.externalId}`,
+      title: "Example Series",
+      alternateTitles: [],
+      summary: "An exciting series...",
+      status: "ongoing",
+      year: 2024,
+      genres: ["Action", "Adventure"],
+      tags: [],
+      authors: ["Author Name"],
+      artists: [],
+      externalLinks: [],
+    };
+  },
+
+  // Optional: implement match for auto-matching during library scans
+  async match(params) {
+    const result = await this.search({
+      query: params.title,
+      contentType: params.contentType,
+    });
+
+    return {
+      match: result.results[0] ?? null,
+      confidence: result.results[0] ? 0.8 : 0,
+    };
+  },
+};
+
+// Start the plugin
+createMetadataPlugin({ manifest, provider });
+```
+
+## Features
+
+- **Type-safe**: Full TypeScript support with interface contracts
+- **Protocol compliance**: Types match the Codex JSON-RPC protocol exactly
+- **Simple API**: Implement the `MetadataProvider` interface, SDK handles the rest
+- **Error handling**: Built-in error classes that map to JSON-RPC errors
+- **Logging**: Safe logging to stderr (stdout is reserved for protocol)
+
+## Concepts
+
+### Capabilities
+
+Plugins declare capabilities in their manifest. Each capability has a corresponding interface:
+
+| Capability | Interface | Description |
+|------------|-----------|-------------|
+| `metadataProvider` | `MetadataProvider` | Search and fetch metadata for content |
+
+The `metadataProvider` capability is an array of content types your plugin supports:
+
+```typescript
+capabilities: {
+  metadataProvider: ["series"] as MetadataContentType[],
+}
+```
+
+Supported content types: `"series"` (future: `"book"`)
+
+### Protocol Types
+
+The SDK provides TypeScript types that exactly match the Codex JSON-RPC protocol:
+
+- `MetadataSearchParams` / `MetadataSearchResponse` - Search parameters and results
+- `MetadataGetParams` / `PluginSeriesMetadata` - Get full metadata
+- `MetadataMatchParams` / `MetadataMatchResponse` - Auto-match content
+- `SearchResult` - Individual search result with `relevanceScore`
+
+### Relevance Score
+
+Search results must include a `relevanceScore` between 0.0 and 1.0:
+
+- `1.0` = Perfect match
+- `0.7-0.9` = Good match
+- `0.5-0.7` = Partial match
+- `< 0.5` = Weak match
+
+## API Reference
+
+### `createMetadataPlugin(options)`
+
+Creates and starts a metadata provider plugin.
+
+```typescript
+interface MetadataPluginOptions {
+  manifest: PluginManifest & { capabilities: { metadataProvider: MetadataContentType[] } };
+  provider: MetadataProvider;
+  onInitialize?: (params: InitializeParams) => void | Promise<void>;
+  logLevel?: "debug" | "info" | "warn" | "error";
+}
+```
+
+### `MetadataProvider`
+
+Interface for metadata provider plugins:
+
+```typescript
+interface MetadataProvider {
+  search(params: MetadataSearchParams): Promise<MetadataSearchResponse>;
+  get(params: MetadataGetParams): Promise<PluginSeriesMetadata>;
+  match?(params: MetadataMatchParams): Promise<MetadataMatchResponse>;
+}
+```
+
+### Error Handling
+
+Use built-in error classes for proper error responses:
+
+```typescript
+import { NotFoundError, RateLimitError, AuthError, ApiError } from "@ashdev/codex-plugin-sdk";
+
+// In your provider:
+async get(params) {
+  const data = await fetchFromApi(params.externalId);
+
+  if (!data) {
+    throw new NotFoundError(`Series ${params.externalId} not found`);
+  }
+
+  return data;
+}
+```
+
+### Logging
+
+Plugins should log to stderr (stdout is reserved for JSON-RPC):
+
+```typescript
+import { createLogger } from "@ashdev/codex-plugin-sdk";
+
+const logger = createLogger({ name: "my-plugin", level: "debug" });
+logger.info("Plugin started");
+logger.debug("Processing request", { query: "..." });
+logger.error("Failed to fetch", error);
+```
+
+## Credentials
+
+Plugins can receive credentials (API keys, tokens) via the `onInitialize` callback:
+
+```typescript
+let apiKey: string | undefined;
+
+createMetadataPlugin({
+  manifest,
+  provider,
+  onInitialize(params) {
+    apiKey = params.credentials?.api_key;
+  },
+});
+```
+
+Credentials are configured by admins in Codex and delivered securely to the plugin.
+
+## Protocol
+
+Plugins communicate with Codex via JSON-RPC 2.0 over stdio:
+
+- **stdin**: Receives JSON-RPC requests (one per line)
+- **stdout**: Sends JSON-RPC responses (one per line)
+- **stderr**: Logging output (visible in Codex logs)
+
+## Building Your Plugin
+
+1. Create a new npm package
+2. Install the SDK: `npm install @ashdev/codex-plugin-sdk`
+3. Implement your provider
+4. Bundle with esbuild (include shebang for npx support):
+
+```json
+{
+  "name": "@your-org/plugin-metadata-example",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "bin": "dist/index.js",
+  "type": "module",
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --sourcemap --banner:js='#!/usr/bin/env node'",
+    "prepublishOnly": "npm run lint && npm run build"
+  }
+}
+```
+
+**Key fields for npx support:**
+- `bin`: Points to the entry file, tells npx what to execute
+- `--banner:js='#!/usr/bin/env node'`: Adds shebang so the file is directly executable
+- `files`: Only publish dist and README to npm
+
+## Example Plugins
+
+- [`@ashdev/codex-plugin-metadata-echo`](https://github.com/AshDevFr/codex/tree/main/plugins/metadata-echo) - Test metadata plugin that echoes back queries
+- [`@ashdev/codex-plugin-metadata-mangabaka`](https://github.com/AshDevFr/codex/tree/main/plugins/metadata-mangabaka) - MangaBaka metadata provider
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin error classes for structured error handling
+ */
+import { type JsonRpcError } from "./types/rpc.js";
+/**
+ * Base class for plugin errors that map to JSON-RPC errors
+ */
+export declare abstract class PluginError extends Error {
+    abstract readonly code: number;
+    readonly data?: unknown;
+    constructor(message: string, data?: unknown);
+    /**
+     * Convert to JSON-RPC error format
+     */
+    toJsonRpcError(): JsonRpcError;
+}
+/**
+ * Thrown when rate limited by an external API
+ */
+export declare class RateLimitError extends PluginError {
+    readonly code: -32001;
+    /** Seconds to wait before retrying */
+    readonly retryAfterSeconds: number;
+    constructor(retryAfterSeconds: number, message?: string);
+}
+/**
+ * Thrown when a requested resource is not found
+ */
+export declare class NotFoundError extends PluginError {
+    readonly code: -32002;
+}
+/**
+ * Thrown when authentication fails (invalid credentials)
+ */
+export declare class AuthError extends PluginError {
+    readonly code: -32003;
+    constructor(message?: string);
+}
+/**
+ * Thrown when an external API returns an error
+ */
+export declare class ApiError extends PluginError {
+    readonly code: -32004;
+    readonly statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Thrown when the plugin is misconfigured
+ */
+export declare class ConfigError extends PluginError {
+    readonly code: -32005;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,gBAAgB,CAAC;AAEvE;;GAEG;AACH,8BAAsB,WAAY,SAAQ,KAAK;IAC7C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAM3C;;OAEG;IACH,cAAc,IAAI,YAAY;CAO/B;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,QAAQ,CAAC,IAAI,SAAmC;IAChD,sCAAsC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBAEvB,iBAAiB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAMxD;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,SAAgC;CAC9C;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,WAAW;IACxC,QAAQ,CAAC,IAAI,SAAkC;gBAEnC,OAAO,CAAC,EAAE,MAAM;CAG7B;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACvC,QAAQ,CAAC,IAAI,SAAgC;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAIjD;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,WAAW;IAC1C,QAAQ,CAAC,IAAI,SAAmC;CACjD"}

package/dist/errors.js

@@ -0,0 +1,72 @@
+/**
+ * Plugin error classes for structured error handling
+ */
+import { PLUGIN_ERROR_CODES } from "./types/rpc.js";
+/**
+ * Base class for plugin errors that map to JSON-RPC errors
+ */
+export class PluginError extends Error {
+    data;
+    constructor(message, data) {
+        super(message);
+        this.name = this.constructor.name;
+        this.data = data;
+    }
+    /**
+     * Convert to JSON-RPC error format
+     */
+    toJsonRpcError() {
+        return {
+            code: this.code,
+            message: this.message,
+            data: this.data,
+        };
+    }
+}
+/**
+ * Thrown when rate limited by an external API
+ */
+export class RateLimitError extends PluginError {
+    code = PLUGIN_ERROR_CODES.RATE_LIMITED;
+    /** Seconds to wait before retrying */
+    retryAfterSeconds;
+    constructor(retryAfterSeconds, message) {
+        super(message ?? `Rate limited, retry after ${retryAfterSeconds}s`, {
+            retryAfterSeconds,
+        });
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/**
+ * Thrown when a requested resource is not found
+ */
+export class NotFoundError extends PluginError {
+    code = PLUGIN_ERROR_CODES.NOT_FOUND;
+}
+/**
+ * Thrown when authentication fails (invalid credentials)
+ */
+export class AuthError extends PluginError {
+    code = PLUGIN_ERROR_CODES.AUTH_FAILED;
+    constructor(message) {
+        super(message ?? "Authentication failed");
+    }
+}
+/**
+ * Thrown when an external API returns an error
+ */
+export class ApiError extends PluginError {
+    code = PLUGIN_ERROR_CODES.API_ERROR;
+    statusCode;
+    constructor(message, statusCode) {
+        super(message, statusCode !== undefined ? { statusCode } : undefined);
+        this.statusCode = statusCode;
+    }
+}
+/**
+ * Thrown when the plugin is misconfigured
+ */
+export class ConfigError extends PluginError {
+    code = PLUGIN_ERROR_CODES.CONFIG_ERROR;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAqB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;GAEG;AACH,MAAM,OAAgB,WAAY,SAAQ,KAAK;IAEpC,IAAI,CAAW;IAExB,YAAY,OAAe,EAAE,IAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC;IACJ,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IACpC,IAAI,GAAG,kBAAkB,CAAC,YAAY,CAAC;IAChD,sCAAsC;IAC7B,iBAAiB,CAAS;IAEnC,YAAY,iBAAyB,EAAE,OAAgB;QACrD,KAAK,CAAC,OAAO,IAAI,6BAA6B,iBAAiB,GAAG,EAAE;YAClE,iBAAiB;SAClB,CAAC,CAAC;QACH,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC7C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IACnC,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,WAAW;IAC/B,IAAI,GAAG,kBAAkB,CAAC,WAAW,CAAC;IAE/C,YAAY,OAAgB;QAC1B,KAAK,CAAC,OAAO,IAAI,uBAAuB,CAAC,CAAC;IAC5C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,WAAW;IAC9B,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC;IACpC,UAAU,CAAqB;IAExC,YAAY,OAAe,EAAE,UAAmB;QAC9C,KAAK,CAAC,OAAO,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,WAAW;IACjC,IAAI,GAAG,kBAAkB,CAAC,YAAY,CAAC;CACjD"}

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @ashdev/codex-plugin-sdk
+ *
+ * SDK for building Codex plugins. Provides types, utilities, and a server
+ * framework for communicating with Codex via JSON-RPC over stdio.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createMetadataPlugin,
+ *   type MetadataProvider,
+ *   type PluginManifest,
+ * } from "@ashdev/codex-plugin-sdk";
+ *
+ * const manifest: PluginManifest = {
+ *   name: "my-plugin",
+ *   displayName: "My Plugin",
+ *   version: "1.0.0",
+ *   description: "A custom metadata plugin",
+ *   author: "Your Name",
+ *   protocolVersion: "1.0",
+ *   capabilities: { metadataProvider: ["series"] },
+ * };
+ *
+ * const provider: MetadataProvider = {
+ *   async search(params) {
+ *     return {
+ *       results: [{
+ *         externalId: "123",
+ *         title: "Example",
+ *         alternateTitles: [],
+ *         relevanceScore: 0.95,
+ *       }],
+ *     };
+ *   },
+ *   async get(params) {
+ *     return {
+ *       externalId: params.externalId,
+ *       externalUrl: "https://example.com/123",
+ *       alternateTitles: [],
+ *       genres: [],
+ *       tags: [],
+ *       authors: [],
+ *       artists: [],
+ *       externalLinks: [],
+ *     };
+ *   },
+ * };
+ *
+ * createMetadataPlugin({ manifest, provider });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ApiError, AuthError, ConfigError, NotFoundError, PluginError, RateLimitError, } from "./errors.js";
+export { createLogger, Logger, type LoggerOptions, type LogLevel } from "./logger.js";
+export { createMetadataPlugin, createSeriesMetadataPlugin, type InitializeParams, type MetadataPluginOptions, type SeriesMetadataPluginOptions, } from "./server.js";
+export * from "./types/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtF,OAAO,EAEL,oBAAoB,EAEpB,0BAA0B,EAC1B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,GACjC,MAAM,aAAa,CAAC;AAGrB,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,67 @@
+/**
+ * @ashdev/codex-plugin-sdk
+ *
+ * SDK for building Codex plugins. Provides types, utilities, and a server
+ * framework for communicating with Codex via JSON-RPC over stdio.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createMetadataPlugin,
+ *   type MetadataProvider,
+ *   type PluginManifest,
+ * } from "@ashdev/codex-plugin-sdk";
+ *
+ * const manifest: PluginManifest = {
+ *   name: "my-plugin",
+ *   displayName: "My Plugin",
+ *   version: "1.0.0",
+ *   description: "A custom metadata plugin",
+ *   author: "Your Name",
+ *   protocolVersion: "1.0",
+ *   capabilities: { metadataProvider: ["series"] },
+ * };
+ *
+ * const provider: MetadataProvider = {
+ *   async search(params) {
+ *     return {
+ *       results: [{
+ *         externalId: "123",
+ *         title: "Example",
+ *         alternateTitles: [],
+ *         relevanceScore: 0.95,
+ *       }],
+ *     };
+ *   },
+ *   async get(params) {
+ *     return {
+ *       externalId: params.externalId,
+ *       externalUrl: "https://example.com/123",
+ *       alternateTitles: [],
+ *       genres: [],
+ *       tags: [],
+ *       authors: [],
+ *       artists: [],
+ *       externalLinks: [],
+ *     };
+ *   },
+ * };
+ *
+ * createMetadataPlugin({ manifest, provider });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Errors
+export { ApiError, AuthError, ConfigError, NotFoundError, PluginError, RateLimitError, } from "./errors.js";
+// Logger
+export { createLogger, Logger } from "./logger.js";
+// Server
+export { 
+// Primary exports
+createMetadataPlugin, 
+// Deprecated aliases
+createSeriesMetadataPlugin, } from "./server.js";
+// Types
+export * from "./types/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,SAAS;AACT,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,EAAqC,MAAM,aAAa,CAAC;AACtF,SAAS;AACT,OAAO;AACL,kBAAkB;AAClB,oBAAoB;AACpB,qBAAqB;AACrB,0BAA0B,GAI3B,MAAM,aAAa,CAAC;AAErB,QAAQ;AACR,cAAc,kBAAkB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Logging utilities for plugins
+ *
+ * IMPORTANT: Plugins must ONLY write to stderr for logging.
+ * stdout is reserved for JSON-RPC communication.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LoggerOptions {
+    /** Plugin name to prefix log messages */
+    name: string;
+    /** Minimum log level (default: "info") */
+    level?: LogLevel;
+    /** Whether to include timestamps (default: true) */
+    timestamps?: boolean;
+}
+/**
+ * Logger that writes to stderr (safe for plugins)
+ */
+export declare class Logger {
+    private readonly name;
+    private readonly minLevel;
+    private readonly timestamps;
+    constructor(options: LoggerOptions);
+    private shouldLog;
+    private format;
+    private log;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * Create a logger for a plugin
+ */
+export declare function createLogger(options: LoggerOptions): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAS3D,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,oDAAoD;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;gBAEzB,OAAO,EAAE,aAAa;IAMlC,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,MAAM;IA2Bd,OAAO,CAAC,GAAG;IAOX,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAI3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CAG7C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAE3D"}

package/dist/logger.js

@@ -0,0 +1,77 @@
+/**
+ * Logging utilities for plugins
+ *
+ * IMPORTANT: Plugins must ONLY write to stderr for logging.
+ * stdout is reserved for JSON-RPC communication.
+ */
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Logger that writes to stderr (safe for plugins)
+ */
+export class Logger {
+    name;
+    minLevel;
+    timestamps;
+    constructor(options) {
+        this.name = options.name;
+        this.minLevel = LOG_LEVELS[options.level ?? "info"];
+        this.timestamps = options.timestamps ?? true;
+    }
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= this.minLevel;
+    }
+    format(level, message, data) {
+        const parts = [];
+        if (this.timestamps) {
+            parts.push(new Date().toISOString());
+        }
+        parts.push(`[${level.toUpperCase()}]`);
+        parts.push(`[${this.name}]`);
+        parts.push(message);
+        if (data !== undefined) {
+            if (data instanceof Error) {
+                parts.push(`- ${data.message}`);
+                if (data.stack) {
+                    parts.push(`\n${data.stack}`);
+                }
+            }
+            else if (typeof data === "object") {
+                parts.push(`- ${JSON.stringify(data)}`);
+            }
+            else {
+                parts.push(`- ${String(data)}`);
+            }
+        }
+        return parts.join(" ");
+    }
+    log(level, message, data) {
+        if (this.shouldLog(level)) {
+            // Write to stderr (not stdout!) - stdout is for JSON-RPC only
+            process.stderr.write(`${this.format(level, message, data)}\n`);
+        }
+    }
+    debug(message, data) {
+        this.log("debug", message, data);
+    }
+    info(message, data) {
+        this.log("info", message, data);
+    }
+    warn(message, data) {
+        this.log("warn", message, data);
+    }
+    error(message, data) {
+        this.log("error", message, data);
+    }
+}
+/**
+ * Create a logger for a plugin
+ */
+export function createLogger(options) {
+    return new Logger(options);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}