Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,154 @@
import { Writable } from "node:stream";
import { describe, expect, it } from "vitest";
import { createChildLogger, createLogger, resolveLogLevel } from "./index.js";
function createLogSink() {
let buffer = "";
const records: Array<Record<string, unknown>> = [];
const stream = new Writable({
write(chunk, _encoding, callback) {
buffer += chunk.toString();
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const line of lines) {
if (line.length > 0) {
records.push(JSON.parse(line) as Record<string, unknown>);
}
}
callback();
},
});
return { records, stream };
}
describe("@toolctrl/logger", () => {
it("uses TOOLCTRL_LOG_LEVEL before LOG_LEVEL and falls back to info", () => {
expect(resolveLogLevel({ TOOLCTRL_LOG_LEVEL: "debug", LOG_LEVEL: "warn" })).toBe("debug");
expect(resolveLogLevel({ LOG_LEVEL: "warn" })).toBe("warn");
expect(resolveLogLevel({})).toBe("info");
});
it("creates structured logs without base pid/hostname metadata", () => {
const sink = createLogSink();
const logger = createLogger({ level: "info", stream: sink.stream });
logger.info({ requestId: "req-1" }, "hello");
expect(sink.records).toHaveLength(1);
expect(sink.records[0]).toMatchObject({
level: 30,
msg: "hello",
requestId: "req-1",
});
expect(sink.records[0]).not.toHaveProperty("pid");
expect(sink.records[0]).not.toHaveProperty("hostname");
});
it("creates child loggers with runtime bindings", () => {
const sink = createLogSink();
const logger = createLogger({ level: "info", stream: sink.stream });
const childLogger = createChildLogger(logger, { component: "worker", queue: "email" });
childLogger.warn({ jobId: "job-1" }, "job failed");
expect(sink.records).toHaveLength(1);
expect(sink.records[0]).toMatchObject({
level: 40,
component: "worker",
queue: "email",
jobId: "job-1",
msg: "job failed",
});
});
it("redacts secret-bearing log fields", () => {
const sink = createLogSink();
const logger = createLogger({ level: "info", stream: sink.stream });
const rawSecrets = [
"Bearer auth-token",
"session=abc",
"plain-password",
"nested-token",
"top-secret",
"api-key-value",
"redis://:redis-password@localhost:6379",
"postgres://user:password@localhost/database",
];
logger.info(
{
authorization: rawSecrets[0],
headers: { cookie: rawSecrets[1] },
password: rawSecrets[2],
nested: {
token: rawSecrets[3],
secret: rawSecrets[4],
apiKey: rawSecrets[5],
redisUrl: rawSecrets[6],
connectionString: rawSecrets[7],
},
},
"secret payload",
);
expect(sink.records).toHaveLength(1);
expect(sink.records[0]).toMatchObject({
authorization: "[Redacted]",
headers: { cookie: "[Redacted]" },
password: "[Redacted]",
nested: {
token: "[Redacted]",
secret: "[Redacted]",
apiKey: "[Redacted]",
redisUrl: "[Redacted]",
connectionString: "[Redacted]",
},
});
const serializedRecord = JSON.stringify(sink.records[0]);
for (const rawSecret of rawSecrets) {
expect(serializedRecord).not.toContain(rawSecret);
}
});
it("preserves child requestId bindings while redacting sibling secrets", () => {
const sink = createLogSink();
const logger = createLogger({ level: "info", stream: sink.stream });
const childLogger = createChildLogger(logger, {
component: "worker",
requestId: "req_correlation_1",
token: "child-token",
});
childLogger.info(
{
authorization: "Bearer request-token",
requestId: "req_correlation_1",
nested: { secret: "nested-secret", requestId: "req_nested_1" },
},
"correlated event",
);
expect(sink.records).toHaveLength(1);
expect(sink.records[0]).toMatchObject({
component: "worker",
requestId: "req_correlation_1",
token: "[Redacted]",
authorization: "[Redacted]",
nested: { secret: "[Redacted]", requestId: "req_nested_1" },
msg: "correlated event",
});
const serializedRecord = JSON.stringify(sink.records[0]);
expect(serializedRecord).toContain("req_correlation_1");
expect(serializedRecord).toContain("req_nested_1");
expect(serializedRecord).not.toContain("child-token");
expect(serializedRecord).not.toContain("Bearer request-token");
expect(serializedRecord).not.toContain("nested-secret");
});
});
@@ -0,0 +1,60 @@
import pino, { type DestinationStream, type Logger, type LoggerOptions } from "pino";
export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
export type ToolctrlLogger = Pick<Logger, "debug" | "info" | "warn" | "error" | "child">;
const REDACT_PATHS = [
"authorization",
"headers.authorization",
"req.headers.authorization",
"request.headers.authorization",
"cookie",
"headers.cookie",
"req.headers.cookie",
"request.headers.cookie",
"password",
"*.password",
"token",
"*.token",
"secret",
"*.secret",
"apiKey",
"*.apiKey",
"redisUrl",
"*.redisUrl",
"connectionString",
"*.connectionString",
] as const;
export interface CreateLoggerOptions extends Omit<LoggerOptions, "base" | "level" | "redact"> {
level?: LogLevel;
stream?: DestinationStream;
}
export function resolveLogLevel(env: NodeJS.ProcessEnv = process.env): LogLevel {
return (env.TOOLCTRL_LOG_LEVEL ?? env.LOG_LEVEL ?? "info") as LogLevel;
}
export function createLogger(options: CreateLoggerOptions = {}): ToolctrlLogger {
const { level = resolveLogLevel(), stream, ...pinoOptions } = options;
return pino(
{
...pinoOptions,
base: undefined,
level,
redact: {
paths: [...REDACT_PATHS],
censor: "[Redacted]",
},
},
stream,
);
}
export function createChildLogger(logger: ToolctrlLogger, bindings: Record<string, unknown>): ToolctrlLogger {
return logger.child(bindings);
}
export const defaultLogger = createLogger();