agent-first-data 0.8.1 → 0.10.0

package/README.md

@@ -92,6 +92,13 @@ redactedValueWith(value: unknown, redactionPolicy: RedactionPolicy): JsonValue
 redactedValueWithOptions(value: unknown, redactionOptions: RedactionOptions): JsonValue
 ```
 
+`_url` fields are scrubbed in place during redaction (userinfo password, plus query parameters whose name follows the `_secret`/`secretNames` rule). For a URL inside a free-form string, redact it directly before interpolating:
+
+```typescript
+redactUrlSecrets(url: string): string
+redactUrlSecretsWithOptions(url: string, redactionOptions: RedactionOptions): string
+```
+
 **Use case:** structured protocol payloads (frameworks automatically serialize)
 
 **Example:**
@@ -131,16 +138,16 @@ const notFound = buildJson(
 
 ### Output Formatters (returns string)
 
-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.
+Format values for CLI output and logs. `outputJson` uses full `_secret` redaction by default. `outputJsonWith` supports explicit scoped policies. Use `OutputOptions` to pass legacy secret names such as `api_key` or request schema-preserving YAML/plain rendering with `OutputStyle.Raw`.
 
 ```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
+outputJsonWithOptions(value: JsonValue, outputOptions: OutputOptions): string
 outputYaml(value: JsonValue): string   // Multi-line YAML, keys stripped, values formatted
-outputYamlWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string
+outputYamlWithOptions(value: JsonValue, outputOptions: OutputOptions): string
 outputPlain(value: JsonValue): string  // Single-line logfmt, keys stripped, values formatted
-outputPlainWithOptions(value: JsonValue, redactionOptions: RedactionOptions): string
+outputPlainWithOptions(value: JsonValue, outputOptions: OutputOptions): string
 ```
 
 ```typescript
@@ -154,9 +161,19 @@ type RedactionOptions = {
   policy?: RedactionPolicy;
   secretNames?: readonly string[]; // legacy names like "api_key" or "authorization"
 }
+
+enum OutputStyle {
+  Readable = "Readable",
+  Raw = "Raw",
+}
+
+type OutputOptions = {
+  redaction?: RedactionOptions;
+  style?: OutputStyle;
+}
 ```
 
-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.
+Secret names match exact field names at any nesting level; there is no trim, case folding, hyphen/underscore normalization, glob, regex, or substring matching. `OutputOptions` combines `RedactionOptions` with `OutputStyle.Readable` (default suffix stripping and value formatting) or `OutputStyle.Raw` (no suffix stripping or value formatting).
 
 **Example:**
 ```typescript
