provisioning/docs/src/development/TASKSERV_QUICK_GUIDE.md

# Taskserv Quick Guide

## 🚀 Quick Start

### Create a New Taskserv (Interactive)
```bash
nu provisioning/tools/create-taskserv-helper.nu interactive
```

### Create a New Taskserv (Direct)
```bash
nu provisioning/tools/create-taskserv-helper.nu create my-api \
  --category development \
  --port 8080 \
  --description "My REST API service"
```

## 📋 5-Minute Setup

### 1. Choose Your Method
- **Interactive**: `nu provisioning/tools/create-taskserv-helper.nu interactive`
- **Command Line**: Use the direct command above
- **Manual**: Follow the structure guide below

### 2. Basic Structure
```
my-service/
├── kcl/
│   ├── kcl.mod         # Package definition
│   ├── my-service.k    # Main schema
│   └── version.k       # Version info
├── default/
│   ├── defs.toml       # Default config
│   └── install-*.sh    # Install script
└── README.md           # Documentation
```

### 3. Essential Files

**kcl.mod** (package definition):
```toml
[package]
name = "my-service"
version = "1.0.0"
description = "My service"

[dependencies]
k8s = { oci = "oci://ghcr.io/kcl-lang/k8s", tag = "1.30" }
```

**my-service.k** (main schema):
```kcl
schema MyService {
    name: str = "my-service"
    version: str = "latest"
    port: int = 8080
    replicas: int = 1
}

my_service_config: MyService = MyService {}
```

### 4. Test Your Taskserv
```bash
# Discover your taskserv
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; get-taskserv-info my-service"

# Test layer resolution
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"

# Deploy with check
provisioning/core/cli/provisioning taskserv create my-service --infra wuji --check
```

## 🎯 Common Patterns

### Web Service
```kcl
schema WebService {
    name: str
    version: str = "latest"
    port: int = 8080
    replicas: int = 1

    ingress: {
        enabled: bool = true
        hostname: str
        tls: bool = false
    }

    resources: {
        cpu: str = "100m"
        memory: str = "128Mi"
    }
}
```

### Database Service
```kcl
schema DatabaseService {
    name: str
    version: str = "latest"
    port: int = 5432

    persistence: {
        enabled: bool = true
        size: str = "10Gi"
        storage_class: str = "ssd"
    }

    auth: {
        database: str = "app"
        username: str = "user"
        password_secret: str
    }
}
```

### Background Worker
```kcl
schema BackgroundWorker {
    name: str
    version: str = "latest"
    replicas: int = 1

    job: {
        schedule?: str  # Cron format for scheduled jobs
        parallelism: int = 1
        completions: int = 1
    }

    resources: {
        cpu: str = "500m"
        memory: str = "512Mi"
    }
}
```

## 🛠️ CLI Shortcuts

### Discovery
```bash
# List all taskservs
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | select name group"

# Search taskservs
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; search-taskservs redis"

# Show stats
nu -c "use provisioning/workspace/tools/layer-utils.nu *; show_layer_stats"
```

### Development
```bash
# Check KCL syntax
kcl check provisioning/extensions/taskservs/{category}/{name}/kcl/{name}.k

# Generate configuration
provisioning/core/cli/provisioning taskserv generate {name} --infra {infra}

# Version management
provisioning/core/cli/provisioning taskserv versions {name}
provisioning/core/cli/provisioning taskserv check-updates
```

### Testing
```bash
# Dry run deployment
provisioning/core/cli/provisioning taskserv create {name} --infra {infra} --check

# Layer resolution debug
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution {name} {infra} {provider}"
```

## 📚 Categories Reference

| Category | Examples | Use Case |
|----------|----------|----------|
| **container-runtime** | containerd, crio, podman | Container runtime engines |
| **databases** | postgres, redis | Database services |
| **development** | coder, gitea, desktop | Development tools |
| **infrastructure** | kms, webhook, os | System infrastructure |
| **kubernetes** | kubernetes | Kubernetes orchestration |
| **networking** | cilium, coredns, etcd | Network services |
| **storage** | rook-ceph, external-nfs | Storage solutions |

## 🔧 Troubleshooting

### Taskserv Not Found
```bash
# Check if discovered
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | where name == my-service"

# Verify kcl.mod exists
ls provisioning/extensions/taskservs/{category}/my-service/kcl/kcl.mod
```

### Layer Resolution Issues
```bash
# Debug resolution
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"

# Check template exists
ls provisioning/workspace/templates/taskservs/{category}/my-service.k
```

### KCL Syntax Errors
```bash
# Check syntax
kcl check provisioning/extensions/taskservs/{category}/my-service/kcl/my-service.k

# Format code
kcl fmt provisioning/extensions/taskservs/{category}/my-service/kcl/
```

## 💡 Pro Tips

1. **Use existing taskservs as templates** - Copy and modify similar services
2. **Test with --check first** - Always use dry run before actual deployment
3. **Follow naming conventions** - Use kebab-case for consistency
4. **Document thoroughly** - Good docs save time later
5. **Version your schemas** - Include version.k for compatibility tracking

## 🔗 Next Steps

1. Read the full [Taskserv Developer Guide](./TASKSERV_DEVELOPER_GUIDE.md)
2. Explore existing taskservs in `provisioning/extensions/taskservs/`
3. Check out templates in `provisioning/workspace/templates/taskservs/`
4. Join the development community for support