Invowk Schema Guidelines

Use this skill when:

• •Editing the invkfile.cue root example file
• •Working with sample modules in modules/
• •Adding or modifying command/implementation structures
• •Handling cross-platform runtime selection (native vs virtual runtimes on different platforms)

Invkfile Examples

Built-in Examples (invkfile.cue at project root)

• •Always update the example file when invkfile definitions or features are added, modified, or removed.
• •All commands should be idempotent and not cause any side effects on the host.
• •No commands should be related to building invowk itself or manipulating any of its source code.
• •Examples should range from simple (e.g., native "hello-world") to complex (e.g., container "hello-world" with enable_host_ssh).
• •Examples should cover different features, such as:
  • •Native vs. container execution.
  • •Volume mounts for container execution.
  • •Environment variables.
  • •Host SSH access enabled vs. disabled.
  • •Capabilities checks (with and without alternatives).
  • •Tools checks (with and without alternatives).
  • •Custom checks (with and without alternatives).
• •Module metadata does not belong in invkfile examples; it lives in invkmod.cue for modules.

Command Structure Validation

Leaf-Only Args Constraint

Commands with positional arguments (args) cannot have subcommands. This is enforced during command discovery and module validation.

Why: CLI parsers interpret positional arguments after a command name as potential subcommand names. If deploy has both args: [{name: "env"}] and a subcommand deploy staging, running invowk cmd deploy prod is ambiguous—is prod an argument or a subcommand name?

Valid:

// Leaf command with args (no subcommands)
cmds: [
    {name: "deploy", args: [{name: "env"}], ...}
]

// Parent command with subcommands (no args on parent)
cmds: [
    {name: "deploy"},           // No args here
    {name: "deploy staging"},   // Subcommand
    {name: "deploy prod"},      // Subcommand
]

Invalid:

cmds: [
    {name: "deploy", args: [{name: "env"}], ...},  // Has args
    {name: "deploy staging", ...}                   // Is a subcommand of deploy
]
// Error: command 'deploy' has both args and subcommands

This validation runs:

1. •During invowk cmd execution (command discovery)
2. •During invowk module validate --deep

Cross-Platform Runtime Selection

Bash scripts with native+virtual runtimes must use platform-specific implementations.

The problem: The native runtime on Windows uses PowerShell (or cmd), which cannot parse bash syntax. When a command declares runtimes: [{name: "native"}, {name: "virtual"}], the first runtime (native) becomes the default. This causes bash scripts to fail on Windows with PowerShell parser errors.

The solution: Split implementations by platform:

• •Linux/macOS: Use runtimes: [{name: "native"}, {name: "virtual"}] with platforms: [{name: "linux"}, {name: "macos"}]
• •Windows: Use runtimes: [{name: "virtual"}] with platforms: [{name: "windows"}] (virtual runtime uses mvdan/sh, a cross-platform POSIX shell)

Valid (platform-specific implementations):

implementations: [
    {
        script: """
            echo "Hello from bash"
            if [ -f /etc/os-release ]; then
                cat /etc/os-release
            fi
            """
        runtimes:  [{name: "native"}, {name: "virtual"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    },
    {
        script: """
            echo "Hello from bash"
            if [ -f /etc/os-release ]; then
                cat /etc/os-release
            fi
            """
        runtimes:  [{name: "virtual"}]
        platforms: [{name: "windows"}]
    },
]

Invalid (bash script without platform restriction):

implementations: [
    {
        script: """
            echo "Hello from bash"
            if [ -f /etc/os-release ]; then
                cat /etc/os-release
            fi
            """
        runtimes: [{name: "native"}, {name: "virtual"}]
        // Missing platforms restriction - will fail on Windows!
    },
]

When to apply this pattern:

• •Any command with bash/POSIX shell scripts
• •That declares both native and virtual runtimes
• •And should work on Windows

Exceptions (no split needed):

• •Commands with runtimes: [{name: "virtual"}] only (already cross-platform)
• •Commands with runtimes: [{name: "native"}] only and platforms: [{name: "linux"}, {name: "macos"}] (Linux/macOS only)
• •Commands with PowerShell scripts intended for Windows

Invkmod Modules

Samples (modules/ directory)

The modules/ directory contains sample modules that serve as reference implementations and validation tests.

• •A module is a .invkmod directory containing invkmod.cue (metadata) and invkfile.cue (commands).
• •The invkmod schema lives in pkg/invkmod/invkmod_schema.cue and the invkfile schema in pkg/invkfile/invkfile_schema.cue.
• •Always update sample modules when the invkmod schema, validation rules, or module behavior changes.
• •Modules should demonstrate module-specific features (script file references, cross-platform paths, requirements).
• •After module-related changes, run validation: go run . module validate modules/<module-name>.invkmod --deep.

Current Sample Modules

• •io.invowk.sample.invkmod - Minimal cross-platform module with a simple greeting command.

Module Validation Checklist

When modifying module-related code, verify:

1. •All modules in modules/ pass validation: go run . module validate modules/*.invkmod --deep.
2. •Module naming conventions and module ID matching are enforced.
3. •invkmod.cue is required and parsed; invkfile.cue contains only commands.
4. •Script path resolution works correctly (forward slashes, relative paths).
5. •Nested module detection works correctly.
6. •The pkg/invkmod/ tests pass: go test -v ./pkg/invkmod/....

Common Pitfalls

For path handling in implementations, see .claude/rules/windows.md.