@chronicle.app/logging 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @chronicle.app/logging
+
+Shared stderr logger for Chronicle. Node.js 22.13+; ESM with TypeScript declarations.
+
+```js
+import { createLogger } from '@chronicle.app/logging';
+
+const logger = createLogger({ prefix: '[extract]', verbose: true });
+logger.info('Extracted records', { count: 3 });
+logger.debug('Source cursor', { position: 3 });
+```
+
+All output goes to stderr so stdout stays available for extracted data. `quiet`
+suppresses everything except errors. Debug messages require `verbose`; `level`
+filters info/warn output. `verboseInfo` requires verbose and non-quiet mode. Errors
+always print. Context can be rendered inline or with `debugMultiline`. A custom
+`theme` supplies functions for each level; default colors are disabled for pipes.
+
+`npm run build -w @chronicle.app/logging` builds the package; `npm test -w
+@chronicle.app/logging` exercises its public API after a build.
+
+MIT. See [LICENSE](LICENSE).

package/dist/DefaultTheme.d.ts

@@ -0,0 +1,3 @@
+import { LoggerTheme } from './types.js';
+export declare const defaultTheme: LoggerTheme;
+//# sourceMappingURL=DefaultTheme.d.ts.map

package/dist/DefaultTheme.js

@@ -0,0 +1,8 @@
+import chalk from 'chalk';
+// Enhanced theme with colored icons/timestamps only
+export const defaultTheme = {
+    debug: msg => `${chalk.gray('⚪')} ${msg}`,
+    info: msg => `${chalk.blue('ℹ')} ${msg}`,
+    warn: msg => `${chalk.yellow('⚠')} ${msg}`,
+    error: msg => `${chalk.red('✖')} ${msg}`,
+};

package/dist/Logger.d.ts