@@ -222,6 +239,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
+cliOutputWithOptions(value: JsonValue, format: OutputFormat, outputOptions: OutputOptions): string
 buildCliError(message: string, hint?: string): JsonValue  // {code:"error", error_code:"invalid_request", hint?, retryable:false, trace:{duration_ms:0}}
 ```
 

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { JsonValue } from "./format.js";
+import { JsonValue, type OutputOptions } from "./format.js";
 /** Output format for CLI and pipe/MCP modes. */
 export type OutputFormat = "json" | "yaml" | "plain";
 /**
@@ -29,6 +29,11 @@ export declare function cliParseLogFilters(entries: string[]): string[];
  * cliOutput({ code: "ok" }, "plain") // → "code=ok"
  */
 export declare function cliOutput(value: JsonValue, format: OutputFormat): string;
+/**
+ * Dispatch output formatting with explicit redaction and style.
+ * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ */
+export declare function cliOutputWithOptions(value: JsonValue, format: OutputFormat, outputOptions: OutputOptions): string;
 /**
  * Build a standard CLI parse error value.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/cli.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { outputJson, outputYaml, outputPlain } from "./format.js";
+import { outputJson, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
  * Throws on unknown values; catch and pass message to buildCliError.
@@ -47,6 +47,17 @@ export function cliOutput(value, format) {
         return outputPlain(value);
     return outputJson(value);
 }
+/**
+ * Dispatch output formatting with explicit redaction and style.
+ * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ */
+export function cliOutputWithOptions(value, format, outputOptions) {
+    if (format === "yaml")
+        return outputYamlWithOptions(value, outputOptions);
+    if (format === "plain")
+        return outputPlainWithOptions(value, outputOptions);
+    return outputJsonWithOptions(value, outputOptions);
+}
 /**
  * Build a standard CLI parse error value.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/format.d.ts

@@ -1,8 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 16 public APIs and 2 types: protocol builders, redacted value helpers,
- * output formatters, redaction, parseSize, RedactionPolicy, and RedactionOptions.
+ * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * in-place; cover _secret and _url fields), output formatters, URL-string
+ * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
+ * RedactionOptions, OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -23,24 +25,36 @@ export type RedactionOptions = {
     policy?: RedactionPolicy;
     /**
      * Field names to treat as secrets in addition to _secret suffixes.
-     * Matching is exact field-name equality at any nesting level.
+     * Matching is exact field-name equality at any nesting level. The same
+     * list also matches URL query-parameter names inside _url fields (see
+     * redactUrlSecrets).
      */
     secretNames?: readonly string[];
 };
+export declare enum OutputStyle {
+    Readable = "Readable",
+    Raw = "Raw"
+}
+export type OutputOptions = {
+    /** Redaction options applied before rendering. */
+    redaction?: RedactionOptions;
+    /** Rendering style for YAML/plain output. Omitted means readable. */
+    style?: OutputStyle;
+};
 /** 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 single-line JSON with explicit output options. */
+export declare function outputJsonWithOptions(value: JsonValue, outputOptions: OutputOptions): 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 multi-line YAML with explicit output options. */
+export declare function outputYamlWithOptions(value: JsonValue, outputOptions: OutputOptions): 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;
+/** Format as single-line logfmt with explicit output options. */
+export declare function outputPlainWithOptions(value: JsonValue, outputOptions: OutputOptions): string;
 /** Redact _secret fields in-place. */
 export declare function internalRedactSecrets(value: JsonValue): void;
 /** Redact secret fields in-place using explicit redaction options. */
@@ -51,6 +65,24 @@ export declare function redactedValue(value: unknown): JsonValue;
 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;
+/**
+ * Redact secret components of a single URL string, using default options.
+ *
+ * Returns url with its userinfo password and any _secret-suffixed query
+ * parameter values replaced by "***". See redactUrlSecretsWithOptions.
+ */
+export declare function redactUrlSecrets(url: string): string;
+/**
+ * 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.
+ */
+export declare function redactUrlSecretsWithOptions(url: string, redactionOptions: RedactionOptions): string;
 /**
  * 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,8 +1,10 @@
 /**
  * AFDATA output formatting and protocol templates.
  *
- * 16 public APIs and 2 types: protocol builders, redacted value helpers,
- * output formatters, redaction, parseSize, RedactionPolicy, and RedactionOptions.
+ * 18 public APIs and 4 types: protocol builders, value redactors (copy and
+ * in-place; cover _secret and _url fields), output formatters, URL-string
+ * redactors (redactUrlSecrets / WithOptions), parseSize, RedactionPolicy,
+ * RedactionOptions, OutputStyle, and OutputOptions.
  */
 // ═══════════════════════════════════════════
 // Public API: Protocol Builders
@@ -40,6 +42,11 @@ export var RedactionPolicy;
     RedactionPolicy["RedactionNone"] = "RedactionNone";
     RedactionPolicy["RedactionStrict"] = "RedactionStrict";
 })(RedactionPolicy || (RedactionPolicy = {}));
+export var OutputStyle;
+(function (OutputStyle) {
+    OutputStyle["Readable"] = "Readable";
+    OutputStyle["Raw"] = "Raw";
+})(OutputStyle || (OutputStyle = {}));
 /** Format as single-line JSON. Secrets redacted, original keys, raw values. */
 export function outputJson(value) {
     return JSON.stringify(redactedValue(value));
@@ -48,39 +55,40 @@ export function outputJson(value) {
 export function outputJsonWith(value, redactionPolicy) {
     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 single-line JSON with explicit output options. */
+export function outputJsonWithOptions(value, outputOptions) {
+    return JSON.stringify(redactedValueWithOptions(value, outputOptions.redaction ?? {}));
 }
 /** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
 export function outputYaml(value) {
-    value = redactedValue(value);
-    const lines = ["---"];
-    renderYamlProcessed(value, 0, lines);
-    return lines.join("\n");
+    return outputYamlWithOptions(value, {});
 }
-/** Format as multi-line YAML with explicit redaction options. */
-export function outputYamlWithOptions(value, redactionOptions) {
-    value = redactedValueWithOptions(value, redactionOptions);
+/** Format as multi-line YAML with explicit output options. */
+export function outputYamlWithOptions(value, outputOptions) {
+    value = redactedValueWithOptions(value, outputOptions.redaction ?? {});
     const lines = ["---"];
-    renderYamlProcessed(value, 0, lines);
+    if (outputOptions.style === OutputStyle.Raw) {
+        renderYamlRaw(value, 0, lines);
+    }
+    else {
+        renderYamlProcessed(value, 0, lines);
+    }
     return lines.join("\n");
 }
 /** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
 export function outputPlain(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(" ");
+    return outputPlainWithOptions(value, {});
 }
-/** Format as single-line logfmt with explicit redaction options. */
-export function outputPlainWithOptions(value, redactionOptions) {
-    value = redactedValueWithOptions(value, redactionOptions);
+/** Format as single-line logfmt with explicit output options. */
+export function outputPlainWithOptions(value, outputOptions) {
+    value = redactedValueWithOptions(value, outputOptions.redaction ?? {});
     const pairs = [];
-    collectPlainPairs(value, "", pairs);
+    if (outputOptions.style === OutputStyle.Raw) {
+        collectPlainPairsRaw(value, "", pairs);
+    }
+    else {
+        collectPlainPairs(value, "", pairs);
+    }
     pairs.sort(([a], [b]) => jcsCompare(a, b));
     return pairs
         .map(([k, v]) => `${k}=${quoteLogfmtValue(v)}`)
@@ -115,6 +123,29 @@ export function redactedValueWithOptions(value, redactionOptions) {
     applyRedactionOptions(v, redactionOptions);
     return v;
 }
+/**
+ * Redact secret components of a single URL string, using default options.
+ *
+ * Returns url with its userinfo password and any _secret-suffixed query
+ * parameter values replaced by "***". See redactUrlSecretsWithOptions.
+ */
+export function redactUrlSecrets(url) {
+    return redactUrlSecretsWithOptions(url, {});
+}
+/**
+ * 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.
+ */
+export function redactUrlSecretsWithOptions(url, redactionOptions) {
+    const redacted = redactUrlInStr(url, secretNameSet(redactionOptions));
+    return redacted ?? url;
+}
 /**
  * Parse a human-readable size string into bytes.
  * Accepts bare numbers or numbers followed by a unit letter (B/K/M/G/T).
@@ -151,82 +182,240 @@ export function parseSize(s) {
         return null;
     return result;
 }
-// ═══════════════════════════════════════════
-// Secret Redaction
-// ═══════════════════════════════════════════
-const EMPTY_SECRET_NAMES = new Set();
+const DEFAULT_CONTEXT = {
+    secretNames: new Set(),
+};
 function secretNameSet(redactionOptions) {
     return new Set(redactionOptions.secretNames ?? []);
 }
+function contextFromOptions(redactionOptions) {
+    return { secretNames: secretNameSet(redactionOptions) };
+}
 function keyHasSecretSuffix(key) {
     return key.endsWith("_secret") || key.endsWith("_SECRET");
 }
+function keyHasUrlSuffix(key) {
+    return key.endsWith("_url") || key.endsWith("_URL");
+}
 function isSecretKey(key, secretNames) {
     return keyHasSecretSuffix(key) || secretNames.has(key);
 }
-function redactSecrets(value, secretNames = EMPTY_SECRET_NAMES) {
+function redactSecrets(value, context = DEFAULT_CONTEXT) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (isSecretKey(k, secretNames)) {
-                const v = value[k];
+            const v = value[k];
+            if (isSecretKey(k, context.secretNames)) {
                 if (isObject(v) || Array.isArray(v)) {
-                    redactSecrets(v, secretNames);
+                    redactSecrets(v, context);
                 }
                 else {
                     value[k] = "***";
                 }
             }
+            else if (keyHasUrlSuffix(k) && typeof v === "string") {
+                const redacted = redactUrlInStr(v, context.secretNames);
+                if (redacted !== null)
+                    value[k] = redacted;
+            }
             else {
-                redactSecrets(value[k], secretNames);
+                redactSecrets(v, context);
             }
         }
     }
     else if (Array.isArray(value)) {
-        for (const item of value) {
-            redactSecrets(item, secretNames);
+        for (let i = 0; i < value.length; i++) {
+            redactSecrets(value[i], context);
         }
     }
 }
-function redactSecretsStrict(value, secretNames = EMPTY_SECRET_NAMES) {
+function redactSecretsStrict(value, context = DEFAULT_CONTEXT) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
-            if (isSecretKey(k, secretNames)) {
+            const v = value[k];
+            if (isSecretKey(k, context.secretNames)) {
                 value[k] = "***";
             }
+            else if (keyHasUrlSuffix(k) && typeof v === "string") {
+                const redacted = redactUrlInStr(v, context.secretNames);
+                if (redacted !== null)
+                    value[k] = redacted;
+            }
             else {
-                redactSecretsStrict(value[k], secretNames);
+                redactSecretsStrict(v, context);
             }
         }
     }
     else if (Array.isArray(value)) {
-        for (const item of value) {
-            redactSecretsStrict(item, secretNames);
+        for (let i = 0; i < value.length; i++) {
+            redactSecretsStrict(value[i], context);
         }
     }
 }
 function applyRedactionPolicy(value, redactionPolicy) {
-    applyRedactionPolicyWithNames(value, redactionPolicy, EMPTY_SECRET_NAMES);
+    applyRedactionPolicyWithContext(value, redactionPolicy, DEFAULT_CONTEXT);
 }
 function applyRedactionOptions(value, redactionOptions) {
-    applyRedactionPolicyWithNames(value, redactionOptions.policy, secretNameSet(redactionOptions));
+    applyRedactionPolicyWithContext(value, redactionOptions.policy, contextFromOptions(redactionOptions));
 }
-function applyRedactionPolicyWithNames(value, redactionPolicy, secretNames) {
+function applyRedactionPolicyWithContext(value, redactionPolicy, context) {
     switch (redactionPolicy) {
         case RedactionPolicy.RedactionTraceOnly:
             if (isObject(value) && value.trace !== undefined) {
-                redactSecrets(value.trace, secretNames);
+                redactSecrets(value.trace, context);
             }
             break;
         case RedactionPolicy.RedactionNone:
             break;
         case RedactionPolicy.RedactionStrict:
-            redactSecretsStrict(value, secretNames);
+            redactSecretsStrict(value, context);
             break;
         default:
             // Empty/unknown policy falls back to default full redaction.
-            redactSecrets(value, secretNames);
+            redactSecrets(value, context);
+            break;
+    }
+}
+// ═══════════════════════════════════════════
+// URL Secret Redaction
+// ═══════════════════════════════════════════
+/**
+ * Redact secret components of a single URL string, returning the redacted URL
+ * when s is a processable URL, or null when it is not (so callers can keep the
+ * original). Only secret spans change; all other bytes are preserved.
+ */
+function redactUrlInStr(s, secretNames) {
+    // Fast path + precondition: a single, whitespace-free, scheme-prefixed URL.
+    if (!s.includes("://") || !isSingleUrl(s) || !urlParses(s)) {
+        return null;
+    }
+    const schemeSep = s.indexOf("://");
+    const scheme = s.slice(0, schemeSep);
+    const rest = s.slice(schemeSep + 3);
+    // Authority runs from after "://" to the first '/', '?', or '#'.
+    let authEnd = rest.length;
+    for (let i = 0; i < rest.length; i++) {
+        const c = rest[i];
+        if (c === "/" || c === "?" || c === "#") {
+            authEnd = i;
+            break;
+        }
+    }
+    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}`;
+}
+/**
+ * Replace the userinfo password (user:pass@) with "***", preserving the
+ * username. Authority without '@', or userinfo without ':', is unchanged.
+ */
+function redactUserinfoPassword(authority) {
+    const at = authority.indexOf("@");
+    if (at < 0)
+        return authority;
+    const userinfo = authority.slice(0, at);
+    const colon = userinfo.indexOf(":");
+    if (colon < 0)
+        return authority;
+    return `${authority.slice(0, colon)}:***${authority.slice(at)}`;
+}
+/**
+ * Redact the values of secret-named query parameters, preserving raw bytes of
+ * every other segment (keys, benign values, encoding, ordering, separators).
+ */
+function redactQuery(query, secretNames) {
+    return query
+        .split("&")
+        .map((segment) => {
+        const eq = segment.indexOf("=");
+        if (eq < 0)
+            return segment;
+        const rawKey = segment.slice(0, eq);
+        const name = formDecode(rawKey);
+        if (isSecretKey(name, secretNames)) {
+            return `${rawKey}=***`;
+        }
+        return segment;
+    })
+        .join("&");
+}
+/** Form-decode a query-parameter name: '+' → space, then percent-decode. */
+function formDecode(rawKey) {
+    const withSpaces = rawKey.replace(/\+/g, " ");
+    try {
+        return decodeURIComponent(withSpaces);
+    }
+    catch {
+        return withSpaces;
+    }
+}
+/** True when s parses as a URL (mirrors Rust's url::Url::parse check). */
+function urlParses(s) {
+    try {
+        new URL(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when s begins with a URL scheme (ALPHA *(ALPHA / DIGIT / "+" / "-" /
+ * ".") "://") and contains no ASCII whitespace — i.e. a single bare URL, not a
+ * URL embedded in prose.
+ */
+function isSingleUrl(s) {
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        // ASCII whitespace: tab, LF, VT, FF, CR, space.
+        if (c === 0x09 || c === 0x0a || c === 0x0b || c === 0x0c || c === 0x0d || c === 0x20) {
+            return false;
+        }
+    }
+    if (s.length === 0)
+        return false;
+    const first = s.charCodeAt(0);
+    if (!isAsciiAlpha(first))
+        return false;
+    let i = 1;
+    while (i < s.length) {
+        const c = s.charCodeAt(i);
+        if (isAsciiAlphanumeric(c) || c === 0x2b /* + */ || c === 0x2d /* - */ || c === 0x2e /* . */) {
+            i += 1;
+        }
+        else {
             break;
+        }
     }
+    return s.slice(i).startsWith("://");
+}
+function isAsciiAlpha(c) {
+    return (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a);
+}
+function isAsciiAlphanumeric(c) {
+    return isAsciiAlpha(c) || (c >= 0x30 && c <= 0x39);
 }
 // ═══════════════════════════════════════════
 // Suffix Processing
@@ -530,6 +719,69 @@ function renderYamlProcessed(value, indent, lines) {
         }
     }
 }
