agent-first-data 0.7.3 → 0.8.0

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`)
+Total: **15 public APIs and 2 types** + **AFDATA logging** (3 protocol builders + 2 redacted value helpers + 4 output functions + 1 internal + 1 utility + 4 CLI helpers + `OutputFormat` + `RedactionPolicy`)
 
 ### Protocol Builders (returns JsonValue)
 
@@ -82,6 +82,15 @@ buildJsonError(message: string, hint?: string, trace?: JsonValue): JsonValue
 buildJson(code: string, fields: JsonValue, trace?: JsonValue): JsonValue
 ```
 
+### Redacted Values (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
+```
+
 **Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
@@ -134,6 +143,7 @@ outputPlain(value: JsonValue): string  // Single-line logfmt, keys stripped, val
 enum RedactionPolicy {
   RedactionTraceOnly = "RedactionTraceOnly",
   RedactionNone = "RedactionNone",
+  RedactionStrict = "RedactionStrict",
 }
 ```
 
@@ -485,9 +495,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 +507,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.
+ * 11 public APIs and 1 type: protocol builders, redacted value helpers,
+ * output formatters, redaction, parseSize, and RedactionPolicy.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -14,7 +15,8 @@ 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"
 }
 /** Format as single-line JSON. Secrets redacted, original keys, raw values. */
 export declare function outputJson(value: JsonValue): string;
@@ -26,6 +28,10 @@ export declare function outputYaml(value: JsonValue): string;
 export declare function outputPlain(value: JsonValue): string;
 /** Redact _secret fields in-place. */
 export declare function internalRedactSecrets(value: JsonValue): 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;
 /**
  * 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.
+ * 11 public APIs and 1 type: protocol builders, redacted value helpers,
+ * output formatters, redaction, parseSize, and RedactionPolicy.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -37,34 +38,31 @@ 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 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 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]) => (v.includes(" ") ? `${k}="${v}"` : `${k}=${v}`))
+        .map(([k, v]) => `${k}=${quoteLogfmtValue(v)}`)
         .join(" ");
 }
 // ═══════════════════════════════════════════
@@ -74,6 +72,18 @@ export function outputPlain(value) {
 export function internalRedactSecrets(value) {
     redactSecrets(value);
 }
+/** 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;
+}
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
@@ -136,6 +146,23 @@ function redactSecrets(value) {
         }
     }
 }
+function redactSecretsStrict(value) {
+    if (isObject(value)) {
+        for (const k of Object.keys(value)) {
+            if (k.endsWith("_secret") || k.endsWith("_SECRET")) {
+                value[k] = "***";
+            }
+            else {
+                redactSecretsStrict(value[k]);
+            }
+        }
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            redactSecretsStrict(item);
+        }
+    }
+}
 function applyRedactionPolicy(value, redactionPolicy) {
     switch (redactionPolicy) {
         case RedactionPolicy.RedactionTraceOnly:
@@ -145,6 +172,9 @@ function applyRedactionPolicy(value, redactionPolicy) {
             break;
         case RedactionPolicy.RedactionNone:
             break;
+        case RedactionPolicy.RedactionStrict:
+            redactSecretsStrict(value);
+            break;
         default:
             // Safety fallback for unknown values.
             redactSecrets(value);
@@ -503,6 +533,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, outputJson, outputJsonWith, outputYaml, outputPlain, internalRedactSecrets, redactedValue, redactedValueWith, 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, outputYaml, outputPlain, internalRedactSecrets, redactedValue, redactedValueWith, 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.3",
+  "version": "0.8.0",
   "description": "Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates for AI agents",
   "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",