agent-first-data 0.23.0__tar.gz → 0.25.0__tar.gz

{agent_first_data-0.23.0 → agent_first_data-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.23.0
+Version: 0.25.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
@@ -28,7 +28,7 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
 
 ## Behavior Notes
 
@@ -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. An explicit `--output` 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.23.0 → agent_first_data-0.25.0}/README.md

@@ -19,7 +19,7 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
 
 ## Behavior Notes
 
@@ -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. An explicit `--output` 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.23.0 → agent_first_data-0.25.0}/agent_first_data/__init__.py

@@ -24,6 +24,7 @@ from agent_first_data.format import (
     PlainStyle,
     OutputOptions,
     redacted_value,
+    redact_argv,
     redact_url_secrets,
     normalize_utc_offset,
     is_valid_bcp47,
@@ -70,6 +71,7 @@ __all__ = [
     "PlainStyle",
     "OutputOptions",
     "redacted_value",
+    "redact_argv",
     "redact_url_secrets",
     "normalize_utc_offset",
     "is_valid_bcp47",

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

{agent_first_data-0.23.0 → agent_first_data-0.25.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 ``--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,19 +492,10 @@ 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
-        if arg == "--json":
-            if output_format is not None and output_format is not OutputFormat.JSON:
-                output_error = ValueError(
-                    "conflicting output formats: --json conflicts with previous output format"
-                )
-            else:
-                output_format = OutputFormat.JSON
-            i += 1
-            continue
         # `--output-to` takes a value but does not affect version output. Consume
         # its space-separated value so it is not mistaken for the subcommand
         # boundary (which would hide a later `--version`/`--output`).
@@ -560,7 +553,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.23.0 → agent_first_data-0.25.0}/agent_first_data/format.py

@@ -613,6 +613,63 @@ def redact_url_secrets(url: str, *, secret_names: Sequence[str] = ()) -> str:
     return redacted if redacted is not None else url
 
 
+def redact_argv(
+    args: Sequence[str],
+    *,
+    secret_names: Sequence[str] = (),
+    policy: RedactionPolicy | None = None,
+) -> list[str]:
+    """Redact secret values out of a command line.
+
+    A long flag whose name is secret by AFDATA naming (``--api-key-secret``, or
+    an exact ``secret_names`` 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.
+    """
+    if policy is RedactionPolicy.Off:
+        return list(args)
+    context = _RedactionContext.from_names(secret_names)
+    out: list[str] = []
+    redact_next = False
+    for arg in args:
+        if redact_next:
+            redact_next = False
+            if not arg.startswith("-"):
+                out.append("***")
+                continue
+        if arg.startswith("--"):
+            rest = arg[2:]
+            name, sep, _value = rest.partition("=")
+            if sep:
+                if _is_secret_flag_name(name, context):
+                    out.append(f"--{name}=***")
+                    continue
+            elif _is_secret_flag_name(rest, context):
+                redact_next = True
+        out.append(arg)
+    return out
+
+
+def _is_secret_flag_name(flag_name: str, context: _RedactionContext) -> bool:
+    """Whether a long flag's name is secret, normalizing kebab-case to snake_case."""
+    normalized = flag_name.replace("-", "_")
+    return context.is_secret_key(normalized) or context.is_secret_key(flag_name)
+
+
 def _apply_redaction(value: Any, secret_names: Sequence[str], policy: RedactionPolicy | None) -> None:
     context = _RedactionContext.from_names(secret_names)
     _apply_redaction_policy_with_context(value, policy, context)

{agent_first_data-0.23.0 → agent_first_data-0.25.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.23.0
+Version: 0.25.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
@@ -28,7 +28,7 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`.
 
 ## Behavior Notes
 
@@ -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. An explicit `--output` 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.23.0 → agent_first_data-0.25.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.23.0 → agent_first_data-0.25.0}/pyproject.toml

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

{agent_first_data-0.23.0 → agent_first_data-0.25.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"],
@@ -656,9 +671,11 @@ def test_cli_handle_version_supports_inline_output_format():
     assert 'version: "1.2.3"' in out
 
 
-def test_cli_handle_version_json_alias():
+def test_cli_handle_version_ignores_json_flag():
+    # --json belongs to the application: it must not select a format, and it
+    # must not conflict with one. --output yaml still wins.
     out = cli_handle_version_or_continue(
-        ["--version", "--json"],
+        ["--version", "--json", "--output", "yaml"],
         VERSION_VALUE_FLAGS,
         "agent-cli",
         None,
@@ -666,15 +683,13 @@ def test_cli_handle_version_json_alias():
         None,
     )
     assert out is not None
-    parsed = json.loads(out.strip())
-    assert parsed["kind"] == "result"
-    assert parsed["result"]["version"] == "1.2.3"
+    assert out.startswith("---\n")
 
 
-def test_cli_handle_version_json_alias_conflict():
+def test_cli_handle_version_conflicting_output_formats():
     with pytest.raises(ValueError, match="conflicting output formats"):
         cli_handle_version_or_continue(
-            ["--version", "--json", "--output", "yaml"],
+            ["--version", "--output", "json", "--output", "yaml"],
             VERSION_VALUE_FLAGS,
             "agent-cli",
             None,

{agent_first_data-0.23.0 → agent_first_data-0.25.0}/tests/test_format.py

@@ -25,6 +25,7 @@ from agent_first_data import (
     OutputOptions,
     OutputFormat,
     redacted_value,
+    redact_argv,
     redact_url_secrets,
     render,
     normalize_utc_offset,
@@ -64,6 +65,23 @@ def test_redact_url_fixtures():
         assert got == case["expected"], f"[redact_url/{name}] got {got!r}"
 
 
+def test_redact_argv_fixtures():
+    for case in _load("redact_argv.json"):
+        name = case["name"]
+        options = _redaction_options(case)
+        got = redact_argv(
+            case["input"],
+            secret_names=options.secret_names,
+            policy=options.policy,
+        )
+        assert got == case["expected"], f"[redact_argv/{name}] got {got!r}"
+
+
+def test_redact_argv_default_matches_explicit_defaults():
+    args = ["tool", "--api-key-secret=sk-live"]
+    assert redact_argv(args) == redact_argv(args, secret_names=(), policy=None)
+
+
 def test_redaction_options_fixtures():
     for case in _load("redaction_options.json"):
         name = case["name"]