@@ -0,0 +1,20 @@
+import { LoggerOptions, LoggerContext } from './types.js';
+export declare class Logger {
+    private prefix;
+    private level;
+    private quiet;
+    private verbose;
+    private theme;
+    constructor(options?: LoggerOptions);
+    private shouldLog;
+    private formatPrefix;
+    private formatMessage;
+    private formatCompactJson;
+    debug(message: string, context?: LoggerContext): void;
+    debugMultiline(message: string, context?: LoggerContext): void;
+    info(message: string, context?: LoggerContext): void;
+    verboseInfo(message: string, context?: LoggerContext): void;
+    warn(message: string, context?: LoggerContext): void;
+    error(message: string, context?: LoggerContext): void;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/dist/Logger.js

@@ -0,0 +1,112 @@
+import { defaultTheme } from './DefaultTheme.js';
+import chalk from 'chalk';
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+export class Logger {
+    prefix;
+    level;
+    quiet;
+    verbose;
+    theme;
+    constructor(options = {}) {
+        this.prefix = options.prefix ? `${options.prefix} ` : '';
+        this.level = options.level ?? 'info';
+        this.quiet = options.quiet ?? false;
+        this.verbose = options.verbose ?? false;
+        this.theme = options.theme ?? defaultTheme;
+        // Only enable colors when writing to a real terminal (not when PM2 captures stderr)
+        if (process.stderr.isTTY) {
+            chalk.level = 3; // Force full color support for terminals
+        }
+        else {
+            chalk.level = 0; // Disable colors for file/pipe output
+        }
+    }
+    shouldLog(level) {
+        if (level === 'error')
+            return true; // Always show errors
+        if (this.quiet)
+            return false;
+        if (level === 'debug')
+            return this.verbose; // Debug messages only in verbose mode
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+    }
+    formatPrefix(serviceName) {
+        // Extract service name from prefix like '[ServiceName]' or just use as-is
+        const match = serviceName.match(/\[([^\]]+)\]/);
+        const name = match ? match[1] : serviceName.replaceAll(/^\s*|\s*$/g, '');
+        // Fixed width of 25 characters, left-aligned
+        return name.padEnd(25);
+    }
+    formatMessage(message, context, multiline = false) {
+        const service = this.prefix ? this.formatPrefix(this.prefix) : ''.padEnd(25);
+        let formatted = `${service} ${message}`;
+        if (context && Object.keys(context).length > 0) {
+            if (multiline) {
+                // Custom JSON formatting: compact arrays, multiline objects
+                const compactJson = this.formatCompactJson(context);
+                formatted += `\n${compactJson}`;
+            }
+            else {
+                formatted += ` ${JSON.stringify(context)}`;
+            }
+        }
+        return formatted;
+    }
+    formatCompactJson(obj, depth = 0) {
+        const indent = '  '.repeat(depth);
+        const nextIndent = '  '.repeat(depth + 1);
+        if (Array.isArray(obj)) {
+            // Keep arrays on single line for compactness
+            return JSON.stringify(obj);
+        }
+        if (obj && typeof obj === 'object') {
+            const entries = Object.entries(obj);
+            if (entries.length === 0)
+                return '{}';
+            const formatted = entries
+                .map(([key, value]) => `${nextIndent}"${key}": ${this.formatCompactJson(value, depth + 1)}`)
+                .join(',\n');
+            return `{\n${formatted}\n${indent}}`;
+        }
+        return JSON.stringify(obj);
+    }
+    debug(message, context) {
+        if (this.shouldLog('debug')) {
+            const formatted = this.formatMessage(message, context);
+            process.stderr.write(`${this.theme.debug(formatted)}\n`);
+        }
+    }
+    debugMultiline(message, context) {
+        if (this.shouldLog('debug')) {
+            const formatted = this.formatMessage(message, context, true);
+            process.stderr.write(`${this.theme.debug(formatted)}\n`);
+        }
+    }
+    info(message, context) {
+        if (this.shouldLog('info')) {
+            const formatted = this.formatMessage(message, context);
+            process.stderr.write(`${this.theme.info(formatted)}\n`);
+        }
+    }
+    verboseInfo(message, context) {
+        if (!this.quiet && this.verbose) {
+            const formatted = this.formatMessage(message, context);
+            process.stderr.write(`${this.theme.info(formatted)}\n`);
+        }
+    }
+    warn(message, context) {
+        if (this.shouldLog('warn')) {
+            const formatted = this.formatMessage(message, context);
+            process.stderr.write(`${this.theme.warn(formatted)}\n`);
+        }
+    }
+    error(message, context) {
+        const formatted = this.formatMessage(message, context);
+        process.stderr.write(`${this.theme.error(formatted)}\n`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Logger } from './Logger.js';
+export { defaultTheme } from './DefaultTheme.js';
+export type { LoggerTheme, LoggerOptions, LogLevel, LoggerContext } from './types.js';
+import { Logger } from './Logger.js';
+import { LoggerOptions } from './types.js';
+/**
+ * Factory function to create a logger instance
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+export { Logger } from './Logger.js';
+export { defaultTheme } from './DefaultTheme.js';
+import { Logger } from './Logger.js';
+/**
+ * Factory function to create a logger instance
+ */
+export function createLogger(options = {}) {
+    return new Logger(options);
+}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export interface LoggerTheme {
+    info: (message: string) => string;
+    warn: (message: string) => string;
+    error: (message: string) => string;
+    debug: (message: string) => string;
+}
+export interface LoggerOptions {
+    prefix?: string;
+    level?: LogLevel;
+    theme?: LoggerTheme;
+    quiet?: boolean;
+    verbose?: boolean;
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LoggerContext {
+    [key: string]: any;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chronicle.app/logging",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle shared logging utilities",
+  "homepage": "https://chronicle.app",
+  "bugs": {
+    "url": "https://github.com/chronicle-app/chronicle/issues/new?labels=core:logging&title=[logging]%20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "core/logging"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@chronicle.app/tsconfig": "0.1.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  }
+}