agent-first-data 0.7.4 → 0.8.1

package/README.md

@@ -63,7 +63,7 @@ Plain: args.input_path=/data/backup.tar.gz code=log event=startup config.max_fil
 
 ## API Reference
 
-Total: **13 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
+Public APIs are grouped by role: protocol builders, redaction helpers, output formatters, internal redaction tools, utility/CLI helpers, types, and AFDATA logging integration.
 
 ### Protocol Builders (returns JsonValue)
 
@@ -82,6 +82,16 @@ buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue
 buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue
 ```
 
+### Redaction Helpers (returns JsonValue)
+
+Use these before raw HTTP/MCP/SSE serializers that do not call `outputJson`.
+
+```typescript
+redactedValue(value: unknown): JsonValue
+redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue
+redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue
+```
+
 **Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
@@ -119,24 +129,35 @@ const notFound = buildJson(
 );
 ```
 
-### CLI/Log Output (returns string)
+### Output Formatters (returns string)
 
-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.
+Format values for CLI output and logs. `outputJson` uses full `_secret` redaction by default. `outputJsonWith` supports explicit scoped policies. Use the `*WithOptions` functions to pass legacy secret names such as `api_key`. YAML and Plain always redact secrets and apply human-readable formatting.
 
 ```typescript
 outputJson(value: JsonValue): string   // Single-line JSON, original keys, for programs/logs
 outputJsonWith(value: JsonValue, redactionPolicy: RedactionPolicy): string
+outputJsonWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string
 outputYaml(value: JsonValue): string   // Multi-line YAML, keys stripped, values formatted
+outputYamlWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string
 outputPlain(value: JsonValue): string  // Single-line logfmt, keys stripped, values formatted
+outputPlainWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string
 ```
 
 ```typescript
 enum RedactionPolicy {
   RedactionTraceOnly = "RedactionTraceOnly",
   RedactionNone = "RedactionNone",
+  RedactionStrict = "RedactionStrict",
+}
+
+type RedactionOptions = {
+  policy?: RedactionPolicy;
+  secretNames?: readonly string[]; // legacy names like "api_key" or "authorization"
 }
 ```
 
+Secret names match exact field names at any nesting level; there is no trim, case folding, hyphen/underscore normalization, glob, regex, or substring matching. They do not change YAML/Plain suffix stripping.
+
 **Example:**
 ```typescript
 import { outputJson, outputYaml, outputPlain } from "agent-first-data";
@@ -169,6 +190,7 @@ console.log(outputPlain(data));
 
 ```typescript
 internalRedactSecrets(value: JsonValue): void  // Manually redact secrets in-place
+internalRedactSecretsWithOptions(value: JsonValue, redactionOptions: RedactionOptions): void
 ```
 
 Most users don't need this. Output functions automatically protect secrets.
@@ -485,9 +507,11 @@ 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)
 
+TypeScript uses JavaScript `number` for JSON values, so `_epoch_ns` values above `Number.MAX_SAFE_INTEGER` lose precision. Prefer `_epoch_ms` for JSON interchange, or convert nanosecond values before formatting.
+
 ## Repository
 
-This package is part of the [agent-first-data](https://github.com/cmnspore/agent-first-data) repository, which also contains:
+This package is part of the [agent-first-data](https://github.com/agentfirstkit/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
@@ -495,7 +519,7 @@ This package is part of the [agent-first-data](https://github.com/cmnspore/agent
 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
+git clone https://github.com/agentfirstkit/agent-first-data
 cd agent-first-data/typescript
 npm test
 ```

package/dist/format.d.ts

