agent-first-data 0.2.3 → 0.3.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: **8 public APIs** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility)
 
 ### 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)
@@ -185,17 +200,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:
@@ -286,9 +306,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 +387,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 +405,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 |
 |:-------|:---------|:-----|:-------|:---------|
@@ -415,6 +435,21 @@ All formats automatically redact `_secret` fields.
 - **Currency**: `_msats`, `_sats`, `_btc`, `_usd_cents`, `_eur_cents`, `_jpy`, `_{code}_cents`
 - **Other**: `_percent`, `_secret` (auto-redacted in all formats)
 
+## Repository
+
+This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
+
+- **`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/`):
+
+```bash
+git clone https://github.com/cmnspore/agent-first-data
+cd agent-first-data/typescript
+npm test
+```
+
 ## License
 
 MIT

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/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,5 @@
 /**
- * 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";

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * 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";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-first-data",
-  "version": "0.2.3",
-  "description": "Agent-First Data (AFD) — suffix-driven output formatting and protocol templates for AI agents",
+  "version": "0.3.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": [