oy/
lib.rs

1//! Library facade for the `oy` command-line application.
2//!
3//! `oy` is primarily a binary crate: install and run the [`oy` CLI][repo] to inspect,
4//! edit, audit, and ask questions about local repositories. The library surface is kept
5//! intentionally small for the binary, integration tests, and lightweight embedders that
6//! want to invoke the same command handlers.
7//!
8//! Most implementation modules are private so their internals can evolve without creating
9//! an API compatibility promise. If you need to automate `oy`, prefer spawning the `oy`
10//! binary and using its documented CLI unless one of the functions below exactly fits your
11//! use case.
12//!
13//! Useful project documentation:
14//!
15//! - [README](https://github.com/wagov-dtt/oy-cli#readme) for installation and user guide.
16//! - [Architecture](https://github.com/wagov-dtt/oy-cli/blob/main/docs/architecture.md)
17//!   for runtime flow, module responsibilities, and trust boundaries.
18//! - [Tool safety](https://github.com/wagov-dtt/oy-cli/blob/main/docs/tool-safety.md)
19//!   for capability and approval-mode details.
20//!
21//! [repo]: https://github.com/wagov-dtt/oy-cli
22
23#![recursion_limit = "256"]
24
25mod agent;
26mod audit;
27mod cli;
28mod tools;
29
30pub(crate) use agent::{bedrock, compaction, model, session};
31pub(crate) use cli::{app, chat, config, ui};
32
33pub use ui::{OutputMode, set_output_mode};
34
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub(crate) enum TextDecodeError {
37    Binary,
38    NonUtf8,
39}
40
41pub(crate) fn decode_utf8(raw: Vec<u8>) -> Result<String, TextDecodeError> {
42    if raw.contains(&0) {
43        return Err(TextDecodeError::Binary);
44    }
45    String::from_utf8(raw).map_err(|_| TextDecodeError::NonUtf8)
46}
47
48/// Runs the `oy` command dispatcher with command-line arguments excluding the program name.
49///
50/// This is the same application entry point used by the binary after `src/main.rs` strips
51/// the executable name. It returns the process exit code that the binary should use.
52///
53/// Prefer invoking the `oy` binary for automation unless embedding the CLI in-process is
54/// specifically needed.
55pub async fn run(argv: Vec<String>) -> anyhow::Result<i32> {
56    app::run(argv).await
57}
58
59/// Returns the interactive chat help text shown by `/help`.
60///
61/// This helper is public so snapshot tests and lightweight integrations can verify or
62/// display the same help content as the interactive shell.
63pub fn chat_help_text() -> String {
64    chat::chat_help_text()
65}
66
67/// Formats a tool result using the same compact preview renderer as the CLI.
68///
69/// `name` is the tool name, and `value` is the JSON result payload returned by that tool.
70/// The output is intended for humans and may change with CLI presentation improvements;
71/// do not treat it as a stable machine-readable format.
72pub fn preview_tool_output(name: &str, value: &serde_json::Value) -> String {
73    tools::preview_tool_output(name, value)
74}
75
76/// Writes a formatted diagnostic line to standard error using the current UI output mode.
77///
78/// Use [`format_args!`] to avoid allocating an intermediate `String`:
79///
80/// ```no_run
81/// oy::err_line(format_args!("provider failed: {}", "timeout"));
82/// ```
83pub fn err_line(args: std::fmt::Arguments<'_>) {
84    ui::err_line(args);
85}
oy/lib.rs

oy/
lib.rs