+function renderYamlRaw(value, indent, lines) {
+    const prefix = "  ".repeat(indent);
+    if (isObject(value)) {
+        for (const key of sortedObjectKeys(value)) {
+            renderYamlFieldRaw(prefix, key, value[key], indent, lines);
+        }
+    }
+    else if (Array.isArray(value)) {
+        renderYamlArrayRaw(value, indent, lines);
+    }
+    else {
+        lines.push(`${prefix}${yamlScalar(value)}`);
+    }
+}
+function renderYamlFieldRaw(prefix, key, value, indent, lines) {
+    if (isObject(value)) {
+        if (Object.keys(value).length > 0) {
+            lines.push(`${prefix}${key}:`);
+            renderYamlRaw(value, indent + 1, lines);
+        }
+        else {
+            lines.push(`${prefix}${key}: {}`);
+        }
+    }
+    else if (Array.isArray(value)) {
+        if (value.length > 0) {
+            lines.push(`${prefix}${key}:`);
+            renderYamlArrayRaw(value, indent + 1, lines);
+        }
+        else {
+            lines.push(`${prefix}${key}: []`);
+        }
+    }
+    else {
+        lines.push(`${prefix}${key}: ${yamlScalar(value)}`);
+    }
+}
+function renderYamlArrayRaw(arr, indent, lines) {
+    const prefix = "  ".repeat(indent);
+    for (const item of arr) {
+        if (isObject(item)) {
+            if (Object.keys(item).length > 0) {
+                lines.push(`${prefix}-`);
+                renderYamlRaw(item, indent + 1, lines);
+            }
+            else {
+                lines.push(`${prefix}- {}`);
+            }
+        }
+        else if (Array.isArray(item)) {
+            if (item.length > 0) {
+                lines.push(`${prefix}-`);
+                renderYamlArrayRaw(item, indent + 1, lines);
+            }
+            else {
+                lines.push(`${prefix}- []`);
+            }
+        }
+        else {
+            lines.push(`${prefix}- ${yamlScalar(item)}`);
+        }
+    }
+}
 function escapeYamlStr(s) {
     return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
 }
