agent-first-data 0.30.0 → 0.31.0

package/README.md

@@ -17,12 +17,15 @@ console.log(render(event.toJSON(), "json"));
 console.log(render(event.toJSON(), "plain"));
 ```
 
-Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, and `buildCliVersion`.
+Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactUrlsInText`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, and `buildCliVersion`.
 
 ## Behavior Notes
 
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
+- `OutputOptions.redaction.urlNames` applies URL treatment to exact legacy field names
+  and recurses through collections. `redactUrlsInText` is explicit and scans
+  only complete scheme URLs, never arbitrary prose secrets.
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `buildCliError(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.

package/assets/cli-spec-v1.schema.json

@@ -32,6 +32,13 @@
     "about": {
       "$ref": "#/$defs/nonEmpty"
     },
+    "shared_arguments": {
+      "description": "Arguments every command accepts, declared once. Spliced into each command and into every combination's optional set when the registry is built, so a resolved spec behaves as if each command declared them.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/argument"
+      }
+    },
     "lifecycle_output": {
       "$ref": "#/$defs/output"
     },
@@ -164,7 +171,8 @@
             "i64",
             "finite_f64",
             "enum",
-            "json"
+            "json",
+            "uuid"
           ]
         },
         "value_name": {
@@ -178,6 +186,15 @@
             "$ref": "#/$defs/nonEmpty"
           }
         },
+        "range": {
+          "description": "Inclusive [minimum, maximum] bounds for an I64 argument, checked when the value is parsed so an out-of-range value is a usage error.",
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "minItems": 2,
+          "maxItems": 2
+        },
         "default": true,
         "repeatable": {
           "const": true

package/dist/cli.d.ts

@@ -6,7 +6,8 @@ import { JsonValue, type OutputOptions, Event } from "./format.js";
 export type OutputFormat = "json" | "yaml" | "plain";
 /**
  * Parse the --output flag value into an OutputFormat.
- * Throws on unknown values; catch and pass message to buildCliError.
+ * Throws a value-safe message on unknown values; catch and pass it to
+ * buildCliError.
  *
  * @example
  * cliParseOutput("json") // → "json"
@@ -78,8 +79,8 @@ export type CliEventWriter = (line: string) => void;
 export type OutputTo = "split" | "stdout" | "stderr";
 /**
  * Parse an `--output-to` value into an OutputTo: "split" (default), "stdout", or
- * "stderr". Throws on unknown values; catch and pass the message to
- * buildCliError.
+ * "stderr". Throws a value-safe message on unknown values; catch and pass it
+ * to buildCliError.
  *
  * @example
  * parseOutputTo("split") // → "split"

package/dist/cli.js

@@ -4,7 +4,8 @@
 import { Event, jsonError, jsonResult, formatJsonValue, formatYamlValue, formatPlainValue, validateProtocolEvent, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
- * Throws on unknown values; catch and pass message to buildCliError.
+ * Throws a value-safe message on unknown values; catch and pass it to
+ * buildCliError.
  *
  * @example
  * cliParseOutput("json") // → "json"
@@ -14,7 +15,7 @@ export function cliParseOutput(s) {
     if (s === "json" || s === "yaml" || s === "plain") {
         return s;
     }
-    throw new Error(`invalid --output format '${s}': expected json, yaml, or plain`);
+    throw new Error("invalid --output format: expected json, yaml, or plain");
 }
 /**
  * Normalized log filter result with enabled() matching and readonly filters property.
@@ -96,8 +97,8 @@ export function render(value, format, options = {}) {
 }
 /**
  * Parse an `--output-to` value into an OutputTo: "split" (default), "stdout", or
- * "stderr". Throws on unknown values; catch and pass the message to
- * buildCliError.
+ * "stderr". Throws a value-safe message on unknown values; catch and pass it
+ * to buildCliError.
  *
  * @example
  * parseOutputTo("split") // → "split"
@@ -107,7 +108,7 @@ export function parseOutputTo(value) {
     if (value === "split" || value === "stdout" || value === "stderr") {
         return value;
     }
-    throw new Error(`invalid --output-to '${value}': expected split, stdout, or stderr`);
+    throw new Error("invalid --output-to: expected split, stdout, or stderr");
 }
 /** Event writer bound to the process stdout stream. */
 const processStdoutWriter = (line) => {

package/dist/format.d.ts

@@ -153,6 +153,11 @@ export type OutputOptions = {
          * Matching is exact field-name equality at any nesting level.
          */
         secretNames?: readonly string[];
+        /**
+         * Exact legacy field names whose string leaves receive URL-aware
+         * redaction in addition to _url/_URL fields.
+         */
+        urlNames?: readonly string[];
     };
     /** Rendering style for plain (logfmt) output only. Omitted means readable.
      * JSON and YAML are structure-preserving and ignore this setting. */
@@ -185,6 +190,7 @@ export declare function formatPlainValue(value: JsonValue | Event, options?: Out
 export declare function redactedValue(value: unknown, options?: {
     policy?: RedactionPolicy;
     secretNames?: readonly string[];
+    urlNames?: readonly string[];
 }): JsonValue;
 /**
  * Redact secret components of a single URL string.
@@ -206,6 +212,16 @@ export declare function redactUrlSecrets(url: string, options?: {
     secretNames?: readonly string[];
     policy?: RedactionPolicy;
 }): string;
+/**
+ * Redact complete scheme-prefixed URL spans embedded in prose.
+ *
+ * This helper is explicit and URL-only: surrounding text is never scanned for
+ * secret-looking names or values.
+ */
+export declare function redactUrlsInText(text: string, options?: {
+    secretNames?: readonly string[];
+    policy?: RedactionPolicy;
+}): string;
 /**
  * Redact secret values out of a command line.
  *

package/dist/format.js

@@ -517,6 +517,17 @@ export function redactUrlSecrets(url, options) {
     const redacted = redactUrlInStr(url, secretNameSet(options ?? {}));
     return redacted ?? url;
 }
+/**
+ * Redact complete scheme-prefixed URL spans embedded in prose.
+ *
+ * This helper is explicit and URL-only: surrounding text is never scanned for
+ * secret-looking names or values.
+ */
+export function redactUrlsInText(text, options) {
+    if (!redactsUnscopedInput(options?.policy))
+        return text;
+    return redactUrlsInTextWithContext(text, contextFromOptions(options ?? {}));
+}
 /**
  * Redact secret values out of a command line.
  *
@@ -749,12 +760,16 @@ function isRedacted(value) {
 }
 const DEFAULT_CONTEXT = {
     secretNames: new Set(),
+    urlNames: new Set(),
 };
 function secretNameSet(redactionOptions) {
     return new Set(redactionOptions.secretNames ?? []);
 }
 function contextFromOptions(redactionOptions) {
-    return { secretNames: secretNameSet(redactionOptions) };
+    return {
+        secretNames: secretNameSet(redactionOptions),
+        urlNames: new Set(redactionOptions.urlNames ?? []),
+    };
 }
 function keyHasSecretSuffix(key) {
     return key.endsWith("_secret") || key.endsWith("_SECRET");
@@ -765,6 +780,9 @@ function keyHasUrlSuffix(key) {
 function isSecretKey(key, secretNames) {
     return keyHasSecretSuffix(key) || secretNames.has(key);
 }
+function isUrlKey(key, context) {
+    return keyHasUrlSuffix(key) || context.urlNames.has(key);
+}
 const MAX_DEPTH = 256;
 const MAX_DEPTH_MARKER = "<afdata:max-depth>";
 function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
@@ -782,13 +800,8 @@ function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
                     value[k] = REDACTED_MARKER;
                 }
             }
-            else if (keyHasUrlSuffix(k)) {
-                if (typeof v === "string") {
-                    value[k] = redactUrlFieldValue(v, context.secretNames);
-                }
-                else {
-                    value[k] = depth + 1 >= MAX_DEPTH ? MAX_DEPTH_MARKER : (redactSecrets(v, context, depth + 1), v);
-                }
+            else if (isUrlKey(k, context)) {
+                value[k] = redactUrlValue(v, context, depth + 1);
             }
             else {
                 value[k] = depth + 1 >= MAX_DEPTH ? MAX_DEPTH_MARKER : (redactSecrets(v, context, depth + 1), v);
@@ -804,6 +817,32 @@ function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
         }
     }
 }
+function redactUrlValue(value, context, depth) {
+    if (depth >= MAX_DEPTH)
+        return MAX_DEPTH_MARKER;
+    if (typeof value === "string") {
+        return redactUrlFieldValue(value, context.secretNames);
+    }
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index++) {
+            value[index] = redactUrlValue(value[index], context, depth + 1);
+        }
+        return value;
+    }
+    if (isObject(value)) {
+        for (const key of Object.keys(value)) {
+            const item = value[key];
+            if (isSecretKey(key, context.secretNames)) {
+                if (item !== null)
+                    value[key] = REDACTED_MARKER;
+            }
+            else {
+                value[key] = redactUrlValue(item, context, depth + 1);
+            }
+        }
+    }
+    return value;
+}
 function applyRedactionOptions(value, redactionOptions) {
     applyRedactionPolicyWithContext(value, redactionOptions.policy, contextFromOptions(redactionOptions));
 }
@@ -872,6 +911,120 @@ function redactUrlInStr(s, secretNames) {
     const newFragment = fragment === null ? "" : `#${redactQuery(fragment, secretNames)}`;
     return `${scheme}://${newAuthority}${newBeforeFragment}${newFragment}`;
 }
