agent-first-data 0.17.3__tar.gz → 0.18.0__tar.gz

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.17.3
-Summary: A naming convention that lets AI agents understand your data without being told what it means.
+Version: 0.18.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
 Requires-Python: >=3.9
@@ -14,7 +14,7 @@ pip install agent-first-data
 ```
 
 ```python
-from agent_first_data import json_result, output_json, output_plain
+from agent_first_data import json_result, render, OutputFormat
 
 value = json_result(
     {
@@ -24,11 +24,11 @@ value = json_result(
     }
 ).build()
 
-print(output_json(value))
-print(output_plain(value))
+print(render(value, OutputFormat.JSON))
+print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
+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`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -42,7 +42,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
-- YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
+- 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 bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/README.md

@@ -5,7 +5,7 @@ pip install agent-first-data
 ```
 
 ```python
-from agent_first_data import json_result, output_json, output_plain
+from agent_first_data import json_result, render, OutputFormat
 
 value = json_result(
     {
@@ -15,11 +15,11 @@ value = json_result(
     }
 ).build()
 
-print(output_json(value))
-print(output_plain(value))
+print(render(value, OutputFormat.JSON))
+print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `output_json`, `output_yaml`, `output_plain` (each takes an optional keyword-only `options=`), `redacted_value`, `redact_secrets_in_place`, `redact_url_secrets`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `cli_output`, `build_cli_error`, `build_cli_version`, `cli_handle_version_or_continue`, `decode_protocol_event`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
+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`. Skill admin and stream-redirect helpers live in `agent_first_data.skill` and `agent_first_data.stream_redirect` (import the submodule directly).
 
 Logging is available through `init_logging_json`, `init_logging_plain`, `init_logging_yaml`, `span`, and `get_logger`.
 
@@ -33,7 +33,7 @@ init_logging_json("INFO", secret_names=("authorization",))
 
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
-- YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
+- 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 bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/agent_first_data/__init__.py

@@ -21,11 +21,8 @@ from agent_first_data.format import (
     DecodedLog,
     decode_protocol_event,
     RedactionPolicy,
-    OutputStyle,
+    PlainStyle,
     OutputOptions,
-    output_json,
-    output_yaml,
-    output_plain,
     redacted_value,
     redact_url_secrets,
     normalize_utc_offset,
@@ -41,7 +38,7 @@ from agent_first_data.cli import (
     CliEmitter,
     cli_parse_output,
     cli_parse_log_filters,
-    cli_output,
+    render,
     build_cli_error,
     build_cli_version,
     cli_render_version,
@@ -69,11 +66,8 @@ __all__ = [
     "DecodedLog",
     "decode_protocol_event",
     "RedactionPolicy",
-    "OutputStyle",
+    "PlainStyle",
     "OutputOptions",
-    "output_json",
-    "output_yaml",
-    "output_plain",
     "redacted_value",
     "redact_url_secrets",
     "normalize_utc_offset",
@@ -86,7 +80,7 @@ __all__ = [
     "CliEmitter",
     "cli_parse_output",
     "cli_parse_log_filters",
-    "cli_output",
+    "render",
     "build_cli_error",
     "build_cli_version",
     "cli_render_version",

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/agent_first_data/assets/skills/agent-first-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-first-data
-description: Apply and review the formal Agent-First Data specification using the Rust/Go/Python/TypeScript libraries or afdata CLI for naming, redaction, formatting, protocol envelopes, logging, linting, and validation. Use proactively when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, CLI output, or compatibility-sensitive public and persistent field names.
+description: Apply and review the formal Agent-First Data specification using the Rust/Go/Python/TypeScript libraries or afdata CLI for naming, redaction, formatting, protocol envelopes, logging, linting, validation, and reading or safely editing structured JSON/TOML/YAML/dotenv/INI documents by dot-path. Use proactively when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, CLI output, compatibility-sensitive public and persistent field names, or when reading or editing a config/document file from the shell.
 ---
 
 <!-- Canonical source: skills/agent-first-data/SKILL.md.
@@ -47,22 +47,21 @@ go get github.com/agentfirstkit/agent-first-data/go
 ```
 
 ```rust
-use agent_first_data::{json_result, output_json};
+use agent_first_data::{json_result, render, OutputFormat, OutputOptions};
 use serde_json::json;
 
 let event = json_result(json!({
     "latency_ms": 1280,
     "api_key_secret": "sk-live-example",
-})).build()?;
-let rendered = output_json(event.as_value());
+})).build();
+let rendered = render(event.as_value(), OutputFormat::Json, &OutputOptions::default());
 assert!(rendered.contains("\"api_key_secret\":\"***\""));
-# Ok::<(), agent_first_data::BuildError>(())
 ```
 
 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` and `VersionConfig::conventional_default()`.
+`cli_handle_version_or_continue(raw_args, name, version)`.
 For non-CLI HTTP/MCP/SSE serialization, call `redacted_value()` or
 `redact_url_secrets()` explicitly at the boundary.
 
@@ -94,11 +93,11 @@ working in that runtime.
 
 ## Redaction behavior contract
 
-Fields named `_secret` or `_url` and values passing through AFDATA output formatters (`output_json`, `output_yaml`, `output_plain`) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
+Fields named `_secret` or `_url` and values passing through AFDATA output rendering (`render`, in any format) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
 
 ## Logging behavior contract
 
-One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `cli_output()` applies output formatting. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
+One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `render()` applies output formatting. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
 
 ## CLI workflow
 
@@ -114,16 +113,62 @@ Use it for deterministic checks:
 ```bash
 afdata lint payload.json
 afdata validate events.jsonl
-afdata format payload.json --output yaml
+afdata render payload.json --output yaml
 afdata skill validate skills/example-skill
 ```
 
 - Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, or MCP input/output schemas.
 - Run `afdata validate` for AFDATA protocol events or finite event streams.
-- Omit the input path to read stdin. `--output` accepts `json`, `yaml`, or
-  `plain`.
+- Run `afdata render` to apply AFDATA redaction/formatting to arbitrary JSON or JSONL. Omit the input path to read stdin. `--output` accepts `json`, `yaml`, or
+  `plain`; JSON and YAML keep original keys/values (structure-preserving), Plain is the lossy human renderer.
 - Treat findings as contract issues unless the owning tool intentionally documents a non-AFDATA field.
 
+## Document workflow
+
+Use `show`/`get`/`value` to read a JSON, TOML, YAML, dotenv, or INI document
+and `set`/`add`/`remove`/`unset` to edit one in place, instead of `sed`,
+regular expressions, or a generic reserializer — those can reorder keys, drop
+comments, or change quoting/anchors in the rest of the file.
+
+- `show` returns the whole document as one AFDATA record; use it for batch
+  inspection, and pass every known sensitive legacy field name with
+  `--secret-name FIELD` (an exact field name, not a dot-path).
+- `get <KEY>` returns one dot-path value as an AFDATA record. A secret-named
+  leaf (`_secret`/`_SECRET`, or an exact `--secret-name` match) is still
+  redacted to `"***"` even though the caller targeted it directly — use
+  `value --reveal-secret` when the real value is genuinely needed.
+- `value <KEY>` writes only the raw scalar to stdout, with no AFDATA envelope
+  and no forced trailing newline, for direct use in shell substitution:
+  `value=$(afdata value server.host config.toml)` (KEY then FILE). Only
+  scalars are supported; an array or object errors with `path <KEY> is not a
+  scalar` (exit 1) — use `get`/`show` for a subtree. A secret-named leaf errors unless
+  `--reveal-secret` is passed — there is no default bypass for a targeted read.
+- Read commands (`show`/`get`/`value`) take a positional FILE or fall back to
+  piped stdin, defaulting to JSON and rejecting an interactive TTY rather than
+  blocking. Mutation commands (`set`/`add`/`remove`/`unset`) always require
+  `--input-file PATH` and never read stdin.
+- Escape a literal dot as `\.` and a literal backslash as `\\` in a dot-path;
+  every command shares this grammar, so an unrecognized escape or empty
+  segment is always an error, never a guess.
+- `add`/`remove` operate on a keyed list — an array of objects addressed by a
+  slug — and always require an explicit `--slug-field FIELD`; the CLI never
+  infers an identity field. Keyed editing is implemented for JSON and YAML
+  only; TOML, dotenv, and INI return a structured "not implemented" error, so
+  edit their list entries by writing the whole value another way.
+- For `set`, choose exactly one secret source instead of a positional value
+  when the value must not land in shell history or `ps`: `--value-secret
+  VALUE` (convenient, but visible to argv/process listings),
+  `--value-secret-stdin` (pipe), `--value-secret-prompt` (human, terminal echo
+  off), or `--value-secret-fd FD` (Unix automation that needs stdin for
+  something else).
+- Mutations preserve the rest of the source document — comments, key order,
+  unrelated formatting — and refuse to write through a symlink or (on Unix) a
+  multi-link hardlink target. Treat a failed mutation as leaving the original
+  file untouched rather than assuming a partial write, and reread before
+  retrying. A format backend that isn't compiled in, or input outside the
+  documented dotenv/INI dialect, is a structured error to report, not a cue to
+  hand-edit the file.
+
 ## Review checklist
 
 1. Numeric fields with units carry the right suffix and safe integer/string representation.

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/agent_first_data/assets/skills/agent-first-data/references/rules.md

@@ -107,7 +107,7 @@ Sub-cent precision — `_{code}_micro`, integer millionths (10⁻⁶) of the maj
 | `_secret` | redact the entire value/subtree to `***` | `api_key_secret: "sk-or-v1-abc..."` |
 | `_url` | scrub secrets *inside* the URL value, keep the rest | `callback_url: "https://h/cb?code_secret=..."` |
 
-All CLI output formats (JSON, YAML, Plain) automatically redact `_secret` fields. Matching recognizes `_secret` and `_SECRET` only — no mixed case. The entire `_secret` value/subtree becomes `***`, including objects and arrays. For legacy fields that cannot be renamed, configure `OutputOptions.redaction` with `secret_names`/`secretNames` such as `["api_key", "authorization"]`; names match exact field names at any nesting level; no trim, case folding, hyphen/underscore normalization, globs, regex, or substring matching. AFDATA does not define named redaction profiles; use the default, `secret_names`, `RedactionTraceOnly`, or `RedactionNone` deliberately at the serialization boundary. Callers that need schema-preserving YAML/plain rendering can pass `OutputOptions` with the `Raw` output style.
+All CLI output formats (JSON, YAML, Plain) automatically redact `_secret` fields. Matching recognizes `_secret` and `_SECRET` only — no mixed case. The entire `_secret` value/subtree becomes `***`, including objects and arrays. For legacy fields that cannot be renamed, configure `OutputOptions.redaction` with `secret_names`/`secretNames` such as `["api_key", "authorization"]`; names match exact field names at any nesting level; no trim, case folding, hyphen/underscore normalization, globs, regex, or substring matching. AFDATA does not define named redaction profiles; use the default policy `All`, `secret_names`, `TraceOnly`, or `Off` deliberately at the serialization boundary. YAML is always schema-preserving, like JSON. Callers that need schema-preserving Plain rendering can pass `OutputOptions` with the `Raw` output style.
 
 `***` means only one thing: AFDATA redacted a sensitive value. Do not use it for serialization failure, truncation, unsupported types, or “maybe secret” guesses.
 
@@ -158,15 +158,17 @@ ORM struct fields preserve the suffix: `duration_ms: i64`, not `duration: i64`.
 
 ## Part 2: Output Processing
 
-Three output formats via `output_json()`, `output_yaml()`, `output_plain()`. Default YAML and Plain apply key stripping + value formatting. Optional `options` (Python/TS keyword arg; Rust/Go `_with_options` variant).
+Three output formats via one entry point `render(value, format, options)` (`format` = json/yaml/plain). JSON and YAML are both **structure-preserving**: original keys, scalar types, and numeric semantics survive after redaction. Plain is the one **lossy/human** renderer — it strips formatting suffixes and reformats values for scanning. `options` is an optional keyword arg in Python/TS; Rust/Go pass `OutputOptions` explicitly.
 
 ### Formats
 
 - **JSON** — single-line, original keys, raw values, no sorting (machine-readable), secrets redacted
-- **YAML** — multi-line, formatting suffixes stripped, values formatted, secrets redacted by default
+- **YAML** — multi-line, original keys, raw values (same semantics as JSON), keys sorted, secrets redacted by default
 - **Plain** — single-line logfmt, formatting suffixes stripped, values formatted, secrets redacted by default
 
-### Key stripping (YAML and Plain)
+Rust gates YAML output behind the `yaml` Cargo feature (on by default, along with the rest of the default feature set). With `default-features = false` and `yaml` not re-enabled, `OutputFormat::Yaml` does not exist and `--output yaml` is rejected with a feature-requirement error instead of silently falling back to another format.
+
+### Key stripping (Plain only)
 
 Remove recognized formatting suffix from key. Longest match first, exact lowercase or uppercase only:
 
@@ -176,9 +178,9 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 4. `_msats`, `_sats`, `_bytes`, `_percent`, `_secret`
 5. `_jpy`, `_ns`, `_us`, `_ms`, `_s`
 
-`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
+`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret. JSON and YAML never strip suffixes — every key renders exactly as written.
 
-### Value formatting (YAML and Plain)
+### Value formatting (Plain only)
 
 - `_ms` with absolute value < 1000 → `{n}ms`; absolute value ≥ 1000 → seconds (`1280` → `1.28s`, `-1500` → `-1.5s`)
 - `_s`, `_ns`, `_us` → append unit (`3600s`, `450000ns`, `830μs`)
@@ -192,7 +194,7 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 - `_secret` → `***` (the redaction phase already replaced the subtree)
 - `_bcp47`, `_utc_offset`, `_rfc3339_date`, `_rfc3339_time` → pass through unchanged
 
-**Type constraints**: `_bytes`/`_epoch_*` require integer. `_usd_cents`/`_eur_cents`/`_jpy`/`_{code}_cents`/`_{code}_micro` require non-negative integer. Duration/Bitcoin/`_percent` accept any number. Wrong type → raw value + original key.
+**Type constraints**: `_bytes`/`_epoch_*` require integer. `_usd_cents`/`_eur_cents`/`_jpy`/`_{code}_cents`/`_{code}_micro` require non-negative integer. Duration/Bitcoin/`_percent` accept any number. Wrong type → raw value + original key. JSON and YAML never format values — a value renders exactly as its JSON type (numbers stay numbers, strings stay quoted strings, no unit/date/currency formatting).
 
 ### Plain logfmt details
 
@@ -204,7 +206,11 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 
 ### Key ordering
 
-YAML and Plain sort keys (after stripping) by UTF-16 code unit order (JCS, RFC 8785). For ASCII keys this equals byte-order sorting.
+YAML sorts keys by UTF-16 code unit order (JCS, RFC 8785) without stripping suffixes. Plain sorts keys the same way, but after stripping. For ASCII keys this equals byte-order sorting.
+
+### `PlainStyle` (Plain only)
+
+`PlainStyle` (`Readable`/`Raw`) only affects Plain: `Readable` (default) strips suffixes and formats values; `Raw` keeps original keys/values (still redacted). YAML ignores `PlainStyle` entirely — it is always structure-preserving, matching JSON.
 
 ---
 
@@ -269,17 +275,17 @@ Use the local language README for installation and the full overview/spec for AP
 
 Required cross-language behavior to rely on:
 
-- Output helpers redact before formatting: `output_json()`, `output_yaml()`, `output_plain()` (with optional `options` in Python/TS).
-- Use `redacted_value()` for raw HTTP/MCP/SSE serialization paths that bypass `output_json()`.
+- The single output entry point `render(value, format, options)` redacts before formatting (with optional `options` in Python/TS).
+- Use `redacted_value()` for raw HTTP/MCP/SSE serialization paths that bypass `render()`.
 - 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()`, `cli_output()`, `build_cli_error()`, and the version helper for CLI tools instead of custom parsing/error envelopes.
+- 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()` before clap parsing so `--version --output json|yaml|plain` emits a structured `kind:"result"` event with `result.version` instead of clap's plain text. Use `VersionConfig::conventional_default()` so bare `--version` stays human text while explicit `--output` remains structured.
+- 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.
 - 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
 
-Long-running services and processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) use a logging init function to capture the full process. One-time CLI output uses `json_log()` + `cli_output()` or `CliEmitter`.
+Long-running services and processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) use a logging init function to capture the full process. One-time CLI output uses `json_log()` + `render()` or `CliEmitter`.
 
 ### Init (Rust only; pick one format per process)
 
