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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.24.0
+Version: 0.26.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` 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.
+- 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.24.0 → agent_first_data-0.26.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` 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.
+- 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.24.0 → agent_first_data-0.26.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.24.0 → agent_first_data-0.26.0}/agent_first_data/assets/cli-help-v1.schema.json

@@ -147,7 +147,8 @@
         },
         "usage": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
         },
         "arguments": {
           "type": "array",
@@ -203,7 +204,8 @@
         },
         "usage": {
           "type": "string",
-          "minLength": 1
+          "minLength": 1,
+          "pattern": "^[^\\n\\r]+$"
         },
         "arguments": {
           "type": "array",

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

@@ -463,7 +463,7 @@ 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`) —
-    An explicit ``--json`` / ``--output <json|yaml|plain>`` wins; otherwise
+    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
@@ -496,15 +496,6 @@ def cli_handle_version_or_continue(
             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`).

{agent_first_data-0.24.0 → agent_first_data-0.26.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.24.0 → agent_first_data-0.26.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.24.0
+Version: 0.26.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` 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.
+- 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.24.0 → agent_first_data-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.24.0"
+version = "0.26.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.24.0 → agent_first_data-0.26.0}/tests/test_cli.py

@@ -671,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,
@@ -681,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.24.0 → agent_first_data-0.26.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"]