CI System - Configuration Guide\n\nInstalled: 2026-01-01\nDetected Languages: rust, nushell, nickel, bash, markdown, python, javascript\n\n---\n\n## Quick Start\n\n### Option 1: Using configure.sh (Recommended)\n\nA convenience script is installed in .typedialog/ci/:\n\n\n# Use web backend (default) - Opens in browser\n.typedialog/ci/configure.sh\n\n# Use TUI backend - Terminal interface\n.typedialog/ci/configure.sh tui\n\n# Use CLI backend - Command-line prompts\n.typedialog/ci/configure.sh cli\n\n\nThis script automatically:\n\n- Sources .typedialog/ci/envrc for environment setup\n- Loads defaults from config.ncl (Nickel format)\n- Uses cascading search for fragments (local → Tools)\n- Creates backup before overwriting existing config\n- Saves output in Nickel format using nickel-roundtrip with documented template\n- Generates config.ncl compatible with nickel doc command\n\n### Option 2: Direct TypeDialog Commands\n\nUse TypeDialog nickel-roundtrip directly with manual paths:\n\n#### Web Backend (Recommended - Easy Viewing)\n\n\ncd .typedialog/ci # Change to CI directory\nsource envrc # Load environment\ntypedialog-web nickel-roundtrip config.ncl form.toml \\n --output config.ncl \\n --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n\n\n#### TUI Backend\n\n\ncd .typedialog/ci\nsource envrc\ntypedialog-tui nickel-roundtrip config.ncl form.toml \\n --output config.ncl \\n --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n\n\n#### CLI Backend\n\n\ncd .typedialog/ci\nsource envrc\ntypedialog nickel-roundtrip config.ncl form.toml \\n --output config.ncl \\n --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n\n\nNote: The --ncl-template flag uses a Tera template that adds:\n\n- Descriptive comments for each section\n- Documentation compatible with nickel doc config.ncl\n- Consistent formatting and structure\n\nAll backends will:\n\n- Show only options relevant to your detected languages\n- Guide you through all configuration choices\n- Validate your inputs\n- Generate config.ncl in Nickel format\n\n### Option 3: Manual Configuration\n\nEdit config.ncl directly:\n\n\nvim .typedialog/ci/config.ncl\n\n\n---\n\n## Configuration Format: Nickel\n\nThis project uses Nickel format by default for all configuration files.\n\n### Why Nickel?\n\n- ✅ Typed configuration - Static type checking with nickel typecheck\n- ✅ Documentation - Generate docs with nickel doc config.ncl\n- ✅ Validation - Built-in schema validation\n- ✅ Comments - Rich inline documentation support\n- ✅ Modular - Import/export system for reusable configs\n\n### Nickel Template\n\nThe output structure is controlled by a Tera template at:\n\n- Tools default: $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n- Local override: .typedialog/ci/config.ncl.j2 (optional)\n\nTo customize the template:\n\n\n# Copy the default template\ncp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \\n .typedialog/ci/config.ncl.j2\n\n# Edit to add custom comments, documentation, or structure\nvim .typedialog/ci/config.ncl.j2\n\n# Your template will now be used automatically\n\n\nTemplate features:\n\n- Customizable comments per section\n- Control field ordering\n- Add project-specific documentation\n- Configure output for nickel doc command\n\n### TypeDialog Environment Variables\n\nYou can customize TypeDialog behavior with environment variables:\n\n\n# Web server configuration\nexport TYPEDIALOG_PORT=9000 # Port for web backend (default: 9000)\nexport TYPEDIALOG_HOST=localhost # Host binding (default: localhost)\n\n# Localization\nexport TYPEDIALOG_LANG=en_US.UTF-8 # Form language (default: system locale)\n\n# Run with custom settings\nTYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web\n\n\nCommon use cases:\n\n\n# Access from other machines in network\nTYPEDIALOG_HOST=0.0.0.0 TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web\n\n# Use different port if 9000 is busy\nTYPEDIALOG_PORT=3000 .typedialog/ci/configure.sh web\n\n# Spanish interface\nTYPEDIALOG_LANG=es_ES.UTF-8 .typedialog/ci/configure.sh web\n\n\n## Configuration Structure\n\nYour config.ncl is organized in the ci namespace (Nickel format):\n\n\n{\n ci = {\n project = {\n name = "rust",\n detected_languages = ["rust, nushell, nickel, bash, markdown, python, javascript"],\n primary_language = "rust",\n },\n tools = {\n # Tools are added based on detected languages\n },\n features = {\n # CI features (pre-commit, GitHub Actions, etc.)\n },\n ci_providers = {\n # CI provider configurations\n },\n },\n}\n\n\n## Available Fragments\n\nTool configurations are modular. Check .typedialog/ci/fragments/ for:\n\n- rust-tools.toml - Tools for rust\n- nushell-tools.toml - Tools for nushell\n- nickel-tools.toml - Tools for nickel\n- bash-tools.toml - Tools for bash\n- markdown-tools.toml - Tools for markdown\n- python-tools.toml - Tools for python\n- javascript-tools.toml - Tools for javascript\n- general-tools.toml - Cross-language tools\n- ci-providers.toml - GitHub Actions, Woodpecker, etc.\n\n## Cascading Override System\n\nThis project uses a local → Tools cascading search for all resources:\n\n### How It Works\n\nResources are searched in priority order:\n\n1. Local files (.typedialog/ci/) - FIRST (highest priority)\n2. Tools files ($TOOLS_PATH/dev-system/ci/) - FALLBACK (default)\n\n### Affected Resources\n\n| Resource | Local Path | Tools Path |\n| ---------- | ------------ | ------------ |\n| Fragments | .typedialog/ci/fragments/ | $TOOLS_PATH/dev-system/ci/forms/fragments/ |\n| Schemas | .typedialog/ci/schemas/ | $TOOLS_PATH/dev-system/ci/schemas/ |\n| Validators | .typedialog/ci/validators/ | $TOOLS_PATH/dev-system/ci/validators/ |\n| Defaults | .typedialog/ci/defaults/ | $TOOLS_PATH/dev-system/ci/defaults/ |\n| Nickel Template | .typedialog/ci/config.ncl.j2 | $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 |\n\n### Environment Setup (.envrc)\n\nThe .typedialog/ci/.envrc file configures search paths:\n\n\n# Source this file to load environment\nsource .typedialog/ci/.envrc\n\n# Or use direnv for automatic loading\necho 'source .typedialog/ci/.envrc' >> .envrc\n\n\nWhat's in .envrc:\n\n\nexport NICKEL_IMPORT_PATH="schemas:$TOOLS_PATH/dev-system/ci/schemas:validators:..."\nexport TYPEDIALOG_FRAGMENT_PATH=".:$TOOLS_PATH/dev-system/ci/forms"\nexport NCL_TEMPLATE="<local or Tools path to config.ncl.j2>"\nexport TYPEDIALOG_PORT=9000 # Web server port\nexport TYPEDIALOG_HOST=localhost # Web server host\nexport TYPEDIALOG_LANG="${LANG}" # Form localization\n\n\n### Creating Overrides\n\nBy default: All resources come from Tools (no duplication).\n\nTo customize: Create file in local directory with same name:\n\n\n# Override a fragment\ncp $TOOLS_PATH/dev-system/ci/fragments/rust-tools.toml \\n .typedialog/ci/fragments/rust-tools.toml\n\n# Edit your local version\nvim .typedialog/ci/fragments/rust-tools.toml\n\n# Override Nickel template (customize comments, structure, nickel doc output)\ncp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \\n .typedialog/ci/config.ncl.j2\n\n# Edit to customize documentation and structure\nvim .typedialog/ci/config.ncl.j2\n\n# Now your version will be used instead of Tools version\n\n\nBenefits:\n\n- ✅ Override only what you need\n- ✅ Everything else stays synchronized with Tools\n- ✅ No duplication by default\n- ✅ Automatic updates when Tools is updated\n\nSee: $TOOLS_PATH/dev-system/ci/docs/cascade-override.md for complete documentation.\n\n## Testing Your Configuration\n\n### Validate Configuration\n\n\nnu $env.TOOLS_PATH/dev-system/ci/scripts/validator.nu \\n --config .typedialog/ci/config.ncl \\n --project . \\n --namespace ci\n\n\n### Regenerate CI Files\n\n\nnu $env.TOOLS_PATH/dev-system/ci/scripts/generate-configs.nu \\n --config .typedialog/ci/config.ncl \\n --templates $env.TOOLS_PATH/dev-system/ci/templates \\n --output . \\n --namespace ci\n\n\n## Common Tasks\n\n### Add a New Tool\n\nEdit config.ncl and add under ci.tools:\n\n\n{\n ci = {\n tools = {\n newtool = {\n enabled = true,\n install_method = "cargo",\n version = "latest",\n },\n },\n },\n}\n\n\n### Disable a Feature\n\n\n[ci.features]\nenable_pre_commit = false\n\n\n## Need Help?\n\nFor detailed documentation, see:\n\n- $env.TOOLS_PATH/dev-system/ci/docs/configuration-guide.md\n- $env.TOOLS_PATH/dev-system/ci/docs/installation-guide.md
