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//! - Closed-world CLI compiler: [`CliSpec`], [`CommandSpec`], [`ArgSpec`],
18//!   [`Combination`], and [`OutputSpec`] generate parsing, typed
19//!   [`ResolvedInvocation`] values, output plans, and help-v2 from one registry.
20//! - Established CLI utilities: [`cli_parse_output`], [`cli_parse_log_filters`]
21//!   (returns [`LogFilters`]), and [`CliEmitter`].
22//! - (feature `skill`): [`skill::validate_skill`] / [`skill::validate_skill_named`] — strict
23//!   Agent Skills `SKILL.md` front-matter validation
24//! - (feature `skill-admin`): [`skill::run_skill_admin`] — install/uninstall/status a spore's
25//!   embedded Agent Skill across Codex, Claude Code, opencode, and Hermes; returns a typed
26//!   [`skill::SkillReport`]
27//! - (feature `tracing`): [`afdata_tracing::try_init`] initializes an AFDATA stderr logging
28//!   layer with configurable format and redaction; also [`afdata_tracing::LogFormat`]
29//!
30//! The shared cross-language contract (which of these exist, under what name, in each of
31//! Rust/Python/TypeScript/Go) is tracked in `spec/api-surface.json` and cross-checked by
32//! `scripts/validate_api_surface.py`.
33
34#[cfg(feature = "tracing")]
35pub mod afdata_tracing;
36
37#[cfg(feature = "stream-redirect")]
38pub mod stream_redirect;
39
40#[cfg(feature = "skill-admin")]
41#[path = "skill.rs"]
42mod skill_admin;
43
44#[cfg(feature = "skill")]
45#[path = "skill_validation.rs"]
46pub mod skill;
47
48/// Format-independent document values (dot-path access, typed coercion, and
49/// pluggable JSON/TOML/YAML/dotenv/INI backends, plus a read-only Markdown
50/// block reader).
51pub mod document;
52
53// The closed-world CLI compiler: spec types, build gates, argv resolution, and
54// the help-v2 model. Nothing else in this crate may reference it — only the
55// adapter below does — which `cargo build --no-default-features` proves.
56#[cfg(feature = "cli")]
57mod cli_spec;
58
59// The AFDATA CLI surface: output format parsing, the emitter, and version
60// payloads.
61#[cfg(feature = "cli")]
62mod cli;
63
64// The one place the compiler and AFDATA meet.
65#[cfg(feature = "cli")]
66mod cli_afdata;
67
68mod formatting;
69mod protocol;
70mod redaction;
71mod validation;
72
73#[cfg(feature = "cli")]
74pub use cli::{
75    CliEmitter, CliEmitterError, LogFilters, OutputTo, build_cli_version, cli_parse_log_filters,
76    cli_parse_output, cli_render_version, write_raw,
77};
78#[cfg(feature = "cli")]
79pub use cli_afdata::{
80    build_afdata_cli, cli_error_event, cli_help_event, cli_version_event, render_cli_reference,
81};
82#[cfg(feature = "cli")]
83pub use cli_spec::{
84    ArgSpec, ArgSyntax, ArgValueType, BoundCliSpec, BuiltCliSpec, CliError, CliErrorRule,
85    CliHelpV2, CliOutcome, CliShape, CliSpec, CliSpecError, CliValue, Combination, CommandSpec,
86    FixedValue, OutputLifecycle, OutputPlan, OutputSpec, ResolvedDocs, ResolvedHelp,
87    ResolvedInvocation, ResolvedVersion, SyntheticInvocation,
88};
89pub use formatting::{OutputFormat, render};
90pub use protocol::{
91    BuildError, DecodedError, DecodedEvent, DecodedLog, DecodedProgress, DecodedResult,
92    ErrorBuilder, Event, EventDecodeError, LogBuilder, LogLevel, ProgressBuilder,
93    ProtocolViolation, ResultBuilder, build_cli_error, decode_protocol_event, json_error, json_log,
94    json_progress, json_result, validate_protocol_event, validate_protocol_stream,
95};
96pub use redaction::{
97    OutputOptions, PlainStyle, RedactionPolicy, Redactor, redact_argv, redact_url_secrets,
98    redacted_value,
99};
100pub use validation::{
101    is_valid_bcp47, is_valid_rfc3339, is_valid_rfc3339_date, is_valid_rfc3339_time,
102    normalize_utc_offset,
103};
104
105#[cfg(test)]
106pub(crate) use formatting::{extract_currency_code, format_bytes_human, format_with_commas};
107
108#[cfg(test)]
109mod tests;
agent_first_data/lib.rs

agent_first_data/
lib.rs
