Skip to main content
Version: Next

Validating Modules

Validate your modules to ensure they're correctly structured and ready for distribution.

Validating a Module​

invowk validate ./mytools.invowkmod

Output for a valid module with an invowkfile:

Module Validation
• Path: /home/user/mytools.invowkmod
• Name: mytools

✓ Module is valid

✓ Structure check passed
✓ Naming convention check passed
✓ Required files present
✓ Invowkfile parses successfully

invowk validate always performs full validation, including invowkfile parsing and command tree checks when the module contains an invowkfile.cue.

What Gets Validated​

Structure Checks​

  • Module directory exists
  • Required invowkmod.cue at root
  • invowkfile.cue is optional (library-only modules are allowed)
  • No nested modules (except inside invowk_modules/)

Security Checks​

  • No symlinks: Symlinks are not allowed in modules for security reasons. They could potentially escape the module directory during extraction (zip-slip vulnerability).

Compatibility Checks​

  • Windows reserved filenames: Files named CON, PRN, AUX, NUL, COM1-COM9, or LPT1-LPT9 will trigger a compatibility warning. These names are reserved on Windows and could cause issues when extracting modules on Windows systems.

Naming Checks​

  • Folder name ends with .invowkmod
  • Name prefix follows rules (starts with letter, alphanumeric + dots)
  • Module ID in invowkmod.cue matches the folder name prefix
  • No invalid characters (hyphens, underscores)

Invowkfile Checks​

When the module contains an invowkfile.cue, these are always checked:

  • Invowkfile parses without errors
  • CUE syntax is valid
  • Schema constraints are met
  • Command tree structure is valid (no args + subcommand conflicts)

Validation Errors​

Missing Invowkmod​

Module Validation
• Path: /home/user/bad.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [structure] missing required invowkmod.cue

Invalid Name​

Module Validation
• Path: /home/user/my-tools.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [naming] module name 'my-tools' contains invalid characters (hyphens not allowed)

Nested Module​

Module Validation
• Path: /home/user/parent.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [structure] nested.invowkmod: nested modules are not allowed (except in invowk_modules/)

Invalid Invowkfile​

Module Validation
• Path: /home/user/broken.invowkmod

✗ Module validation failed with 1 issue(s)

  1. [invowkfile] parse error at line 15: expected '}', found EOF

Batch Validation​

Validate multiple modules:

# Validate all modules in a directory
for mod in ./modules/*.invowkmod; do
    invowk validate "$mod"
done

CI Integration​

Add module validation to your CI pipeline:

# GitHub Actions example
- name: Validate modules
  run: |
    for mod in modules/*.invowkmod; do
      invowk validate "$mod"
    done

Common Issues​

Wrong Path Separators​

// Bad - Windows-style
script: "scriptsuild.sh"

// Good - Forward slashes
script: "scripts/build.sh"

Escaping Module Directory​

// Bad - tries to access parent
script: "../outside/script.sh"

// Good - stays within module
script: "scripts/script.sh"

Absolute Paths​

// Bad - absolute path
script: "/usr/local/bin/script.sh"

// Good - relative path
script: "scripts/script.sh"

Best Practices​

  1. Validate before committing: Catch issues early
  2. Validate in CI: Prevent broken modules from shipping
  3. Fix issues immediately: Don't let validation debt accumulate

Next Steps​