secretumvault/.typedialog/ci/README.md

# CI System - Configuration Guide

**Installed**: 2025-12-28
**Detected Languages**: rust, nickel, bash, markdown

---

## Quick Start

### Option 1: Using configure.sh (Recommended)

A convenience script is installed in `.typedialog/ci/`:

```bash
# Use web backend (default) - Opens in browser
.typedialog/ci/configure.sh

# Use TUI backend - Terminal interface
.typedialog/ci/configure.sh tui

# Use CLI backend - Command-line prompts
.typedialog/ci/configure.sh cli
```

**This script automatically:**
- Sources `.typedialog/ci/envrc` for environment setup
- Loads defaults from `config.ncl` (Nickel format)
- Uses cascading search for fragments (local → Tools)
- Creates backup before overwriting existing config
- Saves output in Nickel format using nickel-roundtrip with documented template
- Generates `config.ncl` compatible with `nickel doc` command

### Option 2: Direct TypeDialog Commands

Use TypeDialog nickel-roundtrip directly with manual paths:

#### Web Backend (Recommended - Easy Viewing)

```bash
cd .typedialog/ci  # Change to CI directory
source envrc  # Load environment
typedialog-web nickel-roundtrip config.ncl form.toml \
  --output config.ncl \
  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2
```

#### TUI Backend

```bash
cd .typedialog/ci
source envrc
typedialog-tui nickel-roundtrip config.ncl form.toml \
  --output config.ncl \
  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2
```

#### CLI Backend

```bash
cd .typedialog/ci
source envrc
typedialog nickel-roundtrip config.ncl form.toml \
  --output config.ncl \
  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2
```

**Note:** The `--ncl-template` flag uses a Tera template that adds:
- Descriptive comments for each section
- Documentation compatible with `nickel doc config.ncl`
- Consistent formatting and structure

**All backends will:**
- Show only options relevant to your detected languages
- Guide you through all configuration choices
- Validate your inputs
- Generate config.ncl in Nickel format

### Option 3: Manual Configuration

Edit `config.ncl` directly:

```bash
vim .typedialog/ci/config.ncl
```

---

## Configuration Format: Nickel

**This project uses Nickel format by default** for all configuration files.

### Why Nickel?

- ✅ **Typed configuration** - Static type checking with `nickel typecheck`
- ✅ **Documentation** - Generate docs with `nickel doc config.ncl`
- ✅ **Validation** - Built-in schema validation
- ✅ **Comments** - Rich inline documentation support
- ✅ **Modular** - Import/export system for reusable configs

### Nickel Template

The output structure is controlled by a **Tera template** at:
- **Tools default**: `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2`
- **Local override**: `.typedialog/ci/config.ncl.j2` (optional)

**To customize the template:**

```bash
# Copy the default template
cp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \
   .typedialog/ci/config.ncl.j2

# Edit to add custom comments, documentation, or structure
vim .typedialog/ci/config.ncl.j2

# Your template will now be used automatically
```

**Template features:**
- Customizable comments per section
- Control field ordering
- Add project-specific documentation
- Configure output for `nickel doc` command

### TypeDialog Environment Variables

You can customize TypeDialog behavior with environment variables:

```bash
# Web server configuration
export TYPEDIALOG_PORT=9000           # Port for web backend (default: 9000)
export TYPEDIALOG_HOST=localhost      # Host binding (default: localhost)

# Localization
export TYPEDIALOG_LANG=en_US.UTF-8    # Form language (default: system locale)

# Run with custom settings
TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web
```

**Common use cases:**

```bash
# Access from other machines in network
TYPEDIALOG_HOST=0.0.0.0 TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web

# Use different port if 9000 is busy
TYPEDIALOG_PORT=3000 .typedialog/ci/configure.sh web

# Spanish interface
TYPEDIALOG_LANG=es_ES.UTF-8 .typedialog/ci/configure.sh web
```

## Configuration Structure

Your config.ncl is organized in the `ci` namespace (Nickel format):

```nickel
{
  ci = {
    project = {
      name = "rust",
      detected_languages = ["rust, nickel, bash, markdown"],
      primary_language = "rust",
    },
    tools = {
      # Tools are added based on detected languages
    },
    features = {
      # CI features (pre-commit, GitHub Actions, etc.)
    },
    ci_providers = {
      # CI provider configurations
    },
  },
}
```