@@ -312,7 +318,7 @@ Log redaction is **by field name** (the same `_secret`/`_url` rule as all output
 CLI tools that use AFDATA should support output and logging flags:
 
 ```
---output json|yaml|plain    # default is tool-defined (interactive → yaml, scripting/logging → json)
+--output json|yaml|plain    # default is tool-defined (structured/scripting → json or yaml, human scanning → plain)
 --log startup,request,progress,retry,redirect
 --verbose                   # shorthand for all log categories
 ```

{agent_first_data-0.17.3 → agent_first_data-0.18.0}/agent_first_data/cli.py

@@ -13,9 +13,9 @@ from agent_first_data.format import (
     json_log,
     json_progress,
     json_result,
-    output_json,
-    output_yaml,
-    output_plain,
+    _format_json,
+    _format_yaml,
+    _format_plain,
     validate_protocol_event,
 )
 
@@ -38,13 +38,15 @@ class LogFilters:
     def enabled(self, event: str) -> bool:
         """Check if event should be logged.
 
-        Empty filter list returns False.
-        Filters containing 'all' or '*' return True.
-        Otherwise returns True if event (lowercased) starts with any filter.
+        An empty filter list returns False (filtering is opt-in). The single
+        wildcard word 'all' returns True ('*' is not special — one wildcard
+        spelling, not two). Otherwise returns True iff event (lowercased) starts
+        with any filter (prefix match); a mistyped filter simply matches nothing
+        and silently emits no output.
         """
         if not self._filters:
             return False
-        if any(f in ("all", "*") for f in self._filters):
+        if "all" in self._filters:
             return True
         event_lower = event.lower()
         return any(event_lower.startswith(f) for f in self._filters)
@@ -104,22 +106,22 @@ def cli_parse_log_filters(entries: list[str]) -> LogFilters:
     return LogFilters(out)
 
 
-def cli_output(value: Any, format: OutputFormat, *, options: OutputOptions | None = None) -> str:
-    """Dispatch output formatting by OutputFormat.
+def render(value: Any, format: OutputFormat, *, options: OutputOptions | None = None) -> str:
+    """Render a value as JSON, YAML, or plain (logfmt) text for OutputFormat.
 
-    Equivalent to calling output_json, output_yaml, or output_plain directly.
-    JSON ignores OutputStyle and preserves original keys and values after redaction.
+    The single public render entry point: value x format x options -> str.
+    JSON ignores PlainStyle and preserves original keys and values after redaction.
 
     >>> import json
     >>> v = {"code": "ok"}
-    >>> cli_output(v, OutputFormat.JSON).startswith('{"code"')
+    >>> render(v, OutputFormat.JSON).startswith('{"code"')
     True
     """
     if format is OutputFormat.YAML:
-        return output_yaml(value, options=options)
+        return _format_yaml(value, options=options)
     if format is OutputFormat.PLAIN:
-        return output_plain(value, options=options)
-    return output_json(value, options=options)
+        return _format_plain(value, options=options)
+    return _format_json(value, options=options)
 
 
 class CliEmitter:
@@ -175,7 +177,7 @@ class CliEmitter:
                 merged_log.update(log_payload)
                 envelope["log"] = merged_log
 
-        self._writer.write(cli_output(envelope, self._format, options=self._output_options) + "\n")
+        self._writer.write(render(envelope, self._format, options=self._output_options) + "\n")
         flush = getattr(self._writer, "flush", None)
         if flush is not None:
             flush()
@@ -219,8 +221,13 @@ class CliEmitter:
 
 
 def build_cli_version(version: str) -> dict:
-    """Build a standard CLI version value."""
-    return json_result({"version": version}).build().to_dict()
+    """Build a standard CLI version result event.
+
+    The result payload always carries ``code: "version"`` alongside
+    ``version``, so structured consumers can dispatch on ``code`` the same
+    way they would for any other result shape.
+    """
+    return json_result({"code": "version", "version": version}).build().to_dict()
 
 
 def cli_render_version(
@@ -234,21 +241,24 @@ def cli_render_version(
     conventional "<name> <version>" text.
     """
     rendered = (
-        f"{name} {version}" if format is None else cli_output(build_cli_version(version), format)
+        f"{name} {version}" if format is None else render(build_cli_version(version), format)
     )
     return rendered.rstrip("\n") + "\n"
 
 
-def cli_handle_version_or_continue(
-    raw_args: list[str],
-    name: str,
-    version: str,
-    default_output: OutputFormat | None = None,
-    output_flag: str = "--output",
-    allow_output_format: bool = True,
-) -> str | None:
+def cli_handle_version_or_continue(raw_args: list[str], name: str, version: str) -> str | None:
     """Render version output if --version/-V is present; otherwise return None.
 
+    One blessed behavior, no configurable knobs: a bare version request
+    (``--version``/``-V`` with no output flag) always renders conventional
+    ``"<name> <version>\\n"`` text; adding ``--json`` or ``--output
+    <json|yaml|plain>`` selects the structured AFDATA rendering instead.
+
+    Only a top-level version request is recognized: scanning stops at the first
+    positional argument (the subcommand), so ``tool sub --version <value>``
+    leaves ``--version`` for the subcommand's parser rather than printing the
+    tool version.
+
     Raises ValueError for malformed version requests, for example
     ``--version --output xml``. The caller should convert that to a CLI error
     with ``build_cli_error``.
@@ -262,11 +272,16 @@ def cli_handle_version_or_continue(
         arg = raw_args[i]
         if arg == "--":
             break
+        # The first positional argument marks the subcommand boundary. Past it,
+        # --version and -V belong to the subcommand's own parser, matching
+        # git/cargo/clap: this pre-parser only owns a top-level version request.
+        if not arg.startswith("-"):
+            break
         if arg in ("--version", "-V"):
             version_requested = True
             i += 1
             continue
-        if allow_output_format and arg == "--json":
+        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"
@@ -275,9 +290,9 @@ def cli_handle_version_or_continue(
                 output_format = OutputFormat.JSON
             i += 1
             continue
-        if allow_output_format and (arg == output_flag or arg.startswith(f"{output_flag}=")):
+        if arg == "--output" or arg.startswith("--output="):
             value: str | None
-            if arg.startswith(f"{output_flag}="):
+            if arg.startswith("--output="):
                 value = arg.split("=", 1)[1]
                 step = 1
             elif i + 1 < len(raw_args) and not raw_args[i + 1].startswith("-"):
@@ -288,14 +303,14 @@ def cli_handle_version_or_continue(
                 step = 1
             if value is None:
                 output_error = ValueError(
-                    f"missing value for {output_flag}: expected json, yaml, or plain"
+                    "missing value for --output: expected json, yaml, or plain"
                 )
             else:
                 try:
                     parsed_output = cli_parse_output(value)
                     if output_format is not None and output_format is not parsed_output:
                         output_error = ValueError(
-                            f"conflicting output formats: {output_flag} {value} conflicts with previous output format"
+                            f"conflicting output formats: --output {value} conflicts with previous output format"
                         )
                     else:
                         output_format = parsed_output
@@ -309,21 +324,23 @@ def cli_handle_version_or_continue(
         return None
     if output_error is not None:
         raise output_error
-    return cli_render_version(
-        name,
-        version,
-        output_format if allow_output_format and output_format is not None else default_output,
-    )
+    return cli_render_version(name, version, output_format)
 
 
 def build_cli_error(message: str, hint: str | None = None) -> dict | Event:
     """Build a standard CLI parse error event.
 
     Use when argument parsing fails or a flag value is invalid.
-    Print with output_json and exit with code 2.
+    Print with render(..., OutputFormat.JSON) and exit with code 2.
+
+    Always returns a strict-valid ``kind: "error"`` event with code
+    ``"cli_error"``. Never raises: an empty ``message`` is replaced with a
+    generic placeholder so the returned event stays strict-valid.
 
     Returns the event envelope as a dict.
     """
+    if not message:
+        message = "unspecified error"
     event = json_error("cli_error", message)
     if hint is not None:
         event = event.hint(hint)