Crate agent_first_data 

Agent-First Data (AFDATA) output formatting and protocol templates.

Public APIs, grouped by concern (see each item’s own docs for details; the full symbol list is the crate root’s own rustdoc index, not repeated here — it drifts out of sync with a hand-maintained count otherwise):

• Protocol v1 builders: json_result, json_error, json_progress, json_log (each returns a builder; call .build())
• Protocol reader: decode_protocol_event parses and strict-validates one protocol line into a typed DecodedEvent
• Redaction: redacted_value / Redactor::value (JSON values), redact_url_secrets / Redactor::url (URL strings) — Redactor carries custom secret_names/policy
• Output rendering: render — the single value × format × options → String entry point for JSON, YAML, and plain (logfmt) output
• Parse utilities: normalize_utc_offset, is_valid_rfc3339_date, is_valid_rfc3339_time, is_valid_rfc3339, is_valid_bcp47
• CLI helpers: cli_parse_output, cli_parse_log_filters (returns LogFilters), build_cli_error, build_cli_version, cli_render_version
• (feature cli or cli-help): cli_handle_version_or_continue (needs a &clap::Command to recognize the caller’s own value-taking global flags)
• (feature cli-help): configurable clap help rendering via cli_render_help_with_options; use cli_handle_version_or_help_or_continue as the preferred Rust entry point for top-level version/help handling
• (feature cli-help-markdown): cli_render_help_markdown — recursive Markdown help
• (feature skill): skill::validate_skill / skill::validate_skill_named — strict Agent Skills SKILL.md front-matter validation
• (feature skill-admin): skill::run_skill_admin — install/uninstall/status a spore’s embedded Agent Skill across Codex, Claude Code, opencode, and Hermes; returns a typed skill::SkillReport
• (feature tracing): afdata_tracing::try_init initializes an AFDATA stdout logging layer with configurable format and redaction; also afdata_tracing::LogFormat

The shared cross-language contract (which of these exist, under what name, in each of Rust/Python/TypeScript/Go) is tracked in spec/api-surface.json and cross-checked by scripts/validate_api_surface.py.

Modules

afdata_tracing

AFDATA-compliant tracing layer.

document

Format-independent document values (dot-path access, typed coercion, and pluggable JSON/TOML/YAML/dotenv/INI backends). Format-independent document values: dot-path get/set/add/remove, type-directed CLI-string coercion, keyed-list (slug-addressed array) helpers, and typed serde adapters, backed by pluggable JSON/TOML/YAML/dotenv/INI format readers and writers.

skill

Agent Skills SKILL.md front-matter validation.

stream_redirect

Optional process stdout/stderr file redirection.

Structs

CliEmitter

Stateful emitter for structured CLI executions.

DecodedError

Decoded kind:"error" event.

DecodedLog

Decoded kind:"log" event.

DecodedProgress

Decoded kind:"progress" event.

DecodedResult

Decoded kind:"result" event.

ErrorBuilder

Builder for error events.

Event

A typed, strict-valid AFDATA protocol v1 event.

HelpConfig

Configuration for pre-clap help handling.

HelpOptions

Options for rendering CLI help.

LogBuilder

Builder for log events.

LogFilters

Parsed and normalized log filters (trimmed, lowercased, deduplicated).

OutputOptions

Output options combining redaction and rendering style.

ProgressBuilder

Builder for progress events.

ProtocolViolation

A single protocol-validation violation: a stable machine-readable rule slug, a JSON pointer to the offending location ("" = the whole event), and a human-readable message.

Redactor

Configurable redaction builder for secrets and legacy field names.

ResultBuilder

Builder for result events.

Enums

BuildError

Error type for builder failures.

CliEmitterError

Error returned by CliEmitter.

DecodedEvent

A decoded, strict-valid AFDATA protocol v1 event, typed by kind.

EventDecodeError

Error returned by decode_protocol_event.

HelpFormat

Output format for help rendering.

HelpScope

How much of a command tree a help request should render.

LogLevel

Log level enumeration (serialized as lowercase).

OutputFormat

Output format for CLI and pipe/MCP modes.

OutputTo

Where a CliEmitter sends its events, selected by --output-to.

PlainStyle

Rendering style for plain (logfmt) output only. JSON and YAML are always structure-preserving and ignore this.

RedactionPolicy

Which fields a Redactor scrubs. The default is RedactionPolicy::All.

Functions

build_cli_error

Build a CLI error event with optional hint.

build_cli_version

Build a standard CLI version event: a kind:"result" event whose payload is { "code": "version", "name": <name>, "version": <version> }, plus "display_name"/"build" when given. name is the short/bin identity (e.g. "afdata"); display_name is an optional human-facing product name (e.g. "Agent-First Data"); build is an opaque caller-supplied identifier (a git commit SHA, for example) — its meaning is entirely up to the caller. Both are None when unavailable, and simply absent from the payload.

cli_handle_help_or_continue

Render help from raw argv if a help flag is present; otherwise return None.

cli_handle_version_or_continue

Render version output from raw argv if --version or -V is present.

cli_handle_version_or_help_or_continue

Handle a top-level version or help request through one early entry point.

cli_parse_log_filters

Normalize --log flag entries: trim, lowercase, deduplicate, remove empty.

cli_parse_output

Parse --output flag value into OutputFormat.

cli_render_help

Render recursive plain-text help for a clap command tree.

cli_render_help_markdown

Render recursive Markdown help for a clap command tree.

cli_render_help_with_options

Render help for a clap command tree with explicit scope and format.

cli_render_version

Render a CLI version response as a protocol-v1 event in format.

decode_protocol_event

Parse one protocol v1 line, strict-validate it, and return a typed decoded event.

is_valid_bcp47

Return true when s is a structurally well-formed BCP 47 (RFC 5646) language tag.

is_valid_rfc3339

Return true when s is a complete RFC 3339 date-time, such as 2026-02-14T10:30:00Z or 2026-02-14T10:30:00.5+08:00.

is_valid_rfc3339_date

Return true when s is an RFC 3339 full-date (YYYY-MM-DD).

is_valid_rfc3339_time

Return true when s is an RFC 3339 partial-time (HH:MM:SS[.fraction]).

json_error

Fluent builder: start building an error event.

json_log

Fluent builder: start building a log event.

json_progress

Fluent builder: start building a progress event.

json_result

Fluent builder: start building a result event.

normalize_utc_offset

Normalize a fixed UTC offset string to AFDATA canonical form.

redact_url_secrets

Redact secret components of a single URL string, using default options.

redacted_value

Return a JSON value copy with default _secret redaction applied.

render

Render a value as a string in the given format with the given options.

validate_protocol_event

Validate one protocol v1 event envelope.

validate_protocol_stream

Validate a finite structured CLI event stream: (log | progress)* -> exactly one (result | error) -> end.