# LCCP Rust API

This document is the Rust-facing API specification for the `lccp` crate.

It complements the general LCCP specification by defining how Rust applications are expected to configure and consume the library.

## Core Model

The library has two responsibilities:

- resolve configuration according to the LCCP precedence rules
- parse the full application command line, including application-specific flags, positionals, subcommands, and help text

Applications should not layer a second command-line parser on top of `lccp`.

## Configuration Discovery

Level 4 user configuration is discovered from the application-owned hidden directory in the user home directory:

- `~/.<app_name>/config.json`
- `~/.<app_name>/config.toml`

This directory may also contain other application-specific files beyond configuration.

## Primary Types

### `Resolver`

`Resolver` is the main entry point.

Applications construct it with:

- `app_name`
- `executable_path`

The resolver owns:

- the LCCP configuration schema
- default configuration values
- the application command model

Key methods:

- `Resolver::new`
- `declare_option`
- `set_default`
- `command_mut`
- `resolve`
- `resolve_with`
- `emit_default_config`
- `render_help`
- `render_help_for`

### `OptionSpec`

`OptionSpec` declares an LCCP-managed configuration key that can be:

- loaded from files
- read from environment variables
- overridden with `--set`
- overridden by explicit named flags

`OptionSpec` supports:

- typed values
- repeated CLI values for array-like explicit flags
- help text
- value display names for help output

### `CommandSpec`

`CommandSpec` declares application-specific CLI structure.

Each command can define:

- named options via `CliOptionSpec`
- positional arguments via `PositionalSpec`
- nested subcommands via `CommandSpec`
- help text

The root command is stored inside the resolver and is mutated through `command_mut()`.

### `CliOptionSpec`

`CliOptionSpec` declares an application-defined long option handled by `lccp`.

Supported behaviors:

- scalar typed values
- repeated values
- required options
- help text
- custom value names

### `PositionalSpec`

`PositionalSpec` declares an application-defined positional argument handled by `lccp`.

Supported behaviors:

- typed values
- required or optional positionals
- variadic trailing positional values
- help text

### `ResolvedConfig`

`ResolvedConfig` is the result of parsing and resolution.

It exposes:

- resolved configuration values
- per-key provenance
- warnings
- standard inspection flags
- parsed application command matches
- TOML emission
- debug output

### `CommandMatches`

`CommandMatches` is the parsed application command result tree.

It exposes:

- the current command name
- parsed named options
- parsed positional values
- an optional nested subcommand match
- whether help was requested
- the command path for help requests

## Parsing Contract

One `resolve` call parses the entire argv.

The parser handles, in a single pass model:

1. LCCP standard flags
2. LCCP configuration flags
3. application-defined options
4. application-defined positionals
5. subcommands

Applications are expected to configure the command model up front and then call `resolve` or `resolve_with`.

## Help Contract

Help text is generated by `lccp`.

Help output includes:

- standard LCCP flags
- declared LCCP configuration flags
- application-defined command options
- application-defined positionals
- application-defined subcommands

Applications should supply help text on specs rather than rendering separate help manually.

## Value Model

All typed values use the crate `ValueType` enum:

- `String`
- `Integer`
- `Float`
- `Boolean`
- `Array(Box<ValueType>)`

Resolved values and parsed command matches are represented as `serde_json::Value`.

## Error Contract

The crate returns deterministic errors for:

- malformed configuration files
- invalid `--set` syntax
- unknown flags
- unknown command paths
- missing required command options
- missing required positional arguments
- unexpected extra positionals
- type conversion failures

## Recommended Application Pattern

1. Construct `Resolver`.
2. Declare all LCCP configuration options with `OptionSpec`.
3. Register default values.
4. Configure the root command and subcommands with `CommandSpec`, `CliOptionSpec`, and `PositionalSpec`.
5. Call `resolve` once.
6. Read both resolved config and parsed command matches from the result.
