# CI System - Configuration Guide

**Installed**: 2026-01-01
**Detected Languages**: rust, nushell, nickel, bash, markdown, python, javascript

---

## Quick Start

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

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

```toml
# 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)

```toml
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

```toml
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

```toml
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:

```nickel
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:**

```toml
# 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:

```toml
# 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:**

```toml
# 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):

```json
{
  ci = {
    project = {
      name = "rust",
      detected_languages = ["rust, nushell, nickel, bash, markdown, python, javascript"],
      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
- nushell-tools.toml - Tools for nushell
- nickel-tools.toml - Tools for nickel
- bash-tools.toml - Tools for bash
- markdown-tools.toml - Tools for markdown
- python-tools.toml - Tools for python
- javascript-tools.toml - Tools for javascript
- 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:

```toml
# 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:**

```javascript
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:

```toml
# 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

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

### Regenerate CI Files

```toml
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`:

```json
{
  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
