provisioning/docs/src/development/taskservs/taskserv-quick-guide.md

# Taskserv Quick Guide

## 🚀 Quick Start

### Create a New Taskserv (Interactive)

```nushell
nu provisioning/tools/create-taskserv-helper.nu interactive
```

### Create a New Taskserv (Direct)

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

```bash
my-service/
├── nickel/
│   ├── manifest.toml   # Package definition
│   ├── my-service.ncl  # Main schema
│   └── version.ncl     # Version info
├── default/
│   ├── defs.toml       # Default config
│   └── install-*.sh    # Install script
└── README.md           # Documentation
```

### 3. Essential Files

**manifest.toml** (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.ncl** (main schema):

```javascript
let MyService = {
    name | String,
    version | String,
    port | Number,
    replicas | Number,
} in

{
    my_service_config = {
        name = "my-service",
        version = "latest",
        port = 8080,
        replicas = 1,
    }
}
```

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

```javascript
let WebService = {
    name | String,
    version | String | default = "latest",
    port | Number | default = 8080,
    replicas | Number | default = 1,
    ingress | {
        enabled | Bool | default = true,
        hostname | String,
        tls | Bool | default = false,
    },
    resources | {
        cpu | String | default = "100m",
        memory | String | default = "128Mi",
    },
} in
WebService
```

### Database Service

```javascript
let DatabaseService = {
    name | String,
    version | String | default = "latest",
    port | Number | default = 5432,
    persistence | {
        enabled | Bool | default = true,
        size | String | default = "10Gi",
        storage_class | String | default = "ssd",
    },
    auth | {
        database | String | default = "app",
        username | String | default = "user",
        password_secret | String,
    },
} in
DatabaseService
```

### Background Worker

```javascript
let BackgroundWorker = {
    name | String,
    version | String | default = "latest",
    replicas | Number | default = 1,
    job | {
        schedule | String | optional,  # Cron format for scheduled jobs
        parallelism | Number | default = 1,
        completions | Number | default = 1,
    },
    resources | {
        cpu | String | default = "500m",
        memory | String | default = "512Mi",
    },
} in
BackgroundWorker
```

## 🛠️ 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 Nickel syntax
nickel typecheck provisioning/extensions/taskservs/{category}/{name}/schemas/{name}.ncl

# 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.ncl
```

### Nickel Syntax Errors

```nickel
# Check syntax
nickel typecheck provisioning/extensions/taskservs/{category}/my-service/schemas/my-service.ncl

# Format code
nickel format provisioning/extensions/taskservs/{category}/my-service/schemas/
```

## 💡 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.ncl 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