@@ -1,7 +1,8 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 9 public APIs and 1 type: 3 protocol builders + 4 output formatters + 1 redaction + 1 utility + RedactionPolicy.
+ * 16 public APIs and 2 types: protocol builders, redacted value helpers,
+ * output formatters, redaction, parseSize, RedactionPolicy, and RedactionOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -14,18 +15,42 @@ export declare function buildJsonError(message: string, hint?: string, trace?: J
 export declare function buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue;
 export declare enum RedactionPolicy {
     RedactionTraceOnly = "RedactionTraceOnly",
-    RedactionNone = "RedactionNone"
+    RedactionNone = "RedactionNone",
+    RedactionStrict = "RedactionStrict"
 }
+export type RedactionOptions = {
+    /** Optional scoped policy. Omitted means default full redaction. */
+    policy?: RedactionPolicy;
+    /**
+     * Field names to treat as secrets in addition to _secret suffixes.
+     * Matching is exact field-name equality at any nesting level.
+     */
+    secretNames?: readonly string[];
+};
 /** 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 single-line JSON with explicit redaction options. */
+export declare function outputJsonWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string;
 /** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
 export declare function outputYaml(value: JsonValue): string;
+/** Format as multi-line YAML with explicit redaction options. */
+export declare function outputYamlWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string;
 /** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
 export declare function outputPlain(value: JsonValue): string;
+/** Format as single-line logfmt with explicit redaction options. */
+export declare function outputPlainWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string;
 /** Redact _secret fields in-place. */
 export declare function internalRedactSecrets(value: JsonValue): void;
+/** Redact secret fields in-place using explicit redaction options. */
+export declare function internalRedactSecretsWithOptions(value: JsonValue, redactionOptions: RedactionOptions): void;
+/** Return a JSON-safe copy with default _secret redaction applied. */
+export declare function redactedValue(value: unknown): JsonValue;
+/** Return a JSON-safe copy with an explicit redaction policy applied. */
+export declare function redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue;
+/** Return a JSON-safe copy with explicit redaction options applied. */
+export declare function redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue;
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).

package/dist/format.js

@@ -1,7 +1,8 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 9 public APIs and 1 type: 3 protocol builders + 4 output formatters + 1 redaction + 1 utility + RedactionPolicy.
+ * 16 public APIs and 2 types: protocol builders, redacted value helpers,
+ * output formatters, redaction, parseSize, RedactionPolicy, and RedactionOptions.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -37,34 +38,52 @@ export var RedactionPolicy;
 (function (RedactionPolicy) {
     RedactionPolicy["RedactionTraceOnly"] = "RedactionTraceOnly";
     RedactionPolicy["RedactionNone"] = "RedactionNone";
+    RedactionPolicy["RedactionStrict"] = "RedactionStrict";
 })(RedactionPolicy || (RedactionPolicy = {}));
 /** Format as single-line JSON. Secrets redacted, original keys, raw values. */
 export function outputJson(value) {
-    const v = sanitizeForJson(value);
-    redactSecrets(v);
-    return JSON.stringify(v);
+    return JSON.stringify(redactedValue(value));
 }
 /** 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);
+    return JSON.stringify(redactedValueWith(value, redactionPolicy));
+}
+/** Format as single-line JSON with explicit redaction options. */
+export function outputJsonWithOptions(value, redactionOptions) {
+    return JSON.stringify(redactedValueWithOptions(value, redactionOptions));
 }
 /** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
 export function outputYaml(value) {
-    value = sanitizeForJson(value);
+    value = redactedValue(value);
+    const lines = ["---"];
+    renderYamlProcessed(value, 0, lines);
+    return lines.join("\n");
+}
+/** Format as multi-line YAML with explicit redaction options. */
+export function outputYamlWithOptions(value, redactionOptions) {
+    value = redactedValueWithOptions(value, redactionOptions);
     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);
+    value = redactedValue(value);
+    const pairs = [];
+    collectPlainPairs(value, "", pairs);
+    pairs.sort(([a], [b]) => jcsCompare(a, b));
+    return pairs
+        .map(([k, v]) => `${k}=${quoteLogfmtValue(v)}`)
+        .join(" ");
+}
+/** Format as single-line logfmt with explicit redaction options. */
+export function outputPlainWithOptions(value, redactionOptions) {
+    value = redactedValueWithOptions(value, redactionOptions);
     const pairs = [];
     collectPlainPairs(value, "", pairs);
     pairs.sort(([a], [b]) => jcsCompare(a, b));
     return pairs
-        .map(([k, v]) => (v.includes(" ") ? `${k}="${v}"` : `${k}=${v}`))
+        .map(([k, v]) => `${k}=${quoteLogfmtValue(v)}`)
         .join(" ");
 }
 // ═══════════════════════════════════════════