+function redactUrlsInTextWithContext(text, context) {
+    const output = [];
+    let copiedThrough = 0;
+    let searchFrom = 0;
+    while (true) {
+        const span = nextSchemeUrlSpan(text, searchFrom);
+        if (span === null)
+            break;
+        const [start, end] = span;
+        output.push(text.slice(copiedThrough, start));
+        const url = text.slice(start, end);
+        output.push(redactUrlInStr(url, context.secretNames) ?? url);
+        copiedThrough = end;
+        searchFrom = end;
+    }
+    if (output.length === 0)
+        return text;
+    output.push(text.slice(copiedThrough));
+    return output.join("");
+}
+function nextSchemeUrlSpan(text, startAt) {
+    let start = startAt;
+    while (start < text.length) {
+        // Only consider the head of a maximal scheme-byte run: a scheme cannot begin
+        // mid-run, so a position whose predecessor is a scheme byte was already
+        // covered by the run that contains it.
+        const atRunHead = start === 0 || !isSchemeCodeUnit(text.charCodeAt(start - 1));
+        if (atRunHead) {
+            let schemeEnd = start;
+            while (schemeEnd < text.length && isSchemeCodeUnit(text.charCodeAt(schemeEnd))) {
+                schemeEnd += 1;
+            }
+            // A scheme must start with a letter, but the run need not: prose like
+            // "2https://h/?token_secret=x" glues a digit onto the URL. Retry from the
+            // first letter *inside* the run instead of abandoning the span — giving up
+            // there fails open and leaks the whole query.
+            let schemeStart = -1;
+            for (let i = start; i < schemeEnd; i++) {
+                if (isAsciiAlpha(text.charCodeAt(i))) {
+                    schemeStart = i;
+                    break;
+                }
+            }
+            if (schemeStart >= 0 && text.startsWith("://", schemeEnd)) {
+                let end = schemeEnd + 3;
+                while (end < text.length
+                    && !isSpanTerminatorWhitespace(text.charCodeAt(end))
+                    && !isTextUrlDelimiter(text[end])) {
+                    end += 1;
+                }
+                while (end > schemeEnd + 3
+                    && isTrailingTextUrlPunctuation(text[end - 1])) {
+                    end -= 1;
+                }
+                if (end > schemeEnd + 3)
+                    return [schemeStart, end];
+            }
+        }
+        start += 1;
+    }
+    return null;
+}
+function isSchemeCodeUnit(code) {
+    return isAsciiAlphanumeric(code) || code === 0x2b || code === 0x2d || code === 0x2e;
+}
+/**
+ * True for a code unit that ends a URL span in prose: the Unicode `White_Space`
+ * property, written out here instead of delegated to `/\s/u`.
+ *
+ * The four AFDATA implementations must cut the span at the same byte, and each
+ * language's native predicate covers a different set — `\s` counts U+FEFF but
+ * not U+0085, Python's `str.isspace()` counts U+001C–U+001F, Rust and Go count
+ * neither. Divergence is a defect in both directions: ending a span early leaves
+ * the rest of the query readable, and ending it late pulls the following prose
+ * into the URL, where redacting the parameter it lands in deletes it. So the set
+ * is enumerated, and it is generous — a redaction helper exists to keep a log
+ * line readable, so anything a human reads as a space must end the URL.
+ *
+ * Two exclusions are deliberate, not oversights:
+ * - **U+FEFF** (zero-width no-break space) is not `White_Space`. `\s` counts it,
+ *   which is what used to cut a URL carrying it short and leave the secret after
+ *   it in the clear. It must not creep back in.
+ * - **U+001C–U+001F** (the file/group/record/unit separators) are not
+ *   `White_Space` either; only Python's `str.isspace()` counted them.
+ *
+ * This is a different question from `isSingleUrl`, which asks whether a whole
+ * string is one URL and stays ASCII-only. A span this scanner produces contains
+ * no whitespace at all, so it satisfies that stricter gate either way.
+ */
+function isSpanTerminatorWhitespace(code) {
+    return (
+    // TAB, LF, VT, FF, CR, SPACE
+    (code >= 0x09 && code <= 0x0d)
+        || code === 0x20
+        // NEL, NBSP, OGHAM SPACE MARK
+        || code === 0x85
+        || code === 0xa0
+        || code === 0x1680
+        // EN QUAD .. HAIR SPACE
+        || (code >= 0x2000 && code <= 0x200a)
+        // LINE SEPARATOR, PARAGRAPH SEPARATOR, NARROW NO-BREAK SPACE,
+        // MEDIUM MATHEMATICAL SPACE, IDEOGRAPHIC SPACE
+        || code === 0x2028
+        || code === 0x2029
+        || code === 0x202f
+        || code === 0x205f
+        || code === 0x3000);
+}
+function isTextUrlDelimiter(character) {
+    return "\"'<>`，。；！？）》】」』".includes(character);
+}
+function isTrailingTextUrlPunctuation(character) {
+    return ".,;!)]}，。；！）》】".includes(character);
+}
 function redactUrlFieldValue(s, secretNames) {
     const redacted = redactUrlInStr(s, secretNames);
     if (redacted !== null)
@@ -1018,8 +1171,9 @@ function decimalIntText(value) {
     }
     return null;
 }
