agent_first_data/
lib.rs

1//! Agent-First Data (AFDATA) output formatting and protocol templates.
2//!
3//! Public APIs, grouped by concern (see each item's own docs for details;
4//! the full symbol list is the crate root's own rustdoc index, not repeated
5//! here — it drifts out of sync with a hand-maintained count otherwise):
6//! - Protocol v1 builders: [`json_result`], [`json_error`], [`json_progress`], [`json_log`]
7//!   (each returns a builder; call `.build()`)
8//! - Protocol reader: [`decode_protocol_event`] parses and strict-validates one protocol
9//!   line into a typed [`DecodedEvent`]
10//! - Redaction: [`redacted_value`] / [`Redactor::value`] (JSON values), [`redact_url_secrets`] /
11//!   [`Redactor::url`] (URL strings), [`redact_argv`] / [`Redactor::argv`] (command lines) —
12//!   `Redactor` carries custom `secret_names`/`policy`
13//! - Output rendering: [`render`] — the single `value × format × options → String` entry point
14//!   for JSON, YAML, and plain (logfmt) output
15//! - Parse utilities: [`normalize_utc_offset`], [`is_valid_rfc3339_date`],
16//!   [`is_valid_rfc3339_time`], [`is_valid_rfc3339`], [`is_valid_bcp47`]
17//! - CLI helpers: [`cli_parse_output`], [`cli_parse_log_filters`] (returns [`LogFilters`]),
18//!   [`build_cli_error`], [`build_cli_version`], [`cli_render_version`]
19//! - (feature `cli` or `cli-help`): [`cli_handle_version_or_continue`] (needs a `&clap::Command`
20//!   to recognize the caller's own value-taking global flags)
21//! - (feature `cli-help`): configurable clap help rendering via [`cli_render_help_with_options`];
22//!   use [`cli_handle_version_or_help_or_continue`] as the preferred Rust entry point
23//!   for top-level version/help handling
24//! - (feature `cli-help-markdown`): [`cli_render_help_markdown`] — recursive Markdown help
25//! - (feature `skill`): [`skill::validate_skill`] / [`skill::validate_skill_named`] — strict
26//!   Agent Skills `SKILL.md` front-matter validation
27//! - (feature `skill-admin`): [`skill::run_skill_admin`] — install/uninstall/status a spore's
28//!   embedded Agent Skill across Codex, Claude Code, opencode, and Hermes; returns a typed
29//!   [`skill::SkillReport`]
30//! - (feature `tracing`): [`afdata_tracing::try_init`] initializes an AFDATA stdout logging
31//!   layer with configurable format and redaction; also [`afdata_tracing::LogFormat`]
32//!
33//! The shared cross-language contract (which of these exist, under what name, in each of
34//! Rust/Python/TypeScript/Go) is tracked in `spec/api-surface.json` and cross-checked by
35//! `scripts/validate_api_surface.py`.
36
37#[cfg(feature = "tracing")]
38pub mod afdata_tracing;
39
40#[cfg(feature = "stream-redirect")]
41pub mod stream_redirect;
42
43#[cfg(feature = "skill-admin")]
44#[path = "skill.rs"]
45mod skill_admin;
46
47#[cfg(feature = "skill")]
48#[path = "skill_validation.rs"]
49pub mod skill;
50
51/// Format-independent document values (dot-path access, typed coercion, and
52/// pluggable JSON/TOML/YAML/dotenv/INI backends).
53pub mod document;
54
55mod cli;
56mod formatting;
57#[cfg(feature = "cli-help")]
58mod help;
59mod protocol;
60mod redaction;
61mod validation;
62
63#[cfg(any(feature = "cli", feature = "cli-help"))]
64pub use cli::cli_handle_version_or_continue;
65pub use cli::{
66    CliEmitter, CliEmitterError, LogFilters, OutputFormat, OutputTo, build_cli_version,
67    cli_parse_log_filters, cli_parse_output, cli_render_version,
68};
69pub use formatting::render;
70#[cfg(feature = "cli-help-markdown")]
71pub use help::cli_render_help_markdown;
72#[cfg(feature = "cli-help")]
73pub use help::{
74    HelpConfig, HelpFormat, HelpOptions, HelpScope, cli_handle_help_or_continue,
75    cli_handle_version_or_help_or_continue, cli_render_help, cli_render_help_with_options,
76};
77pub use protocol::{
78    BuildError, DecodedError, DecodedEvent, DecodedLog, DecodedProgress, DecodedResult,
79    ErrorBuilder, Event, EventDecodeError, LogBuilder, LogLevel, ProgressBuilder,
80    ProtocolViolation, ResultBuilder, build_cli_error, decode_protocol_event, json_error, json_log,
81    json_progress, json_result, validate_protocol_event, validate_protocol_stream,
82};
83pub use redaction::{
84    OutputOptions, PlainStyle, RedactionPolicy, Redactor, redact_argv, redact_url_secrets,
85    redacted_value,
86};
87pub use validation::{
88    is_valid_bcp47, is_valid_rfc3339, is_valid_rfc3339_date, is_valid_rfc3339_time,
89    normalize_utc_offset,
90};
91
92#[cfg(test)]
93pub(crate) use formatting::{extract_currency_code, format_bytes_human, format_with_commas};
94
95#[cfg(test)]
96mod tests;
agent_first_data/lib.rs

agent_first_data/
lib.rs
