agent-first-data 0.23.0 → 0.25.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`/`-V` always answers with a structured protocol-v1 `kind:"result"` version event — JSON by default, or `--output yaml|plain`/`--json` for another format; there is no conventional bare-text form. Pass your own value-taking global flag names so their value is not mistaken for the subcommand boundary.
+- 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

@@ -0,0 +1,227 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-help-v1.schema.json",
+  "title": "AFDATA CLI help v1 event",
+  "description": "Compact, progressively disclosed CLI help carried by an AFDATA result event.",
+  "type": "object",
+  "required": [
+    "kind",
+    "result",
+    "trace"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "result"
+    },
+    "result": {
+      "type": "object",
+      "required": [
+        "code",
+        "help"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "const": "help"
+        },
+        "help": {
+          "$ref": "#/$defs/help"
+        }
+      }
+    },
+    "trace": {
+      "type": "object"
+    }
+  },
+  "$defs": {
+    "argument": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "short": {
+          "type": "string",
+          "pattern": "^-[^-]$"
+        },
+        "help": {
+          "type": "string",
+          "minLength": 1
+        },
+        "required": {
+          "const": true
+        },
+        "global": {
+          "const": true
+        },
+        "repeatable": {
+          "const": true
+        },
+        "value": {
+          "type": "string",
+          "minLength": 1
+        },
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "default": {
+          "type": "string"
+        },
+        "defaults": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "name": {
+                "pattern": "^-"
+              }
+            }
+          },
+          "else": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "value"
+                  ]
+                },
+                {
+                  "required": [
+                    "values"
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "value",
+              "values"
+            ]
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "default",
+              "defaults"
+            ]
+          }
+        }
+      ]
+    },
+    "command": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "about": {
+          "type": "string",
+          "minLength": 1
+        },
+        "usage": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
+        },
+        "arguments": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/argument"
+          }
+        },
+        "subcommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/command"
+          }
+        }
+      }
+    },
+    "help": {
+      "type": "object",
+      "required": [
+        "scope",
+        "command_path",
+        "name"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "scope": {
+          "enum": [
+            "one_level",
+            "recursive"
+          ]
+        },
+        "command_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "inherited_arguments_from": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "about": {
+          "type": "string",
+          "minLength": 1
+        },
+        "usage": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
+        },
+        "arguments": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/argument"
+          }
+        },
+        "subcommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/command"
+          }
+        }
+      }
+    }
+  }
+}

package/dist/cli.d.ts

@@ -186,8 +186,8 @@ 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 — JSON by default, or `--output yaml|plain` (or
- * `--json`) for another format. There is no conventional bare-text path.
+ * `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
  * without leading dashes; the leading dashes are stripped internally). It is the
@@ -200,7 +200,7 @@ export declare function cliRenderVersion(name: string, displayName: string | und
  * leaves `--version` for the subcommand's parser rather than printing the
  * tool version.
  */
-export declare function cliHandleVersionOrContinue(rawArgs: string[], valueFlags: string[], name: string, displayName: string | undefined, version: string, build: string | undefined): string | undefined;
+export declare function cliHandleVersionOrContinue(rawArgs: string[], valueFlags: string[], name: string, displayName: string | undefined, version: string, build: string | undefined, defaultOutput?: OutputFormat): string | undefined;
 /**
  * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.

package/dist/cli.js

@@ -322,8 +322,8 @@ 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 — JSON by default, or `--output yaml|plain` (or
- * `--json`) for another format. There is no conventional bare-text path.
+ * `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
  * without leading dashes; the leading dashes are stripped internally). It is the
@@ -336,7 +336,7 @@ function splitFlag(arg) {
  * leaves `--version` for the subcommand's parser rather than printing the
  * tool version.
  */
-export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayName, version, build) {
+export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayName, version, build, defaultOutput = "json") {
     const valueFlagSet = new Set(valueFlags.map((flag) => flag.replace(/^-+/u, "")));
     let versionRequested = false;
     let outputFormat;
@@ -351,21 +351,11 @@ export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayNam
         if (!arg.startsWith("-"))
             break;
         const { name: flagName, inlineValue } = splitFlag(arg);
-        if (arg === "--version" || arg === "-V") {
+        if (arg === "--version") {
             versionRequested = true;
             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`).
@@ -412,7 +402,7 @@ export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayNam
         return undefined;
     if (outputError !== undefined)
         throw outputError;
-    return cliRenderVersion(name, displayName, version, build, outputFormat ?? "json");
+    return cliRenderVersion(name, displayName, version, build, outputFormat ?? defaultOutput);
 }
 /**
  * Build a standard CLI parse error value. This function cannot fail.

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.23.0",
+  "version": "0.25.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": {