agent-first-data 0.20.0 → 0.21.0

package/README.md

@@ -33,7 +33,7 @@ import { installStreamRedirectFromRawArgs } from "agent-first-data/stream-redire
 - 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 bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.
+- 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 `installStreamRedirectFromRawArgs()` (from `agent-first-data/stream-redirect`) before version/help handling if a CLI exposes `--stdout-file` or `--stderr-file`; stderr is redirected as native diagnostics, not JSON. Node fd-level redirection is process-lifetime because the standard library does not expose `dup2` restoration.
 
 ## Reference

package/assets/skills/agent-first-data/SKILL.md

@@ -61,7 +61,8 @@ assert!(rendered.contains("\"api_key_secret\":\"***\""));
 For a finite CLI execution implemented in Rust, create one `CliEmitter`, select
 `OutputFormat` through `cli_parse_output`, enable strict protocol, and emit one
 terminal result or error. Handle version before clap with
-`cli_handle_version_or_continue(raw_args, name, version)`.
+`cli_handle_version_or_continue(raw_args, cmd, name, display_name, version, build)`,
+which always answers `--version`/`-V` with a structured version event.
 For non-CLI HTTP/MCP/SSE serialization, call `redacted_value()` or
 `redact_url_secrets()` explicitly at the boundary.
 

package/assets/skills/agent-first-data/references/rules.md

@@ -284,7 +284,7 @@ Required cross-language behavior to rely on:
 - Use `redact_url_secrets()` for URLs embedded in log messages or prose before interpolating them into output.
 - Use `cli_parse_output()`, `cli_parse_log_filters()`, `render()`, `build_cli_error()`, and the version helper for CLI tools instead of custom parsing/error envelopes.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Rust CLIs should call `cli_handle_version_or_continue(raw_args, name, version)` before clap parsing so `--version --output json|yaml|plain` emits a structured `kind:"result"` event with `result.code == "version"` and `result.version` instead of clap's plain text. Bare `--version` always stays human `<name> <version>` text; explicit `--output` is always structured — there is no configuration.
+- Rust CLIs (feature `cli`/`cli-help`) should call `cli_handle_version_or_continue(raw_args, cmd, name, display_name, version, build)` before clap parsing so `--version`/`-V` always emits a structured `kind:"result"` event with `result.code == "version"`, `result.name`, and `result.version` (plus optional `result.display_name`/`result.build`) instead of clap's plain text — JSON by default, `--output yaml|plain` or `--json` for another format; there is no conventional bare-text form. Pass the caller's own `clap::Command` (e.g. `Cli::command()`) so any value-taking global flag it defines (e.g. `--stdout-file`) is recognized and its value is never mistaken for the subcommand boundary.
 - Use the protocol reader `decode_protocol_event(text)` to parse and strict-validate a single JSON text line, receiving a typed decoded event.
 
 ## AFDATA Logging

package/dist/cli.d.ts

@@ -165,29 +165,42 @@ export declare class CliEmitter {
      */
     finishResult(payload: JsonValue): number;
 }
-/** Build a standard CLI version value. */
-export declare function buildCliVersion(version: string): Event;
 /**
- * Render CLI version output.
- * Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass null to preserve
- * conventional "<name> <version>" text.
+ * Build a standard CLI version event: a `kind:"result"` event whose payload is
+ * `{ code: "version", name, version }`, plus `display_name`/`build` when given.
+ * `name` is the short/bin identity (e.g. `"afdata"`); `displayName` is an
+ * optional human-facing product name (e.g. `"Agent-First Data"`); `build` is an
+ * opaque caller-supplied identifier (a git commit SHA, for example) — its
+ * meaning is entirely up to the caller. Both are `undefined` when unavailable,
+ * and simply absent from the payload. Note the JSON field is `display_name`
+ * (snake_case) even though the parameter is `displayName`.
  */
-export declare function cliRenderVersion(name: string, version: string, format?: OutputFormat | null): string;
+export declare function buildCliVersion(name: string, displayName: string | undefined, version: string, build: string | undefined): Event;
+/**
+ * Render a CLI version response as a protocol-v1 event in `format`. There is no
+ * conventional-text path — `format` is required.
+ */
+export declare function cliRenderVersion(name: string, displayName: string | undefined, version: string, build: string | undefined, format: OutputFormat): string;
 /**
  * Render version output if --version/-V is present; otherwise return undefined.
  * Throws for malformed version requests, for example `--version --output xml`.
  *
- * One blessed behavior, not configurable: a bare version request renders
- * conventional "<name> <version>" text; `--json` or `--output <fmt>` /
- * `--output=<fmt>` alongside it selects the structured AFDATA payload
- * instead.
+ * 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.
+ *
+ * `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
+ * TS analog of Rust's `&clap::Command`: the pre-parser consults it so a global
+ * flag's space-separated value (e.g. `--log request,startup`) is never mistaken
+ * for the subcommand boundary, which would hide a later `--version`/`--output`.
  *
  * Only a top-level version request is recognized: scanning stops at the first
  * positional argument (the subcommand) or `--`, so `tool sub --version <value>`
  * leaves `--version` for the subcommand's parser rather than printing the
  * tool version.
  */
-export declare function cliHandleVersionOrContinue(rawArgs: string[], name: string, version: string): string | undefined;
+export declare function cliHandleVersionOrContinue(rawArgs: string[], valueFlags: string[], name: string, displayName: string | undefined, version: string, build: string | undefined): 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

@@ -274,34 +274,70 @@ export class CliEmitter {
         return this.finish(jsonResult(payload).build(), 0);
     }
 }
