Crate kaish_tool_api 

Stable plugin API for kaish tools.

This leaf crate defines the contract that every kaish tool — builtin or third-party — implements, without pulling in kaish-kernel’s parser, interpreter, or async runtime internals. It exists so out-of-tree tool bundles (kaish-tools-host, kaish-tools-git, a hypothetical kaish-tools-perl) can be written against a small, audited surface.

The surface

• Tool — the trait every command implements. Its execute takes a &mut dyn ToolCtx, so the concrete kernel context never leaks into the public API.
• ToolCtx — the trimmed execution context. It exposes only what a well-behaved, portable tool needs (backend I/O, cwd, variable access, output format). Trusted in-tree builtins that need deeper kernel state (job control, pipes, the dispatcher) recover the concrete context via ToolCtx::as_any_mut — a documented escape hatch, not part of the portable contract.
• KernelBackend — the I/O + tool-dispatch backend a tool reaches through ctx.backend().
• GlobalFlags, schema_from_clap, validate_against_schema — the clap-reflection and validation machinery shared by all builtins.

The pure-data types tools traffic in (Value, ToolArgs, ToolSchema, ExecResult, OutputData, …) live one layer down in kaish-types.

Structs

ExecResult

The result of executing a command or pipeline.

GlobalFlags

Flags injected into every migrated builtin via #[command(flatten)] global: GlobalFlags.

OutputData

Structured output data from a command.

ParamSchema

Schema for a tool parameter.

PatientGuard

RAII guard returned by ToolCtx::patient.

Span

Source location span.

ToolArgs

Parsed arguments ready for tool execution.

ToolSchema

Schema describing a tool’s interface.

ValidationIssue

A validation issue found in the script.

Enums

IssueCode

Categorizes validation issues for filtering and tooling.

OutputFormat

Output serialization format, requested via global flags.

Severity

Severity level for validation issues.

Value

A literal value.

Traits

KernelBackend

Abstract backend interface for file operations and tool dispatch.

Tool

A tool that can be executed.

ToolCtx

The portable execution context a tool sees.

Functions

is_global_output_flag

Check if a flag name is the kernel-owned --json flag.

params_from_clap

Reflect each Arg in a clap Command into a ParamSchema.

schema_from_clap

Build a ToolSchema for a builtin from its clap Command reflection plus hand-written description and examples.

schema_tree_from_clap

Build a recursive ToolSchema from a composed clap Command tree.

validate_against_schema

Validate arguments against a tool schema.