# Extension Development Quick Start Guide\n\nThis guide provides a hands-on walkthrough for developing custom extensions using the Nickel configuration system and module loader.\n\n## Prerequisites\n\n1. Nickel installed (1.15.0+):\n\n   ```bash\n   # macOS\n   brew install nickel\n\n   # Linux/Other\n   cargo install nickel\n\n   # Verify\n   nickel --version\n   ```\n\n2. Module loader and extension tools available:\n\n   ```bash\n   ./provisioning/core/cli/module-loader --help\n   ./provisioning/tools/create-extension.nu --help\n   ```\n\n## Quick Start: Creating Your First Extension\n\n### Step 1: Create Extension from Template\n\n```\n# Interactive creation (recommended for beginners)\n./provisioning/tools/create-extension.nu interactive\n\n# Or direct creation\n./provisioning/tools/create-extension.nu taskserv my-app \\n    --author "Your Name" \\n    --description "My custom application service"\n```\n\n### Step 2: Navigate and Customize\n\n```\n# Navigate to your new extension\ncd extensions/taskservs/my-app\n\n# View generated files\nls -la\n# main.ncl - Main taskserv definition\n# contracts.ncl - Configuration contract/schema\n# defaults.ncl - Default values\n# README.md - Documentation template\n```\n\n### Step 3: Customize Configuration\n\nEdit `main.ncl` to match your service requirements:\n\n```\n# contracts.ncl - Define the schema\n{\n  MyAppConfig = {\n    database_url | String,\n    api_key | String,\n    debug_mode | Bool,\n    cpu_request | String,\n    memory_request | String,\n    port | Number,\n  }\n}\n\n# defaults.ncl - Provide sensible defaults\n{\n  defaults = {\n    debug_mode = false,\n    cpu_request = "200m",\n    memory_request = "512Mi",\n    port = 3000,\n  }\n}\n\n# main.ncl - Combine and export\nlet contracts = import "./contracts.ncl" in\nlet defaults = import "./defaults.ncl" in\n\n{\n  defaults = defaults,\n  make_config | not_exported = fun overrides =>\n    defaults.defaults & overrides,\n}\n```\n\n### Step 4: Test Your Extension\n\n```\n# Test discovery\n./provisioning/core/cli/module-loader discover taskservs | grep my-app\n\n# Validate Nickel syntax\nnickel typecheck main.ncl\n\n# Validate extension structure\n./provisioning/tools/create-extension.nu validate ../../../my-app\n```\n\n### Step 5: Use in Workspace\n\n```\n# Create test workspace\nmkdir -p /tmp/test-my-app\ncd /tmp/test-my-app\n\n# Initialize workspace\n../provisioning/tools/workspace-init.nu . init\n\n# Load your extension\n../provisioning/core/cli/module-loader load taskservs . [my-app]\n\n# Configure in servers.ncl\ncat > infra/default/servers.ncl << 'EOF'\nlet my_app = import "../../extensions/taskservs/my-app/main.ncl" in\n\n{\n  servers = [\n    {\n      hostname = "app-01",\n      provider = "local",\n      plan = "2xCPU-4 GB",\n      zone = "local",\n      storages = [{ total = 25 }],\n      taskservs = [\n        my_app.make_config {\n          database_url = "postgresql://db:5432/myapp",\n          api_key = "secret-key",\n          debug_mode = false,\n        }\n      ],\n    }\n  ]\n}\nEOF\n\n# Test configuration\nnickel export infra/default/servers.ncl\n```\n\n## Common Extension Patterns\n\n### Database Service Extension\n\n```\n# Create database service\n./provisioning/tools/create-extension.nu taskserv company-db \\n    --author "Your Company" \\n    --description "Company-specific database service"\n\n# Customize for PostgreSQL with company settings\ncd extensions/taskservs/company-db\n```\n\nEdit the schema:\n\n```\n# Database service configuration schema\nlet CompanyDbConfig = {\n  # Database settings\n  database_name | String = "company_db",\n  postgres_version | String = "13",\n\n  # Company-specific settings\n  backup_schedule | String = "0 2 * * *",\n  compliance_mode | Bool = true,\n  encryption_enabled | Bool = true,\n\n  # Connection settings\n  max_connections | Number = 100,\n  shared_buffers | String = "256 MB",\n\n  # Storage settings\n  storage_size | String = "100Gi",\n  storage_class | String = "fast-ssd",\n} | {\n  # Validation contracts\n  database_name | String,\n  max_connections | std.contract.from_validator (fun x => x > 0),\n} in\nCompanyDbConfig\n```\n\n### Monitoring Service Extension\n\n```\n# Create monitoring service\n./provisioning/tools/create-extension.nu taskserv company-monitoring \\n    --author "Your Company" \\n    --description "Company-specific monitoring and alerting"\n```\n\nCustomize for Prometheus with company dashboards:\n\n```\n# Monitoring service configuration\nlet AlertManagerConfig = {\n  smtp_server | String,\n  smtp_port | Number = 587,\n  smtp_auth_enabled | Bool = true,\n} in\n\nlet CompanyMonitoringConfig = {\n  # Prometheus settings\n  retention_days | Number = 30,\n  storage_size | String = "50Gi",\n\n  # Company dashboards\n  enable_business_metrics | Bool = true,\n  enable_compliance_dashboard | Bool = true,\n\n  # Alert routing\n  alert_manager_config | AlertManagerConfig,\n\n  # Integration settings\n  slack_webhook | String | optional,\n  email_notifications | Array String,\n} in\nCompanyMonitoringConfig\n```\n\n### Legacy System Integration\n\n```\n# Create legacy integration\n./provisioning/tools/create-extension.nu taskserv legacy-bridge \\n    --author "Your Company" \\n    --description "Bridge for legacy system integration"\n```\n\nCustomize for mainframe integration:\n\n```\n# Legacy bridge configuration schema\nlet LegacyBridgeConfig = {\n  # Legacy system details\n  mainframe_host | String,\n  mainframe_port | Number = 23,\n  connection_type | [String] = "tn3270",  # "tn3270" or "direct"\n\n  # Data transformation\n  data_format | [String] = "fixed-width",  # "fixed-width", "csv", or "xml"\n  character_encoding | String = "ebcdic",\n\n  # Processing settings\n  batch_size | Number = 1000,\n  poll_interval_seconds | Number = 60,\n\n  # Error handling\n  retry_attempts | Number = 3,\n  dead_letter_queue_enabled | Bool = true,\n} in\nLegacyBridgeConfig\n```\n\n## Advanced Customization\n\n### Custom Provider Development\n\n```\n# Create custom cloud provider\n./provisioning/tools/create-extension.nu provider company-cloud \\n    --author "Your Company" \\n    --description "Company private cloud provider"\n```\n\n### Complete Infrastructure Stack\n\n```\n# Create complete cluster configuration\n./provisioning/tools/create-extension.nu cluster company-stack \\n    --author "Your Company" \\n    --description "Complete company infrastructure stack"\n```\n\n## Testing and Validation\n\n### Local Testing Workflow\n\n```\n# 1. Create test workspace\nmkdir test-workspace && cd test-workspace\n../provisioning/tools/workspace-init.nu . init\n\n# 2. Load your extensions\n../provisioning/core/cli/module-loader load taskservs . [my-app, company-db]\n../provisioning/core/cli/module-loader load providers . [company-cloud]\n\n# 3. Validate loading\n../provisioning/core/cli/module-loader list taskservs .\n../provisioning/core/cli/module-loader validate .\n\n# 4. Test KCL compilation\nnickel export servers.ncl\n\n# 5. Dry-run deployment\n../provisioning/core/cli/provisioning server create --infra . --check\n```\n\n### Continuous Integration Testing\n\nCreate `.github/workflows/test-extensions.yml`:\n\n```\nname: Test Extensions\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n\n      - name: Install Nickel\n        run: |\n          curl -fsSL https://releases.nickel-lang.org/install.sh | bash\n          echo "$HOME/.nickel/bin" >> $GITHUB_PATH\n\n      - name: Install Nushell\n        run: |\n          curl -L https://github.com/nushell/nushell/releases/download/0.107.1/nu-0.107.1-x86_64-unknown-linux-gnu.tar.gz | tar xzf -\n          sudo mv nu-0.107.1-x86_64-unknown-linux-gnu/nu /usr/local/bin/\n\n      - name: Build core package\n        run: |\n          nu provisioning/tools/nickel-packager.nu build --version test\n\n      - name: Test extension discovery\n        run: |\n          nu provisioning/core/cli/module-loader discover taskservs\n\n      - name: Validate extension syntax\n        run: |\n          find extensions -name "*.ncl" -exec nickel typecheck {} \;\n\n      - name: Test workspace creation\n        run: |\n          mkdir test-workspace\n          nu provisioning/tools/workspace-init.nu test-workspace init\n          cd test-workspace\n          nu ../provisioning/core/cli/module-loader load taskservs . [my-app]\n          nickel export servers.ncl\n```\n\n## Best Practices Summary\n\n### 1. Extension Design\n\n- ✅ Use descriptive names in kebab-case\n- ✅ Include comprehensive validation in schemas\n- ✅ Provide multiple profiles for different environments\n- ✅ Document all configuration options\n\n### 2. Dependencies\n\n- ✅ Declare all dependencies explicitly\n- ✅ Use semantic versioning\n- ✅ Test compatibility with different versions\n\n### 3. Security\n\n- ✅ Never hardcode secrets in schemas\n- ✅ Use validation to ensure secure defaults\n- ✅ Follow principle of least privilege\n\n### 4. Documentation\n\n- ✅ Include comprehensive README\n- ✅ Provide usage examples\n- ✅ Document troubleshooting steps\n- ✅ Maintain changelog\n\n### 5. Testing\n\n- ✅ Test extension discovery and loading\n- ✅ Validate Nickel syntax with type checking\n- ✅ Test in multiple environments\n- ✅ Include CI/CD validation\n\n## Common Issues and Solutions\n\n### Extension Not Discovered\n\n**Problem**: `module-loader discover` doesn't find your extension\n\n**Solutions**:\n\n1. Check directory structure: `extensions/taskservs/my-service/schemas/`\n2. Verify `manifest.toml` exists and is valid\n3. Ensure main `.ncl` file has correct name\n4. Check file permissions\n\n### Nickel Type Errors\n\n**Problem**: Nickel type checking errors in your extension\n\n**Solutions**:\n\n1. Use `nickel typecheck my-service.ncl` to validate syntax\n2. Check import statements are correct\n3. Verify schema validation rules\n4. Ensure all required fields have defaults or are provided\n\n### Loading Failures\n\n**Problem**: Extension loads but doesn't work correctly\n\n**Solutions**:\n\n1. Check generated import files: `cat taskservs.ncl`\n2. Verify dependencies are satisfied\n3. Test with minimal configuration first\n4. Check extension manifest: `cat .manifest/taskservs.yaml`\n\n## Next Steps\n\n1. **Explore Examples**: Look at existing extensions in `extensions/` directory\n2. **Read Advanced Docs**: Study the comprehensive guides:\n   - [Nickel Packaging Guide](nickel-packaging-guide.md)\n   - [Infrastructure-Specific Extensions](infrastructure-specific-extensions.md)\n3. **Join Community**: Contribute to the provisioning system\n4. **Share Extensions**: Publish useful extensions for others\n\n## Support\n\n- **Documentation**: [Package and Loader System Guide](package-and-loader-system.md)\n- **Templates**: Use `./provisioning/tools/create-extension.nu list-templates`\n- **Validation**: Use `./provisioning/tools/create-extension.nu validate <path>`\n- **Examples**: Check `provisioning/examples/` directory\n\nHappy extension development. 🚀