-/** Build a standard CLI version value. */
-export function buildCliVersion(version) {
-    return jsonResult({ code: "version", version }).build();
+/**
+ * Build a standard CLI version event: a `kind:"result"` event whose payload is
+ * `{ code: "version", name, version }`, plus `display_name`/`build` when given.
+ * `name` is the short/bin identity (e.g. `"afdata"`); `displayName` is an
+ * optional human-facing product name (e.g. `"Agent-First Data"`); `build` is an
+ * opaque caller-supplied identifier (a git commit SHA, for example) — its
+ * meaning is entirely up to the caller. Both are `undefined` when unavailable,
+ * and simply absent from the payload. Note the JSON field is `display_name`
+ * (snake_case) even though the parameter is `displayName`.
+ */
+export function buildCliVersion(name, displayName, version, build) {
+    return jsonResult({
+        code: "version",
+        name,
+        version,
+        ...(displayName !== undefined ? { display_name: displayName } : {}),
+        ...(build !== undefined ? { build } : {}),
+    }).build();
 }
 /**
- * Render CLI version output.
- * Pass an OutputFormat for AFDATA JSON/YAML/plain. Pass null to preserve
- * conventional "<name> <version>" text.
+ * Render a CLI version response as a protocol-v1 event in `format`. There is no
+ * conventional-text path — `format` is required.
  */
-export function cliRenderVersion(name, version, format = null) {
-    const rendered = format === null ? `${name} ${version}` : render(buildCliVersion(version), format);
+export function cliRenderVersion(name, displayName, version, build, format) {
+    const rendered = render(buildCliVersion(name, displayName, version, build), format);
     return `${rendered.replace(/\n+$/u, "")}\n`;
 }
+/**
+ * Split a flag argument into its long name (leading dashes stripped, any
+ * `=value` suffix dropped) and inline value. Returns `undefined` name for a
+ * non-flag or the bare `-`. `--output=` yields an empty-string inline value.
+ */
+function splitFlag(arg) {
+    if (!arg.startsWith("-") || arg === "-")
+        return { name: undefined, inlineValue: undefined };
+    const eq = arg.indexOf("=");
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1);
+    const name = flag.replace(/^-+/u, "");
+    if (name === "")
+        return { name: undefined, inlineValue: undefined };
+    return { name, inlineValue };
+}
 /**
  * Render version output if --version/-V is present; otherwise return undefined.
  * Throws for malformed version requests, for example `--version --output xml`.
  *
- * One blessed behavior, not configurable: a bare version request renders
- * conventional "<name> <version>" text; `--json` or `--output <fmt>` /
- * `--output=<fmt>` alongside it selects the structured AFDATA payload
- * instead.
+ * 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.
+ *
+ * `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
+ * TS analog of Rust's `&clap::Command`: the pre-parser consults it so a global
+ * flag's space-separated value (e.g. `--log request,startup`) is never mistaken
+ * for the subcommand boundary, which would hide a later `--version`/`--output`.
  *
  * Only a top-level version request is recognized: scanning stops at the first
  * positional argument (the subcommand) or `--`, so `tool sub --version <value>`
  * leaves `--version` for the subcommand's parser rather than printing the
  * tool version.
  */
-export function cliHandleVersionOrContinue(rawArgs, name, version) {
+export function cliHandleVersionOrContinue(rawArgs, valueFlags, name, displayName, version, build) {
+    const valueFlagSet = new Set(valueFlags.map((flag) => flag.replace(/^-+/u, "")));
     let versionRequested = false;
     let outputFormat;
     let outputError;
@@ -314,6 +350,7 @@ export function cliHandleVersionOrContinue(rawArgs, name, version) {
         // git/cargo/clap: this pre-parser only owns a top-level version request.
         if (!arg.startsWith("-"))
             break;
+        const { name: flagName, inlineValue } = splitFlag(arg);
         if (arg === "--version" || arg === "-V") {
             versionRequested = true;
             i += 1;
@@ -329,15 +366,21 @@ export function cliHandleVersionOrContinue(rawArgs, name, version) {
             i += 1;
             continue;
         }
-        if (arg === "--output" || arg.startsWith("--output=")) {
+        // `--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`).
+        if (flagName === "output-to") {
+            const hasSpaceValue = inlineValue === undefined && rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-");
+            i += hasSpaceValue ? 2 : 1;
+            continue;
+        }
+        if (flagName === "output") {
             let value;
-            let step = 1;
-            if (arg.startsWith("--output=")) {
-                value = arg.slice("--output=".length);
+            if (inlineValue !== undefined) {
+                value = inlineValue;
             }
             else if (rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-")) {
                 value = rawArgs[i + 1];
-                step = 2;
             }
             if (value === undefined) {
                 outputError = new Error("missing value for --output: expected json, yaml, or plain");
@@ -356,16 +399,20 @@ export function cliHandleVersionOrContinue(rawArgs, name, version) {
                     outputError = e;
                 }
             }
-            i += step;
+            i += inlineValue !== undefined || value === undefined ? 1 : 2;
             continue;
         }
-        i += 1;
+        // Any other flag: consult the caller's own value-taking global flags so a
+        // flag's space-separated value is never mistaken for the subcommand
+        // boundary above.
+        const hasSpaceValue = inlineValue === undefined && rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-");
+        i += hasSpaceValue && flagName !== undefined && valueFlagSet.has(flagName) ? 2 : 1;
     }
     if (!versionRequested)
         return undefined;
     if (outputError !== undefined)
         throw outputError;
-    return cliRenderVersion(name, version, outputFormat ?? null);
+    return cliRenderVersion(name, displayName, version, build, outputFormat ?? "json");
 }
 /**
  * Build a standard CLI parse error value. This function cannot fail.

package/package.json

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