agent-first-data 0.24.0 → 0.26.0

package/README.md

@@ -17,7 +17,7 @@ console.log(render(event.toJSON(), "json"));
 console.log(render(event.toJSON(), "plain"));
 ```
 
-Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
+Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
 
 ## Behavior Notes
 
@@ -26,7 +26,7 @@ Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redacte
 - 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:{}`.
-- Use `cliHandleVersionOrContinue()` before argument parsing so `--version` always answers with a structured protocol-v1 `kind:"result"` version event. Explicit `--output`/`--json` wins; pass the command's normal output as `defaultOutput` (JSON when omitted), plus its value-taking global flag names.
+- Use `cliHandleVersionOrContinue()` before argument parsing so `--version` always answers with a structured protocol-v1 `kind:"result"` version event. An explicit `--output` wins; pass the command's normal output as `defaultOutput` (JSON when omitted), plus its value-taking global flag names.
 
 ## Reference
 

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

@@ -147,7 +147,8 @@
         },
         "usage": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
         },
         "arguments": {
           "type": "array",
@@ -203,7 +204,8 @@
         },
         "usage": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
         },
         "arguments": {
           "type": "array",

package/dist/cli.d.ts

@@ -186,7 +186,7 @@ export declare function cliRenderVersion(name: string, displayName: string | und
  * Throws for malformed version requests, for example `--version --output xml`.
  *
  * The one blessed behavior: `--version` always answers with a protocol-v1
- * `kind:"result"` version event. Explicit `--output`/`--json` wins; otherwise
+ * `kind:"result"` version event. An explicit `--output` wins; otherwise
  * `defaultOutput` should be the command's normal output default.
  *
  * `valueFlags` is the caller's own value-taking global long flags (with or

package/dist/cli.js

@@ -322,7 +322,7 @@ function splitFlag(arg) {
  * Throws for malformed version requests, for example `--version --output xml`.
  *
  * The one blessed behavior: `--version` always answers with a protocol-v1
- * `kind:"result"` version event. Explicit `--output`/`--json` wins; otherwise
+ * `kind:"result"` version event. An explicit `--output` wins; otherwise
  * `defaultOutput` should be the command's normal output default.
  *
  * `valueFlags` is the caller's own value-taking global long flags (with or
@@ -356,16 +356,6 @@ export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayNam
             i += 1;
             continue;
         }
-        if (arg === "--json") {
-            if (outputFormat !== undefined && outputFormat !== "json") {
-                outputError = new Error("conflicting output formats: --json conflicts with previous output format");
-            }
-            else {
-                outputFormat = "json";
-            }
-            i += 1;
-            continue;
-        }
         // `--output-to` takes a value but does not affect version text output.
         // Consume its space-separated value so it is not mistaken for the
         // subcommand boundary (which would hide a later `--version`/`--output`).

package/dist/format.d.ts

@@ -191,6 +191,31 @@ export declare function redactedValue(value: unknown, options?: {
 export declare function redactUrlSecrets(url: string, options?: {
     secretNames?: readonly string[];
 }): string;
+/**
+ * Redact secret values out of a command line.
+ *
+ * A long flag whose name is secret by AFDATA naming (`--api-key-secret`, or an
+ * exact `secretNames` entry) has its value replaced by `***`, in both
+ * `--flag=value` and `--flag value` spellings. Everything else is preserved
+ * byte-for-byte.
+ *
+ * Free text is deliberately never scanned: a bare `api_key_secret=sk-live`
+ * positional, or a secret-looking token after a non-secret flag, is left alone.
+ * AFDATA decides sensitivity from the *field name*, and argv is no exception —
+ * rename the flag rather than pattern-matching values. A flag with no value
+ * (end of argv, or followed by another flag) is likewise left inspectable.
+ *
+ * Only long (`--`) flags are recognized, matching the convention's
+ * long-flags-only rule.
+ *
+ * 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.
+ */
+export declare function redactArgv(args: readonly string[], options?: {
+    secretNames?: readonly string[];
+    policy?: RedactionPolicy;
+}): string[];
 /**
  * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
  * This helper handles fixed offsets only; IANA timezone names and DST rules

package/dist/format.js

@@ -476,6 +476,67 @@ export function redactUrlSecrets(url, options) {
     const redacted = redactUrlInStr(url, secretNameSet(options ?? {}));
     return redacted ?? url;
 }
+/**
+ * Redact secret values out of a command line.
+ *
+ * A long flag whose name is secret by AFDATA naming (`--api-key-secret`, or an
+ * exact `secretNames` entry) has its value replaced by `***`, in both
+ * `--flag=value` and `--flag value` spellings. Everything else is preserved
+ * byte-for-byte.
+ *
+ * Free text is deliberately never scanned: a bare `api_key_secret=sk-live`
+ * positional, or a secret-looking token after a non-secret flag, is left alone.
+ * AFDATA decides sensitivity from the *field name*, and argv is no exception —
+ * rename the flag rather than pattern-matching values. A flag with no value
+ * (end of argv, or followed by another flag) is likewise left inspectable.
+ *
+ * Only long (`--`) flags are recognized, matching the convention's
+ * long-flags-only rule.
+ *
+ * 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.
+ */
+export function redactArgv(args, options) {
+    if (options?.policy === RedactionPolicy.Off)
+        return [...args];
+    const secretNames = secretNameSet(options ?? {});
+    const out = [];
+    let redactNext = false;
+    for (const arg of args) {
+        if (redactNext) {
+            redactNext = false;
+            if (!arg.startsWith("-")) {
+                out.push("***");
+                continue;
+            }
+        }
+        if (arg.startsWith("--")) {
+            const rest = arg.slice(2);
+            const equals = rest.indexOf("=");
+            if (equals >= 0) {
+                const name = rest.slice(0, equals);
+                if (isSecretFlagName(name, secretNames)) {
+                    out.push(`--${name}=***`);
+                    continue;
+                }
+            }
+            else if (isSecretFlagName(rest, secretNames)) {
+                redactNext = true;
+            }
+        }
+        out.push(arg);
+    }
+    return out;
+}
+/**
+ * Whether a long flag's name is secret, normalizing the kebab-case flag
+ * spelling to the snake_case field spelling the convention is defined in.
+ */
+function isSecretFlagName(flagName, secretNames) {
+    const normalized = flagName.replace(/-/gu, "_");
+    return isSecretKey(normalized, secretNames) || isSecretKey(flagName, secretNames);
+}
 /**
  * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
  * This helper handles fixed offsets only; IANA timezone names and DST rules

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, 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, 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";

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, 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, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
 export { CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.24.0",
+  "version": "0.26.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": {