agent-first-data 0.1.3 → 0.2.1

package/README.md

@@ -0,0 +1,383 @@
+# agent-first-data
+
+**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+
+The field name is the schema. Agents read `latency_ms` and know milliseconds, `api_key_secret` and know to redact, no external schema needed.
+
+## Installation
+
+```bash
+npm install agent-first-data
+```
+
+## API Reference
+
+Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+
+### Protocol Builders (returns JsonValue)
+
+Build AFD protocol structures. Return JSON-serializable objects for API responses.
+
+```typescript
+type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+// Startup (configuration)
+buildJsonStartup(config: JsonValue, args: JsonValue, env: JsonValue): JsonValue
+
+// Success (result)
+buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue
+
+// Error (simple message)
+buildJsonError(message: string, trace?: JsonValue): JsonValue
+
+// Generic (any code + fields)
+buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue
+```
+
+**Use case:** API responses (frameworks like Express automatically serialize)
+
+**Example:**
+```typescript
+import { buildJsonStartup, buildJsonOk, buildJsonError, buildJson } from "agent-first-data";
+
+// Startup
+const startup = buildJsonStartup(
+  { api_key_secret: "sk-123", timeout_s: 30 },
+  { config_path: "config.yml" },
+  { RUST_LOG: "info" },
+);
+
+// Success (always include trace)
+const response = buildJsonOk(
+  { user_id: 123 },
+  { duration_ms: 150, source: "db" },
+);
+
+// Error
+const error = buildJsonError("user not found", { duration_ms: 5 });
+
+// Specific error code
+const notFound = buildJson(
+  "not_found",
+  { resource: "user", id: 123 },
+  { duration_ms: 8 },
+);
+```
+
+### CLI/Log Output (returns string)
+
+Format values for CLI output and logs. **All formats redact `_secret` fields.** YAML and Plain also strip suffixes from keys and format values for human readability.
+
+```typescript
+outputJson(value: JsonValue): string   // Single-line JSON, original keys, for programs/logs
+outputYaml(value: JsonValue): string   // Multi-line YAML, keys stripped, values formatted
+outputPlain(value: JsonValue): string  // Single-line logfmt, keys stripped, values formatted
+```
+
+**Example:**
+```typescript
+import { outputJson, outputYaml, outputPlain } from "agent-first-data";
+
+const data = {
+  user_id: 123,
+  api_key_secret: "sk-1234567890abcdef",
+  created_at_epoch_ms: 1738886400000,
+  file_size_bytes: 5242880,
+};
+
+// JSON (secrets redacted, original keys, raw values)
+console.log(outputJson(data));
+// {"api_key_secret":"***","created_at_epoch_ms":1738886400000,"file_size_bytes":5242880,"user_id":123}
+
+// YAML (keys stripped, values formatted, secrets redacted)
+console.log(outputYaml(data));
+// ---
+// api_key: "***"
+// created_at: "2025-02-07T00:00:00.000Z"
+// file_size: "5.0MB"
+// user_id: 123
+
+// Plain logfmt (keys stripped, values formatted, secrets redacted)
+console.log(outputPlain(data));
+// api_key=*** created_at=2025-02-07T00:00:00.000Z file_size=5.0MB user_id=123
+```
+
+### Internal Tools
+
+```typescript
+internalRedactSecrets(value: JsonValue): void  // Manually redact secrets in-place
+```
+
+Most users don't need this. Output functions automatically protect secrets.
+
+### Utility Functions
+
+```typescript
+parseSize(s: string): number | null  // Parse "10M" → bytes
+```
+
+**Example:**
+```typescript
+import { parseSize } from "agent-first-data";
+
+parseSize("10M");  // 10485760
+parseSize("1.5K"); // 1536
+parseSize("512");  // 512
+```
+
+## Usage Examples
+
+### Example 1: REST API
+
+```typescript
+import { buildJsonOk } from "agent-first-data";
+import express from "express";
+
+const app = express();
+
+app.get("/users/:id", (req, res) => {
+  const response = buildJsonOk(
+    { user_id: Number(req.params.id), name: "alice" },
+    { duration_ms: 150, source: "db" },
+  );
+  // API returns raw JSON — no output processing, no key stripping
+  res.json(response);
+});
+```
+
+### Example 2: CLI Tool (Complete Lifecycle)
+
+```typescript
+import { buildJsonStartup, buildJsonOk, buildJson, outputYaml, outputPlain } from "agent-first-data";
+
+// 1. Startup
+const startup = buildJsonStartup(
+  { api_key_secret: "sk-sensitive-key", timeout_s: 30 },
+  { input_path: "data.json" },
+  { RUST_LOG: "info" },
+);
+console.log(outputYaml(startup));
+// ---
+// code: "startup"
+// args:
+//   input_path: "data.json"
+// config:
+//   api_key: "***"
+//   timeout: "30s"
+// env:
+//   RUST_LOG: "info"
+
+// 2. Progress
+const progress = buildJson(
+  "progress",
+  { current: 3, total: 10, message: "processing" },
+  { duration_ms: 1500 },
+);
+console.log(outputPlain(progress));
+// code=progress current=3 message=processing total=10 trace.duration=1.5s
+
+// 3. Result
+const result = buildJsonOk(
+  {
+    records_processed: 10,
+    file_size_bytes: 5242880,
+    created_at_epoch_ms: 1738886400000,
+  },
+  { duration_ms: 3500, source: "file" },
+);
+console.log(outputYaml(result));
+// ---
+// code: "ok"
+// result:
+//   created_at: "2025-02-07T00:00:00.000Z"
+//   file_size: "5.0MB"
+//   records_processed: 10
+// trace:
+//   duration: "3.5s"
+//   source: "file"
+```
+
+### Example 3: JSONL Output
+
+```typescript
+import { buildJsonOk, outputJson } from "agent-first-data";
+
+const result = buildJsonOk(
+  { status: "success" },
+  { duration_ms: 250, api_key_secret: "sk-123" },
+);
+
+// Print JSONL to stdout (secrets redacted, one JSON object per line)
+console.log(outputJson(result));
+// {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
+```
+
+## Complete Suffix Example
+
+```typescript
+import { outputYaml, outputPlain } from "agent-first-data";
+
+const data = {
+  created_at_epoch_ms: 1738886400000,
+  request_timeout_ms: 5000,
+  cache_ttl_s: 3600,
+  file_size_bytes: 5242880,
+  payment_msats: 50000000,
+  price_usd_cents: 9999,
+  success_rate_percent: 95.5,
+  api_key_secret: "sk-1234567890abcdef",
+  user_name: "alice",
+  count: 42,
+};
+
+// YAML output (keys stripped, values formatted, secrets redacted)
+console.log(outputYaml(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"
+
+// Plain logfmt output (same transformations, single line)
+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:
+
+| Format | Structure | Keys | Values | Use case |
+|:-------|:----------|:-----|:-------|:---------|
+| **JSON** | single-line | original (with suffix) | raw | programs, logs |
+| **YAML** | multi-line | stripped | formatted | human inspection |
+| **Plain** | single-line logfmt | stripped | formatted | compact scanning |
+
+All formats automatically redact `_secret` fields.
+
+## Supported Suffixes
+
+- **Duration**: `_ms`, `_s`, `_ns`, `_us`, `_minutes`, `_hours`, `_days`
+- **Timestamps**: `_epoch_ms`, `_epoch_s`, `_epoch_ns`, `_rfc3339`
+- **Size**: `_bytes` (auto-scales to KB/MB/GB/TB), `_size` (config input, pass through)
+- **Currency**: `_msats`, `_sats`, `_btc`, `_usd_cents`, `_eur_cents`, `_jpy`, `_{code}_cents`
+- **Other**: `_percent`, `_secret` (auto-redacted in all formats)
+
+## License
+
+MIT

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

@@ -1,31 +1,30 @@
 /**
- * AFD output formatting: JSON, YAML, plain text with suffix-driven transforms.
+ * AFD output formatting and protocol templates.
+ *
+ * 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;
 };
-export declare enum OutputFormat {
-    Json = "json",
-    Yaml = "yaml",
-    Plain = "plain"
-}
-export declare function formatValue(fmt: OutputFormat, value: JsonValue): string;
-export declare function formatPretty(fmt: OutputFormat, value: JsonValue): string;
-export declare function toYaml(value: JsonValue): string;
-export declare function toPlain(value: JsonValue): string;
-export declare function redactSecrets(value: JsonValue): JsonValue;
-export declare function ok(result: JsonValue): JsonValue;
-export declare function okTrace(result: JsonValue, trace: JsonValue): JsonValue;
-export declare function error(message: string): JsonValue;
-export declare function errorTrace(message: string, trace: JsonValue): JsonValue;
-export declare function startup(config: JsonValue, args: JsonValue, env: JsonValue): JsonValue;
-export declare function status(code: string, fields?: {
-    [key: string]: JsonValue;
-}): JsonValue;
+/** Build {code: "startup", config, args, env}. */
+export declare function buildJsonStartup(config: JsonValue, args: JsonValue, env: JsonValue): JsonValue;
+/** Build {code: "ok", result, trace?}. */
+export declare function buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue;
+/** Build {code: "error", error: message, trace?}. */
+export declare function buildJsonError(message: string, trace?: JsonValue): JsonValue;
+/** Build {code: "<custom>", ...fields, trace?}. */
+export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
+/** Format as single-line JSON. Secrets redacted, original keys, raw values. */
+export declare function outputJson(value: JsonValue): string;
+/** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
+export declare function outputYaml(value: JsonValue): string;
+/** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
+export declare function outputPlain(value: JsonValue): string;
+/** Redact _secret fields in-place. */
+export declare function internalRedactSecrets(value: JsonValue): void;
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
  * Case-insensitive. Trims whitespace. Returns null for invalid input.
  */
 export declare function parseSize(s: string): number | null;
-export {};

package/dist/format.js

@@ -1,236 +1,119 @@
 /**
- * AFD output formatting: JSON, YAML, plain text with suffix-driven transforms.
+ * AFD output formatting and protocol templates.
+ *
+ * 9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
  */
 // ═══════════════════════════════════════════
-// OutputFormat
+// Public API: Protocol Builders
 // ═══════════════════════════════════════════
-export var OutputFormat;
-(function (OutputFormat) {
-    OutputFormat["Json"] = "json";
-    OutputFormat["Yaml"] = "yaml";
-    OutputFormat["Plain"] = "plain";
-})(OutputFormat || (OutputFormat = {}));
-export function formatValue(fmt, value) {
-    switch (fmt) {
-        case OutputFormat.Json:
-            return JSON.stringify(value);
-        case OutputFormat.Yaml:
-            return toYaml(value);
-        case OutputFormat.Plain:
-            return toPlain(value);
-    }
+/** Build {code: "startup", config, args, env}. */
+export function buildJsonStartup(config, args, env) {
+    return { code: "startup", config, args, env };
 }
-export function formatPretty(fmt, value) {
-    switch (fmt) {
-        case OutputFormat.Json:
-            return JSON.stringify(value, null, 2);
-        case OutputFormat.Yaml:
-            return toYaml(value);
-        case OutputFormat.Plain:
-            return toPlain(value);
-    }
+/** Build {code: "ok", result, trace?}. */
+export function buildJsonOk(result, trace) {
+    const m = { code: "ok", result };
+    if (trace !== undefined)
+        m.trace = trace;
+    return m;
+}
+/** Build {code: "error", error: message, trace?}. */
+export function buildJsonError(message, trace) {
+    const m = { code: "error", error: message };
+    if (trace !== undefined)
+        m.trace = trace;
+    return m;
+}
+/** Build {code: "<custom>", ...fields, trace?}. */
+export function buildJson(code, fields, trace) {
+    const result = isObject(fields) ? { ...fields } : {};
+    result.code = code;
+    if (trace !== undefined)
+        result.trace = trace;
+    return result;
 }
 // ═══════════════════════════════════════════
-// YAML
+// Public API: Output Formatters
 // ═══════════════════════════════════════════
-export function toYaml(value) {
+/** Format as single-line JSON. Secrets redacted, original keys, raw values. */
+export function outputJson(value) {
+    const v = JSON.parse(JSON.stringify(value));
+    redactSecrets(v);
+    return JSON.stringify(v);
+}
+/** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
+export function outputYaml(value) {
     const lines = ["---"];
-    renderYaml(value, 0, lines);
+    renderYamlProcessed(value, 0, lines);
     return lines.join("\n");
 }
-function renderYaml(value, indent, lines) {
-    const prefix = "  ".repeat(indent);
-    if (isObject(value)) {
-        for (const [k, v] of Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
-            if (isObject(v)) {
-                if (Object.keys(v).length > 0) {
-                    lines.push(`${prefix}${k}:`);
-                    renderYaml(v, indent + 1, lines);
-                }
-                else {
-                    lines.push(`${prefix}${k}: {}`);
-                }
-            }
-            else if (Array.isArray(v)) {
-                if (v.length === 0) {
-                    lines.push(`${prefix}${k}: []`);
-                }
-                else {
-                    lines.push(`${prefix}${k}:`);
-                    for (const item of v) {
-                        if (isObject(item)) {
-                            lines.push(`${prefix}  -`);
-                            renderYaml(item, indent + 2, lines);
-                        }
-                        else {
-                            lines.push(`${prefix}  - ${yamlScalar(item)}`);
-                        }
-                    }
-                }
-            }
-            else {
-                lines.push(`${prefix}${k}: ${yamlScalar(v)}`);
-            }
-        }
-    }
-    else {
-        lines.push(`${prefix}${yamlScalar(value)}`);
-    }
-}
-function yamlScalar(value) {
-    if (typeof value === "string") {
-        return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
-    }
-    if (value === null)
-        return "null";
-    if (typeof value === "boolean")
-        return value.toString();
-    if (typeof value === "number")
-        return value.toString();
-    return `"${String(value).replace(/"/g, '\\"')}"`;
+/** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
+export function outputPlain(value) {
+    const pairs = [];
+    collectPlainPairs(value, "", pairs);
+    pairs.sort(([a], [b]) => jcsCompare(a, b));
+    return pairs
+        .map(([k, v]) => (v.includes(" ") ? `${k}="${v}"` : `${k}=${v}`))
+        .join(" ");
 }
 // ═══════════════════════════════════════════
-// Plain
+// Public API: Redaction & Utility
 // ═══════════════════════════════════════════
-export function toPlain(value) {
-    const lines = [];
-    renderPlain(value, 0, lines);
-    return lines.join("\n");
+/** Redact _secret fields in-place. */
+export function internalRedactSecrets(value) {
+    redactSecrets(value);
 }
