Skip to main content
Version: 0.1.0-alpha.1

Validating Modules

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

Basic Validation​

invowk module validate ./mytools.invkmod

Output for a valid module:

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

✓ Module is valid

✓ Structure check passed
✓ Naming convention check passed
✓ Required files present

Deep Validation​

Add --deep to also parse and validate the invkfile (when present):

invowk module validate ./mytools.invkmod --deep

Output:

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

✓ Module is valid

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

What Gets Validated​

Structure Checks​

  • Module directory exists
  • Required invkmod.cue at root
  • invkfile.cue is optional (library-only modules are allowed)
  • No nested modules (except inside invk_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 .invkmod
  • Name prefix follows rules (starts with letter, alphanumeric + dots)
  • Module ID in invkmod.cue matches the folder name prefix
  • No invalid characters (hyphens, underscores)

Deep Checks (with --deep)​

  • Invkfile parses without errors (if present)
  • CUE syntax is valid
  • Schema constraints are met

Validation Errors​

Missing Invkmod​

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

✗ Module validation failed with 1 issue(s)

  1. [structure] missing required invkmod.cue

Invalid Name​

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

✗ 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.invkmod

✗ Module validation failed with 1 issue(s)

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

Invalid Invkfile (deep)​

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

✗ Module validation failed with 1 issue(s)

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

Batch Validation​

Validate multiple modules:

# Validate all modules in a directory
for mod in ./modules/*.invkmod; do
    invowk module validate "$mod" --deep
done

CI Integration​

Add module validation to your CI pipeline:

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

Common Issues​

Wrong Path Separators​

// Bad - Windows-style
script: "scripts\\build.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. Use --deep: Catches invkfile errors
  3. Validate in CI: Prevent broken modules from shipping
  4. Fix issues immediately: Don't let validation debt accumulate

Next Steps​