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/:

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

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

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

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:

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:

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

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

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

{
  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:

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

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:

# 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

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

Regenerate CI Files

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:

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

Disable a Feature

[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