# crow-config-docs

> Technical documentation and reference portal for `crow-config`, the standalone, lossless Linux configuration engine powering [Crow](https://github.com/errorware/crow).

This repository contains both the source documentation in Markdown (`docs/`) and the static documentation website styled with the [Obsidian Edge](https://github.com/errorware/obsidian-edge) design system for deployment on Cloudflare Pages at [crow-config.errorware.net](https://crow-config.errorware.net).

---

## What is `crow-config`?

`crow-config` (implemented across `crow-config-core` and `crow-config-schemas`) is a standalone Rust engine that transforms arbitrary line- and block-oriented Linux configuration formats (`/etc/hosts`, `sshd_config`, `pg_hba.conf`, `ufw.rules`, etc.) into structured, typed, round-trippable Intermediate Representations (IR).

UI clients and CLI management tools can inspect, validate, and edit critical server configuration files generically — **without writing format-specific UI rendering code or risking destructive serialization artifacts**.

```
                           ┌───────────────────────────┐
                           │   Raw Server Config File  │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │   Lossless CST Parser     │
                           │   (Trivia & Token Spans)  │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │   Semantic Schema Binder  │
                           │   (TOML Plugin Manifests) │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │    View-Binding IR (JSON) │
                           │  (Widgets, Spans & Risks) │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │  UI / Operator Mutation   │
                           │     (EditOp Dispatch)     │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │  Surgical CST In-Place    │
                           │  Token Replacement       │
                           └─────────────┬─────────────┘
                                         │
                                         ▼
                           ┌───────────────────────────┐
                           │ Byte-Identical Serializer │
                           └───────────────────────────┘
```

---

## Core Guarantees

1. **100% Lossless Concrete Syntax Tree (CST)**: Every whitespace token, inline comment, trailing blank line, and formatting quirk is preserved. Serializing an unedited document outputs the exact original input byte-for-byte.
2. **Surgical In-Place Edits**: Mutating a field or directive changes only the targeted tokens. Surrounding whitespace, alignment tabs, comments, and adjacent lines remain completely untouched.
3. **Panic-Free & Resilient**: Malformed syntax, unexpected directives, or corrupted files never trigger a panic; anomalies are captured into structured `Error` CST nodes and round-tripped without data loss.
4. **Semantic Schemas & Security Risk Metadata**: TOML plugin manifests define field types, validation rules, man-page documentation anchors, and risk ratings (`recommended`, `caution`, `weak`, `never_on_prod`) for high-consequence settings.
5. **View-Binding Intermediate Representation (IR)**: Emits a generic IR (`rule_table`, `key_value_list`, `block_tree`, `toggle_panel`) that native UI engines (like Crow's `gpui` interface) render directly.
6. **Order-Sensitive Mutation**: Provides atomic row reordering (`MoveRow` before/after) critical for first-match-wins formats such as `pg_hba.conf` and UFW firewall rule tables.

---

## Documentation Index

### Architecture & Engine Internals
- [Three-Layer Architecture](docs/architecture.md) — CST grammar, schema binding, and View-Binding IR.
- [Lossless CST Engine](docs/cst-engine.md) — Node hierarchy, trivia preservation, spans, and panic-free parsing.
- [Semantic Schema Manifests](docs/schema-manifests.md) — TOML manifest specifications, field types, risk levels, and external validators.
- [View-Binding IR Specification](docs/view-binding-ir.md) — JSON schema, widget kinds, row models, and UI contracts.
- [Mutation & In-Place Editing API](docs/mutation-api.md) — `ConfigDocument`, `EditOp` variants, and surgical token replacement.

### Format Plugins Reference
- [`/etc/hosts` Plugin](docs/plugins/hosts.md) — Host resolution table, line grammar, and hostname mutation.
- [`sshd_config` Plugin](docs/plugins/sshd.md) — OpenSSH daemon configuration, directive ordering, and security risk ratings.
- [`pg_hba.conf` Plugin](docs/plugins/pg-hba.md) — PostgreSQL client authentication rule table and first-match order reordering.
- [`ufw.rules` Plugin](docs/plugins/ufw.md) — Uncomplicated Firewall rule table, actions, and packet filters.

### Guides & Development
- [Authoring New Format Plugins](docs/authoring-plugins.md) — Step-by-step guide to adding support for new Linux configuration files.
- [Testing & Verification](docs/testing-and-verification.md) — Unit tests, golden file round-trips, and `proptest` invariant fuzzing.

---

## Quick Example

```rust
use crow_config_core::edit::{ConfigDocument, EditOp};
use crow_config_schemas::HostsPlugin;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hosts_content = "127.0.0.1\tlocalhost\n10.0.4.12\tdb-01\t# primary postgres\n";
    let plugin = HostsPlugin::new();

    // 1. Parse into an active in-memory document
    let mut doc = ConfigDocument::parse(&plugin, hosts_content)?;

    // 2. Generate generic View-Binding IR for the UI
    let ir = doc.to_ir()?;
    println!("Plugin: {}", ir.plugin_name);
    println!("Shape: {:?}", ir.shape.kind);

    // 3. Apply a surgical in-place field edit
    doc.apply_edit(&EditOp::UpdateField {
        row_id: "line-2".to_string(),
        field_name: "address".to_string(),
        new_value: serde_json::json!("10.0.4.13"),
    })?;

    // 4. Serialize back — only the modified IP token changes!
    let updated = doc.serialize();
    assert_eq!(
        updated,
        "127.0.0.1\tlocalhost\n10.0.4.13\tdb-01\t# primary postgres\n"
    );

    Ok(())
}
```

---

## Design System & Cloudflare Pages

This site is styled with **Obsidian Edge**, Crow's native operator visual system:
- **Zero radius** across all surfaces, panels, controls, and tables.
- **1px hairline borders** (`--border-default`, `--border-panel`, `--border-row`).
- **Monochrome near-black palette** with color reserved exclusively for signals (`--ok`, `--warn`, `--crit`).
- **JetBrains Mono** for all technical entities, code, IP addresses, and identifiers; **Inter** for prose and section headers.

To view the live documentation, visit [crow-config.errorware.net](https://crow-config.errorware.net) or open `index.html` locally.

---

## License

This documentation and `crow-config` are licensed under the [AEUPL-1.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12) (Ancient European Union Public License v1.2).