Crate agent_first_data

Expand description

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, cli_handle_version_or_continue
(feature cli-help): configurable clap help rendering via cli_render_help_with_options and cli_handle_help_or_continue
(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), ported from agent-first-config. 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. Ported from the standalone agent-first-config crate.
skill: Agent Skills SKILL.md front-matter validation.
stream_redirect: Optional process stdout/stderr file redirection.

Structs§

CliEmitter: Stateful emitter for finite 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.
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", "version": <version> }.
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_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.
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.