agent-first-data 0.2.4 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-first-data
 
-**Agent-First Data (AFD)** — Suffix-driven output formatting and protocol templates for AI agents.
+**Agent-First Data (AFDATA)** — 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.
 
@@ -18,23 +18,37 @@ A backup tool invoked from the CLI — flags, env vars, and config all use the s
 API_KEY_SECRET=sk-1234 cloudback --timeout-s 30 --max-file-size-bytes 10737418240 /data/backup.tar.gz
 ```
 
-The tool reads env vars, flags, and config — all with AFD suffixes — and emits a startup message:
+For CLI diagnostics, enable log categories explicitly:
+
+```bash
+--log startup,request,progress,retry,redirect
+--verbose   # shorthand for all categories
+```
+
+Without these flags, startup diagnostics should stay off by default.
+
+The tool reads env vars, flags, and config — all with AFDATA suffixes — and can emit a startup diagnostic event:
 
 ```typescript
-import { buildJsonStartup, outputJson, outputYaml, outputPlain } from "agent-first-data";
+import { buildJson, outputJson, outputYaml, outputPlain } from "agent-first-data";
 
-const startup = buildJsonStartup(
-  { timeout_s: 30, max_file_size_bytes: 10737418240 },
-  { input_path: "/data/backup.tar.gz" },
-  { API_KEY_SECRET: process.env.API_KEY_SECRET ?? null },
+const startup = buildJson(
+  "log",
+  {
+    event: "startup",
+    config: { timeout_s: 30, max_file_size_bytes: 10737418240 },
+    args: { input_path: "/data/backup.tar.gz" },
+    env: { API_KEY_SECRET: process.env.API_KEY_SECRET ?? null },
+  },
 );
 ```
 
 Three output formats, same data:
 
 ```
-JSON:  {"code":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
-YAML:  code: "startup"
+JSON:  {"code":"log","event":"startup","args":{"input_path":"/data/backup.tar.gz"},"config":{"max_file_size_bytes":10737418240,"timeout_s":30},"env":{"API_KEY_SECRET":"***"}}
+YAML:  code: "log"
+       event: "startup"
        args:
          input_path: "/data/backup.tar.gz"
        config:
@@ -42,25 +56,22 @@ YAML:  code: "startup"
          timeout: "30s"
        env:
          API_KEY: "***"
-Plain: args.input_path=/data/backup.tar.gz code=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
+Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_file_size=10.0GB config.timeout=30s env.API_KEY=***
 ```
 
 `--timeout-s` → `timeout_s` → `timeout: 30s`. `API_KEY_SECRET` → `API_KEY: "***"`. The suffix is the schema.
 
 ## API Reference
 
-Total: **9 public APIs** + **AFD logging** (4 protocol builders + 3 output functions + 1 internal + 1 utility)
+Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
 
 ### Protocol Builders (returns JsonValue)
 
-Build AFD protocol structures. Return JSON-serializable objects for API responses.
+Build AFDATA 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
 
@@ -75,13 +86,17 @@ buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue
 
 **Example:**
 ```typescript
-import { buildJsonStartup, buildJsonOk, buildJsonError, buildJson } from "agent-first-data";
+import { 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" },
+const startup = buildJson(
+  "log",
+  {
+    event: "startup",
+    config: { api_key_secret: "sk-123", timeout_s: 30 },
+    args: { config_path: "config.yml" },
+    env: { RUST_LOG: "info" },
+  },
 );
 
 // Success (always include trace)
@@ -162,6 +177,42 @@ parseSize("1.5K"); // 1536
 parseSize("512");  // 512
 ```
 
+### CLI Helpers (for tools built on AFDATA)
+
+Shared helpers that prevent flag-parsing drift between CLI tools. Use these instead of reimplementing `--output` and `--log` handling in each tool.
+
+```typescript
+type OutputFormat = "json" | "yaml" | "plain"
+
+cliParseOutput(s: string): OutputFormat             // Parse --output flag; throws on unknown
+cliParseLogFilters(entries: string[]): string[]     // Normalize --log: trim, lowercase, dedup, remove empty
+cliOutput(value: JsonValue, format: OutputFormat): string  // Dispatch to outputJson/Yaml/Plain
+buildCliError(message: string): JsonValue           // {code:"error", error_code:"invalid_request", retryable:false, trace:{duration_ms:0}}
+```
+
+**Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:
+
+```typescript
+import {
+  type OutputFormat, cliParseOutput, cliParseLogFilters,
+  cliOutput, buildCliError, outputJson,
+} from "agent-first-data";
+
+let fmt: OutputFormat;
+try {
+  fmt = cliParseOutput(outputArg);
+} catch (e) {
+  console.log(outputJson(buildCliError((e as Error).message)));
+  process.exit(2);
+}
+
+const log = cliParseLogFilters(logArg ? logArg.split(",") : []);
+// ... do work ...
+console.log(cliOutput(result, fmt));
+```
+
+See `examples/agent_cli.ts` for the complete working example (`npx tsx --test examples/agent_cli.ts`).
+
 ## Usage Examples
 
 ### Example 1: REST API
@@ -185,17 +236,22 @@ app.get("/users/:id", (req, res) => {
 ### Example 2: CLI Tool (Complete Lifecycle)
 
 ```typescript
-import { buildJsonStartup, buildJsonOk, buildJson, outputYaml, outputPlain } from "agent-first-data";
+import { 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" },
+const startup = buildJson(
+  "log",
+  {
+    event: "startup",
+    config: { api_key_secret: "sk-sensitive-key", timeout_s: 30 },
+    args: { input_path: "data.json" },
+    env: { RUST_LOG: "info" },
+  },
 );
 console.log(outputYaml(startup));
 // ---
-// code: "startup"
+// code: "log"
+// event: "startup"
 // args:
 //   input_path: "data.json"
 // config:
@@ -245,6 +301,7 @@ const result = buildJsonOk(
 );
 
 // Print JSONL to stdout (secrets redacted, one JSON object per line)
+// Channel policy: machine-readable protocol/log events must not use stderr.
 console.log(outputJson(result));
 // {"code":"ok","result":{"status":"success"},"trace":{"api_key_secret":"***","duration_ms":250}}
 ```
@@ -286,9 +343,9 @@ 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
+## AFDATA 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.
+AFDATA-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
 
@@ -367,8 +424,8 @@ await span({ request_id: "abc-123" }, async () => {
 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"}
+log.info("Server ready", { code: "log", event: "startup" });
+// {"timestamp_epoch_ms":...,"message":"Server ready","code":"log","event":"startup"}
 ```
 
 ### Output Fields
@@ -385,7 +442,7 @@ Every log line contains:
 
 ### Log Output Formats
 
-All three formats use the library's own output functions, so AFD suffix processing applies to log fields too:
+All three formats use the library's own output functions, so AFDATA suffix processing applies to log fields too:
 
 | Format | Function | Keys | Values | Use case |
 |:-------|:---------|:-----|:-------|:---------|
@@ -419,8 +476,8 @@ All formats automatically redact `_secret` fields.
 
 This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
 
-- **`spec/`** — Full AFD specification with suffix definitions, protocol format rules, and cross-language test fixtures
-- **`skills/`** — Claude Code skill for AI agents working with AFD conventions
+- **`spec/`** — Full AFDATA specification with suffix definitions, protocol format rules, and cross-language test fixtures
+- **`skills/`** — AI coding agent skill for working with AFDATA conventions
 
 To run tests, clone the full repository (tests use shared cross-language fixtures from `spec/fixtures/`):
 

package/dist/{afd_logging.d.ts → afdata_logging.d.ts}

@@ -1,5 +1,5 @@
 /**
- * AFD-compliant structured logging.
+ * AFDATA-compliant structured logging.
  *
  * Outputs log events using agent-first-data formatting functions:
  * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
@@ -9,7 +9,7 @@
  * Span fields are carried via AsyncLocalStorage (async-safe).
  *
  * Usage:
- *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afd_logging";
+ *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afdata_logging";
  *   initJson();  // or initPlain() or initYaml()
  *   log.info("Server started");
  *   await span({ request_id: "abc" }, async () => {
@@ -23,7 +23,7 @@ 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.
+ * AFDATA logger. Each method outputs a single log line to stdout.
  * Format is controlled by initJson/initPlain/initYaml (default: JSON).
  */
 export declare const log: {

package/dist/{afd_logging.js → afdata_logging.js}

@@ -1,5 +1,5 @@
 /**
- * AFD-compliant structured logging.
+ * AFDATA-compliant structured logging.
  *
  * Outputs log events using agent-first-data formatting functions:
  * - JSON: single-line JSONL via outputJson (secrets redacted, original keys)
@@ -9,7 +9,7 @@
  * Span fields are carried via AsyncLocalStorage (async-safe).
  *
  * Usage:
- *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afd_logging";
+ *   import { log, span, initJson, initPlain, initYaml } from "agent-first-data/afdata_logging";
  *   initJson();  // or initPlain() or initYaml()
  *   log.info("Server started");
  *   await span({ request_id: "abc" }, async () => {
@@ -68,7 +68,7 @@ function emit(level, message, fields) {
     process.stdout.write(line + "\n");
 }
 /**
- * AFD logger. Each method outputs a single log line to stdout.
+ * AFDATA logger. Each method outputs a single log line to stdout.
  * Format is controlled by initJson/initPlain/initYaml (default: JSON).
  */
 export const log = {

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
+ */
+import { JsonValue } from "./format.js";
+/** Output format for CLI and pipe/MCP modes. */
+export type OutputFormat = "json" | "yaml" | "plain";
+/**
+ * Parse the --output flag value into an OutputFormat.
+ * Throws on unknown values; catch and pass message to buildCliError.
+ *
+ * @example
+ * cliParseOutput("json") // → "json"
+ * cliParseOutput("xml")  // throws Error
+ */
+export declare function cliParseOutput(s: string): OutputFormat;
+/**
+ * Normalize --output flag entries: trim, lowercase, deduplicate, remove empty.
+ * Accepts pre-split entries (e.g. after splitting on comma).
+ *
+ * @example
+ * cliParseLogFilters(["Query", " error ", "query"]) // → ["query", "error"]
+ */
+export declare function cliParseLogFilters(entries: string[]): string[];
+/**
+ * Dispatch output formatting by OutputFormat.
+ * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ *
+ * @example
+ * cliOutput({ code: "ok" }, "plain") // → "code=ok"
+ */
+export declare function cliOutput(value: JsonValue, format: OutputFormat): string;
+/**
+ * Build a standard CLI parse error value.
+ * Use when flag parsing fails or a flag value is invalid.
+ * Print with outputJson and exit with code 2.
+ *
+ * @example
+ * const err = buildCliError("--output: invalid value 'xml'");
+ * console.log(outputJson(err));
+ * process.exit(2);
+ */
+export declare function buildCliError(message: string): JsonValue;

package/dist/cli.js

@@ -0,0 +1,68 @@
+/**
+ * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
+ */
+import { outputJson, outputYaml, outputPlain } from "./format.js";
+/**
+ * Parse the --output flag value into an OutputFormat.
+ * Throws on unknown values; catch and pass message to buildCliError.
+ *
+ * @example
+ * cliParseOutput("json") // → "json"
+ * cliParseOutput("xml")  // throws Error
+ */
+export function cliParseOutput(s) {
+    if (s === "json" || s === "yaml" || s === "plain") {
+        return s;
+    }
+    throw new Error(`invalid --output format '${s}': expected json, yaml, or plain`);
+}
+/**
+ * Normalize --output flag entries: trim, lowercase, deduplicate, remove empty.
+ * Accepts pre-split entries (e.g. after splitting on comma).
+ *
+ * @example
+ * cliParseLogFilters(["Query", " error ", "query"]) // → ["query", "error"]
+ */
+export function cliParseLogFilters(entries) {
+    const out = [];
+    for (const entry of entries) {
+        const s = entry.trim().toLowerCase();
+        if (s && !out.includes(s)) {
+            out.push(s);
+        }
+    }
+    return out;
+}
+/**
+ * Dispatch output formatting by OutputFormat.
+ * Equivalent to calling outputJson, outputYaml, or outputPlain directly.
+ *
+ * @example
+ * cliOutput({ code: "ok" }, "plain") // → "code=ok"
+ */
+export function cliOutput(value, format) {
+    if (format === "yaml")
+        return outputYaml(value);
+    if (format === "plain")
+        return outputPlain(value);
+    return outputJson(value);
+}
+/**
+ * Build a standard CLI parse error value.
+ * Use when flag parsing fails or a flag value is invalid.
+ * Print with outputJson and exit with code 2.
+ *
+ * @example
+ * const err = buildCliError("--output: invalid value 'xml'");
+ * console.log(outputJson(err));
+ * process.exit(2);
+ */
+export function buildCliError(message) {
+    return {
+        code: "error",
+        error_code: "invalid_request",
+        error: message,
+        retryable: false,
+        trace: { duration_ms: 0 },
+    };
+}

package/dist/format.d.ts

@@ -1,13 +1,11 @@
 /**
- * AFD output formatting and protocol templates.
+ * AFDATA output formatting and protocol templates.
  *
- * 9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+ * 8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: 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?}. */

package/dist/format.js

@@ -1,15 +1,11 @@
 /**
- * AFD output formatting and protocol templates.
+ * AFDATA output formatting and protocol templates.
  *
- * 9 public APIs: 4 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+ * 8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
 // ═══════════════════════════════════════════
-/** Build {code: "startup", config, args, env}. */
-export function buildJsonStartup(config, args, env) {
-    return { code: "startup", config, args, env };
-}
 /** Build {code: "ok", result, trace?}. */
 export function buildJsonOk(result, trace) {
     const m = { code: "ok", result };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /**
- * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
+ * Agent-First Data (AFDATA) — 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";
+export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
+export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 /**
- * Agent-First Data (AFD) — suffix-driven output formatting and protocol templates.
+ * Agent-First Data (AFDATA) — 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";
+export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
+export { cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-first-data",
-  "version": "0.2.4",
-  "description": "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents",
+  "version": "0.4.0",
+  "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,9 +15,9 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./afd_logging": {
-      "import": "./dist/afd_logging.js",
-      "types": "./dist/afd_logging.d.ts"
+    "./afdata_logging": {
+      "import": "./dist/afdata_logging.js",
+      "types": "./dist/afdata_logging.d.ts"
     }
   },
   "files": [