@@ -74,6 +93,28 @@ export function outputPlain(value) {
 export function internalRedactSecrets(value) {
     redactSecrets(value);
 }
+/** Redact secret fields in-place using explicit redaction options. */
+export function internalRedactSecretsWithOptions(value, redactionOptions) {
+    applyRedactionOptions(value, redactionOptions);
+}
+/** Return a JSON-safe copy with default _secret redaction applied. */
+export function redactedValue(value) {
+    const v = sanitizeForJson(value);
+    redactSecrets(v);
+    return v;
+}
+/** Return a JSON-safe copy with an explicit redaction policy applied. */
+export function redactedValueWith(value, redactionPolicy) {
+    const v = sanitizeForJson(value);
+    applyRedactionPolicy(v, redactionPolicy);
+    return v;
+}
+/** Return a JSON-safe copy with explicit redaction options applied. */
+export function redactedValueWithOptions(value, redactionOptions) {
+    const v = sanitizeForJson(value);
+    applyRedactionOptions(v, redactionOptions);
+    return v;
+}
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
@@ -113,41 +154,77 @@ export function parseSize(s) {
 // ═══════════════════════════════════════════
 // Secret Redaction
 // ═══════════════════════════════════════════
-function redactSecrets(value) {
+const EMPTY_SECRET_NAMES = new Set();
+function secretNameSet(redactionOptions) {
+    return new Set(redactionOptions.secretNames ?? []);
+}
+function keyHasSecretSuffix(key) {
+    return key.endsWith("_secret") || key.endsWith("_SECRET");
+}
+function isSecretKey(key, secretNames) {
+    return keyHasSecretSuffix(key) || secretNames.has(key);
+}
+function redactSecrets(value, secretNames = EMPTY_SECRET_NAMES) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (k.endsWith("_secret") || k.endsWith("_SECRET")) {
+            if (isSecretKey(k, secretNames)) {
                 const v = value[k];
                 if (isObject(v) || Array.isArray(v)) {
-                    redactSecrets(v);
+                    redactSecrets(v, secretNames);
                 }
                 else {
                     value[k] = "***";
                 }
             }
             else {
-                redactSecrets(value[k]);
+                redactSecrets(value[k], secretNames);
+            }
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            redactSecrets(item, secretNames);
+        }
+    }
+}
+function redactSecretsStrict(value, secretNames = EMPTY_SECRET_NAMES) {
+    if (isObject(value)) {
+        for (const k of Object.keys(value)) {
+            if (isSecretKey(k, secretNames)) {
+                value[k] = "***";
+            }
+            else {
+                redactSecretsStrict(value[k], secretNames);
             }
         }
     }
     else if (Array.isArray(value)) {
         for (const item of value) {
-            redactSecrets(item);
+            redactSecretsStrict(item, secretNames);
         }
     }
 }
 function applyRedactionPolicy(value, redactionPolicy) {
+    applyRedactionPolicyWithNames(value, redactionPolicy, EMPTY_SECRET_NAMES);
+}
+function applyRedactionOptions(value, redactionOptions) {
+    applyRedactionPolicyWithNames(value, redactionOptions.policy, secretNameSet(redactionOptions));
+}
+function applyRedactionPolicyWithNames(value, redactionPolicy, secretNames) {
     switch (redactionPolicy) {
         case RedactionPolicy.RedactionTraceOnly:
             if (isObject(value) && value.trace !== undefined) {
-                redactSecrets(value.trace);
+                redactSecrets(value.trace, secretNames);
             }
             break;
         case RedactionPolicy.RedactionNone:
             break;
+        case RedactionPolicy.RedactionStrict:
+            redactSecretsStrict(value, secretNames);
+            break;
         default:
-            // Safety fallback for unknown values.
-            redactSecrets(value);
+            // Empty/unknown policy falls back to default full redaction.
+            redactSecrets(value, secretNames);
             break;
     }
 }
@@ -503,6 +580,19 @@ function plainScalar(value) {
         return value.toString();
     return String(value);
 }
+function quoteLogfmtValue(value) {
+    if (value === "")
+        return "";
+    if (!/[\s="\\]/.test(value))
+        return value;
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    return `"${escaped}"`;
+}
 // ═══════════════════════════════════════════
 // Utilities
 // ═══════════════════════════════════════════

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, outputJson, outputJsonWith, outputYaml, outputPlain, internalRedactSecrets, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, type RedactionOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, 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, RedactionPolicy, outputJson, outputJsonWith, outputYaml, outputPlain, internalRedactSecrets, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, 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,11 +1,11 @@
 {
   "name": "agent-first-data",
-  "version": "0.7.4",
-  "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
+  "version": "0.8.1",
+  "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cmnspore/agent-first-data"
+    "url": "https://github.com/agentfirstkit/agent-first-data"
   },
   "type": "module",
   "main": "dist/index.js",