@svayam-opensource/svm-util-log 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# @svayam-opensource/svm-util-log
+
+Svayam's shared logging framework — the logger from `svm-util`, carrying only the
+dependencies a logger needs.
+
+**Mandated by POL-423.** All Svayam-owned Node code uses this framework and leaves messages
+at the various levels, so a run can be reviewed afterwards for issue and problem resolution.
+
+## Why this package exists
+
+`@svayam/svm-util` is one package: the logger, the helpers, database access and the API
+server. Taking it whole installs **675 packages, 274 MB** — right for an API service, and the
+whole cost for a command-line tool that wants one log line. `@svayam-opensource/gov` is
+installed with `npm i -g` on adopters' laptops.
+
+This package is **25 packages, 8.4 MB**.
+
+It is also on the **public** scope, because `@svayam/svm-util` publishes to the internal
+registry, which adopters of a public CLI cannot resolve. A logging mandate that makes the
+governance CLI uninstallable is a mandate nothing can obey.
+
+First package of the split — see [911#224](https://github.com/Svayamtech/911-SVM-LIB-SVC/issues/224).
+
+## Use
+
+```ts
+import { createApplicationLogger, LogLevel } from "@svayam-opensource/svm-util-log";
+
+const logger = createApplicationLogger({
+  appId: "gov-work",
+  logDir: "~/.gov/svm/logs",
+  methods: [
+    { METHOD: "console", LOGLEVEL: LogLevel.warn },
+    { METHOD: "file",    LOGLEVEL: LogLevel.debug },
+  ],
+});
+
+logger.log(LogLevel.debug, "chose the api-key route", "gov-work:cli:sign-in-choice", "captureAgentKey");
+```
+
+### `pgm_cd` is the code path
+
+`<package>:<dir>:<module>` — `gov-work:cli:sign-in-choice` is `src/cli/sign-in-choice.ts`.
+The point is that a reader can get from a line back to the code without guessing (POL-426).
+
+### Turning it on in the field
+
+Errors and warnings always come through. Everything below them is opt-in:
+
+```bash
+NODE_DEBUG=gov-work:cli:sign-in-choice   gov work     # one module
+NODE_DEBUG=gov-work:*                    gov work     # the package
+```
+
+That is POL-425: **the person who needs the log is usually not the person who can reproduce
+the fault.** They turn it on, reproduce, and send the file.
+
+### Secrets
+
+POL-427 is **C01**: no credential, key, token or PII reaches a log, at any level, in any
+transport. `meta` is masked before rendering — by field name, case-insensitively, matching a
+name that *contains* a masked word (`userPassword`, `db_pwd`, `authToken`). Extend
+`DEFAULT_MASK`, never replace it.
+
+## Transports
+
+`console` and `file` (daily-rotate) ship here. `database` and `api` belong to the packages
+carrying `mysql` and `axios`, and register themselves:
+
+```ts
+registerTransport("database", (conf, config) => new MyDbTransport(conf, config));
+```
+
+A method declared in config with nothing registered for it is **ignored, not an error** — a
+line that does not go somewhere, never a crash at startup.
+
+## Two deliberate departures from `svm-util`
+
+1. **Configuration is injected, never global.** `svm-util` reaches a module-level
+   `getSvayamConfiguration()`; a CLI has a first run where no configuration exists at all.
+2. **Console output goes to STDERR.** `stdout` is a program's answer, and a caller piping it
+   should not receive the log as data.

package/lib/cjs/config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MASK = void 0;
+/** What a `mask` covers before a consumer adds to it. Extend, do not replace. */
+exports.DEFAULT_MASK = [
+    "password", "passwd", "pwd", "secret", "token", "apiKey", "api_key",
+    "authorization", "auth", "credential", "credentials", "privateKey", "private_key",
+    "sessionId", "session_id", "cookie", "jwt", "bearer",
+];

package/lib/cjs/format.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLogEnabled = isLogEnabled;
+exports.maskValues = maskValues;
+exports.stringify = stringify;
+exports.toLogEntry = toLogEntry;
+exports.formatLogMessage = formatLogMessage;
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * Turning a call into a line — masking, provenance, and the one-line layout.
+ *
+ * Extracted from `svm-util/src/svm-helper.ts` (`stringify`, `getLogEntry`, `formatLogMessage`,
+ * `isLogEnabled`), with the global configuration lookup removed: every function here takes
+ * what it needs. See `config.ts` for why.
+ */
+const node_util_1 = __importDefault(require("node:util"));
+const config_js_1 = require("./config.js");
+const COMPACT = {
+    depth: 4, compact: true, breakLength: Infinity, maxStringLength: 512, colors: false,
+};
+/**
+ * Is logging switched on for this origin?
+ *
+ * `node:util.debuglog` is the switch, so `NODE_DEBUG=gov-work:cli:agent-install` enables one
+ * module and `NODE_DEBUG=gov-work:*` the package — POL-425's "switchable at run time by
+ * whoever is in front of the problem, with no rebuild and no release".
+ *
+ * NOT CACHED PER CALL BY ACCIDENT: `debuglog` itself is lazy and memoised, so asking it every
+ * time is cheap, and asking it every time is what lets a long-running process be told the
+ * truth if the environment is re-read.
+ */
+function isLogEnabled(pgm_cd, fn_cd, act_id) {
+    const on = (s) => (s ? node_util_1.default.debuglog(s).enabled : false);
+    return on(pgm_cd) || on(fn_cd) || on(act_id?.toString());
+}
+/**
+ * Replace the value of any masked field, at any depth, before it can be rendered.
+ *
+ * POL-427 (C01). The comparison is case-insensitive and matches a field whose name CONTAINS a
+ * masked word, because the field that leaks is rarely named exactly `password` — it is
+ * `userPassword`, `db_pwd`, `authToken`. Over-masking costs a reader one lookup; under-masking
+ * costs a credential.
+ */
+function maskValues(value, mask = config_js_1.DEFAULT_MASK) {
+    const hidden = (key) => {
+        const k = key.toLowerCase();
+        return mask.some((m) => k.includes(m.toLowerCase()));
+    };
+    const walk = (v, depth) => {
+        if (depth > 8 || v === null || typeof v !== "object")
+            return v;
+        if (Array.isArray(v))
+            return v.map((x) => walk(x, depth + 1));
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            out[k] = hidden(k) ? "***" : walk(val, depth + 1);
+        }
+        return out;
+    };
+    return walk(value, 0);
+}
+/** Render anything for a log line: masked, depth-limited, and never throwing. */
+function stringify(obj, config) {
+    if (obj === null)
+        return "null";
+    if (obj === undefined)
+        return "undefined";
+    if (typeof obj !== "object")
+        return String(obj);
+    try {
+        const masked = maskValues(obj, config?.mask ?? config_js_1.DEFAULT_MASK);
+        return node_util_1.default.inspect(masked, { ...COMPACT, ...(config?.inspect ?? {}) });
+    }
+    catch (e) {
+        // A logger that throws while rendering takes the program down at the moment it was trying
+        // to explain itself. Say what went wrong with the value and keep the line.
+        return `<unrenderable: ${e?.message ?? "unknown"}>`;
+    }
+}
+/** Give a call its provenance. Padding keeps a wall of lines readable in columns. */
+function toLogEntry(appId, lvl, msg, pgm_cd, fn_cd, act_id, meta) {
+    return {
+        level: lvl,
+        message: msg,
+        app_cd: appId,
+        pgm_cd: pgm_cd ?? "n/a",
+        fn_cd: fn_cd ?? "n/a",
+        act_id: act_id ?? 0,
+        meta,
+        logTime: new Date().toISOString(),
+    };
+}
+/**
+ * The single line a transport writes.
+ *
+ * The origin comes FIRST and at a fixed width, because the common act is scanning a column
+ * for one module rather than reading prose — which is what a log is for when it is being read
+ * at all.
+ */
+function formatLogMessage(e, config) {
+    const pgm = (e.pgm_cd ?? "n/a").padEnd(34);
+    const fn = (e.fn_cd ?? "n/a").padEnd(22);
+    const act = String(e.act_id ?? 0).padEnd(4);
+    const meta = e.meta === undefined ? "" : ` meta=${stringify(e.meta, config)}`;
+    return `${e.logTime ?? ""} ${e.level.padEnd(7)} ${pgm} ${fn} ${act} ${e.message}${meta}`;
+}

