// SPDX-License-Identifier: CC-BY-SA-4.0
= K9 Tools
:toc: preamble
:toclevels: 2
:icons: font

Essential tooling for K9 contractile development and adoption.

== Overview

K9 Tools provides everything you need to create, validate, sign, and deploy K9 contractiles:

* **k9-init** - Scaffold new K9 configs from templates
* **k9-validate** - Standalone validator (without just/must dependencies)
* **k9-sign** - Simplified signing workflow with Ed25519
* **GitHub Action** - Validate K9 contractiles in CI
* **VS Code Extension** - Syntax highlighting + validation
* **Template Library** - Common use cases (web server, build, deploy, etc.)

== Installation

=== From Source

[source,bash]
----
git clone https://github.com/hyperpolymath/k9-tools.git
cd k9-tools

# Install all tools
make install

# Or install individually
make install-k9-init
make install-k9-validate
make install-k9-sign
----

=== Package Managers

[source,bash]
----
# Cargo (Rust)
cargo install k9-tools

# npm (JavaScript)
npm install -g @hyperpolymath/k9-tools

# Homebrew (macOS/Linux)
brew install hyperpolymath/tap/k9-tools
----

== Quick Start

=== Initialize a New K9 Contractile

[source,bash]
----
# Interactive mode
k9-init

# From template
k9-init --template web-server

# With options
k9-init --name my-app --security-level yard
----

=== Validate a K9 Contractile

[source,bash]
----
# Validate single file
k9-validate setup.k9.ncl

# Validate directory
k9-validate .

# With strict mode
k9-validate --strict setup.k9.ncl
----

=== Sign a K9 Contractile

[source,bash]
----
# Generate keypair (first time)
k9-sign keygen

# Sign contractile
k9-sign sign setup.k9.ncl

# Verify signature
k9-sign verify setup.k9.ncl
----

== Tools

=== k9-init

Scaffold new K9 contractiles from templates.

**Features:**
- Interactive prompt for configuration
- Pre-built templates for common use cases
- Security level selection (kennel/yard/hunt)
- Automatic must/just/nickel generation

**Usage:**
[source,bash]
----
k9-init [OPTIONS]

Options:
  --template <name>    Use template (web-server, build, deploy, etc.)
  --name <name>        Contractile name
  --security <level>   Security level (kennel, yard, hunt)
  --output <path>      Output directory
  --interactive        Interactive mode (default)
----

**Templates Available:**
- `web-server` - Deploy web server (nginx, caddy, Apache)
- `build` - Build automation (Rust, Node, Go, etc.)
- `deploy` - Deployment workflow (Docker, k8s, etc.)
- `dev-env` - Development environment setup
- `ci-cd` - CI/CD pipeline
- `backup` - Backup and restore
- `monitoring` - Monitoring setup (Prometheus, Grafana)
- `minimal` - Minimal K9 contractile

=== k9-validate

Standalone validator for K9 contractiles.

**Features:**
- Schema validation (must-just-nickel structure)
- Security level checking
- Signature verification (optional)
- No runtime dependencies (just/must not required)

**Usage:**
[source,bash]
----
k9-validate [OPTIONS] <file>

Options:
  --strict             Strict validation (fail on warnings)
  --check-signatures   Verify cryptographic signatures
  --schema <path>      Custom schema file
  --format <json|text> Output format
----

**Exit Codes:**
- `0` - Valid K9 contractile
- `1` - Validation errors
- `2` - Schema errors
- `3` - File not found

=== k9-sign

Simplified signing workflow for K9 contractiles.

**Features:**
- Ed25519 keypair generation
- Sign contractiles with metadata
- Verify signatures
- Key management (import/export)

**Usage:**
[source,bash]
----
k9-sign <command> [OPTIONS]

Commands:
  keygen              Generate new Ed25519 keypair
  sign <file>         Sign contractile
  verify <file>       Verify signature
  import <key>        Import private key
  export <key>        Export public key

Options:
  --key-file <path>   Key file location (default: ~/.k9/keys/)
  --output <path>     Output file for signed contractile
----

**Key Storage:**
- Private keys: `~/.k9/keys/private.key` (encrypted)
- Public keys: `~/.k9/keys/public.key`
- Signatures: Embedded in contractile metadata