@@ -569,6 +821,26 @@ function collectPlainPairs(value, prefix, pairs) {
         }
     }
 }
+function collectPlainPairsRaw(value, prefix, pairs) {
+    if (!isObject(value))
+        return;
+    for (const key of sortedObjectKeys(value)) {
+        const v = value[key];
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (isObject(v)) {
+            collectPlainPairsRaw(v, fullKey, pairs);
+        }
+        else if (Array.isArray(v)) {
+            pairs.push([fullKey, v.map((i) => plainScalarRaw(i)).join(",")]);
+        }
+        else if (v === null) {
+            pairs.push([fullKey, ""]);
+        }
+        else {
+            pairs.push([fullKey, plainScalar(v)]);
+        }
+    }
+}
 function plainScalar(value) {
     if (typeof value === "string")
         return value;
@@ -580,6 +852,12 @@ function plainScalar(value) {
         return value.toString();
     return String(value);
 }
+function plainScalarRaw(value) {
+    if (isObject(value) || Array.isArray(value)) {
+        return JSON.stringify(sortJsonValue(value));
+    }
+    return plainScalar(value);
+}
 function quoteLogfmtValue(value) {
     if (value === "")
         return "";
@@ -645,6 +923,21 @@ function sanitizeForJson(value, stack = new WeakSet()) {
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function sortedObjectKeys(obj) {
+    return Object.keys(obj).sort(jcsCompare);
+}
+function sortJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortJsonValue);
+    if (isObject(value)) {
+        const out = {};
+        for (const key of sortedObjectKeys(value)) {
+            out[key] = sortJsonValue(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
 function jcsCompare(a, b) {
     const ua = Array.from(a).flatMap((c) => {
         const cp = c.codePointAt(0);

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, type RedactionOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, type RedactionOptions, OutputStyle, type OutputOptions, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";
+export { type OutputFormat, cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, 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, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, parseSize, } from "./format.js";
+export { buildJsonOk, buildJsonError, buildJson, RedactionPolicy, OutputStyle, outputJson, outputJsonWith, outputJsonWithOptions, outputYaml, outputYamlWithOptions, outputPlain, outputPlainWithOptions, internalRedactSecrets, internalRedactSecretsWithOptions, redactedValue, redactedValueWith, redactedValueWithOptions, redactUrlSecrets, redactUrlSecretsWithOptions, parseSize, } from "./format.js";
 export { log, span, initJson, initPlain, initYaml } from "./afdata_logging.js";
-export { cliParseOutput, cliParseLogFilters, cliOutput, buildCliError } from "./cli.js";
+export { cliParseOutput, cliParseLogFilters, cliOutput, cliOutputWithOptions, buildCliError, } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {