@kitr/logger 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @kitr/logger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Logger.** Write readable logs in development and structured logs in production.
+
+```sh
+pnpm kitr add logger
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/logger`.
+
+Read the guide at https://kitr.dev/packages/logger.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/** A log level, lowest to highest; `silent` drops everything and is for configuration only. */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+/** One log line as an object: what `write` receives and what `json` format serialises. */
+export interface LogRecord {
+  /** The level it was written at. */
+  level: LogLevel;
+  /** When it was written, as an ISO 8601 string. */
+  time: string;
+  /** The logger's name, when it has one. */
+  name?: string;
+  /** The message, or the error's message. */
+  msg: string;
+  /** Bindings, fields, `err` for errors and `durationMs` from `time()`. */
+  [key: string]: unknown;
+}
+/** Options for `createLogger`, and the shape of `config/logger.ts`. */
+export interface LoggerOptions {
+  /** The lowest level written. Default `info`. */
+  level?: LogLevel;
+  /** Shown as `[name]` in pretty output and as `name` in JSON. */
+  name?: string;
+  /** 'pretty' for terminals, 'json' for production. Default: pretty in dev, json otherwise. */
+  format?: 'pretty' | 'json';
+  /** Fields merged into every record (e.g. requestId). */
+  bindings?: Record<string, unknown>;
+  /** Where lines go. Default: console. */
+  write?: (line: string, record: LogRecord) => void;
+}
+/** A logger: one method per level, child loggers that carry fields, and timing. Bound as `logger` by the provider. */
+export interface Logger {
+  /** The lowest level written. Settable at run time; children copy it when created. */
+  level: LogLevel;
+  /** Write at `trace`: step-by-step detail. */
+  trace(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `debug`: detail for development. */
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `info`: something that happened. */
+  info(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `warn`: something odd that did not fail. */
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `error`. Pass an `Error` to keep its name, message, stack and code under `err`. */
+  error(msg: string | Error, fields?: Record<string, unknown>): void;
+  /** Write at `fatal`. Pass an `Error` to keep its name, message, stack and code under `err`. */
+  fatal(msg: string | Error, fields?: Record<string, unknown>): void;
+  /** A logger that adds `bindings` to every record, optionally under another name. */
+  child(bindings: Record<string, unknown>, name?: string): Logger;
+  /** Run `fn`, then log `msg` at info with `durationMs`, even when it throws; returns its result. */
+  time<T>(msg: string, fn: () => Promise<T>, fields?: Record<string, unknown>): Promise<T>;
+}
+/** Create a logger without the provider, for scripts, packages and tests. */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/** The options in `config/logger.ts`; the same as `LoggerOptions`. */
+export type LoggerConfig = LoggerOptions;
+declare module '@kitr/core' {
+  interface ConfigRegistry {
+    logger: LoggerConfig;
+  }
+  interface ContainerBindings {
+    logger: Logger;
+  }
+}
+/** Types `config/logger.ts`. Returns its argument unchanged. */
+export declare const defineConfig: <const C extends LoggerOptions>(config: C) => C;
+/**
+ * Binds `logger` into the container from `config/logger.ts`, on the server and in the browser.
+ * In development with devtools, every record is also mirrored to the Log panel.
+ */
+export declare const loggerProvider: import("@kitr/core").KitrProvider;
+/** A logger that discards everything, for tests. */
+export declare const silentLogger: Logger;
+export { loggerProvider as default };

package/dist/index.js

@@ -0,0 +1,146 @@
+import { createDefineConfig, defineProvider, getDevtools } from "@kitr/core";
+// src/index.ts
+const levels = {
+	trace: 10,
+	debug: 20,
+	info: 30,
+	warn: 40,
+	error: 50,
+	fatal: 60,
+	silent: 100
+};
+const colors = {
+	trace: "\x1B[90m",
+	debug: "\x1B[36m",
+	info: "\x1B[32m",
+	warn: "\x1B[33m",
+	error: "\x1B[31m",
+	fatal: "\x1B[35m",
+	silent: ""
+};
+/** Create a logger without the provider, for scripts, packages and tests. */
+function createLogger(options = {}) {
+	const isDev = globalThis.process?.env?.NODE_ENV !== "production";
+	const browserConsole = typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined" && !options.format && !options.write;
+	const format = options.format ?? (isDev ? "pretty" : "json");
+	const write = options.write ?? (browserConsole ? (_line, record) => browserWrite(record) : (line, record) => {
+		if (levels[record.level] >= levels.error) console.error(line);
+		else console.log(line);
+	});
+	const build = (bindings, name, level = options.level ?? "info") => {
+		const emit = (lvl, msg, fields) => {
+			if (levels[lvl] < levels[logger.level]) return;
+			const record = {
+				level: lvl,
+				time: (/* @__PURE__ */ new Date()).toISOString(),
+				...name ? { name } : {},
+				...withoutReserved(bindings),
+				...withoutReserved(fields),
+				msg: ""
+			};
+			if (msg instanceof Error) {
+				record.msg = msg.message;
+				record.err = {
+					name: msg.name,
+					message: msg.message,
+					stack: msg.stack,
+					...msg.code ? { code: msg.code } : {}
+				};
+			} else record.msg = msg;
+			write(format === "json" ? JSON.stringify(record) : pretty(record), record);
+		};
+		const logger = {
+			level,
+			trace: (m, f) => emit("trace", m, f),
+			debug: (m, f) => emit("debug", m, f),
+			info: (m, f) => emit("info", m, f),
+			warn: (m, f) => emit("warn", m, f),
+			error: (m, f) => emit("error", m, f),
+			fatal: (m, f) => emit("fatal", m, f),
+			child: (extra, childName) => build({
+				...bindings,
+				...extra
+			}, childName ?? name, logger.level),
+			time: async (msg, fn, fields) => {
+				const start = performance.now();
+				try {
+					return await fn();
+				} finally {
+					emit("info", msg, {
+						...fields,
+						durationMs: Math.round(performance.now() - start)
+					});
+				}
+			}
+		};
+		return logger;
+	};
+	return build(options.bindings ?? {}, options.name);
+}
+const reserved = /* @__PURE__ */ new Set([
+	"level",
+	"time",
+	"msg"
+]);
+/** Fields may not overwrite `level`, `time` or `msg`: filtering and formatting rely on them. */
+function withoutReserved(fields) {
+	if (!fields) return {};
+	let out;
+	for (const key of Object.keys(fields)) {
+		if (!reserved.has(key)) continue;
+		out ??= { ...fields };
+		delete out[key];
+	}
+	return out ?? fields;
+}
+function browserWrite(r) {
+	const { level, time: _time, name, msg, ...rest } = r;
+	const method = level === "error" || level === "fatal" ? "error" : level === "warn" ? "warn" : level === "info" ? "info" : "debug";
+	const text = `${name ? `[${name}] ` : ""}${msg}`;
+	if (Object.keys(rest).length) console[method](text, rest);
+	else console[method](text);
+}
+function pretty(r) {
+	const { level, time, name, msg, err, ...rest } = r;
+	const tag = `${colors[level]}${level.toUpperCase().padEnd(5)}\x1b[0m`;
+	const extras = Object.keys(rest).length ? ` \x1b[90m${JSON.stringify(rest)}\x1b[0m` : "";
+	const stack = err && typeof err === "object" && "stack" in err ? `\n${err.stack}` : "";
+	return `${tag} \x1b[90m${time.slice(11, 23)}\x1b[0m ${name ? `[${name}] ` : ""}${msg}${extras}${stack}`;
+}
+/** Types `config/logger.ts`. Returns its argument unchanged. */
+const defineConfig = createDefineConfig();
+/**
+* Binds `logger` into the container from `config/logger.ts`, on the server and in the browser.
+* In development with devtools, every record is also mirrored to the Log panel.
+*/
+const loggerProvider = defineProvider({
+	name: "logger",
+	register(app) {
+		app.container.singleton("logger", () => {
+			const config = app.config.get("logger", {});
+			const hub = getDevtools(app);
+			if (!hub) return createLogger(config);
+			const write = config.write ?? ((line) => console.log(line));
+			return createLogger({
+				...config,
+				write: (line, record) => {
+					write(line, record);
+					const { level, msg, time, name, ...fields } = record;
+					hub.log("logger", msg, Object.keys(fields).length ? fields : void 0, levelOf(level));
+				}
+			});
+		});
+	}
+});
+function levelOf(level) {
+	if (level === "trace" || level === "debug") return "debug";
+	if (level === "warn") return "warn";
+	if (level === "error" || level === "fatal") return "error";
+	return "info";
+}
+/** A logger that discards everything, for tests. */
+const silentLogger = createLogger({
+	level: "silent",
+	write: () => {}
+});
+export { createLogger, loggerProvider as default, loggerProvider, defineConfig, silentLogger };

package/dist/kitr.d.ts

@@ -0,0 +1,7 @@
+/** `kitr add logger`: the structured logger with levels, children and request ids. */
+declare const _default: {
+  readonly name: "logger";
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,16 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add logger`: the structured logger with levels, children and request ids. */
+var kitr_default = definePackage({
+	name: "logger",
+	add(ctx) {
+		ctx.provider.add("@kitr/logger");
+		ctx.config("logger", `import { defineConfig } from '@kitr/logger'\n\nexport default defineConfig({\n  name: 'app',\n  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',\n  // 'pretty' in dev, 'json' in production by default.\n})\n`);
+		ctx.agents.add("logger", `- Log through \`ctx.logger\` (request-scoped, carries the request id) or \`app.container.use('logger')\`. Never \`console.log\` in server code.`);
+	},
+	remove(ctx) {
+		ctx.provider.remove("@kitr/logger");
+		ctx.agents.remove("logger");
+	}
+});
+export { kitr_default as default };

package/docs/api.md

@@ -0,0 +1,127 @@
+---
+title: API reference
+description: Every export of @kitr/logger, with its signature.
+order: 2
+---
+
+# API reference
+
+Every export of `@kitr/logger`, read from the published type definitions. The [guide](/packages/logger/guide) shows them in use.
+
+## @kitr/logger
+
+### createLogger
+
+```ts
+function createLogger(options?: LoggerOptions): Logger;
+```
+
+Create a logger without the provider, for scripts, packages and tests.
+
+### defineConfig
+
+```ts
+const defineConfig: <const C extends LoggerOptions>(config: C) => C;
+```
+
+Types `config/logger.ts`. Returns its argument unchanged.
+
+### loggerProvider
+
+```ts
+const loggerProvider: import("@kitr/core").KitrProvider;
+```
+
+Binds `logger` into the container from `config/logger.ts`, on the server and in the browser.
+In development with devtools, every record is also mirrored to the Log panel.
+
+### silentLogger
+
+```ts
+const silentLogger: Logger;
+```
+
+A logger that discards everything, for tests.
+
+### Logger
+
+```ts
+interface Logger {
+  /** The lowest level written. Settable at run time; children copy it when created. */
+  level: LogLevel;
+  /** Write at `trace`: step-by-step detail. */
+  trace(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `debug`: detail for development. */
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `info`: something that happened. */
+  info(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `warn`: something odd that did not fail. */
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  /** Write at `error`. Pass an `Error` to keep its name, message, stack and code under `err`. */
+  error(msg: string | Error, fields?: Record<string, unknown>): void;
+  /** Write at `fatal`. Pass an `Error` to keep its name, message, stack and code under `err`. */
+  fatal(msg: string | Error, fields?: Record<string, unknown>): void;
+  /** A logger that adds `bindings` to every record, optionally under another name. */
+  child(bindings: Record<string, unknown>, name?: string): Logger;
+  /** Run `fn`, then log `msg` at info with `durationMs`, even when it throws; returns its result. */
+  time<T>(msg: string, fn: () => Promise<T>, fields?: Record<string, unknown>): Promise<T>;
+}
+```
+
+A logger: one method per level, child loggers that carry fields, and timing. Bound as `logger` by the provider.
+
+### LoggerOptions
+
+```ts
+interface LoggerOptions {
+  /** The lowest level written. Default `info`. */
+  level?: LogLevel;
+  /** Shown as `[name]` in pretty output and as `name` in JSON. */
+  name?: string;
+  /** 'pretty' for terminals, 'json' for production. Default: pretty in dev, json otherwise. */
+  format?: 'pretty' | 'json';
+  /** Fields merged into every record (e.g. requestId). */
+  bindings?: Record<string, unknown>;
+  /** Where lines go. Default: console. */
+  write?: (line: string, record: LogRecord) => void;
+}
+```
+
+Options for `createLogger`, and the shape of `config/logger.ts`.
+
+### LogRecord
+
+```ts
+interface LogRecord {
+  /** The level it was written at. */
+  level: LogLevel;
+  /** When it was written, as an ISO 8601 string. */
+  time: string;
+  /** The logger's name, when it has one. */
+  name?: string;
+  /** The message, or the error's message. */
+  msg: string;
+  /** Bindings, fields, `err` for errors and `durationMs` from `time()`. */
+  [key: string]: unknown;
+}
+```
+
+One log line as an object: what `write` receives and what `json` format serialises.
+
+### LoggerConfig
+
+```ts
+type LoggerConfig = LoggerOptions;
+```
+
+The options in `config/logger.ts`; the same as `LoggerOptions`.
+
+### LogLevel
+
+```ts
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+```
+
+A log level, lowest to highest; `silent` drops everything and is for configuration only.
+
+<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->

package/docs/index.md

@@ -0,0 +1,455 @@
+---
+title: Logger
+description: Write readable logs in development and structured logs in production.
+order: 1
+---
+
+# Logger
+
+When Ada reports that her order never shipped, the logs are where you find out why. In development you want lines you can read at a glance; in production you want one JSON object per line, so your log service can filter by `orderId` or `requestId`. `@kitr/logger` writes both from the same calls.
+
+> [!SUMMARY]
+> Readable logs in development and JSON logs in production, with levels, child loggers and a request id on every server line. Every kitr app with a server includes it; the overview is at [/packages/logger](/packages/logger).
+
+It runs on the server and in the browser and is for lines a developer reads. For alerts with the user and the steps that led to an error, use [monitoring](/packages/monitoring); to count what users do, use [analytics](/packages/analytics).
+
+The examples follow Acme's app at `app.acme.com`, where Ada, Grace and Linus read the logs when something goes wrong.
+
+## Install
+
+```sh
+kitr add logger
+```
+
+<details>
+<summary>Everything kitr add changes</summary>
+
+What `kitr add` does:
+
+- Installs `@kitr/logger`.
+- Adds `'@kitr/logger'` to `packages` and `() => import('@kitr/logger')` to `providers` in `kitrrc.ts`.
+- Writes `config/logger.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
+- Adds a `## kitr: logger` section to `AGENTS.md` telling coding agents to log through `ctx.logger` or `app.container.use('logger')`, never `console.log` in server code.
+
+The [server](/packages/server) package requires the logger, so `kitr add server` adds it first and adds `LOG_LEVEL=info` to `.env.example`. Every kit with a server platform already has it.
+
+`kitr remove logger` reverses these steps and deletes `config/logger.ts`.
+
+</details>
+
+## Configure
+
+`kitr add logger` writes this file:
+
+```ts
+// config/logger.ts
+import { defineConfig } from '@kitr/logger'
+
+export default defineConfig({
+  name: 'app',
+  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
+  // 'pretty' in dev, 'json' in production by default.
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `level` | `'info'` | The lowest level written: `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `silent`. |
+| `name` | none | Shown in brackets before each message in pretty output, and as `name` in JSON. |
+| `format` | `'pretty'` unless `NODE_ENV` is `production`, then `'json'` | How each line is written. |
+| `bindings` | `{}` | Fields added to every record, such as `{ region: 'eu-west-1' }`. |
+| `write(line, record)` | the console | Where lines go. The default writes `error` and `fatal` to `console.error` (stderr) and the rest to `console.log` (stdout). |
+
+| Variable | Used for |
+| --- | --- |
+| `LOG_LEVEL` | The lowest level to print, such as `info`. |
+
+The default `format` reads `process.env.NODE_ENV`, not the app's mode. In the browser the logger calls the console directly; see [Log in the browser](#log-in-the-browser).
+
+## Write your first log line
+
+In a controller, the logger is `ctx.logger`. It is a child of the app's logger that adds the request id to every line:
+
+```ts
+// server/controllers/orders-controller.ts
+import type { HttpContext } from '@kitr/api'
+
+export default class OrdersController {
+  async ship({ logger, params }: HttpContext<{ id: string }>) {
+    logger.info('order shipped', { orderId: params.id })
+    return { orderId: params.id, status: 'shipped' }
+  }
+}
+```
+
+Call `POST /api/orders/1042/ship` in development and the server prints:
+
+```
+INFO  14:03:22.418 [app] order shipped {"requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042"}
+```
+
+In production, where `NODE_ENV=production`, the same call writes one JSON object:
+
+```json
+{"level":"info","time":"2026-11-07T14:03:22.418Z","name":"app","requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042","msg":"order shipped"}
+```
+
+Keep the message fixed and put the variable parts in fields: `'order shipped'` with `{ orderId }`, not `` `order ${id} shipped` ``. Your log service can then count and filter the lines.
+
+## Write at a level
+
+Each level has a method. Lines below the configured `level` are dropped before formatting, so a `debug` call in a hot path is nearly free in production.
+
+| Level | Method | Use it for |
+| --- | --- | --- |
+| `trace` | `logger.trace(msg, fields?)` | Step-by-step detail you only turn on while debugging one thing. |
+| `debug` | `logger.debug(msg, fields?)` | Detail for development: the server's request lines, cache hits. |
+| `info` | `logger.info(msg, fields?)` | Things that happened: an order shipped, a job finished. |
+| `warn` | `logger.warn(msg, fields?)` | Something odd that did not fail: a slow query, a retry. |
+| `error` | `logger.error(msgOrError, fields?)` | A failure someone should look at. |
+| `fatal` | `logger.fatal(msgOrError, fields?)` | The process cannot continue. |
+
+`silent` is a level for configuration only: it drops everything.
+
+```ts
+// server/services/project-service.ts
+import type { KitrApp } from '@kitr/kitr/app'
+
+export async function syncProject(app: KitrApp, projectId: string) {
+  const logger = app.container.use('logger')
+  logger.debug('loading project', { projectId })
+  logger.warn('slow query', { projectId, ms: 1840 })
+  logger.info('project synced', { projectId, tasks: 42 })
+}
+```
+
+## Log an error
+
+Pass the `Error` itself to `error()` or `fatal()`. Its message becomes `msg`, and its name, message, stack and `code` are kept under `err`:
+
+```ts
+// server/services/invoice-service.ts
+import type { KitrApp } from '@kitr/kitr/app'
+
+export async function generateInvoice(app: KitrApp, invoiceNumber: string) {
+  const logger = app.container.use('logger')
+  try {
+    throw Object.assign(new Error('connect ECONNREFUSED 10.0.0.5:5432'), { code: 'ECONNREFUSED' })
+  } catch (error) {
+    logger.error(error as Error, { invoiceNumber })
+    throw error
+  }
+}
+```
+
+In JSON that becomes:
+
+```json
+{"level":"error","time":"2026-11-07T14:05:10.002Z","name":"app","invoiceNumber":"INV-2026-007","msg":"connect ECONNREFUSED 10.0.0.5:5432","err":{"name":"Error","message":"connect ECONNREFUSED 10.0.0.5:5432","stack":"Error: connect ECONNREFUSED ...","code":"ECONNREFUSED"}}
+```
+
+> [!WARNING] Pass the error as the first argument
+> `logger.error('failed', { error })` writes `{}`, because an `Error`'s message and stack are not enumerable.
+
+The server already logs every 5xx response at `error` level, so log only errors you catch and handle yourself.
+
+## Add fields to every line
+
+`child(bindings, name?)` returns a logger that adds `bindings` to every record, so an id travels with a piece of work:
+
+```ts
+// server/services/order-service.ts
+import type { KitrApp } from '@kitr/kitr/app'
+
+export async function shipOrder(app: KitrApp, orderId: string) {
+  const logger = app.container.use('logger').child({ orderId }, 'orders')
+  logger.info('picking items')
+  logger.info('label printed', { carrier: 'DHL' })
+  logger.info('order shipped')
+  return { orderId, status: 'shipped' as const }
+}
+```
+
+```
+INFO  14:03:22.418 [orders] picking items {"orderId":"1042"}
+INFO  14:03:22.419 [orders] label printed {"orderId":"1042","carrier":"DHL"}
+INFO  14:03:22.420 [orders] order shipped {"orderId":"1042"}
+```
+
+A child keeps its parent's bindings; fields passed in a call win over bindings with the same key. For fields every line should carry, such as the region, set `bindings` in `config/logger.ts`:
+
+```ts
+// config/logger.ts
+import { defineConfig } from '@kitr/logger'
+
+export default defineConfig({
+  name: 'app',
+  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
+  bindings: { region: process.env.FLY_REGION ?? 'local', release: process.env.RELEASE ?? 'dev' },
+})
+```
+
+> [!WARNING] Reserved names
+> `level`, `time` and `msg` are reserved. A field or binding with one of those names is dropped.
+
+## Log during a request
+
+Every request gets its own child logger with `requestId`, taken from the `x-request-id` header or a new UUID and echoed in the response header. Grep for it to see every line one request wrote.
+
+| Where | How |
+| --- | --- |
+| A controller | `ctx.logger` |
+| Middleware, an action or a service during a request | `useRequest().logger`, with `useRequest` from `@kitr/server` |
+| Code that may run inside or outside a request | `tryUseRequest()?.logger ?? app.container.use('logger')` |
+
+```ts
+// server/services/team-service.ts
+import { useRequest } from '@kitr/server'
+
+export function inviteToTeam(teamId: string, email: string) {
+  const { logger } = useRequest()
+  logger.info('team invite sent', { teamId, invitee: email })
+}
+```
+
+`useRequest()` throws outside a request, such as in a job or at startup.
+
+When a request finishes, the server writes one `debug` line with the method, path, status, client IP and duration:
+
+```
+DEBUG 14:03:22.431 [app] POST /api/orders/1042/ship {"requestId":"9b2f6c1e-...","status":200,"ip":"127.0.0.1","durationMs":13}
+```
+
+Set `LOG_LEVEL=debug` to see them.
+
+## Log outside a request
+
+The provider binds the logger as `logger` in the container. Jobs, scripts and providers read it from there:
+
+```ts
+// server/jobs/prune-sessions.ts
+import { defineJob } from '@kitr/jobs'
+
+export const pruneSessions = defineJob('prune_sessions', {
+  schedule: '0 3 * * *',
+  async run(_payload, { app, jobId }) {
+    const logger = app.container.use('logger').child({ jobId }, 'jobs')
+    logger.info('pruning expired sessions')
+  },
+})
+```
+
+The server keeps the same logger as `server.logger`, set once `server.boot()` has run.
+
+## Log in the browser
+
+In a component, read the logger with `useService` from [`@kitr/react`](/packages/react):
+
+```tsx
+// app/components/projects/project-actions.tsx
+import { useService } from '@kitr/react'
+
+export function ArchiveProjectButton({ projectId }: { projectId: string }) {
+  const logger = useService('logger')
+  return (
+    <button type="button" onClick={() => logger.info('project archived', { projectId })}>
+      Archive
+    </button>
+  )
+}
+```
+
+Browser lines go to the matching console method with the fields as an expandable object, for example `console.info('[app] project archived', { projectId })`. Set `format` or `write` for formatted lines instead. Nothing is sent to your server; to collect client-side failures, use [monitoring](/packages/monitoring).
+
+## Time an operation
+
+`logger.time(msg, fn, fields?)` runs an async function, logs `msg` at `info` with `durationMs` when it settles, and returns its result:
+
+```ts
+// server/services/invoice-service.ts
+import type { KitrApp } from '@kitr/kitr/app'
+
+export async function renderInvoicePdf(app: KitrApp, invoiceNumber: string) {
+  const logger = app.container.use('logger').child({ invoiceNumber }, 'billing')
+  const bytes = await logger.time('rendered invoice PDF', async () => new Uint8Array(48_213), {
+    pages: 2,
+  })
+  return bytes.length
+  // => 48213
+}
+```
+
+```
+INFO  14:07:41.006 [billing] rendered invoice PDF {"invoiceNumber":"INV-2026-007","pages":2,"durationMs":212}
+```
+
+The line is written even when the function throws, and the error is rethrown. The line doesn't say it failed, so log the error separately.
+
+## Change the level at run time
+
+Set `level` to turn on debug output in a running process:
+
+```ts
+// server/controllers/admin-controller.ts
+import type { HttpContext } from '@kitr/api'
+
+export default class AdminController {
+  async setLogLevel({ app, body }: HttpContext<{}, {}, { level: 'debug' | 'info' }>) {
+    const logger = app.container.use('logger')
+    logger.level = body.level
+    return { level: logger.level }
+  }
+}
+```
+
+A child copies its parent's level when created, so a change affects only children created afterwards, such as the next request's logger. Protect a route like this with [auth](/packages/auth).
+
+## Choose the output format
+
+`pretty` is for terminals: a coloured level, the UTC time, `[name]`, the message, fields as dim JSON and any stack. `json` is one record per line, with keys in this order: `level`, `time`, `name`, bindings, fields, `msg`, `err`.
+
+Force one format everywhere, for example JSON in a staging environment that runs with `NODE_ENV=development`:
+
+```ts
+// config/logger.ts
+import { defineConfig } from '@kitr/logger'
+
+export default defineConfig({
+  name: 'app',
+  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
+  format: process.env.LOG_FORMAT === 'json' ? 'json' : undefined,
+})
+```
+
+Most hosting platforms collect stdout and stderr and parse JSON lines into searchable fields, so `json` in production needs nothing else.
+
+## Send logs to a file or a service
+
+`write(line, record)` replaces the console. It receives the formatted line and the record for every line at or above the level:
+
+```ts
+// config/logger.ts
+import { appendFileSync } from 'node:fs'
+import { defineConfig } from '@kitr/logger'
+
+export default defineConfig({
+  name: 'app',
+  format: 'json',
+  write(line, record) {
+    appendFileSync('storage/logs/app.log', `${line}\n`)
+    if (record.level === 'error' || record.level === 'fatal') console.error(line)
+  },
+})
+```
+
+To ship to an HTTP endpoint, buffer records and send them in batches:
+
+```ts
+// server/log_shipper.ts
+import type { LogRecord } from '@kitr/logger'
+
+const buffer: LogRecord[] = []
+
+export function shipLog(_line: string, record: LogRecord) {
+  buffer.push(record)
+  if (buffer.length >= 100) void flushLogs()
+}
+
+export async function flushLogs() {
+  const batch = buffer.splice(0)
+  if (!batch.length) return
+  await fetch('https://logs.acme.com/ingest', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(batch),
+  }).catch(() => {
+    // Never let logging take the app down.
+  })
+}
+
+setInterval(flushLogs, 5_000).unref()
+```
+
+```ts
+// config/logger.ts
+import { defineConfig } from '@kitr/logger'
+import { shipLog } from '#server/log_shipper'
+
+export default defineConfig({ name: 'app', format: 'json', write: shipLog })
+```
+
+> [!WARNING] Keep write fast and safe
+> `write` runs synchronously on every log call, and a throw escapes the `logger.info()` that triggered it. Catch inside it.
+
+## Create a logger without the provider
+
+`createLogger(options)` takes the same options as `config/logger.ts`. Use it in scripts or anywhere no app exists:
+
+```ts
+// scripts/import_projects.ts
+import { createLogger } from '@kitr/logger'
+
+const logger = createLogger({ name: 'import', level: 'debug' })
+logger.info('importing projects', { file: 'projects.csv' })
+```
+
+`silentLogger` writes nothing; pass it where an API wants a logger and you want no output.
+
+## See logs in devtools
+
+With [devtools](/packages/devtools) installed, every record is copied to the Log panel under the `logger` channel, so server and client lines sit in one place.
+
+## Testing
+
+`createLogger({ write })` lets a test collect records. For code that reads the logger from the container, boot an app with the provider and a collecting `write`:
+
+```ts
+// test/ship-order.test.ts
+import { type LogRecord, loggerProvider } from '@kitr/logger'
+import { createTestApp } from '@kitr/testing'
+import { describe, expect, it } from 'vitest'
+import { shipOrder } from '#server/services/order-service'
+
+describe('shipOrder', () => {
+  it('logs each step with the order id', async () => {
+    const records: LogRecord[] = []
+    const app = await createTestApp({
+      providers: [loggerProvider],
+      config: {
+        logger: { level: 'debug', format: 'json', write: (_line, record) => records.push(record) },
+      },
+    })
+
+    await shipOrder(app, '1042')
+
+    expect(records.map((r) => r.msg)).toEqual(['picking items', 'label printed', 'order shipped'])
+    expect(records[1]).toMatchObject({
+      level: 'info',
+      name: 'orders',
+      orderId: '1042',
+      carrier: 'DHL',
+    })
+  })
+})
+```
+
+Each record is a plain object with `level`, `msg`, `name`, your fields and bindings, `err` and `durationMs`, so assert with `toMatchObject`. To check a line's exact text, assert on the first argument of `write`. To keep a noisy test quiet, use `level: 'silent'` or `silentLogger`:
+
+```ts
+// test/quiet-server.test.ts
+import { silentLogger } from '@kitr/logger'
+import { createServer } from '@kitr/server'
+import { expect, it } from 'vitest'
+
+it('answers the health check without printing', async () => {
+  const server = createServer({ logger: silentLogger })
+  const res = await server.fetch(new Request('http://localhost/healthz'))
+  expect(await res.json()).toEqual({ ok: true })
+})
+```
+
+## Next steps
+
+- [Logger API reference](/packages/logger/api): every export with its signature.
+- [Server](/packages/server): request ids, the request logger and error logging.
+- [Monitoring](/packages/monitoring): alerts with user and breadcrumbs when something breaks.

package/docs/overview.md

@@ -0,0 +1,72 @@
+---
+title: Overview
+description: Write readable logs in development and structured logs in production.
+order: 0
+---
+
+# Logger
+
+## What it is
+
+`@kitr/logger` is a small logger with levels, child loggers that carry fields, and two output formats: readable in development, JSON in production. On the server every request gets a child logger with its request id.
+
+Runs on the server and in the browser. For alerts about errors, use [monitoring](/packages/monitoring).
+
+## Install
+
+```sh
+kitr add logger
+```
+
+Adds `@kitr/logger`, its provider and `config/logger.ts`. [server](/packages/server) adds it for you. [Every change](/packages/logger/guide#install).
+
+## Quick start
+
+In a controller, the logger is `ctx.logger`, a child of the app's logger that adds the request id to every line:
+
+```ts
+// server/controllers/orders_controller.ts
+import type { HttpContext } from '@kitr/api'
+
+export default class OrdersController {
+  async ship({ logger, params }: HttpContext<{ id: string }>) {
+    logger.info('order shipped', { orderId: params.id })
+    return { orderId: params.id, status: 'shipped' }
+  }
+}
+```
+
+Call `POST /api/orders/1042/ship` in development and the server prints:
+
+```
+INFO  14:03:22.418 [app] order shipped {"requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042"}
+```
+
+In production, where `NODE_ENV=production`, the same call writes one JSON object per line, ready for your log service:
+
+```json
+{"level":"info","time":"2026-11-07T14:03:22.418Z","name":"app","requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042","msg":"order shipped"}
+```
+
+Keep the message fixed and put the variable parts in fields, so a log service can count every `order shipped` line. Next in the guide: [Write your first log line](/packages/logger/guide#write-your-first-log-line).
+
+## Built on
+
+kitr adds the request-scoped child logger, the pretty format, timing, run-time level changes and the devtools mirror.
+
+## Problems it solves
+
+- **Unreadable logs in development, unsearchable logs in production.** [Choose the output format](/packages/logger/guide#choose-the-output-format).
+- **Repeating the same fields on every line.** [Add fields to every line](/packages/logger/guide#add-fields-to-every-line).
+- **Lines you cannot tie to a request.** [Log during a request](/packages/logger/guide#log-during-a-request).
+- **Errors logged as `[object Object]`.** [Log an error](/packages/logger/guide#log-an-error).
+- **Timing by hand.** [Time an operation](/packages/logger/guide#time-an-operation).
+- **Restarting to see debug output.** [Change the level at run time](/packages/logger/guide#change-the-level-at-run-time).
+
+## Further reading
+
+- [Guide](/packages/logger/guide).
+- [API reference](/packages/logger/api).
+- [Server](/packages/server).
+- [Monitoring](/packages/monitoring) and [Devtools](/packages/devtools).
+- [Configuration](/docs/configuration).

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@kitr/logger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "@kitr/logger: a tiny structured logger with levels, children and pretty/JSON output. No dependencies.",
+  "kitr": {
+    "name": "logger",
+    "title": "Logger",
+    "summary": "Write readable logs in development and structured logs in production.",
+    "category": "dev-tools",
+    "runsOn": "both",
+    "docs": "docs",
+    "setup": "./kitr"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitrjs/kitr.git",
+    "directory": "packages/logger"
+  },
+  "homepage": "https://kitr.dev/packages/logger",
+  "bugs": "https://github.com/kitrjs/kitr/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kitr": {
+      "types": "./dist/kitr.d.ts",
+      "default": "./dist/kitr.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@kitr/core": "0.3.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "tsdown": "^0.23.7",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "kitr",
+    "kitr-package"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }