agent-first-data 0.2.0 → 0.2.1

package/README.md

@@ -12,7 +12,7 @@ npm install agent-first-data
 
 ## API Reference
 
-Total: **9 public APIs** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### Protocol Builders (returns JsonValue)
 
@@ -249,6 +249,115 @@ console.log(outputPlain(data));
 // api_key=*** cache_ttl=3600s count=42 created_at=2025-02-07T00:00:00.000Z file_size=5.0MB payment=50000000msats price=$99.99 request_timeout=5.0s success_rate=95.5% user_name=alice
 ```
 
+## AFD Logging
+
+AFD-compliant structured logging. Every log line is formatted using the library's own `outputJson`/`outputPlain`/`outputYaml` functions. Span fields are carried via `AsyncLocalStorage` (async-safe), automatically flattened into each log line. Zero dependencies beyond Node.js built-ins.
+
+### API
+
+```typescript
+import { log, span, initJson, initPlain, initYaml } from "agent-first-data";
+
+// Format selectors — set the output format for all subsequent log calls
+initJson()    // Single-line JSONL (secrets redacted, original keys) — default
+initPlain()   // Single-line logfmt (keys stripped, values formatted)
+initYaml()    // Multi-line YAML (keys stripped, values formatted)
+
+// Logger — each method outputs a single log line to stdout
+log.trace(msg, fields?)
+log.debug(msg, fields?)
+log.info(msg, fields?)
+log.warn(msg, fields?)
+log.error(msg, fields?)
+
+// Span — run fn with additional fields on all log events
+span<T>(fields, fn: () => T): T  // works with sync and async functions
+```
+
+### Setup
+
+```typescript
+import { log, initJson, initPlain, initYaml } from "agent-first-data";
+
+// JSON output for production (one JSONL line per event, secrets redacted)
+initJson();  // default, can be omitted
+
+// Plain logfmt for development (keys stripped, values formatted)
+initPlain();
+
+// YAML for detailed inspection (multi-line, keys stripped, values formatted)
+initYaml();
+```
+
+### Log Output
+
+Output format depends on the init function used.
+
+```typescript
+log.info("Server started");
+// JSON:  {"timestamp_epoch_ms":1739000000000,"message":"Server started","code":"info"}
+// Plain: code=info message="Server started" timestamp_epoch_ms=1739000000000
+// YAML:  ---
+//        code: "info"
+//        message: "Server started"
+//        timestamp_epoch_ms: 1739000000000
+
+log.warn("DNS lookup failed", { error: "timeout", domain: "example.com" });
+// JSON:  {"timestamp_epoch_ms":...,"message":"DNS lookup failed","error":"timeout","domain":"example.com","code":"warn"}
+// Plain: code=warn domain=example.com error=timeout message="DNS lookup failed" ...
+```
+
+### Span Support
+
+Use `span()` to add fields to all log events within the callback. Spans nest and work with both sync and async functions.
+
+```typescript
+import { log, span } from "agent-first-data";
+
+await span({ request_id: "abc-123" }, async () => {
+  log.info("Processing");
+  // {"timestamp_epoch_ms":...,"message":"Processing","request_id":"abc-123","code":"info"}
+
+  await span({ step: "validate" }, async () => {
+    log.info("Validating input");
+    // {"timestamp_epoch_ms":...,"message":"Validating input","request_id":"abc-123","step":"validate","code":"info"}
+  });
+});
+```
+
+### Custom Code Override
+
+The `code` field defaults to the log level. Override with an explicit field:
+
+```typescript
+log.info("Server ready", { code: "startup" });
+// {"timestamp_epoch_ms":...,"message":"Server ready","code":"startup"}
+```
+
+### Output Fields
+
+Every log line contains:
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `timestamp_epoch_ms` | number | Unix milliseconds |
+| `message` | string | Log message |
+| `code` | string | Level (trace/debug/info/warn/error) or explicit override |
+| *span fields* | any | From `span()` callback |
+| *event fields* | any | From fields argument |
+
+### Log Output Formats
+
+All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+
+| Format | Function | Keys | Values | Use case |
+|:-------|:---------|:-----|:-------|:---------|
+| **JSON** | `initJson` | original (with suffix) | raw | production, log aggregation |
+| **Plain** | `initPlain` | stripped | formatted | development, compact scanning |
+| **YAML** | `initYaml` | stripped | formatted | debugging, detailed inspection |
+
+All formats automatically redact `_secret` fields in log output.
+
 ## Output Formats
 
 Three output formats for different use cases:

package/dist/afd_logging.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AFD-compliant structured logging.
+ *
+ * Outputs log events using agent-first-data formatting functions:
+ * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
+ * - Plain: single-line logfmt via outputPlain (keys stripped, values formatted)
+ * - YAML: multi-line via outputYaml (keys stripped, values formatted)
+ *
+ * Span fields are carried via AsyncLocalStorage (async-safe).
+ *
+ * Usage:
+ *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afd_logging";
+ *   initJson();  // or initPlain() or initYaml()
+ *   log.info("Server started");
+ *   await span({ request_id: "abc" }, async () => {
+ *     log.info("Processing", { domain: "example.com" });
+ *   });
+ */
+/** Set log output to single-line JSONL (secrets redacted, original keys). */
+export declare function initJson(): void;
+/** Set log output to single-line logfmt (keys stripped, values formatted). */
+export declare function initPlain(): void;
+/** Set log output to multi-line YAML (keys stripped, values formatted). */
+export declare function initYaml(): void;
+/**
+ * AFD logger. Each method outputs a single log line to stdout.
+ * Format is controlled by initJson/initPlain/initYaml (default: JSON).
+ */
+export declare const log: {
+    trace: (msg: string, fields?: Record<string, unknown>) => void;
+    debug: (msg: string, fields?: Record<string, unknown>) => void;
+    info: (msg: string, fields?: Record<string, unknown>) => void;
+    warn: (msg: string, fields?: Record<string, unknown>) => void;
+    error: (msg: string, fields?: Record<string, unknown>) => void;
+};
+/**
+ * Run fn within a span that adds fields to all log events.
+ * Spans nest: inner spans inherit and can override outer span fields.
+ */
+export declare function span<T>(fields: Record<string, unknown>, fn: () => T): T;

package/dist/afd_logging.js

@@ -0,0 +1,88 @@
+/**
+ * AFD-compliant structured logging.
+ *
+ * Outputs log events using agent-first-data formatting functions:
+ * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
+ * - Plain: single-line logfmt via outputPlain (keys stripped, values formatted)
+ * - YAML: multi-line via outputYaml (keys stripped, values formatted)
+ *
+ * Span fields are carried via AsyncLocalStorage (async-safe).
+ *
+ * Usage:
+ *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afd_logging";
+ *   initJson();  // or initPlain() or initYaml()
+ *   log.info("Server started");
+ *   await span({ request_id: "abc" }, async () => {
+ *     log.info("Processing", { domain: "example.com" });
+ *   });
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { outputJson, outputYaml, outputPlain } from "./format.js";
+const spanStore = new AsyncLocalStorage();
+let currentFormat = "json";
+/** Set log output to single-line JSONL (secrets redacted, original keys). */
+export function initJson() { currentFormat = "json"; }
+/** Set log output to single-line logfmt (keys stripped, values formatted). */
+export function initPlain() { currentFormat = "plain"; }
+/** Set log output to multi-line YAML (keys stripped, values formatted). */
+export function initYaml() { currentFormat = "yaml"; }
+function emit(level, message, fields) {
+    const entry = {
+        timestamp_epoch_ms: Date.now(),
+        message,
+    };
+    // Span fields (from AsyncLocalStorage)
+    const spanFields = spanStore.getStore();
+    if (spanFields) {
+        for (const [k, v] of Object.entries(spanFields)) {
+            entry[k] = v;
+        }
+    }
+    // Event fields (override span fields on collision)
+    let hasCode = false;
+    if (fields) {
+        for (const [k, v] of Object.entries(fields)) {
+            if (k === "code")
+                hasCode = true;
+            entry[k] = v;
+        }
+    }
+    // Default code from level
+    if (!hasCode) {
+        entry["code"] = level;
+    }
+    // Format using the library's own output functions
+    const value = entry;
+    let line;
+    switch (currentFormat) {
+        case "plain":
+            line = outputPlain(value);
+            break;
+        case "yaml":
+            line = outputYaml(value);
+            break;
+        default:
+            line = outputJson(value);
+            break;
+    }
+    process.stdout.write(line + "\n");
+}
+/**
+ * AFD logger. Each method outputs a single log line to stdout.
+ * Format is controlled by initJson/initPlain/initYaml (default: JSON).
+ */
+export const log = {
+    trace: (msg, fields) => emit("trace", msg, fields),
+    debug: (msg, fields) => emit("debug", msg, fields),
+    info: (msg, fields) => emit("info", msg, fields),
+    warn: (msg, fields) => emit("warn", msg, fields),
+    error: (msg, fields) => emit("error", msg, fields),
+};
+/**
+ * Run fn within a span that adds fields to all log events.
+ * Spans nest: inner spans inherit and can override outer span fields.
+ */
+export function span(fields, fn) {
+    const parent = spanStore.getStore() ?? {};
+    return spanStore.run({ ...parent, ...fields }, fn);
+}

package/dist/format.d.ts

@@ -3,7 +3,7 @@
  *
  * 9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
  */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 /** Build {code: "startup", config, args, env}. */
@@ -28,4 +28,3 @@ export declare function internalRedactSecrets(value: JsonValue): void;
  * Case-insensitive. Trims whitespace. Returns null for invalid input.
  */
 export declare function parseSize(s: string): number | null;
-export {};

package/dist/index.d.ts

@@ -2,3 +2,4 @@
  * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
  */
 export { buildJsonStartup, buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { log, span, initJson, initPlain, initYaml } from "./afd_logging.js";

package/dist/index.js

@@ -2,3 +2,4 @@
  * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
  */
 export { buildJsonStartup, buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { log, span, initJson, initPlain, initYaml } from "./afd_logging.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents",
   "license": "MIT",
   "repository": {
@@ -14,14 +14,22 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./afd_logging": {
+      "import": "./dist/afd_logging.js",
+      "types": "./dist/afd_logging.d.ts"
     }
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "node --test src/*.test.ts --experimental-strip-types"
   },
   "devDependencies": {
+    "@types/node": "^25.2.3",
     "typescript": "^5.0"
   }
 }