argsbarg 6.1.7 → 6.1.9

package/examples/full-example/docs/cli.md

@@ -195,7 +195,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -231,7 +231,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -408,7 +408,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -444,7 +444,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -649,7 +649,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -685,7 +685,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -872,7 +872,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -908,7 +908,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1085,7 +1085,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1121,7 +1121,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1309,7 +1309,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1345,7 +1345,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1522,7 +1522,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1558,7 +1558,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1735,7 +1735,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1771,7 +1771,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1948,7 +1948,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1984,7 +1984,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |

package/examples/full-example/docs/http.md

@@ -45,6 +45,16 @@ Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.
 
 Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.
 
+## Logging
+
+Server logs go to **stderr** (one JSON object per line by default).
+
+- Configure with `program.log` on the program root
+- **`enrich`** — add custom JSON fields on top of the default line
+- **`serialize`** — replace the formatter and emit your own line shape
+
+See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/main/docs/logging.md) for examples and the full `LogEnrichContext` shape.
+
 ## REST routes
 
 - `POST /echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).

package/index.d.ts

@@ -113,6 +113,59 @@ export declare class CliContext {
 	private _posMap;
 	private _positionalMap;
 }
+/** ECS version string written to every JSON log line. */
+export declare const ECS_VERSION = "8.11.0";
+/** Severity label for ECS `log.level`. */
+export type EcsLogLevel = "debug" | "info" | "warn" | "error";
+/** Fields merged into every ECS log line. */
+export interface EcsServiceFields {
+	name: string;
+	version: string;
+}
+/** Context for {@link CliLogConfig.enrich} and {@link CliLogConfig.serialize}. */
+export interface LogEnrichContext {
+	level: EcsLogLevel;
+	message: string;
+	action?: string;
+	requestId?: string;
+	traceId?: string;
+	spanId?: string;
+	labels?: Record<string, string | number | boolean>;
+	error?: unknown;
+	service: EcsServiceFields;
+	http?: {
+		method: string;
+		path: string;
+		status: number;
+		durationMs: number;
+		clientIp?: string;
+	};
+}
+/** Input for one ECS log event. */
+export interface EcsLogEvent {
+	level: EcsLogLevel;
+	message: string;
+	action?: string;
+	labels?: Record<string, string | number | boolean>;
+	error?: unknown;
+	fields?: Record<string, unknown>;
+	requestId?: string;
+	traceId?: string;
+	spanId?: string;
+	/** Populated on HTTP/MCP access log events for {@link CliLogConfig.enrich}. */
+	http?: LogEnrichContext["http"];
+}
+/** Options for {@link formatEcsLine}. */
+export interface FormatEcsLineOpts {
+	service: EcsServiceFields;
+	event: EcsLogEvent;
+	/** Additive fields merged after the ECS baseline (cannot override protected keys). */
+	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
+}
+/** Formats one ECS Logging–compatible JSON log line (newline omitted). */
+export declare function formatEcsLine(opts: FormatEcsLineOpts): string;
+/** @deprecated Pass {@link FormatEcsLineOpts} instead. */
+export declare function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string;
 /**
  * How a leaf handler was dispatched.
  */
@@ -324,6 +377,10 @@ export interface CliHttpWireContext {
 	clientIp: string;
 	path: string;
 	method: string;
+	/** W3C trace id when `traceparent` is present on the request. */
+	traceId?: string;
+	/** Span id for this server hop when `traceparent` is present. */
+	spanId?: string;
 }
 /** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
 export interface CliMcpWireHooks {
@@ -672,6 +729,8 @@ export interface InvokeHookContext {
 		request: Request;
 		clientIp: string;
 		requestId: string;
+		traceId?: string;
+		spanId?: string;
 	};
 	mcp?: {
 		rpcMethod: string;
@@ -717,9 +776,9 @@ export interface ReadinessContext {
 	appConfig: AnyAppConfigSnapshot;
 	runtime: ServerRuntime;
 }
-/** Framework logging defaults (ECS json or human text on stderr). */
+/** Framework logging defaults (ECS Logging json or human text on stderr). */
 export interface CliLogConfig {
-	/** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+	/** `json` = ECS Logging lines; `text` = human stderr lines. Default: `json`. */
 	format?: "json" | "text";
 	/** Tee stderr + append; relative paths resolve under the app config dir. */
 	file?: string;
@@ -727,6 +786,16 @@ export interface CliLogConfig {
 	access?: boolean;
 	/** Emit error events after the hook pipeline. Default: true. */
 	errors?: boolean;
+	/**
+	 * Add non-standard fields to each JSON log line after the ECS baseline.
+	 * Cannot override `@timestamp`, `log.level`, `message`, `ecs.version`, or service fields.
+	 */
+	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
+	/**
+	 * Full control over JSON log line serialization. When set, bypasses the built-in ECS formatter.
+	 * The consumer owns the entire line (including newline omission).
+	 */
+	serialize?: (ctx: LogEnrichContext) => string;
 }
 /**
  * Program root passed to {@link Cli}.
@@ -870,17 +939,6 @@ export interface CliSchemaRootExport extends CliSchemaExport {
 	/** Program-level error JSON Schema when configured on `httpServer.errors` or `mcpServer.errors`. */
 	errorSchema?: Record<string, unknown>;
 }
-/** Severity label for ECS `log.level`. */
-export type EcsLogLevel = "debug" | "info" | "warn" | "error";
-/** Input for one ECS log event. */
-export interface EcsLogEvent {
-	level: EcsLogLevel;
-	message: string;
-	action?: string;
-	labels?: Record<string, string | number | boolean>;
-	error?: unknown;
-	fields?: Record<string, unknown>;
-}
 /** Resolved logging options for a server or invoke session. */
 export interface ResolvedLogConfig {
 	format: "json" | "text";
@@ -888,6 +946,8 @@ export interface ResolvedLogConfig {
 	access: boolean;
 	errors: boolean;
 	dev: boolean;
+	enrich?: CliLogConfig["enrich"];
+	serialize?: CliLogConfig["serialize"];
 }
 /** Options for {@link LogEmitter}. */
 export interface LogEmitterOpts {
@@ -911,10 +971,18 @@ declare class LogEmitter {
 		durationMs: number;
 		requestId?: string;
 		clientIp?: string;
+		traceId?: string;
+		spanId?: string;
 	}): void;
 	/** Error log after the hook pipeline (real stack always included). */
-	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, labels?: Record<string, string | number | boolean>): void;
+	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, meta?: {
+		labels?: Record<string, string | number | boolean>;
+		requestId?: string;
+		traceId?: string;
+		spanId?: string;
+	}): void;
 	private formatLine;
+	private buildEnrichContext;
 	private formatTextLine;
 	private appendFile;
 }
@@ -996,6 +1064,8 @@ export declare class Cli {
 			request: Request;
 			clientIp: string;
 			requestId: string;
+			traceId?: string;
+			spanId?: string;
 		};
 		mcp?: {
 			rpcMethod: string;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "argsbarg",
-  "version": "6.1.7",
+  "version": "6.1.9",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {
+    "@cfworker/json-schema": "^4",
     "ts-json-schema-generator": "^2.3.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.0",
+    "@biomejs/biome": "^2.5.5",
     "@types/bun": "^1.3.12",
     "dts-bundle-generator": "^9.5.1",
     "typescript": "^5.9.3"

package/src/builtins/http.ts

@@ -18,7 +18,7 @@ const HTTP_SERVE_OPTIONS: CliOption[] = [
   { name: "obscure-errors", description: "Hide unexpected errors from clients.", kind: CliOptionKind.Presence },
   {
     name: "log-format",
-    description: "Log format: json (ECS) or text.",
+    description: "Log format: json (ECS Logging) or text.",
     kind: CliOptionKind.Enum,
     choices: ["json", "text"],
   },

package/src/builtins/mcp.ts

@@ -13,7 +13,7 @@ const MCP_SERVE_OPTIONS: CliOption[] = [
   { name: "obscure-errors", description: "Hide unexpected errors from clients.", kind: CliOptionKind.Presence },
   {
     name: "log-format",
-    description: "Log format: json (ECS) or text.",
+    description: "Log format: json (ECS Logging) or text.",
     kind: CliOptionKind.Enum,
     choices: ["json", "text"],
   },

package/src/config/validate.test.ts

@@ -3,7 +3,7 @@ Tests for config/validate module behavior.
 */
 
 import { describe, expect, test } from "bun:test";
-import { parseConfigSetValue, validateConfigDocument } from "./validate.ts";
+import { parseConfigSetValue, resolveSchemaDraft, validateConfigDocument } from "./validate.ts";
 
 const rootSchema = {
   type: "object",
@@ -98,4 +98,48 @@ describe("config/validate", () => {
     expect(() => parseConfigSetValue("a,b", schema, rootSchema, false)).toThrow(/--json/);
     expect(parseConfigSetValue('[{"ttl":1}]', schema, rootSchema, false)).toEqual([{ ttl: 1 }]);
   });
+
+  test("resolveSchemaDraft maps $schema URIs", () => {
+    expect(resolveSchemaDraft({ $schema: "http://json-schema.org/draft-07/schema#" })).toBe("7");
+    expect(resolveSchemaDraft({ $schema: "https://json-schema.org/draft/2020-12/schema" })).toBe("2020-12");
+    expect(resolveSchemaDraft({ $schema: "https://json-schema.org/draft/2019-09/schema" })).toBe("2019-09");
+    expect(resolveSchemaDraft({})).toBe("7");
+  });
+
+  test("validates draft 2020-12 schemas when $schema is set", () => {
+    const schema = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      additionalProperties: false,
+      required: ["name"],
+      properties: {
+        name: { type: "string", minLength: 1 },
+      },
+    };
+    expect(validateConfigDocument({ name: "ok" }, schema).valid).toBe(true);
+    expect(validateConfigDocument({ name: "" }, schema).valid).toBe(false);
+    expect(validateConfigDocument({}, schema).valid).toBe(false);
+  });
+
+  test("validates draft 2020-12 $defs refs", () => {
+    const schema = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      type: "object",
+      additionalProperties: false,
+      required: ["item"],
+      properties: {
+        item: { $ref: "#/$defs/Item" },
+      },
+      $defs: {
+        Item: {
+          type: "object",
+          additionalProperties: false,
+          required: ["id"],
+          properties: { id: { type: "string" } },
+        },
+      },
+    };
+    expect(validateConfigDocument({ item: { id: "a" } }, schema).valid).toBe(true);
+    expect(validateConfigDocument({ item: { id: 1 } }, schema).valid).toBe(false);
+  });
 });