## Available Fragments

Tool configurations are modular. Check `.typedialog/ci/fragments/` for:

- rust-tools.toml - Tools for rust
- nickel-tools.toml - Tools for nickel
- bash-tools.toml - Tools for bash
- markdown-tools.toml - Tools for markdown
- general-tools.toml - Cross-language tools
- ci-providers.toml - GitHub Actions, Woodpecker, etc.

## Cascading Override System

This project uses a **local → Tools cascading search** for all resources:

### How It Works

Resources are searched in priority order:

1. **Local files** (`.typedialog/ci/`) - **FIRST** (highest priority)
2. **Tools files** (`$TOOLS_PATH/dev-system/ci/`) - **FALLBACK** (default)

### Affected Resources

| Resource | Local Path | Tools Path |
|----------|------------|------------|
| Fragments | `.typedialog/ci/fragments/` | `$TOOLS_PATH/dev-system/ci/forms/fragments/` |
| Schemas | `.typedialog/ci/schemas/` | `$TOOLS_PATH/dev-system/ci/schemas/` |
| Validators | `.typedialog/ci/validators/` | `$TOOLS_PATH/dev-system/ci/validators/` |
| Defaults | `.typedialog/ci/defaults/` | `$TOOLS_PATH/dev-system/ci/defaults/` |
| Nickel Template | `.typedialog/ci/config.ncl.j2` | `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2` |

### Environment Setup (.envrc)

The `.typedialog/ci/.envrc` file configures search paths:

```bash
# Source this file to load environment
source .typedialog/ci/.envrc

# Or use direnv for automatic loading
echo 'source .typedialog/ci/.envrc' >> .envrc
```

**What's in .envrc:**

```bash
export NICKEL_IMPORT_PATH="schemas:$TOOLS_PATH/dev-system/ci/schemas:validators:..."
export TYPEDIALOG_FRAGMENT_PATH=".:$TOOLS_PATH/dev-system/ci/forms"
export NCL_TEMPLATE="<local or Tools path to config.ncl.j2>"
export TYPEDIALOG_PORT=9000           # Web server port
export TYPEDIALOG_HOST=localhost      # Web server host
export TYPEDIALOG_LANG="${LANG}"       # Form localization
```

### Creating Overrides

**By default:** All resources come from Tools (no duplication).

**To customize:** Create file in local directory with same name:

```bash
# Override a fragment
cp $TOOLS_PATH/dev-system/ci/fragments/rust-tools.toml \
   .typedialog/ci/fragments/rust-tools.toml

# Edit your local version
vim .typedialog/ci/fragments/rust-tools.toml

# Override Nickel template (customize comments, structure, nickel doc output)
cp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \
   .typedialog/ci/config.ncl.j2

# Edit to customize documentation and structure
vim .typedialog/ci/config.ncl.j2

# Now your version will be used instead of Tools version
```

**Benefits:**

- ✅ Override only what you need
- ✅ Everything else stays synchronized with Tools
- ✅ No duplication by default
- ✅ Automatic updates when Tools is updated

**See:** `$TOOLS_PATH/dev-system/ci/docs/cascade-override.md` for complete documentation.

## Testing Your Configuration

### Validate Configuration

```bash
nu $env.TOOLS_PATH/dev-system/ci/scripts/validator.nu \
  --config .typedialog/ci/config.ncl \
  --project . \
  --namespace ci
```

### Regenerate CI Files

```bash
nu $env.TOOLS_PATH/dev-system/ci/scripts/generate-configs.nu \
  --config .typedialog/ci/config.ncl \
  --templates $env.TOOLS_PATH/dev-system/ci/templates \
  --output . \
  --namespace ci
```

## Common Tasks

### Add a New Tool

Edit `config.ncl` and add under `ci.tools`:

```nickel
{
  ci = {
    tools = {
      newtool = {
        enabled = true,
        install_method = "cargo",
        version = "latest",
      },
    },
  },
}
```

### Disable a Feature

```toml
[ci.features]
enable_pre_commit = false
```

## Need Help?

For detailed documentation, see:
- $env.TOOLS_PATH/dev-system/ci/docs/configuration-guide.md
- $env.TOOLS_PATH/dev-system/ci/docs/installation-guide.md