agent-first-data 0.22.0 → 0.24.0

package/README.md

@@ -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. Explicit `--output`/`--json` 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,225 @@
+{
+  "$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
+        },
+        "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
+        },
+        "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. Explicit `--output`/`--json` 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. Explicit `--output`/`--json` 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,7 +351,7 @@ 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;
@@ -412,7 +412,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/package.json

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