agent-first-data 0.4.2 → 0.6.0

package/README.md

@@ -63,11 +63,11 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **12 public APIs and 1 type** + **AFDATA logging** (3 protocol builders + 3 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat`)
+Total: **13 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
 
 ### Protocol Builders (returns JsonValue)
 
-Build AFDATA protocol structures. Return JSON-serializable objects for API responses.
+Build AFDATA protocol structures. Return JSON-serializable objects for transport payloads.
 
 ```typescript
 type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
@@ -75,14 +75,14 @@ type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string
 // Success (result)
 buildJsonOk(result: JsonValue, trace?: JsonValue): JsonValue
 
-// Error (simple message)
-buildJsonError(message: string, trace?: JsonValue): JsonValue
+// Error (simple message, optional hint)
+buildJsonError(message: string, hint?: 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)
+**Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
 ```typescript
@@ -106,7 +106,10 @@ const response = buildJsonOk(
 );
 
 // Error
-const error = buildJsonError("user not found", { duration_ms: 5 });
+const error = buildJsonError("user not found", undefined, { duration_ms: 5 });
+
+// Error with hint
+const errorHint = buildJsonError("wallet not found", "list wallets with: afpay wallet list", { duration_ms: 5 });
 
 // Specific error code
 const notFound = buildJson(
@@ -118,14 +121,22 @@ const notFound = buildJson(
 
 ### 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.
+Format values for CLI output and logs. `outputJson` uses full `_secret` redaction by default. `outputJsonWith` supports explicit scoped policies. YAML and Plain always redact `_secret` and apply human-readable formatting.
 
 ```typescript
 outputJson(value: JsonValue): string   // Single-line JSON, original keys, for programs/logs
+outputJsonWith(value: JsonValue, redactionPolicy: RedactionPolicy): string
 outputYaml(value: JsonValue): string   // Multi-line YAML, keys stripped, values formatted
 outputPlain(value: JsonValue): string  // Single-line logfmt, keys stripped, values formatted
 ```
 
+```typescript
+enum RedactionPolicy {
+  RedactionTraceOnly = "RedactionTraceOnly",
+  RedactionNone = "RedactionNone",
+}
+```
+
 **Example:**
 ```typescript
 import { outputJson, outputYaml, outputPlain } from "agent-first-data";
@@ -168,6 +179,8 @@ Most users don't need this. Output functions automatically protect secrets.
 parseSize(s: string): number | null  // Parse "10M" → bytes
 ```
 
+Returns `null` for invalid input and for values that cannot be represented as a safe JavaScript integer.
+
 **Example:**
 ```typescript
 import { parseSize } from "agent-first-data";
@@ -187,7 +200,7 @@ 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}}
+buildCliError(message: string, hint?: string): JsonValue  // {code:"error", error_code:"invalid_request", hint?, retryable:false, trace:{duration_ms:0}}
 ```
 
 **Canonical pattern** — parse all flags before doing work, emit JSONL errors to stdout:

package/dist/cli.d.ts

@@ -39,4 +39,4 @@ export declare function cliOutput(value: JsonValue, format: OutputFormat): strin
  * console.log(outputJson(err));
  * process.exit(2);
  */
-export declare function buildCliError(message: string): JsonValue;
+export declare function buildCliError(message: string, hint?: string): JsonValue;

package/dist/cli.js

@@ -57,12 +57,15 @@ export function cliOutput(value, format) {
  * console.log(outputJson(err));
  * process.exit(2);
  */
-export function buildCliError(message) {
-    return {
+export function buildCliError(message, hint) {
+    const m = {
         code: "error",
         error_code: "invalid_request",
         error: message,
         retryable: false,
         trace: { duration_ms: 0 },
     };
+    if (hint !== undefined)
+        m.hint = hint;
+    return m;
 }

package/dist/format.d.ts

@@ -1,19 +1,25 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+ * 9 public APIs and 1 type: 3 protocol builders + 4 output formatters + 1 redaction + 1 utility + RedactionPolicy.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: 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: "error", error: message, hint?, trace?}. */
+export declare function buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue;
 /** Build {code: "<custom>", ...fields, trace?}. */
 export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
+export declare enum RedactionPolicy {
+    RedactionTraceOnly = "RedactionTraceOnly",
+    RedactionNone = "RedactionNone"
+}
 /** Format as single-line JSON. Secrets redacted, original keys, raw values. */
 export declare function outputJson(value: JsonValue): string;
+/** Format as single-line JSON with explicit redaction policy. */
+export declare function outputJsonWith(value: JsonValue, redactionPolicy: RedactionPolicy): 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. */

package/dist/format.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 8 public APIs: 3 protocol builders + 3 output formatters + 1 redaction + 1 utility.
+ * 9 public APIs and 1 type: 3 protocol builders + 4 output formatters + 1 redaction + 1 utility + RedactionPolicy.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -13,9 +13,11 @@ export function buildJsonOk(result, trace) {
         m.trace = trace;
     return m;
 }
-/** Build {code: "error", error: message, trace?}. */
-export function buildJsonError(message, trace) {
+/** Build {code: "error", error: message, hint?, trace?}. */
+export function buildJsonError(message, hint, trace) {
     const m = { code: "error", error: message };
+    if (hint !== undefined)
+        m.hint = hint;
     if (trace !== undefined)
         m.trace = trace;
     return m;
@@ -31,20 +33,33 @@ export function buildJson(code, fields, trace) {
 // ═══════════════════════════════════════════
 // Public API: Output Formatters
 // ═══════════════════════════════════════════
+export var RedactionPolicy;
+(function (RedactionPolicy) {
+    RedactionPolicy["RedactionTraceOnly"] = "RedactionTraceOnly";
+    RedactionPolicy["RedactionNone"] = "RedactionNone";
+})(RedactionPolicy || (RedactionPolicy = {}));
 /** Format as single-line JSON. Secrets redacted, original keys, raw values. */
 export function outputJson(value) {
-    const v = JSON.parse(JSON.stringify(value));
+    const v = sanitizeForJson(value);
     redactSecrets(v);
     return JSON.stringify(v);
 }
+/** Format as single-line JSON with explicit redaction policy. */
+export function outputJsonWith(value, redactionPolicy) {
+    const v = sanitizeForJson(value);
+    applyRedactionPolicy(v, redactionPolicy);
+    return JSON.stringify(v);
+}
 /** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
 export function outputYaml(value) {
+    value = sanitizeForJson(value);
     const lines = ["---"];
     renderYamlProcessed(value, 0, lines);
     return lines.join("\n");
 }
 /** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
 export function outputPlain(value) {
+    value = sanitizeForJson(value);
     const pairs = [];
     collectPlainPairs(value, "", pairs);
     pairs.sort(([a], [b]) => jcsCompare(a, b));
@@ -90,7 +105,10 @@ export function parseSize(s) {
     const n = Number(numStr);
     if (isNaN(n) || n < 0 || !isFinite(n))
         return null;
-    return Math.trunc(n * mult);
+    const result = Math.trunc(n * mult);
+    if (!Number.isSafeInteger(result))
+        return null;
+    return result;
 }
 // ═══════════════════════════════════════════
 // Secret Redaction
@@ -118,6 +136,21 @@ function redactSecrets(value) {
         }
     }
 }
+function applyRedactionPolicy(value, redactionPolicy) {
+    switch (redactionPolicy) {
+        case RedactionPolicy.RedactionTraceOnly:
+            if (isObject(value) && value.trace !== undefined) {
+                redactSecrets(value.trace);
+            }
+            break;
+        case RedactionPolicy.RedactionNone:
+            break;
+        default:
+            // Safety fallback for unknown values.
+            redactSecrets(value);
+            break;
+    }
+}
 // ═══════════════════════════════════════════
 // Suffix Processing
 // ═══════════════════════════════════════════
@@ -473,6 +506,52 @@ function plainScalar(value) {
 // ═══════════════════════════════════════════
 // Utilities
 // ═══════════════════════════════════════════
+function sanitizeForJson(value, stack = new WeakSet()) {
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === "string")
+        return value;
+    if (t === "boolean")
+        return value;
+    if (t === "number") {
+        const n = value;
+        return Number.isFinite(n) ? n : "<unsupported:number>";
+    }
+    if (t === "bigint")
+        return "<unsupported:bigint>";
+    if (t === "undefined")
+        return "<unsupported:undefined>";
+    if (t === "function")
+        return "<unsupported:function>";
+    if (t === "symbol")
+        return "<unsupported:symbol>";
+    if (value instanceof Error)
+        return value.message;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value)) {
+        if (stack.has(value))
+            return "<unsupported:circular>";
+        stack.add(value);
+        const out = value.map((item) => sanitizeForJson(item, stack));
+        stack.delete(value);
+        return out;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        if (stack.has(obj))
+            return "<unsupported:circular>";
+        stack.add(obj);
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = sanitizeForJson(v, stack);
+        }
+        stack.delete(obj);
+        return out;
+    }
+    return "<unsupported:unknown>";
+}
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, outputJson, outputJsonWith, 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,6 +1,6 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, outputJson, outputYaml, outputPlain, internalRedactSecrets, parseSize } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, outputJson, outputJsonWith, 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,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
   "license": "MIT",
   "repository": {
@@ -26,10 +26,11 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "node --test src/*.test.ts --experimental-strip-types"
+    "test": "tsx --test src/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",
+    "tsx": "^4.20.6",
     "typescript": "^5.0"
   }
 }