=== GitHub Action

Validate K9 contractiles in CI/CD pipelines.

**Usage:**
[source,yaml]
----
name: Validate K9 Contractiles

on:
  push:
    paths:
      - '**.k9.ncl'
  pull_request:
    paths:
      - '**.k9.ncl'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate K9 Contractiles
        uses: hyperpolymath/validate-k9@v1
        with:
          path: '.'
          strict: true
          check-signatures: false
----

**Inputs:**
- `path` - Directory or file to validate (default: `.`)
- `strict` - Enable strict validation (default: `false`)
- `check-signatures` - Verify signatures (default: `false`)
- `fail-on-warnings` - Fail on warnings (default: `false`)

=== VS Code Extension

Syntax highlighting and validation for K9 contractiles.

**Features:**
- Syntax highlighting for `.k9.ncl` files
- Real-time validation
- Auto-completion for directives
- Hover documentation
- Signature verification indicators

**Installation:**
[source,bash]
----
# From VS Code Marketplace
code --install-extension hyperpolymath.k9-tools

# Or via Extensions panel
# Search: "K9 Tools"
----

**Features:**
- Language server protocol (LSP) integration
- Diagnostics (errors, warnings)
- Quick fixes for common issues
- Snippet library for common patterns

== Template Library

Pre-built templates for common K9 use cases.

=== Available Templates

==== web-server

Deploy and configure web servers.

**Variants:**
- `nginx` - nginx web server
- `caddy` - Caddy web server (automatic HTTPS)
- `apache` - Apache HTTP Server

**Example:**
[source,bash]
----
k9-init --template web-server/nginx
----

==== build

Build automation for various languages.

**Variants:**
- `rust` - Rust project (cargo)
- `node` - Node.js project (npm/pnpm)
- `go` - Go project
- `python` - Python project (poetry)

**Example:**
[source,bash]
----
k9-init --template build/rust
----

==== deploy

Deployment workflows.

**Variants:**
- `docker` - Docker deployment
- `kubernetes` - Kubernetes deployment
- `terraform` - Terraform infrastructure

**Example:**
[source,bash]
----
k9-init --template deploy/docker
----

==== dev-env

Development environment setup.

**Variants:**
- `minimal` - Minimal dev tools
- `full-stack` - Full-stack web development
- `data-science` - Data science environment

**Example:**
[source,bash]
----
k9-init --template dev-env/full-stack
----

== Development

=== Building from Source

[source,bash]
----
# Clone repository
git clone https://github.com/hyperpolymath/k9-tools.git
cd k9-tools

# Build all tools
make build

# Run tests
make test

# Install locally
make install
----

=== Project Structure

[source]
----
k9-tools/
├── src/
│   ├── k9-init/          # Scaffolding tool
│   ├── k9-validate/      # Validator
│   └── k9-sign/          # Signing tool
├── templates/            # Template library
│   ├── web-server/
│   ├── build/
│   ├── deploy/
│   └── dev-env/
├── github-action/        # GitHub Action
├── vscode-extension/     # VS Code extension
└── docs/                 # Documentation

----

=== Contributing

See link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for guidelines.

== Documentation

- **Getting Started**: link:docs/GETTING-STARTED.adoc[Getting Started Guide]
- **Template Guide**: link:docs/TEMPLATES.adoc[Template Guide]
- **API Reference**: link:docs/API.adoc[API Reference]
- **Examples**: link:examples/[examples/]

== License

PMPL-1.0-or-later. See link:LICENSE[LICENSE].

== Related Projects

- **k9-svc**: https://github.com/hyperpolymath/standards/tree/main/k9-svc
- **rsr-template-repo**: https://github.com/hyperpolymath/rsr-template-repo
- **Nickel**: https://nickel-lang.org

== Support

- **Issues**: https://github.com/hyperpolymath/k9-tools/issues
- **Discussions**: https://github.com/hyperpolymath/k9-tools/discussions
- **Email**: j.d.a.jewell@open.ac.uk

---

**Created:** 2026-01-30
**Author:** Jonathan D.A. Jewell
**Co-Authored-By:** Claude Sonnet 4.5
