KCL Module Dependency Patterns - Quick Reference

kcl.mod Templates

Standard Category Taskserv (Depth 2)

Location: provisioning/extensions/taskservs/{category}/{taskserv}/kcl/kcl.mod

[package]
name = "{taskserv-name}"
edition = "v0.11.2"
version = "0.0.1"

[dependencies]
provisioning = { path = "../../../../kcl", version = "0.0.1" }
taskservs = { path = "../..", version = "0.0.1" }

Sub-Category Taskserv (Depth 3)

Location: provisioning/extensions/taskservs/{category}/{subcategory}/{taskserv}/kcl/kcl.mod

[package]
name = "{taskserv-name}"
edition = "v0.11.2"
version = "0.0.1"

[dependencies]
provisioning = { path = "../../../../../kcl", version = "0.0.1" }
taskservs = { path = "../../..", version = "0.0.1" }

Category Root (e.g., kubernetes)

Location: provisioning/extensions/taskservs/{category}/kcl/kcl.mod

[package]
name = "{category}"
edition = "v0.11.2"
version = "0.0.1"

[dependencies]
provisioning = { path = "../../../kcl", version = "0.0.1" }
taskservs = { path = "..", version = "0.0.1" }

Import Patterns

In Taskserv Schema Files

# Import core provisioning schemas
import provisioning.settings
import provisioning.server
import provisioning.version

# Import taskserv utilities
import taskservs.version as schema

# Use imported schemas
config = settings.Settings { ... }
version = schema.TaskservVersion { ... }

Version Schema Pattern

Standard Version File

Location: {taskserv}/kcl/version.k

import taskservs.version as schema

_version = schema.TaskservVersion {
    name = "{taskserv-name}"
    version = schema.Version {
        current = "latest"  # or specific version like "1.31.0"
        source = "https://api.github.com/repos/{org}/{repo}/releases"
        tags = "https://api.github.com/repos/{org}/{repo}/tags"
        site = "https://{project-site}"
        check_latest = False
        grace_period = 86400
    }
    dependencies = []  # list of other taskservs this depends on
}

_version

Internal Component (no upstream)

_version = schema.TaskservVersion {
    name = "{taskserv-name}"
    version = schema.Version {
        current = "latest"
        site = "Internal provisioning component"
        check_latest = False
        grace_period = 86400
    }
    dependencies = []
}

Path Calculation

From Taskserv KCL to Core KCL

From Taskserv KCL to Taskservs Root

Validation

Test Single Schema

cd {taskserv}/kcl
kcl run {schema-name}.k

Test All Schemas in Taskserv

cd {taskserv}/kcl
for file in *.k; do kcl run "$file"; done

Validate Entire Category

find provisioning/extensions/taskservs/{category} -name "*.k" -type f | while read f; do
    echo "Validating: $f"
    kcl run "$f"
done

Common Issues & Fixes

Issue: “name ‘provisioning’ is not defined”

Cause: Wrong path in kcl.mod Fix: Check relative path depth and adjust

Issue: “name ‘schema’ is not defined”

Cause: Missing import or wrong alias Fix: Add import taskservs.version as schema

Issue: “Instance check failed” on Version

Cause: Empty or missing required field Fix: Ensure current is non-empty (use “latest” if no version)

Issue: CompileError on long lines

Cause: Line too long Fix: Use line continuation with \

long_condition, \
    "error message"

Examples by Category

Container Runtime

provisioning/extensions/taskservs/container-runtime/containerd/kcl/
├── kcl.mod          # depth 2 pattern
├── containerd.k
├── dependencies.k
└── version.k

Polkadot (Sub-category)

provisioning/extensions/taskservs/infrastructure/polkadot/bootnode/kcl/
├── kcl.mod               # depth 3 pattern
├── polkadot-bootnode.k
└── version.k

Kubernetes (Root + Items)

provisioning/extensions/taskservs/kubernetes/
├── kcl/
│   ├── kcl.mod          # root pattern
│   ├── kubernetes.k
│   ├── dependencies.k
│   └── version.k
└── kubectl/
    └── kcl/
        ├── kcl.mod      # depth 2 pattern
        └── kubectl.k

Quick Commands

# Find all kcl.mod files
find provisioning/extensions/taskservs -name "kcl.mod"

# Validate all KCL files
find provisioning/extensions/taskservs -name "*.k" -exec kcl run {} \;

# Check dependencies
grep -r "path =" provisioning/extensions/taskservs/*/kcl/kcl.mod

# List taskservs
ls -d provisioning/extensions/taskservs/*/* | grep -v kcl

Reference: Based on fixes applied 2025-10-03 See: KCL_MODULE_FIX_REPORT.md for detailed analysis