@a2a-wrapper/core 1.2.0

package/dist/utils/logger.js

@@ -0,0 +1,244 @@
+/**
+ * @module utils/logger
+ *
+ * Structured, leveled logging with child-logger support and configurable root names.
+ *
+ * This module provides the logging infrastructure for all A2A wrapper projects.
+ * Each wrapper creates its own root logger via {@link createLogger}, avoiding
+ * hardcoded singletons and enabling independent log hierarchies per project.
+ *
+ * Output format: `[ISO_timestamp] [LEVEL] [name] message {data}`
+ *
+ * - ERROR messages route to `console.error`
+ * - WARN messages route to `console.warn`
+ * - DEBUG and INFO messages route to `console.log`
+ *
+ * @example
+ * ```ts
+ * import { createLogger, LogLevel } from '@a2a-wrapper/core';
+ *
+ * const logger = createLogger('a2a-copilot');
+ * logger.setLevel(LogLevel.DEBUG);
+ *
+ * const child = logger.child('session');
+ * child.info('session started', { contextId: 'abc-123' });
+ * // => [2024-01-15T10:30:00.000Z] [INFO] [a2a-copilot:session] session started {"contextId":"abc-123"}
+ * ```
+ */
+/**
+ * Numeric log levels controlling message suppression.
+ *
+ * Messages are emitted only when their level is greater than or equal to the
+ * logger's configured minimum level. Lower numeric values represent more
+ * verbose output.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    /** Verbose diagnostic output, typically disabled in production. */
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    /** General operational messages indicating normal behavior. */
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    /** Potentially harmful situations that deserve attention. */
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    /** Failures requiring immediate investigation. */
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Human-readable label for each {@link LogLevel}, used in formatted output.
+ *
+ * @internal
+ */
+const LEVEL_NAMES = {
+    [LogLevel.DEBUG]: "DEBUG",
+    [LogLevel.INFO]: "INFO",
+    [LogLevel.WARN]: "WARN",
+    [LogLevel.ERROR]: "ERROR",
+};
+/**
+ * Structured logger with hierarchical naming and runtime level control.
+ *
+ * Each Logger instance has a `name` (used as a prefix in output) and a minimum
+ * {@link LogLevel}. Child loggers inherit the parent's level at creation time
+ * and format their name as `{parent}:{child}`.
+ *
+ * @example
+ * ```ts
+ * const root = new Logger('myApp', LogLevel.DEBUG);
+ * const child = root.child('http');
+ * child.info('request received', { method: 'GET', path: '/' });
+ * ```
+ */
+export class Logger {
+    /**
+     * Dot-colon-separated name identifying this logger in output.
+     *
+     * @readonly
+     */
+    name;
+    /**
+     * Current minimum log level. Messages below this level are suppressed.
+     */
+    level;
+    /**
+     * Creates a new Logger instance.
+     *
+     * @param name  - Identifier included in every log line (e.g. `"a2a-copilot"` or `"a2a-copilot:session"`).
+     * @param level - Minimum log level; defaults to {@link LogLevel.INFO}.
+     */
+    constructor(name, level = LogLevel.INFO) {
+        this.name = name;
+        this.level = level;
+    }
+    /**
+     * Changes the minimum log level at runtime.
+     *
+     * All subsequent calls to {@link debug}, {@link info}, {@link warn}, and
+     * {@link error} will be filtered against the new level.
+     *
+     * @param level - The new minimum {@link LogLevel}.
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Parses a string into a {@link LogLevel}.
+     *
+     * Matching is case-insensitive. The string `"warning"` is accepted as an
+     * alias for {@link LogLevel.WARN}. Unrecognized strings default to
+     * {@link LogLevel.INFO}.
+     *
+     * @param str - The string to parse (e.g. `"debug"`, `"WARN"`, `"error"`).
+     * @returns The corresponding {@link LogLevel} value.
+     */
+    static parseLevel(str) {
+        switch (str.toLowerCase()) {
+            case "debug":
+                return LogLevel.DEBUG;
+            case "warn":
+            case "warning":
+                return LogLevel.WARN;
+            case "error":
+                return LogLevel.ERROR;
+            default:
+                return LogLevel.INFO;
+        }
+    }
+    /**
+     * Creates a child logger that inherits this logger's current level.
+     *
+     * The child's name is formatted as `{parentName}:{childName}`, producing
+     * a colon-separated hierarchy visible in log output.
+     *
+     * @param childName - Short identifier appended to the parent name.
+     * @returns A new {@link Logger} instance with the composite name.
+     *
+     * @example
+     * ```ts
+     * const root = createLogger('app');
+     * const child = root.child('db');
+     * const grandchild = child.child('query');
+     * // grandchild.name === 'app:db:query'
+     * ```
+     */
+    child(childName) {
+        return new Logger(`${this.name}:${childName}`, this.level);
+    }
+    /**
+     * Logs a message at {@link LogLevel.DEBUG}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    debug(msg, data) {
+        this.write(LogLevel.DEBUG, msg, data);
+    }
+    /**
+     * Logs a message at {@link LogLevel.INFO}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    info(msg, data) {
+        this.write(LogLevel.INFO, msg, data);
+    }
+    /**
+     * Logs a message at {@link LogLevel.WARN}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    warn(msg, data) {
+        this.write(LogLevel.WARN, msg, data);
+    }
+    /**
+     * Logs a message at {@link LogLevel.ERROR}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    error(msg, data) {
+        this.write(LogLevel.ERROR, msg, data);
+    }
+    /**
+     * Internal method that formats and emits a log line if the message level
+     * meets or exceeds the configured minimum.
+     *
+     * Output format: `[ISO_timestamp] [LEVEL] [name] message {data}`
+     *
+     * Routing:
+     * - {@link LogLevel.ERROR} → `console.error`
+     * - {@link LogLevel.WARN} → `console.warn`
+     * - All others → `console.log`
+     *
+     * @param level - The severity level of this message.
+     * @param msg   - Human-readable log message.
+     * @param data  - Optional structured data serialized as JSON.
+     *
+     * @internal
+     */
+    write(level, msg, data) {
+        if (level < this.level)
+            return;
+        const ts = new Date().toISOString();
+        const prefix = `[${ts}] [${LEVEL_NAMES[level]}] [${this.name}]`;
+        const line = data
+            ? `${prefix} ${msg} ${JSON.stringify(data)}`
+            : `${prefix} ${msg}`;
+        if (level === LogLevel.ERROR) {
+            console.error(line);
+        }
+        else if (level === LogLevel.WARN) {
+            console.warn(line);
+        }
+        else {
+            console.log(line);
+        }
+    }
+}
+/**
+ * Creates a new root {@link Logger} instance with the given name.
+ *
+ * This is the recommended entry point for obtaining a logger. Each wrapper
+ * project should call this once with its own root name, then use
+ * {@link Logger.child} to create scoped loggers for subsystems.
+ *
+ * Unlike a singleton, this factory allows multiple independent logger
+ * hierarchies to coexist — one per wrapper project or test suite.
+ *
+ * @param rootName - The root identifier for the logger hierarchy
+ *                   (e.g. `"a2a-copilot"`, `"a2a-opencode"`).
+ * @returns A new {@link Logger} instance with the default level {@link LogLevel.INFO}.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from '@a2a-wrapper/core';
+ *
+ * const logger = createLogger('a2a-copilot');
+ * const sessionLog = logger.child('session');
+ * sessionLog.info('ready');
+ * ```
+ */
+export function createLogger(rootName) {
+    return new Logger(rootName);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@a2a-wrapper/core",
+  "version": "1.2.0",
+  "description": "Shared infrastructure core for A2A protocol wrapper projects. Provides logging, configuration loading, event publishing, agent card building, server bootstrapping, session management, and CLI scaffolding.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@a2a-js/sdk": "^0.3.9",
+    "express": "^4.18.2",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@a2a-js/sdk": "^0.3.13",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "@types/supertest": "^7.2.0",
+    "@types/uuid": "^9.0.7",
+    "express": "^5.2.1",
+    "fast-check": "^3.15.0",
+    "supertest": "^7.2.2",
+    "typescript": "^5.3.0",
+    "uuid": "^13.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shashikanth-gs/a2a-wrapper.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/shashikanth-gs/a2a-wrapper/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/shashikanth-gs/a2a-wrapper/issues"
+  },
+  "license": "MIT"
+}