package/lib/cjs/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTransport = exports.createApplicationLogger = exports.toLogEntry = exports.stringify = exports.maskValues = exports.isLogEnabled = exports.formatLogMessage = exports.DEFAULT_MASK = exports.withinLevel = exports.logLevelIndex = exports.LogMethod = exports.LogLevelIndex = exports.LogLevelColors = exports.LogLevel = void 0;
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * `@svayam-opensource/svm-util-log` — the shared logging framework mandated by POL-423,
+ * carrying only the dependencies a logger needs.
+ *
+ * The first package of the `svm-util` split (911#224). It exists because the logger and the
+ * API server were one package, so a command-line tool could not obey POL-423 without shipping
+ * express, mysql, axios and ajv to every adopter — 675 packages for a log line.
+ *
+ * PUBLIC SCOPE, deliberately. `@svayam/svm-util` publishes to the internal registry, which
+ * adopters of `@svayam-opensource/gov` cannot resolve. A logging mandate that makes the
+ * governance CLI uninstallable is a mandate nothing can obey.
+ */
+var levels_js_1 = require("./levels.js");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return levels_js_1.LogLevel; } });
+Object.defineProperty(exports, "LogLevelColors", { enumerable: true, get: function () { return levels_js_1.LogLevelColors; } });
+Object.defineProperty(exports, "LogLevelIndex", { enumerable: true, get: function () { return levels_js_1.LogLevelIndex; } });
+Object.defineProperty(exports, "LogMethod", { enumerable: true, get: function () { return levels_js_1.LogMethod; } });
+Object.defineProperty(exports, "logLevelIndex", { enumerable: true, get: function () { return levels_js_1.logLevelIndex; } });
+Object.defineProperty(exports, "withinLevel", { enumerable: true, get: function () { return levels_js_1.withinLevel; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "DEFAULT_MASK", { enumerable: true, get: function () { return config_js_1.DEFAULT_MASK; } });
+var format_js_1 = require("./format.js");
+Object.defineProperty(exports, "formatLogMessage", { enumerable: true, get: function () { return format_js_1.formatLogMessage; } });
+Object.defineProperty(exports, "isLogEnabled", { enumerable: true, get: function () { return format_js_1.isLogEnabled; } });
+Object.defineProperty(exports, "maskValues", { enumerable: true, get: function () { return format_js_1.maskValues; } });
+Object.defineProperty(exports, "stringify", { enumerable: true, get: function () { return format_js_1.stringify; } });
+Object.defineProperty(exports, "toLogEntry", { enumerable: true, get: function () { return format_js_1.toLogEntry; } });
+var logger_js_1 = require("./logger.js");
+Object.defineProperty(exports, "createApplicationLogger", { enumerable: true, get: function () { return logger_js_1.createApplicationLogger; } });
+Object.defineProperty(exports, "registerTransport", { enumerable: true, get: function () { return logger_js_1.registerTransport; } });

package/lib/cjs/levels.js

@@ -0,0 +1,39 @@
+"use strict";
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * Levels, and the shape of a log call — extracted from `svm-util/src/svm-util-base.ts`
+ * unchanged, so a line written against either library means the same thing.
+ *
+ * DELIBERATELY DEPENDENCY-FREE. In `svm-util` these live beside `PoolConfig` from mysql,
+ * Axios request types, Ajv and Express, in one shared types module — so importing the level
+ * enum pulled a web-server stack. That single file is why a CLI could not take the logger
+ * (911#224), and separating it is most of this package's reason to exist.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLevelColors = exports.LogLevelIndex = exports.logLevelIndex = exports.LogLevel = exports.LogMethod = void 0;
+exports.withinLevel = withinLevel;
+/** Where a log line can be sent. `database` and `api` are registered by other packages. */
+exports.LogMethod = { console: "console", file: "file", database: "database", api: "api" };
+exports.LogLevel = {
+    error: "error", warn: "warn", info: "info", http: "http",
+    verbose: "verbose", debug: "debug", silly: "silly",
+};
+/** Ordered least to most verbose; the index IS the threshold comparison. */
+exports.logLevelIndex = [
+    exports.LogLevel.error, exports.LogLevel.warn, exports.LogLevel.info, exports.LogLevel.http,
+    exports.LogLevel.verbose, exports.LogLevel.debug, exports.LogLevel.silly,
+];
+exports.LogLevelIndex = { error: 0, warn: 1, info: 2, http: 3, verbose: 4, debug: 5, silly: 6 };
+exports.LogLevelColors = {
+    error: "red", warn: "magenta", info: "green", http: "blue",
+    verbose: "cyan", debug: "yellow", silly: "gray",
+};
+/** Is `lvl` within the threshold `at`? Both are level names, not numbers, at the call site. */
+function withinLevel(lvl, at) {
+    return exports.LogLevelIndex[lvl] <= exports.LogLevelIndex[at];
+}

package/lib/cjs/logger.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTransport = registerTransport;
+exports.createApplicationLogger = createApplicationLogger;
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * The application logger — `svm-util`'s, with the console and file transports and nothing else.
+ *
+ * TRANSPORTS ARE PLUGGABLE, and that is the change that makes this package possible.
+ * `svm-util/src/svm-logger.ts` builds every transport itself, so it imports `svm-db.js` for the
+ * database one and drags `mysql` into anything that wants to log. Here a transport for a method
+ * this package does not implement is looked up in a registry, and the packages that own those
+ * dependencies register into it (911#224).
+ *
+ * `exitOnError: false`, as in the original: a library must never take the host process down
+ * because a transport failed. That is doubly true here — the transport most likely to fail is
+ * the one writing the file you were going to read afterwards.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const winston_1 = require("winston");
+const winston_daily_rotate_file_1 = __importDefault(require("winston-daily-rotate-file"));
+const config_js_1 = require("./config.js");
+const levels_js_1 = require("./levels.js");
+const format_js_1 = require("./format.js");
+const registry = new Map();
+function registerTransport(method, make) {
+    registry.set(method, make);
+}
+function buildTransports(config) {
+    const out = [];
+    for (const conf of config.methods) {
+        if (conf.METHOD === "console") {
+            out.push(new winston_1.transports.Console({
+                level: conf.LOGLEVEL || levels_js_1.LogLevel.info,
+                handleExceptions: true,
+                format: winston_1.format.combine(winston_1.format.colorize({ all: true }), winston_1.format.printf((info) => (0, format_js_1.formatLogMessage)(info, config))),
+                // Diagnostics belong on STDERR. stdout is a program's ANSWER, and a caller piping it
+                // into another command should not receive the log as data.
+                stderrLevels: Object.values(levels_js_1.LogLevel),
+            }));
+            continue;
+        }
+        if (conf.METHOD === "file") {
+            const f = conf;
+            const dir = f.DATA_STORE?.dirname ?? config.logDir;
+            out.push(new winston_daily_rotate_file_1.default({
+                level: f.LOGLEVEL || levels_js_1.LogLevel.info,
+                dirname: dir,
+                filename: node_path_1.default.join(String(f.DATA_STORE?.filename ?? ""), `%DATE%-${config.appId}.log`),
+                datePattern: f.DATA_STORE?.datePattern ?? "YYYY-MM-DD",
+                zippedArchive: f.DATA_STORE?.zippedArchive ?? true,
+                maxSize: f.DATA_STORE?.maxSize ?? "20m",
+                // A log kept forever is a disclosure risk that grows on its own; a fortnight is enough
+                // to diagnose something an adopter noticed today.
+                maxFiles: f.DATA_STORE?.maxFiles ?? "14d",
+                format: winston_1.format.combine(winston_1.format.printf((info) => (0, format_js_1.formatLogMessage)(info, config))),
+            }));
+            continue;
+        }
+        const make = registry.get(conf.METHOD);
+        if (make)
+            out.push(make(conf, config));
+        // else: declared but unavailable. Silence here is correct — see registerTransport.
+    }
+    return out;
+}
+function createApplicationLogger(config) {
+    (0, winston_1.addColors)(levels_js_1.LogLevelColors);
+    const built = buildTransports(config);
+    const winston = (0, winston_1.createLogger)({
+        levels: levels_js_1.LogLevelIndex,
+        transports: built,
+        exitOnError: false,
+    });
+    const effective = { mask: config_js_1.DEFAULT_MASK, ...config };
+    const log = (lvl, msg, pgm_cd, fn_cd, act_id, meta) => {
+        // ERRORS AND WARNINGS ALWAYS PASS. Everything below them is opt-in through NODE_DEBUG, so
+        // an ordinary run is quiet — but a run that went wrong still said so without anybody
+        // having had the foresight to enable anything.
+        const always = levels_js_1.LogLevelIndex[lvl] <= levels_js_1.LogLevelIndex[levels_js_1.LogLevel.warn];
+        if (!always && !(0, format_js_1.isLogEnabled)(pgm_cd, fn_cd, act_id))
+            return;
+        winston.log((0, format_js_1.toLogEntry)(effective.appId, lvl, msg, pgm_cd, fn_cd, act_id, meta));
+    };
+    const toLogObject = () => ({
+        APP_ID: effective.appId,
+        LOG_DIR: effective.logDir,
+        REQUESTED_METHODS: effective.methods.map((m) => m.METHOD),
+        ENABLED_TRANSPORTS: winston.transports.map((t) => ({ type: t.constructor.name, level: t.level })),
+        MASK: effective.mask,
+    });
+    return {
+        log,
+        toLogObject,
+        toString: () => JSON.stringify(toLogObject()),
+        // A CLI exits in seconds and a rotating file transport writes asynchronously; without a
+        // close the last lines of a short run — the ones describing why it ended — are the ones
+        // most likely to be lost.
+        close: () => { try {
+            winston.close();
+        }
+        catch { /* closing a closed logger is not news */ } },
+    };
+}

package/lib/esm/config.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What a consumer declares, and what it injects.
+ *
+ * TWO DEPARTURES FROM `svm-util`, both deliberate.
+ *
+ * 1. CONFIG IS INJECTED, NEVER GLOBAL. `svm-util`'s `formatLogMessage` reaches a module-level
+ *    `getSvayamConfiguration()`, which assumes an application initialised its configuration
+ *    before anything logged. A long-lived API server can promise that. A command-line tool
+ *    cannot: `gov` has a first run where no configuration exists at all, several entry points,
+ *    and a lifetime measured in seconds. A library that requires a global to be set up first
+ *    is a library that throws during the very failure you are trying to log.
+ *
+ * 2. ONLY console AND file ARE DECLARED HERE. The database and api transports belong to the
+ *    packages that carry their dependencies, and register themselves (911#224). Declaring
+ *    them here would put `mysql` and `axios` back in the type graph, which is the thing this
+ *    package exists to remove.
+ */
+import type { logLevelType, logMethodType } from "./levels.js";
+/** Where a rotating file transport writes. Winston's own options, narrowed to what is used. */
+export interface FileLogOptions {
+    /** directory; defaults to the application's log directory. */
+    dirname?: string;
+    /** basename; the date and the app id are added around it. */
+    filename?: string;
+    datePattern?: string;
+    zippedArchive?: boolean;
+    maxSize?: string;
+    maxFiles?: string;
+    [key: string]: unknown;
+}
+export type CONSOLE_LOG_CONFIG_METHOD = {
+    METHOD: "console";
+    LOGLEVEL: logLevelType;
+};
+export interface FILE_LOG_CONFIG_METHOD {
+    METHOD: "file";
+    LOGLEVEL: logLevelType;
+    DATA_STORE?: FileLogOptions;
+    [key: string]: unknown;
+}
+/**
+ * A method this package does not implement — `database`, `api`, or anything a future package
+ * adds. Carried through the config so a consumer's file does not have to be rewritten when it
+ * moves between environments, and IGNORED unless something registered a transport for it.
+ */
+export interface EXTERNAL_LOG_CONFIG_METHOD {
+    METHOD: Exclude<logMethodType, "console" | "file">;
+    LOGLEVEL: logLevelType;
+    [key: string]: unknown;
+}
+export type LOG_CONFIG_METHOD = CONSOLE_LOG_CONFIG_METHOD | FILE_LOG_CONFIG_METHOD | EXTERNAL_LOG_CONFIG_METHOD;
+/** Everything the logger needs, handed to it rather than found by it. */
+export interface LoggerConfig {
+    /** Names the application in every line and in the log filename. */
+    readonly appId: string;
+    /** Where file transports write when they do not say otherwise. */
+    readonly logDir: string;
+    readonly methods: readonly LOG_CONFIG_METHOD[];
+    /**
+     * Field names to mask wherever they appear in `meta`.
+     *
+     * POL-427 is C01: no credential, key, token or PII reaches a log, at any level, in any
+     * transport. Masking belongs here rather than in a call site's memory — a log is a file, it
+     * is copied, and it is sent to other people precisely when something has gone wrong.
+     */
+    readonly mask?: readonly string[];
+    /** Depth and length limits for `meta`, so one object cannot become the whole file. */
+    readonly inspect?: {
+        depth?: number;
+        maxStringLength?: number;
+    };
+}
+/** What a `mask` covers before a consumer adds to it. Extend, do not replace. */
+export declare const DEFAULT_MASK: readonly string[];

package/lib/esm/config.js

@@ -0,0 +1,6 @@
+/** What a `mask` covers before a consumer adds to it. Extend, do not replace. */
+export const DEFAULT_MASK = [
+    "password", "passwd", "pwd", "secret", "token", "apiKey", "api_key",
+    "authorization", "auth", "credential", "credentials", "privateKey", "private_key",
+    "sessionId", "session_id", "cookie", "jwt", "bearer",
+];

package/lib/esm/format.d.ts

@@ -0,0 +1,39 @@
+import type { LoggerConfig } from "./config.js";
+import type { LogEntryFields, logLevelType } from "./levels.js";
+/**
+ * Is logging switched on for this origin?
+ *
+ * `node:util.debuglog` is the switch, so `NODE_DEBUG=gov-work:cli:agent-install` enables one
+ * module and `NODE_DEBUG=gov-work:*` the package — POL-425's "switchable at run time by
+ * whoever is in front of the problem, with no rebuild and no release".
+ *
+ * NOT CACHED PER CALL BY ACCIDENT: `debuglog` itself is lazy and memoised, so asking it every
+ * time is cheap, and asking it every time is what lets a long-running process be told the
+ * truth if the environment is re-read.
+ */
+export declare function isLogEnabled(pgm_cd?: string, fn_cd?: string, act_id?: number): boolean;
+/**
+ * Replace the value of any masked field, at any depth, before it can be rendered.
+ *
+ * POL-427 (C01). The comparison is case-insensitive and matches a field whose name CONTAINS a
+ * masked word, because the field that leaks is rarely named exactly `password` — it is
+ * `userPassword`, `db_pwd`, `authToken`. Over-masking costs a reader one lookup; under-masking
+ * costs a credential.
+ */
+export declare function maskValues(value: unknown, mask?: readonly string[]): unknown;
+/** Render anything for a log line: masked, depth-limited, and never throwing. */
+export declare function stringify(obj: unknown, config?: Pick<LoggerConfig, "mask" | "inspect">): string;
+/** Give a call its provenance. Padding keeps a wall of lines readable in columns. */
+export declare function toLogEntry(appId: string, lvl: logLevelType, msg: string, pgm_cd?: string, fn_cd?: string, act_id?: number, meta?: unknown): LogEntryFields & {
+    logTime: string;
+};
+/**
+ * The single line a transport writes.
+ *
+ * The origin comes FIRST and at a fixed width, because the common act is scanning a column
+ * for one module rather than reading prose — which is what a log is for when it is being read
+ * at all.
+ */
+export declare function formatLogMessage(e: LogEntryFields & {
+    logTime?: string;
+}, config?: Pick<LoggerConfig, "mask" | "inspect">): string;

package/lib/esm/format.js

@@ -0,0 +1,104 @@
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * Turning a call into a line — masking, provenance, and the one-line layout.
+ *
+ * Extracted from `svm-util/src/svm-helper.ts` (`stringify`, `getLogEntry`, `formatLogMessage`,
+ * `isLogEnabled`), with the global configuration lookup removed: every function here takes
+ * what it needs. See `config.ts` for why.
+ */
+import nodeUtil from "node:util";
+import { DEFAULT_MASK } from "./config.js";
+const COMPACT = {
+    depth: 4, compact: true, breakLength: Infinity, maxStringLength: 512, colors: false,
+};
+/**
+ * Is logging switched on for this origin?
+ *
+ * `node:util.debuglog` is the switch, so `NODE_DEBUG=gov-work:cli:agent-install` enables one
+ * module and `NODE_DEBUG=gov-work:*` the package — POL-425's "switchable at run time by
+ * whoever is in front of the problem, with no rebuild and no release".
+ *
+ * NOT CACHED PER CALL BY ACCIDENT: `debuglog` itself is lazy and memoised, so asking it every
+ * time is cheap, and asking it every time is what lets a long-running process be told the
+ * truth if the environment is re-read.
+ */
+export function isLogEnabled(pgm_cd, fn_cd, act_id) {
+    const on = (s) => (s ? nodeUtil.debuglog(s).enabled : false);
+    return on(pgm_cd) || on(fn_cd) || on(act_id?.toString());
+}
+/**
+ * Replace the value of any masked field, at any depth, before it can be rendered.
+ *
+ * POL-427 (C01). The comparison is case-insensitive and matches a field whose name CONTAINS a
+ * masked word, because the field that leaks is rarely named exactly `password` — it is
+ * `userPassword`, `db_pwd`, `authToken`. Over-masking costs a reader one lookup; under-masking
+ * costs a credential.
+ */
+export function maskValues(value, mask = DEFAULT_MASK) {
+    const hidden = (key) => {
+        const k = key.toLowerCase();
+        return mask.some((m) => k.includes(m.toLowerCase()));
+    };
+    const walk = (v, depth) => {
+        if (depth > 8 || v === null || typeof v !== "object")
+            return v;
+        if (Array.isArray(v))
+            return v.map((x) => walk(x, depth + 1));
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            out[k] = hidden(k) ? "***" : walk(val, depth + 1);
+        }
+        return out;
+    };
+    return walk(value, 0);
+}
+/** Render anything for a log line: masked, depth-limited, and never throwing. */
+export function stringify(obj, config) {
+    if (obj === null)
+        return "null";
+    if (obj === undefined)
+        return "undefined";
+    if (typeof obj !== "object")
+        return String(obj);
+    try {
+        const masked = maskValues(obj, config?.mask ?? DEFAULT_MASK);
+        return nodeUtil.inspect(masked, { ...COMPACT, ...(config?.inspect ?? {}) });
+    }
+    catch (e) {
+        // A logger that throws while rendering takes the program down at the moment it was trying
+        // to explain itself. Say what went wrong with the value and keep the line.
+        return `<unrenderable: ${e?.message ?? "unknown"}>`;
+    }
+}
+/** Give a call its provenance. Padding keeps a wall of lines readable in columns. */
+export function toLogEntry(appId, lvl, msg, pgm_cd, fn_cd, act_id, meta) {
+    return {
+        level: lvl,
+        message: msg,
+        app_cd: appId,
+        pgm_cd: pgm_cd ?? "n/a",
+        fn_cd: fn_cd ?? "n/a",
+        act_id: act_id ?? 0,
+        meta,
+        logTime: new Date().toISOString(),
+    };
+}
+/**
+ * The single line a transport writes.
+ *
+ * The origin comes FIRST and at a fixed width, because the common act is scanning a column
+ * for one module rather than reading prose — which is what a log is for when it is being read
+ * at all.
+ */
+export function formatLogMessage(e, config) {
+    const pgm = (e.pgm_cd ?? "n/a").padEnd(34);
+    const fn = (e.fn_cd ?? "n/a").padEnd(22);
+    const act = String(e.act_id ?? 0).padEnd(4);
+    const meta = e.meta === undefined ? "" : ` meta=${stringify(e.meta, config)}`;
+    return `${e.logTime ?? ""} ${e.level.padEnd(7)} ${pgm} ${fn} ${act} ${e.message}${meta}`;
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@svayam-opensource/svm-util-log` — the shared logging framework mandated by POL-423,
+ * carrying only the dependencies a logger needs.
+ *
+ * The first package of the `svm-util` split (911#224). It exists because the logger and the
+ * API server were one package, so a command-line tool could not obey POL-423 without shipping
+ * express, mysql, axios and ajv to every adopter — 675 packages for a log line.
+ *
+ * PUBLIC SCOPE, deliberately. `@svayam/svm-util` publishes to the internal registry, which
+ * adopters of `@svayam-opensource/gov` cannot resolve. A logging mandate that makes the
+ * governance CLI uninstallable is a mandate nothing can obey.
+ */
+export { LogLevel, LogLevelColors, LogLevelIndex, LogMethod, logLevelIndex, withinLevel } from "./levels.js";
+export type { LogEntryFields, logFunctionType, logLevelType, logMethodType } from "./levels.js";
+export { DEFAULT_MASK } from "./config.js";
+export type { CONSOLE_LOG_CONFIG_METHOD, EXTERNAL_LOG_CONFIG_METHOD, FILE_LOG_CONFIG_METHOD, FileLogOptions, LOG_CONFIG_METHOD, LoggerConfig, } from "./config.js";
+export { formatLogMessage, isLogEnabled, maskValues, stringify, toLogEntry } from "./format.js";
+export { createApplicationLogger, registerTransport } from "./logger.js";
+export type { ApplicationLogger, TransportFactory } from "./logger.js";

package/lib/esm/index.js

@@ -0,0 +1,22 @@
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * `@svayam-opensource/svm-util-log` — the shared logging framework mandated by POL-423,
+ * carrying only the dependencies a logger needs.
+ *
+ * The first package of the `svm-util` split (911#224). It exists because the logger and the
+ * API server were one package, so a command-line tool could not obey POL-423 without shipping
+ * express, mysql, axios and ajv to every adopter — 675 packages for a log line.
+ *
+ * PUBLIC SCOPE, deliberately. `@svayam/svm-util` publishes to the internal registry, which
+ * adopters of `@svayam-opensource/gov` cannot resolve. A logging mandate that makes the
+ * governance CLI uninstallable is a mandate nothing can obey.
+ */
+export { LogLevel, LogLevelColors, LogLevelIndex, LogMethod, logLevelIndex, withinLevel } from "./levels.js";
+export { DEFAULT_MASK } from "./config.js";
+export { formatLogMessage, isLogEnabled, maskValues, stringify, toLogEntry } from "./format.js";
+export { createApplicationLogger, registerTransport } from "./logger.js";

package/lib/esm/levels.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Levels, and the shape of a log call — extracted from `svm-util/src/svm-util-base.ts`
+ * unchanged, so a line written against either library means the same thing.
+ *
+ * DELIBERATELY DEPENDENCY-FREE. In `svm-util` these live beside `PoolConfig` from mysql,
+ * Axios request types, Ajv and Express, in one shared types module — so importing the level
+ * enum pulled a web-server stack. That single file is why a CLI could not take the logger
+ * (911#224), and separating it is most of this package's reason to exist.
+ */
+/** Where a log line can be sent. `database` and `api` are registered by other packages. */
+export declare const LogMethod: {
+    readonly console: "console";
+    readonly file: "file";
+    readonly database: "database";
+    readonly api: "api";
+};
+export type logMethodType = keyof typeof LogMethod;
+export declare const LogLevel: {
+    readonly error: "error";
+    readonly warn: "warn";
+    readonly info: "info";
+    readonly http: "http";
+    readonly verbose: "verbose";
+    readonly debug: "debug";
+    readonly silly: "silly";
+};
+export type logLevelType = keyof typeof LogLevel;
+/** Ordered least to most verbose; the index IS the threshold comparison. */
+export declare const logLevelIndex: logLevelType[];
+export declare const LogLevelIndex: {
+    readonly error: 0;
+    readonly warn: 1;
+    readonly info: 2;
+    readonly http: 3;
+    readonly verbose: 4;
+    readonly debug: 5;
+    readonly silly: 6;
+};
+export declare const LogLevelColors: {
+    error: string;
+    warn: string;
+    info: string;
+    http: string;
+    verbose: string;
+    debug: string;
+    silly: string;
+};
+/**
+ * The call every logged line makes.
+ *
+ * `pgm_cd` and `fn_cd` are not decoration — they are how a reader gets from a line back to the
+ * code that wrote it (POL-426). The convention is the CODE PATH: `<package>:<dir>:<module>`,
+ * so `gov-work:cli:agent-install` is `src/cli/agent-install.ts` and nothing has to be guessed.
+ *
+ * `act_id` ties lines from one unit of work together across modules.
+ */
+export type logFunctionType = (lvl: logLevelType, msg: string, pgm_cd?: string, fn_cd?: string, act_id?: number, meta?: unknown) => void;
+/** A line, once it has been given its provenance. */
+export interface LogEntryFields {
+    level: logLevelType;
+    message: string;
+    pgm_cd?: string;
+    fn_cd?: string;
+    app_cd?: string;
+    act_id?: number;
+    meta?: unknown;
+}
+/** Is `lvl` within the threshold `at`? Both are level names, not numbers, at the call site. */
+export declare function withinLevel(lvl: logLevelType, at: logLevelType): boolean;

package/lib/esm/levels.js

@@ -0,0 +1,35 @@
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * Levels, and the shape of a log call — extracted from `svm-util/src/svm-util-base.ts`
+ * unchanged, so a line written against either library means the same thing.
+ *
+ * DELIBERATELY DEPENDENCY-FREE. In `svm-util` these live beside `PoolConfig` from mysql,
+ * Axios request types, Ajv and Express, in one shared types module — so importing the level
+ * enum pulled a web-server stack. That single file is why a CLI could not take the logger
+ * (911#224), and separating it is most of this package's reason to exist.
+ */
+/** Where a log line can be sent. `database` and `api` are registered by other packages. */
+export const LogMethod = { console: "console", file: "file", database: "database", api: "api" };
+export const LogLevel = {
+    error: "error", warn: "warn", info: "info", http: "http",
+    verbose: "verbose", debug: "debug", silly: "silly",
+};
+/** Ordered least to most verbose; the index IS the threshold comparison. */
+export const logLevelIndex = [
+    LogLevel.error, LogLevel.warn, LogLevel.info, LogLevel.http,
+    LogLevel.verbose, LogLevel.debug, LogLevel.silly,
+];
+export const LogLevelIndex = { error: 0, warn: 1, info: 2, http: 3, verbose: 4, debug: 5, silly: 6 };
+export const LogLevelColors = {
+    error: "red", warn: "magenta", info: "green", http: "blue",
+    verbose: "cyan", debug: "yellow", silly: "gray",
+};
+/** Is `lvl` within the threshold `at`? Both are level names, not numbers, at the call site. */
+export function withinLevel(lvl, at) {
+    return LogLevelIndex[lvl] <= LogLevelIndex[at];
+}

package/lib/esm/logger.d.ts

@@ -0,0 +1,22 @@
+import type Transport from "winston-transport";
+import type { LoggerConfig, LOG_CONFIG_METHOD } from "./config.js";
+import { type logFunctionType, type logLevelType, type logMethodType } from "./levels.js";
+/**
+ * Transports this package does not implement, contributed by packages that do.
+ *
+ * Registration is by METHOD name, so a consumer's config file is unchanged whether or not the
+ * contributing package is installed — a `database` method simply does nothing until
+ * `@svayam/svm-util-db` is present and has registered. A missing transport is a line that does
+ * not go somewhere, never a crash at startup.
+ */
+export type TransportFactory = (conf: LOG_CONFIG_METHOD, config: LoggerConfig) => Transport;
+export declare function registerTransport(method: logMethodType, make: TransportFactory): void;
+export interface ApplicationLogger {
+    readonly log: logFunctionType;
+    /** What is actually enabled, for `gov doctor`-style reporting and for tests. */
+    toLogObject(): Record<string, unknown>;
+    toString(): string;
+    close(): void;
+}
+export declare function createApplicationLogger(config: LoggerConfig): ApplicationLogger;
+export type { logLevelType, logFunctionType };

package/lib/esm/logger.js

@@ -0,0 +1,105 @@
+/* -------------------------------------------------
+*  Copyright (c) 2026 - Svayam Infoware Pvt. Ltd.
+*  All rights reserved. This code may not be copied
+*  or duplicated in whole or part by any means
+*  without express prior agreement in writing.
+*  -----------------------------------------------*/
+/**
+ * The application logger — `svm-util`'s, with the console and file transports and nothing else.
+ *
+ * TRANSPORTS ARE PLUGGABLE, and that is the change that makes this package possible.
+ * `svm-util/src/svm-logger.ts` builds every transport itself, so it imports `svm-db.js` for the
+ * database one and drags `mysql` into anything that wants to log. Here a transport for a method
+ * this package does not implement is looked up in a registry, and the packages that own those
+ * dependencies register into it (911#224).
+ *
+ * `exitOnError: false`, as in the original: a library must never take the host process down
+ * because a transport failed. That is doubly true here — the transport most likely to fail is
+ * the one writing the file you were going to read afterwards.
+ */
+import path from "node:path";
+import { createLogger, format, transports as winstonTransports, addColors } from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+import { DEFAULT_MASK } from "./config.js";
+import { LogLevel, LogLevelColors, LogLevelIndex } from "./levels.js";
+import { formatLogMessage, isLogEnabled, toLogEntry } from "./format.js";
+const registry = new Map();
+export function registerTransport(method, make) {
+    registry.set(method, make);
+}
+function buildTransports(config) {
+    const out = [];
+    for (const conf of config.methods) {
+        if (conf.METHOD === "console") {
+            out.push(new winstonTransports.Console({
+                level: conf.LOGLEVEL || LogLevel.info,
+                handleExceptions: true,
+                format: format.combine(format.colorize({ all: true }), format.printf((info) => formatLogMessage(info, config))),
+                // Diagnostics belong on STDERR. stdout is a program's ANSWER, and a caller piping it
+                // into another command should not receive the log as data.
+                stderrLevels: Object.values(LogLevel),
+            }));
+            continue;
+        }
+        if (conf.METHOD === "file") {
+            const f = conf;
+            const dir = f.DATA_STORE?.dirname ?? config.logDir;
+            out.push(new DailyRotateFile({
+                level: f.LOGLEVEL || LogLevel.info,
+                dirname: dir,
+                filename: path.join(String(f.DATA_STORE?.filename ?? ""), `%DATE%-${config.appId}.log`),
+                datePattern: f.DATA_STORE?.datePattern ?? "YYYY-MM-DD",
+                zippedArchive: f.DATA_STORE?.zippedArchive ?? true,
+                maxSize: f.DATA_STORE?.maxSize ?? "20m",
+                // A log kept forever is a disclosure risk that grows on its own; a fortnight is enough
+                // to diagnose something an adopter noticed today.
+                maxFiles: f.DATA_STORE?.maxFiles ?? "14d",
+                format: format.combine(format.printf((info) => formatLogMessage(info, config))),
+            }));
+            continue;
+        }
+        const make = registry.get(conf.METHOD);
+        if (make)
+            out.push(make(conf, config));
+        // else: declared but unavailable. Silence here is correct — see registerTransport.
+    }
+    return out;
+}
+export function createApplicationLogger(config) {
+    addColors(LogLevelColors);
+    const built = buildTransports(config);
+    const winston = createLogger({
+        levels: LogLevelIndex,
+        transports: built,
+        exitOnError: false,
+    });
+    const effective = { mask: DEFAULT_MASK, ...config };
+    const log = (lvl, msg, pgm_cd, fn_cd, act_id, meta) => {
+        // ERRORS AND WARNINGS ALWAYS PASS. Everything below them is opt-in through NODE_DEBUG, so
+        // an ordinary run is quiet — but a run that went wrong still said so without anybody
+        // having had the foresight to enable anything.
+        const always = LogLevelIndex[lvl] <= LogLevelIndex[LogLevel.warn];
+        if (!always && !isLogEnabled(pgm_cd, fn_cd, act_id))
+            return;
+        winston.log(toLogEntry(effective.appId, lvl, msg, pgm_cd, fn_cd, act_id, meta));
+    };
+    const toLogObject = () => ({
+        APP_ID: effective.appId,
+        LOG_DIR: effective.logDir,
+        REQUESTED_METHODS: effective.methods.map((m) => m.METHOD),
+        ENABLED_TRANSPORTS: winston.transports.map((t) => ({ type: t.constructor.name, level: t.level })),
+        MASK: effective.mask,
+    });
+    return {
+        log,
+        toLogObject,
+        toString: () => JSON.stringify(toLogObject()),
+        // A CLI exits in seconds and a rotating file transport writes asynchronously; without a
+        // close the last lines of a short run — the ones describing why it ended — are the ones
+        // most likely to be lost.
+        close: () => { try {
+            winston.close();
+        }
+        catch { /* closing a closed logger is not news */ } },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@svayam-opensource/svm-util-log",
+  "version": "1.0.0",
+  "description": "Svayam's shared logging framework — the logger from svm-util, with only the dependencies a logger needs.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/esm/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    }
+  },
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/esm/index.d.ts",
+  "files": [
+    "lib/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Svayamtech/911-SVM-LIB-SVC.git",
+    "directory": "packages/libraries/ts/svm-util-log"
+  },
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig-cjs.json",
+    "test": "NODE_OPTIONS='--import tsx' mocha --extensions ts 'test/**/*.test.ts'",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "winston": "^3.19.0",
+    "winston-daily-rotate-file": "^5.0.0",
+    "winston-transport": "^4.9.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.10.2",
+    "chai": "^5.1.2",
+    "mocha": "^11.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "gov": {
+    "contentSha": "4b8408bbbe485fc7feb93faad9f8642ff260fb193d76e20561f5913f6ee1fcc8",
+    "shaFrom": "built-ref",
+    "commit": "2aec38c1b7ec1dc9f658f76e8a90b7c70bb54d21"
+  }
+}