agent-first-data 0.22.0__tar.gz → 0.24.0__tar.gz

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.22.0
+Version: 0.24.0
 Summary: 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-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -37,7 +37,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - 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.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cli_handle_version_or_continue()` 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 `cli_handle_version_or_continue()` 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 `default_format` (JSON when omitted), plus its value-taking global flag names.
 
 ## Reference
 

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/README.md

@@ -28,7 +28,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - 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.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cli_handle_version_or_continue()` 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 `cli_handle_version_or_continue()` 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 `default_format` (JSON when omitted), plus its value-taking global flag names.
 
 ## Reference
 

agent_first_data-0.24.0/agent_first_data/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"
+          }
+        }
+      }
+    }
+  }
+}

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/agent_first_data/cli.py

@@ -451,6 +451,8 @@ def cli_handle_version_or_continue(
     display_name: str | None,
     version: str,
     build: str | None,
+    *,
+    default_format: OutputFormat = OutputFormat.JSON,
 ) -> str | None:
     """Render version output if --version/-V is present; otherwise return None.
 
@@ -461,8 +463,8 @@ def cli_handle_version_or_continue(
 
     The one blessed behavior: ``--version``/``-V`` always answers with a
     protocol-v1 ``kind:"result"`` version event (see :func:`build_cli_version`) —
-    JSON by default, or ``--json`` / ``--output <json|yaml|plain>`` to select
-    another format.
+    An explicit ``--json`` / ``--output <json|yaml|plain>`` wins; otherwise
+    ``default_format`` should be the command's normal output default.
 
     Only a top-level version request is recognized: scanning stops at the first
     positional argument (the subcommand), so ``tool sub --version <value>``
@@ -490,7 +492,7 @@ def cli_handle_version_or_continue(
             break
 
         flag_name, inline_value = _split_flag(arg)
-        if arg in ("--version", "-V"):
+        if arg == "--version":
             version_requested = True
             i += 1
             continue
@@ -560,7 +562,7 @@ def cli_handle_version_or_continue(
         display_name,
         version,
         build,
-        output_format if output_format is not None else OutputFormat.JSON,
+        output_format if output_format is not None else default_format,
     )
 
 

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.22.0
+Version: 0.24.0
 Summary: 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-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
@@ -37,7 +37,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - 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.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cli_handle_version_or_continue()` 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 `cli_handle_version_or_continue()` 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 `default_format` (JSON when omitted), plus its value-taking global flag names.
 
 ## Reference
 

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/agent_first_data.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ agent_first_data.egg-info/PKG-INFO
 agent_first_data.egg-info/SOURCES.txt
 agent_first_data.egg-info/dependency_links.txt
 agent_first_data.egg-info/top_level.txt
+agent_first_data/assets/cli-help-v1.schema.json
 agent_first_data/assets/protocol-v1.schema.json
 agent_first_data/assets/registry.json
 tests/test_cli.py

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 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"
 readme = "README.md"

{agent_first_data-0.22.0 → agent_first_data-0.24.0}/tests/test_cli.py

@@ -520,9 +520,9 @@ def test_cli_render_version_renders_json():
     assert '"version":"1.2.3"' in out
 
 
-def test_cli_handle_version_bare_defaults_to_json():
-    # The one blessed behavior: `--version` always answers with a protocol-v1
-    # event, JSON by default — no more conventional bare-text special case.
+def test_cli_handle_version_bare_inherits_json_default():
+    # `--version` answers with a protocol-v1 event and follows the command's
+    # declared output default.
     out = cli_handle_version_or_continue(
         ["--version"],
         VERSION_VALUE_FLAGS,
@@ -542,6 +542,21 @@ def test_cli_handle_version_bare_defaults_to_json():
     assert parsed["trace"] == {}
 
 
+def test_cli_handle_version_bare_inherits_plain_default():
+    out = cli_handle_version_or_continue(
+        ["--version"],
+        VERSION_VALUE_FLAGS,
+        "agent-cli",
+        None,
+        "1.2.3",
+        None,
+        default_format=OutputFormat.PLAIN,
+    )
+    assert out is not None
+    assert "result.code=version" in out
+    assert "result.version=1.2.3" in out
+
+
 def test_cli_handle_version_honors_explicit_plain_output():
     out = cli_handle_version_or_continue(
         ["--version", "--output", "plain"],