agent-first-data 0.26.2 → 0.28.0

package/dist/format.js

@@ -12,8 +12,9 @@
  * precision integers, high-precision floats, exponent forms, "-0") survives
  * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
  * rendering path here treats it as an opaque scalar leaf (never destructured
- * as a plain object) and re-emits its exact literal text. This is internal —
- * LosslessNumber is never part of the public JsonValue type or exports.
+ * as a plain object) and re-emits its exact literal text. Native bigint values
+ * are also supported so callers can render integers beyond Number's safe
+ * range without first corrupting them.
  */
 import { parse as losslessParse, stringify as losslessStringify, isLosslessNumber } from "lossless-json";
 // ═══════════════════════════════════════════
@@ -96,10 +97,7 @@ export class JsonErrorBuilder {
         return this;
     }
     hint(value) {
-        if (!value || value === "") {
-            this.issues.push("hint must be a non-empty string");
-        }
-        else {
+        if (value && value !== "") {
             this.hintValue = value;
         }
         return this;
@@ -174,6 +172,13 @@ export class JsonErrorBuilder {
         if (this.hintValue !== undefined)
             error.hint = this.hintValue;
         const m = { kind: "error", error, trace: this.traceValue };
+        try {
+            losslessStringify(m);
+        }
+        catch (error) {
+            const issue = `event is not JSON serializable: ${error instanceof Error ? error.message : String(error)}`;
+            throw new EventBuildError(`Failed to build error event: ${issue}`, [issue]);
+        }
         return new Event(m);
     }
 }
@@ -380,13 +385,35 @@ export function decodeProtocolEvent(text) {
 // ═══════════════════════════════════════════
 // Internal: Output Formatters (called by render() in cli.ts)
 // ═══════════════════════════════════════════
-/** Which fields a redaction pass scrubs. The default is `All`. */
+/**
+ * Which fields a redaction pass scrubs. The default is `All`.
+ *
+ * The policy selects a *scope* inside a structured value. A command line
+ * (`redactArgv`) and a bare URL string (`redactUrlSecrets`) have no
+ * result/trace split to scope to, so on those two paths `TraceOnly` redacts in
+ * full like `All`, and only `Off` turns redaction off.
+ */
 export var RedactionPolicy;
 (function (RedactionPolicy) {
     RedactionPolicy["All"] = "All";
     RedactionPolicy["TraceOnly"] = "TraceOnly";
     RedactionPolicy["Off"] = "Off";
 })(RedactionPolicy || (RedactionPolicy = {}));
+/**
+ * Whether a policy redacts an input that carries no scope of its own — a
+ * command line or a single URL string, as opposed to a JSON value with a
+ * `trace` object to narrow to.
+ *
+ * `TraceOnly` narrows *where* redaction applies within a value; it does not
+ * weaken redaction. A standalone argv or URL has no non-`trace` half to leave
+ * alone — and both are diagnostic material by construction, the very thing
+ * `TraceOnly` scrubs — so `TraceOnly` redacts them in full, exactly like `All`.
+ * Only `Off`, the caller explicitly asking for raw output, disables redaction,
+ * and it does so on all three paths alike.
+ */
+function redactsUnscopedInput(policy) {
+    return policy !== RedactionPolicy.Off;
+}
 export var PlainStyle;
 (function (PlainStyle) {
     PlainStyle["Readable"] = "Readable";
@@ -441,6 +468,9 @@ export function formatYamlValue(value, options = {}) {
 export function formatPlainValue(value, options = {}) {
     const unwrapped = value instanceof Event ? value.toJSON() : value;
     const redacted = redactedValue(unwrapped, options.redaction ?? {});
+    if (!isObject(redacted)) {
+        return plainScalar(redacted);
+    }
     const pairs = [];
     if (options.style === PlainStyle.Raw) {
         collectPlainPairsRaw(redacted, "", pairs);
@@ -448,6 +478,9 @@ export function formatPlainValue(value, options = {}) {
     else {
         collectPlainPairs(redacted, "", pairs);
     }
+    if (pairs.length === 0) {
+        return "{}";
+    }
     pairs.sort(([a], [b]) => jcsCompare(a, b));
     return pairs
         .map(([k, v]) => `${quoteLogfmtKey(k)}=${quoteLogfmtValue(v)}`)
@@ -466,13 +499,21 @@ export function redactedValue(value, options) {
  * Redact secret components of a single URL string.
  *
  * A query parameter is redacted iff its (form-decoded) name ends in
- * _secret/_SECRET or matches an exact entry in secretNames. The userinfo
- * password (scheme://user:pass@host) is always redacted as a structural rule.
- * Only the secret spans are replaced with "***"; every other byte is preserved.
- * A string that is not a single, whitespace-free, scheme-prefixed URL
- * (including a URL embedded in surrounding prose) is returned unchanged.
+ * _secret/_SECRET or matches an exact entry in secretNames. A fragment written
+ * in the same `k=v&k=v` shape — how an OAuth implicit-flow response carries its
+ * token — is redacted by that same rule; any other fragment passes through
+ * byte-for-byte. The userinfo password (scheme://user:pass@host) is always
+ * redacted as a structural rule. Only the secret spans are replaced with "***";
+ * every other byte is preserved. A string that is not a single,
+ * whitespace-free, scheme-prefixed URL (including a URL embedded in surrounding
+ * prose) is returned unchanged.
+ *
+ * A URL is unscoped input: `RedactionPolicy.Off` returns it unchanged, every
+ * other policy redacts it in full.
  */
 export function redactUrlSecrets(url, options) {
+    if (!redactsUnscopedInput(options?.policy))
+        return url;
     const redacted = redactUrlInStr(url, secretNameSet(options ?? {}));
     return redacted ?? url;
 }
@@ -496,9 +537,12 @@ export function redactUrlSecrets(url, options) {
  * Intended for CLIs that record their own invocation — startup diagnostics,
  * audit trails, crash reports — where writing argv verbatim would put a
  * credential in the log.
+ *
+ * A command line is unscoped input: `RedactionPolicy.Off` returns `args`
+ * unchanged, every other policy redacts in full.
  */
 export function redactArgv(args, options) {
-    if (options?.policy === RedactionPolicy.Off)
+    if (!redactsUnscopedInput(options?.policy))
         return [...args];
     const secretNames = secretNameSet(options ?? {});
     const out = [];
@@ -507,7 +551,7 @@ export function redactArgv(args, options) {
         if (redactNext) {
             redactNext = false;
             if (!arg.startsWith("-")) {
-                out.push("***");
+                out.push(REDACTED_MARKER);
                 continue;
             }
         }
@@ -517,7 +561,7 @@ export function redactArgv(args, options) {
             if (equals >= 0) {
                 const name = rest.slice(0, equals);
                 if (isSecretFlagName(name, secretNames)) {
-                    out.push(`--${name}=***`);
+                    out.push(`--${name}=${REDACTED_MARKER}`);
                     continue;
                 }
             }
@@ -688,6 +732,21 @@ function daysInMonth(year, month) {
 function isLeapYear(year) {
     return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
 }
+// ═══════════════════════════════════════════
+// Secret Redaction
+// ═══════════════════════════════════════════
+/**
+ * The scalar every redacted span, value, and subtree is replaced with. Also the
+ * signal plain rendering reads to tell a hidden field from a live one.
+ */
+const REDACTED_MARKER = "***";
+/**
+ * True when a field already carries the redaction marker, i.e. redaction ran
+ * over it and hid the value.
+ */
+function isRedacted(value) {
+    return value === REDACTED_MARKER;
+}
 const DEFAULT_CONTEXT = {
     secretNames: new Set(),
 };
@@ -715,7 +774,7 @@ function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
         for (const k of Object.keys(value)) {
             const v = value[k];
             if (isSecretKey(k, context.secretNames)) {
-                value[k] = "***";
+                value[k] = REDACTED_MARKER;
             }
             else if (keyHasUrlSuffix(k)) {
                 if (typeof v === "string") {
@@ -790,29 +849,22 @@ function redactUrlInStr(s, secretNames) {
     const authority = rest.slice(0, authEnd);
     const remainder = rest.slice(authEnd);
     const newAuthority = redactUserinfoPassword(authority);
-    // Query runs from the first '?' to the first '#' (or end).
-    let newRemainder;
-    const q = remainder.indexOf("?");
-    if (q >= 0) {
-        const path = remainder.slice(0, q);
-        const qOnwards = remainder.slice(q + 1);
-        const hash = qOnwards.indexOf("#");
-        let query;
-        let fragment;
-        if (hash >= 0) {
-            query = qOnwards.slice(0, hash);
-            fragment = qOnwards.slice(hash);
-        }
-        else {
-            query = qOnwards;
-            fragment = "";
-        }
-        newRemainder = `${path}?${redactQuery(query, secretNames)}${fragment}`;
-    }
-    else {
-        newRemainder = remainder;
-    }
-    return `${scheme}://${newAuthority}${newRemainder}`;
+    // `remainder` is `path[?query][#fragment]`; '#' ends the query, so split the
+    // fragment off first and the query out of what is left.
+    const hash = remainder.indexOf("#");
+    const beforeFragment = hash >= 0 ? remainder.slice(0, hash) : remainder;
+    const fragment = hash >= 0 ? remainder.slice(hash + 1) : null;
+    const q = beforeFragment.indexOf("?");
+    const newBeforeFragment = q >= 0
+        ? `${beforeFragment.slice(0, q)}?${redactQuery(beforeFragment.slice(q + 1), secretNames)}`
+        : beforeFragment;
+    // A fragment gets the same treatment as the query: `k=v&k=v` after the '#' is
+    // exactly how an OAuth implicit-flow response hands back a token, so a
+    // secret-named fragment parameter must not survive where the identically
+    // named query parameter would not. A fragment that is not in that shape has
+    // no '=' in its segments and passes through byte-for-byte.
+    const newFragment = fragment === null ? "" : `#${redactQuery(fragment, secretNames)}`;
+    return `${scheme}://${newAuthority}${newBeforeFragment}${newFragment}`;
 }
 function redactUrlFieldValue(s, secretNames) {
     const redacted = redactUrlInStr(s, secretNames);
@@ -830,7 +882,7 @@ function redactUrlFieldValue(s, secretNames) {
     // connection string like user:pass@host/db has no scheme anchor for the
     // surgical span logic above, so blanket redaction is the safe default.
     if (/\s/.test(s) || s.includes("@"))
-        return "***";
+        return REDACTED_MARKER;
     return s;
 }
 /**
@@ -845,7 +897,7 @@ function redactUserinfoPassword(authority) {
     const colon = userinfo.indexOf(":");
     if (colon < 0)
         return authority;
-    return `${authority.slice(0, colon)}:***${authority.slice(at)}`;
+    return `${authority.slice(0, colon)}:${REDACTED_MARKER}${authority.slice(at)}`;
 }
 /**
  * Redact the values of secret-named query parameters, preserving raw bytes of
@@ -861,7 +913,7 @@ function redactQuery(query, secretNames) {
         const rawKey = segment.slice(0, eq);
         const name = formDecode(rawKey);
         if (isSecretKey(name, secretNames)) {
-            return `${rawKey}=***`;
+            return `${rawKey}=${REDACTED_MARKER}`;
         }
         return segment;
     })
@@ -950,7 +1002,9 @@ function isInt(value) {
 function decimalIntText(value) {
     if (typeof value === "string" && /^-?\d+$/.test(value))
         return value;
-    if (isInt(value))
+    if (typeof value === "bigint")
+        return value.toString();
+    if (isInt(value) && Number.isSafeInteger(value))
         return String(value);
     if (isLosslessNumber(value)) {
         const text = value.toString();
@@ -958,6 +1012,33 @@ function decimalIntText(value) {
     }
     return null;
 }
+const MAX_I64 = 9223372036854775807n;
+function nonNegativeI64(value) {
+    let text = null;
+    if (typeof value === "bigint") {
+        text = value.toString();
+    }
+    else if (typeof value === "number" && Number.isSafeInteger(value)) {
+        text = String(value);
+    }
+    else if (isLosslessNumber(value)) {
+        const literal = value.toString();
+        if (/^-?\d+$/.test(literal))
+            text = literal;
+    }
+    if (text === null)
+        return null;
+    try {
+        const integer = BigInt(text);
+        return integer >= 0n && integer <= MAX_I64 ? integer : null;
+    }
+    catch {
+        return null;
+    }
+}
+function formatCents(value, symbol) {
+    return `${symbol}${value / 100n}.${String(value % 100n).padStart(2, "0")}`;
+}
 function epochNsToMs(value) {
     const text = decimalIntText(value);
     if (text === null)
@@ -1027,28 +1108,34 @@ function tryProcessField(key, value) {
     // Group 2: compound currency suffixes
     stripped = stripSuffixCI(key, "_usd_cents");
     if (stripped !== null) {
-        if (isInt(numeric) && numeric >= 0)
-            return [stripped, `$${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")}`];
+        const integer = nonNegativeI64(value);
+        if (integer !== null)
+            return [stripped, formatCents(integer, "$")];
         return null;
     }
     stripped = stripSuffixCI(key, "_eur_cents");
     if (stripped !== null) {
-        if (isInt(numeric) && numeric >= 0)
-            return [stripped, `\u20ac${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")}`];
+        const integer = nonNegativeI64(value);
+        if (integer !== null)
+            return [stripped, formatCents(integer, "\u20ac")];
         return null;
     }
     const gc = tryStripGenericCents(key);
     if (gc !== null) {
         const [gcStripped, code] = gc;
-        if (isInt(numeric) && numeric >= 0)
-            return [gcStripped, `${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")} ${code.toUpperCase()}`];
+        const integer = nonNegativeI64(value);
+        if (integer !== null) {
+            return [gcStripped, `${integer / 100n}.${String(integer % 100n).padStart(2, "0")} ${code.toUpperCase()}`];
+        }
         return null;
     }
     const gm = tryStripGenericMicro(key);
     if (gm !== null) {
         const [gmStripped, code] = gm;
-        if (isInt(numeric) && numeric >= 0)
-            return [gmStripped, `${Math.floor(numeric / 1_000_000)}.${String(numeric % 1_000_000).padStart(6, "0")} ${code.toUpperCase()}`];
+        const integer = nonNegativeI64(value);
+        if (integer !== null) {
+            return [gmStripped, `${integer / 1000000n}.${String(integer % 1000000n).padStart(6, "0")} ${code.toUpperCase()}`];
+        }
         return null;
     }
     // Group 3: multi-char suffixes
@@ -1106,8 +1193,9 @@ function tryProcessField(key, value) {
     // Group 5: short suffixes (last to avoid false positives)
     stripped = stripSuffixCI(key, "_jpy");
     if (stripped !== null) {
-        if (isInt(numeric) && numeric >= 0)
-            return [stripped, `\u00a5${formatWithCommas(numeric)}`];
+        const integer = nonNegativeI64(value);
+        if (integer !== null)
+            return [stripped, `\u00a5${formatWithCommas(integer)}`];
         return null;
     }
     stripped = stripSuffixCI(key, "_ns");
@@ -1142,7 +1230,13 @@ function processObjectFields(obj) {
     for (const [k, v] of Object.entries(obj)) {
         const secretStripped = stripSuffixCI(k, "_secret");
         if (secretStripped !== null) {
-            entries.push({ stripped: secretStripped, original: k, value: v, formatted: null });
+            // Dropping `_secret` is the readable half of an actual redaction: the
+            // marker has done its job once the value reads `***`. When the value was
+            // *not* redacted — policy `Off`, or a field outside `trace` under
+            // `TraceOnly` — the suffix is the only thing telling a downstream reader
+            // that `api_key_secret=sk-live-xxx` is a credential, so it stays.
+            const displayKey = isRedacted(v) ? secretStripped : k;
+            entries.push({ stripped: displayKey, original: k, value: v, formatted: null });
             continue;
         }
         const result = tryProcessField(k, v);
@@ -1344,14 +1438,29 @@ function escapeYamlStr(s) {
     return s
         .replace(/\\/g, "\\\\")
         .replace(/"/g, '\\"')
-        .replace(/\n/g, "\\n")
-        .replace(/\r/g, "\\r")
-        .replace(/\t/g, "\\t")
-        .replace(/\f/g, "\\f")
-        .replace(/\v/g, "\\v");
+        .replace(/[\x00-\x1f]/g, (character) => {
+        switch (character) {
+            case "\0": return "\\0";
+            case "\b": return "\\b";
+            case "\t": return "\\t";
+            case "\n": return "\\n";
+            case "\v": return "\\v";
+            case "\f": return "\\f";
+            case "\r": return "\\r";
+            default: return `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
+        }
+    });
 }
 function yamlKey(key) {
-    return /^[A-Za-z0-9_.-]+$/.test(key) ? key : `"${escapeYamlStr(key)}"`;
+    return /^[A-Za-z0-9_.-]+$/.test(key) && !isAmbiguousYamlKey(key)
+        ? key
+        : `"${escapeYamlStr(key)}"`;
+}
+function isAmbiguousYamlKey(key) {
+    if (["true", "false", "null", "~", ".nan", ".inf", "+.inf", "-.inf"].includes(key.toLowerCase())) {
+        return true;
+    }
+    return key.trim() !== "" && Number.isFinite(Number(key));
 }
 function yamlScalar(value) {
     if (typeof value === "string")
@@ -1362,6 +1471,8 @@ function yamlScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
+    if (typeof value === "bigint")
+        return value.toString();
     // Decoded number: emit the exact source literal unquoted, matching JSON's
     // structure-preserving fidelity contract for YAML too.
     if (isLosslessNumber(value))
@@ -1380,10 +1491,13 @@ function collectPlainPairs(value, prefix, pairs) {
             pairs.push([fullKey, pf.formatted]);
         }
         else if (isObject(pf.value)) {
-            collectPlainPairs(pf.value, fullKey, pairs);
+            if (Object.keys(pf.value).length === 0)
+                pairs.push([fullKey, "{}"]);
+            else
+                collectPlainPairs(pf.value, fullKey, pairs);
         }
         else if (Array.isArray(pf.value)) {
-            pairs.push([fullKey, pf.value.map((i) => plainScalar(i)).join(",")]);
+            pairs.push([fullKey, pf.value.length === 0 ? "[]" : pf.value.map((i) => plainScalar(i)).join(",")]);
         }
         else if (pf.value === null) {
             pairs.push([fullKey, ""]);
@@ -1400,10 +1514,13 @@ function collectPlainPairsRaw(value, prefix, pairs) {
         const v = value[key];
         const fullKey = prefix ? `${prefix}.${key}` : key;
         if (isObject(v)) {
-            collectPlainPairsRaw(v, fullKey, pairs);
+            if (Object.keys(v).length === 0)
+                pairs.push([fullKey, "{}"]);
+            else
+                collectPlainPairsRaw(v, fullKey, pairs);
         }
         else if (Array.isArray(v)) {
-            pairs.push([fullKey, v.map((i) => plainScalarRaw(i)).join(",")]);
+            pairs.push([fullKey, v.length === 0 ? "[]" : v.map((i) => plainScalarRaw(i)).join(",")]);
         }
         else if (v === null) {
             pairs.push([fullKey, ""]);
@@ -1422,6 +1539,8 @@ function plainScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
+    if (typeof value === "bigint")
+        return value.toString();
     // Decoded number: emit the exact source literal (Plain is documented lossy
     // for arithmetic-derived formatting, but a bare pass-through scalar still
     // gets its exact digits, not a mangled float64 round-trip).
@@ -1468,10 +1587,14 @@ function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
         return value;
     if (t === "number") {
         const n = value;
-        return Number.isFinite(n) ? n : "<unsupported:number>";
+        if (!Number.isFinite(n))
+            return "<unsupported:number>";
+        if (Number.isInteger(n) && !Number.isSafeInteger(n))
+            return "<unsupported:unsafe-integer>";
+        return n;
     }
     if (t === "bigint")
-        return "<unsupported:bigint>";
+        return value;
     if (t === "undefined")
         return "<unsupported:undefined>";
     if (t === "function")

package/dist/index.d.ts

@@ -2,4 +2,4 @@
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
 export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, PlainStyle, type OutputOptions, outputOptionsForPolicy, redactedValue, redactArgv, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
-export { type OutputFormat, type OutputTo, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
+export { type OutputFormat, type OutputTo, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, } from "./cli.js";

package/dist/index.js

@@ -2,4 +2,4 @@
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
 export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, PlainStyle, outputOptionsForPolicy, redactedValue, redactArgv, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
-export { CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
+export { CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,7 @@
   "scripts": {
     "build": "tsc",
     "prepack": "npm run build",
-    "test": "tsx --test src/*.test.ts examples/agent_cli.ts"
+    "test": "tsx --test src/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -32,6 +32,6 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "lossless-json": "^4.3.0"
+    "lossless-json": "^4.3.1"
   }
 }