+const MIN_I64 = -9223372036854775808n;
 const MAX_I64 = 9223372036854775807n;
-function nonNegativeI64(value) {
+function signedI64(value) {
     let text = null;
     if (typeof value === "bigint") {
         text = value.toString();
@@ -1036,14 +1190,16 @@ function nonNegativeI64(value) {
         return null;
     try {
         const integer = BigInt(text);
-        return integer >= 0n && integer <= MAX_I64 ? integer : null;
+        return integer >= MIN_I64 && integer <= MAX_I64 ? integer : null;
     }
     catch {
         return null;
     }
 }
 function formatCents(value, symbol) {
-    return `${symbol}${value / 100n}.${String(value % 100n).padStart(2, "0")}`;
+    const sign = value < 0n ? "-" : "";
+    const magnitude = value < 0n ? -value : value;
+    return `${sign}${symbol}${magnitude / 100n}.${String(magnitude % 100n).padStart(2, "0")}`;
 }
 function epochNsToMs(value) {
     const text = decimalIntText(value);
@@ -1114,14 +1270,14 @@ function tryProcessField(key, value) {
     // Group 2: compound currency suffixes
     stripped = stripSuffixCI(key, "_usd_cents");
     if (stripped !== null) {
-        const integer = nonNegativeI64(value);
+        const integer = signedI64(value);
         if (integer !== null)
             return [stripped, formatCents(integer, "$")];
         return null;
     }
     stripped = stripSuffixCI(key, "_eur_cents");
     if (stripped !== null) {
-        const integer = nonNegativeI64(value);
+        const integer = signedI64(value);
         if (integer !== null)
             return [stripped, formatCents(integer, "\u20ac")];
         return null;
@@ -1129,18 +1285,22 @@ function tryProcessField(key, value) {
     const gc = tryStripGenericCents(key);
     if (gc !== null) {
         const [gcStripped, code] = gc;
-        const integer = nonNegativeI64(value);
+        const integer = signedI64(value);
         if (integer !== null) {
-            return [gcStripped, `${integer / 100n}.${String(integer % 100n).padStart(2, "0")} ${code.toUpperCase()}`];
+            const sign = integer < 0n ? "-" : "";
+            const magnitude = integer < 0n ? -integer : integer;
+            return [gcStripped, `${sign}${magnitude / 100n}.${String(magnitude % 100n).padStart(2, "0")} ${code.toUpperCase()}`];
         }
         return null;
     }
     const gm = tryStripGenericMicro(key);
     if (gm !== null) {
         const [gmStripped, code] = gm;
-        const integer = nonNegativeI64(value);
+        const integer = signedI64(value);
         if (integer !== null) {
-            return [gmStripped, `${integer / 1000000n}.${String(integer % 1000000n).padStart(6, "0")} ${code.toUpperCase()}`];
+            const sign = integer < 0n ? "-" : "";
+            const magnitude = integer < 0n ? -integer : integer;
+            return [gmStripped, `${sign}${magnitude / 1000000n}.${String(magnitude % 1000000n).padStart(6, "0")} ${code.toUpperCase()}`];
         }
         return null;
     }
@@ -1199,9 +1359,12 @@ function tryProcessField(key, value) {
     // Group 5: short suffixes (last to avoid false positives)
     stripped = stripSuffixCI(key, "_jpy");
     if (stripped !== null) {
-        const integer = nonNegativeI64(value);
-        if (integer !== null)
-            return [stripped, `\u00a5${formatWithCommas(integer)}`];
+        const integer = signedI64(value);
+        if (integer !== null) {
+            const sign = integer < 0n ? "-" : "";
+            const magnitude = integer < 0n ? -integer : integer;
+            return [stripped, `${sign}\u00a5${formatWithCommas(magnitude)}`];
+        }
         return null;
     }
     stripped = stripSuffixCI(key, "_ns");

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * 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 { 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, redactUrlsInText, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
 export { type OutputFormat, type OutputTo, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, } from "./cli.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
  * 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 { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, PlainStyle, outputOptionsForPolicy, redactedValue, redactArgv, redactUrlSecrets, redactUrlsInText, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.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.30.0",
+  "version": "0.31.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 Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.",
   "license": "MIT",
   "repository": {