kaish_tool_api/
lib.rs

1//! Stable plugin API for kaish tools.
2//!
3//! This leaf crate defines the contract that every kaish tool — builtin or
4//! third-party — implements, without pulling in `kaish-kernel`'s parser,
5//! interpreter, or async runtime internals. It exists so out-of-tree tool
6//! bundles (`kaish-tools-host`, `kaish-tools-git`, a hypothetical
7//! `kaish-tools-perl`) can be written against a small, audited surface.
8//!
9//! # The surface
10//!
11//! - [`Tool`] — the trait every command implements. Its `execute` takes a
12//!   `&mut dyn ToolCtx`, so the concrete kernel context never leaks into the
13//!   public API.
14//! - [`ToolCtx`] — the **trimmed** execution context. It exposes only what a
15//!   well-behaved, portable tool needs (backend I/O, cwd, variable access,
16//!   output format). Trusted in-tree builtins that need deeper kernel state
17//!   (job control, pipes, the dispatcher) recover the concrete context via
18//!   [`ToolCtx::as_any_mut`] — a documented escape hatch, not part of the
19//!   portable contract.
20//! - [`KernelBackend`] — the I/O + tool-dispatch backend a tool reaches
21//!   through `ctx.backend()`.
22//! - [`GlobalFlags`], [`schema_from_clap`], [`validate_against_schema`] — the
23//!   clap-reflection and validation machinery shared by all builtins.
24//!
25//! The pure-data types tools traffic in (`Value`, `ToolArgs`, `ToolSchema`,
26//! `ExecResult`, `OutputData`, …) live one layer down in `kaish-types`.
27
28mod backend;
29mod clap_schema;
30mod ctx;
31mod global_flags;
32mod issue;
33mod tool;
34
35pub use backend::KernelBackend;
36pub use clap_schema::{params_from_clap, schema_from_clap, schema_tree_from_clap};
37pub use ctx::{PatientGuard, ToolCtx};
38pub use global_flags::GlobalFlags;
39pub use issue::{IssueCode, Severity, Span, ValidationIssue};
40pub use tool::{is_global_output_flag, validate_against_schema, Tool};
41
42// Re-export the data types tool authors need most often, so a tool crate can
43// depend on just `kaish-tool-api` for the common case.
44pub use kaish_types::{
45    ExecResult, OutputData, OutputFormat, ParamSchema, ToolArgs, ToolSchema, Value,
46};
kaish_tool_api/lib.rs

kaish_tool_api/
lib.rs