-function renderPlain(value, indent, lines) {
-    const prefix = "  ".repeat(indent);
-    if (isObject(value)) {
-        for (const [k, v] of Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
-            if (isObject(v)) {
-                lines.push(`${prefix}${k}:`);
-                renderPlain(v, indent + 1, lines);
-            }
-            else if (Array.isArray(v)) {
-                if (v.length === 0) {
-                    lines.push(`${prefix}${k}: []`);
-                }
-                else if (v.every((i) => !isObject(i) && !Array.isArray(i))) {
-                    lines.push(`${prefix}${k}:`);
-                    for (const item of v) {
-                        lines.push(`${prefix}  - ${plainScalar(item)}`);
-                    }
-                }
-                else {
-                    lines.push(`${prefix}${k}:`);
-                    for (const item of v) {
-                        if (isObject(item)) {
-                            lines.push(`${prefix}  -`);
-                            renderPlain(item, indent + 2, lines);
-                        }
-                        else {
-                            lines.push(`${prefix}  - ${plainScalar(item)}`);
-                        }
-                    }
-                }
-            }
-            else {
-                lines.push(`${prefix}${k}: ${formatPlainField(k, v)}`);
-            }
-        }
+/**
+ * Parse a human-readable size string into bytes.
+ * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
+ * Case-insensitive. Trims whitespace. Returns null for invalid input.
+ */
+export function parseSize(s) {
+    s = s.trim();
+    if (!s)
+        return null;
+    const multipliers = {
+        b: 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3, t: 1024 ** 4,
+    };
+    const last = s[s.length - 1].toLowerCase();
+    let numStr;
+    let mult;
+    if (last in multipliers) {
+        numStr = s.slice(0, -1);
+        mult = multipliers[last];
     }
-    else {
-        lines.push(`${prefix}${plainScalar(value)}`);
+    else if ((last >= "0" && last <= "9") || last === ".") {
+        numStr = s;
+        mult = 1;
     }
-}
-function formatPlainField(key, value) {
-    const lower = key.toLowerCase();
-    // Secret
-    if (lower.endsWith("_secret"))
-        return "***";
-    // Timestamps
-    if (lower.endsWith("_epoch_ms")) {
-        if (typeof value === "number" && Number.isInteger(value))
-            return formatRfc3339Ms(value);
-    }
-    if (lower.endsWith("_epoch_s")) {
-        if (typeof value === "number" && Number.isInteger(value))
-            return formatRfc3339Ms(value * 1000);
-    }
-    if (lower.endsWith("_epoch_ns")) {
-        if (typeof value === "number" && Number.isInteger(value))
-            return formatRfc3339Ms(Math.floor(value / 1_000_000));
-    }
-    if (lower.endsWith("_rfc3339"))
-        return plainScalar(value);
-    // Size
-    if (lower.endsWith("_bytes")) {
-        if (typeof value === "number" && Number.isInteger(value))
-            return formatBytesHuman(value);
-    }
-    // Percentage
-    if (lower.endsWith("_percent") && typeof value === "number")
-        return `${plainScalar(value)}%`;
-    // Currency — Bitcoin
-    if (lower.endsWith("_msats") && typeof value === "number")
-        return `${plainScalar(value)}msats`;
-    if (lower.endsWith("_sats") && typeof value === "number")
-        return `${plainScalar(value)}sats`;
-    if (lower.endsWith("_btc") && typeof value === "number")
-        return `${plainScalar(value)} BTC`;
-    // Currency — Fiat
-    if (lower.endsWith("_usd_cents") && typeof value === "number" && value >= 0 && Number.isInteger(value)) {
-        return `$${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`;
-    }
-    if (lower.endsWith("_eur_cents") && typeof value === "number" && value >= 0 && Number.isInteger(value)) {
-        return `\u20ac${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`;
-    }
-    if (lower.endsWith("_jpy") && typeof value === "number" && value >= 0 && Number.isInteger(value)) {
-        return `\u00a5${formatWithCommas(value)}`;
-    }
-    if (lower.endsWith("_cents")) {
-        const code = extractCurrencyCode(lower);
-        if (code && typeof value === "number" && value >= 0 && Number.isInteger(value)) {
-            return `${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")} ${code.toUpperCase()}`;
-        }
+    else {
+        return null;
     }
-    // Duration — long
-    if (lower.endsWith("_minutes") && typeof value === "number")
-        return `${plainScalar(value)} minutes`;
-    if (lower.endsWith("_hours") && typeof value === "number")
-        return `${plainScalar(value)} hours`;
-    if (lower.endsWith("_days") && typeof value === "number")
-        return `${plainScalar(value)} days`;
-    // Duration — ms
-    if (lower.endsWith("_ms") && !lower.endsWith("_epoch_ms") && typeof value === "number") {
-        if (value >= 1000)
-            return `${(value / 1000).toFixed(2)}s`;
-        return `${plainScalar(value)}ms`;
-    }
-    // Duration — ns, us, s
-    if (lower.endsWith("_ns") && !lower.endsWith("_epoch_ns") && typeof value === "number")
-        return `${plainScalar(value)}ns`;
-    if (lower.endsWith("_us") && typeof value === "number")
-        return `${plainScalar(value)}\u03bcs`;
-    if (lower.endsWith("_s") && !lower.endsWith("_epoch_s") && typeof value === "number")
-        return `${plainScalar(value)}s`;
-    return plainScalar(value);
-}
-function plainScalar(value) {
-    if (typeof value === "string")
-        return value;
-    if (value === null)
-        return "null";
-    if (typeof value === "boolean")
-        return value.toString();
-    if (typeof value === "number")
-        return value.toString();
-    return String(value);
+    if (!numStr)
+        return null;
+    const n = Number(numStr);
+    if (isNaN(n) || n < 0 || !isFinite(n))
+        return null;
+    return Math.trunc(n * mult);
 }
 // ═══════════════════════════════════════════
-// Secret redaction
+// Secret Redaction
 // ═══════════════════════════════════════════
-export function redactSecrets(value) {
+function redactSecrets(value) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (k.toLowerCase().endsWith("_secret") && typeof value[k] === "string") {
-                value[k] = "***";
+            if (k.endsWith("_secret") || k.endsWith("_SECRET")) {
+                const v = value[k];
+                if (isObject(v) || Array.isArray(v)) {
+                    redactSecrets(v);
+                }
+                else {
+                    value[k] = "***";
+                }
+            }
+            else {
+                redactSecrets(value[k]);
             }
-            redactSecrets(value[k]);
         }
     }
     else if (Array.isArray(value)) {
@@ -238,32 +121,212 @@ export function redactSecrets(value) {
             redactSecrets(item);
         }
     }
-    return value;
 }
 // ═══════════════════════════════════════════
-// AFD Protocol templates
+// Suffix Processing
 // ═══════════════════════════════════════════
-export function ok(result) {
-    return { code: "ok", result };
+function stripSuffixCI(key, suffixLower) {
+    if (key.endsWith(suffixLower))
+        return key.slice(0, -suffixLower.length);
+    const suffixUpper = suffixLower.toUpperCase();
+    if (key.endsWith(suffixUpper))
+        return key.slice(0, -suffixUpper.length);
+    return null;
 }
-export function okTrace(result, trace) {
-    return { code: "ok", result, trace };
+function tryStripGenericCents(key) {
+    const code = extractCurrencyCode(key);
+    if (code === null)
+        return null;
+    const suffixLen = code.length + "_cents".length + 1; // _{code}_cents
+    const stripped = key.slice(0, -suffixLen);
+    if (!stripped)
+        return null;
+    return [stripped, code];
 }
-export function error(message) {
-    return { code: "error", error: message };
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
 }
-export function errorTrace(message, trace) {
-    return { code: "error", error: message, trace };
+function isNum(value) {
+    return typeof value === "number";
 }
-export function startup(config, args, env) {
-    return { code: "startup", config, args, env };
+function tryProcessField(key, value) {
+    let stripped;
+    // Group 1: compound timestamp suffixes
+    stripped = stripSuffixCI(key, "_epoch_ms");
+    if (stripped !== null) {
+        if (isInt(value))
+            return [stripped, formatRfc3339Ms(value)];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_epoch_s");
+    if (stripped !== null) {
+        if (isInt(value))
+            return [stripped, formatRfc3339Ms(value * 1000)];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_epoch_ns");
+    if (stripped !== null) {
+        if (isInt(value))
+            return [stripped, formatRfc3339Ms(Math.floor(value / 1_000_000))];
+        return null;
+    }
+    // Group 2: compound currency suffixes
+    stripped = stripSuffixCI(key, "_usd_cents");
+    if (stripped !== null) {
+        if (isInt(value) && value >= 0)
+            return [stripped, `$${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_eur_cents");
+    if (stripped !== null) {
+        if (isInt(value) && value >= 0)
+            return [stripped, `\u20ac${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`];
+        return null;
+    }
+    const gc = tryStripGenericCents(key);
+    if (gc !== null) {
+        const [gcStripped, code] = gc;
+        if (isInt(value) && value >= 0)
+            return [gcStripped, `${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")} ${code.toUpperCase()}`];
+        return null;
+    }
+    // Group 3: multi-char suffixes
+    stripped = stripSuffixCI(key, "_rfc3339");
+    if (stripped !== null) {
+        if (typeof value === "string")
+            return [stripped, value];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_minutes");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)} minutes`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_hours");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)} hours`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_days");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)} days`];
+        return null;
+    }
+    // Group 4: single-unit suffixes
+    stripped = stripSuffixCI(key, "_msats");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}msats`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_sats");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}sats`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_bytes");
+    if (stripped !== null) {
+        if (isInt(value))
+            return [stripped, formatBytesHuman(value)];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_percent");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}%`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_secret");
+    if (stripped !== null)
+        return [stripped, "***"];
+    // Group 5: short suffixes (last to avoid false positives)
+    stripped = stripSuffixCI(key, "_btc");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)} BTC`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_jpy");
+    if (stripped !== null) {
+        if (isInt(value) && value >= 0)
+            return [stripped, `\u00a5${formatWithCommas(value)}`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_ns");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}ns`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_us");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}\u03bcs`];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_ms");
+    if (stripped !== null) {
+        const fv = formatMsValue(value);
+        if (fv !== null)
+            return [stripped, fv];
+        return null;
+    }
+    stripped = stripSuffixCI(key, "_s");
+    if (stripped !== null) {
+        if (isNum(value))
+            return [stripped, `${plainScalar(value)}s`];
+        return null;
+    }
+    return null;
 }
-export function status(code, fields) {
-    return { ...fields, code };
+function processObjectFields(obj) {
+    const entries = [];
+    for (const [k, v] of Object.entries(obj)) {
+        const result = tryProcessField(k, v);
+        if (result !== null) {
+            entries.push({ stripped: result[0], original: k, value: v, formatted: result[1] });
+        }
+        else {
+            entries.push({ stripped: k, original: k, value: v, formatted: null });
+        }
+    }
+    // Detect collisions
+    const counts = new Map();
+    for (const e of entries) {
+        counts.set(e.stripped, (counts.get(e.stripped) ?? 0) + 1);
+    }
+    // Resolve collisions: revert both key and formatted value
+    const result = entries.map((e) => {
+        if ((counts.get(e.stripped) ?? 0) > 1 && e.original !== e.stripped) {
+            return { key: e.original, value: e.value, formatted: null };
+        }
+        return { key: e.stripped, value: e.value, formatted: e.formatted };
+    });
+    // Sort by display key (JCS order)
+    result.sort((a, b) => jcsCompare(a.key, b.key));
+    return result;
 }
 // ═══════════════════════════════════════════
-// Helpers
+// Formatting Helpers
 // ═══════════════════════════════════════════
+function formatMsAsSeconds(ms) {
+    const formatted = (ms / 1000).toFixed(3);
+    const trimmed = formatted.replace(/0+$/, "");
+    if (trimmed.endsWith("."))
+        return trimmed + "0s";
+    return trimmed + "s";
+}
+function formatMsValue(value) {
+    if (!isNum(value))
+        return null;
+    if (Math.abs(value) >= 1000)
+        return formatMsAsSeconds(value);
+    return `${plainScalar(value)}ms`;
+}
 function formatRfc3339Ms(ms) {
     try {
         const d = new Date(ms);
@@ -291,50 +354,152 @@ function formatBytesHuman(bytes) {
     return `${bytes}B`;
 }
 function formatWithCommas(n) {
-    return n.toLocaleString("en-US");
-}
-/**
- * Parse a human-readable size string into bytes.
- * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
- * Case-insensitive. Trims whitespace. Returns null for invalid input.
- */
-export function parseSize(s) {
-    s = s.trim();
-    if (!s)
-        return null;
-    const multipliers = {
-        b: 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3, t: 1024 ** 4,
-    };
-    const last = s[s.length - 1].toLowerCase();
-    let numStr;
-    let mult;
-    if (last in multipliers) {
-        numStr = s.slice(0, -1);
-        mult = multipliers[last];
-    }
-    else if ((last >= "0" && last <= "9") || last === ".") {
-        numStr = s;
-        mult = 1;
-    }
-    else {
-        return null;
+    const s = String(n);
+    const result = [];
+    for (let i = 0; i < s.length; i++) {
+        if (i > 0 && (s.length - i) % 3 === 0)
+            result.push(",");
+        result.push(s[i]);
     }
-    if (!numStr)
-        return null;
-    const n = Number(numStr);
-    if (isNaN(n) || n < 0 || !isFinite(n))
-        return null;
-    return Math.trunc(n * mult);
+    return result.join("");
 }
+/** Extract currency code from _{code}_cents / _{CODE}_CENTS suffix. */
 function extractCurrencyCode(key) {
-    if (!key.endsWith("_cents"))
+    let withoutCents;
+    if (key.endsWith("_cents"))
+        withoutCents = key.slice(0, -6);
+    else if (key.endsWith("_CENTS"))
+        withoutCents = key.slice(0, -6);
+    else
         return null;
-    const withoutCents = key.slice(0, -6);
     const idx = withoutCents.lastIndexOf("_");
     if (idx < 0)
         return null;
-    return withoutCents.slice(idx + 1);
+    const code = withoutCents.slice(idx + 1);
+    if (!code)
+        return null;
+    return code;
+}
+// ═══════════════════════════════════════════
+// YAML Rendering
+// ═══════════════════════════════════════════
+function renderYamlProcessed(value, indent, lines) {
+    const prefix = "  ".repeat(indent);
+    if (!isObject(value)) {
+        lines.push(`${prefix}${yamlScalar(value)}`);
+        return;
+    }
+    for (const pf of processObjectFields(value)) {
+        if (pf.formatted !== null) {
+            lines.push(`${prefix}${pf.key}: "${escapeYamlStr(pf.formatted)}"`);
+        }
+        else if (isObject(pf.value)) {
+            if (Object.keys(pf.value).length > 0) {
+                lines.push(`${prefix}${pf.key}:`);
+                renderYamlProcessed(pf.value, indent + 1, lines);
+            }
+            else {
+                lines.push(`${prefix}${pf.key}: {}`);
+            }
+        }
+        else if (Array.isArray(pf.value)) {
+            if (pf.value.length === 0) {
+                lines.push(`${prefix}${pf.key}: []`);
+            }
+            else {
+                lines.push(`${prefix}${pf.key}:`);
+                for (const item of pf.value) {
+                    if (isObject(item)) {
+                        lines.push(`${prefix}  -`);
+                        renderYamlProcessed(item, indent + 2, lines);
+                    }
+                    else {
+                        lines.push(`${prefix}  - ${yamlScalar(item)}`);
+                    }
+                }
+            }
+        }
+        else {
+            lines.push(`${prefix}${pf.key}: ${yamlScalar(pf.value)}`);
+        }
+    }
+}
+function escapeYamlStr(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
 }
+function yamlScalar(value) {
+    if (typeof value === "string")
+        return `"${escapeYamlStr(value)}"`;
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value.toString();
+    if (typeof value === "number")
+        return value.toString();
+    return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+// ═══════════════════════════════════════════
+// Plain Rendering (logfmt)
+// ═══════════════════════════════════════════
+function collectPlainPairs(value, prefix, pairs) {
+    if (!isObject(value))
+        return;
+    for (const pf of processObjectFields(value)) {
+        const fullKey = prefix ? `${prefix}.${pf.key}` : pf.key;
+        if (pf.formatted !== null) {
+            pairs.push([fullKey, pf.formatted]);
+        }
+        else if (isObject(pf.value)) {
+            collectPlainPairs(pf.value, fullKey, pairs);
+        }
+        else if (Array.isArray(pf.value)) {
+            pairs.push([fullKey, pf.value.map((i) => plainScalar(i)).join(",")]);
+        }
+        else if (pf.value === null) {
+            pairs.push([fullKey, ""]);
+        }
+        else {
+            pairs.push([fullKey, plainScalar(pf.value)]);
+        }
+    }
+}
+function plainScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value.toString();
+    if (typeof value === "number")
+        return value.toString();
+    return String(value);
+}
+// ═══════════════════════════════════════════
+// Utilities
+// ═══════════════════════════════════════════
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function jcsCompare(a, b) {
+    const ua = Array.from(a).flatMap((c) => {
+        const cp = c.codePointAt(0);
+        if (cp > 0xffff) {
+            const offset = cp - 0x10000;
+            return [0xd800 + (offset >> 10), 0xdc00 + (offset & 0x3ff)];
+        }
+        return [cp];
+    });
+    const ub = Array.from(b).flatMap((c) => {
+        const cp = c.codePointAt(0);
+        if (cp > 0xffff) {
+            const offset = cp - 0x10000;
+            return [0xd800 + (offset >> 10), 0xdc00 + (offset & 0x3ff)];
+        }
+        return [cp];
+    });
+    for (let i = 0; i < ua.length && i < ub.length; i++) {
+        if (ua[i] !== ub[i])
+            return ua[i] - ub[i];
+    }
+    return ua.length - ub.length;
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
  */
-export { OutputFormat, formatValue, formatPretty, toYaml, toPlain, redactSecrets, parseSize } from "./format.js";
-export { ok, okTrace, error, errorTrace, startup, status } from "./format.js";
+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

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
  */
-export { OutputFormat, formatValue, formatPretty, toYaml, toPlain, redactSecrets, parseSize } from "./format.js";
-export { ok, okTrace, error, errorTrace, startup, status } from "./format.js";
+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.1.3",
+  "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"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "node --test src/*.test.ts --experimental-strip-types"
   },
   "devDependencies": {
-    "typescript": "^5.7"
+    "@types/node": "^25.2.3",
+    "typescript": "^5.0"
   }
 }