Skip to main content
Version: 0.4.0

Discovery Precedence Flowchart

This diagram shows how commands are discovered and how conflicts are resolved when the same command name appears in multiple locations.

Discovery Flow​

Diagram: architecture/discovery-flow

Conflict Resolution​

When the same command name exists in multiple locations:

Diagram: architecture/discovery-conflict

Resolution Rules​

PrioritySourceExample Path
1 (highest)Current directory invowkfile./invowkfile.cue
2Local modules./mytools.invowkmod/
3Configured includes/opt/invowk-modules/tools.invowkmod
4 (lowest)User commands directory~/.invowk/cmds/mytools.invowkmod/

Key principles:

  • Closer to the working directory = higher priority.
  • Configured includes take precedence over the user commands directory because they represent explicit, intentional configuration.
  • The user commands directory (~/.invowk/cmds/) only discovers *.invowkmod directories as immediate children (non-recursive). Loose invowkfiles are not discovered from this location.

Module Discovery Details​

Diagram: architecture/discovery-module-structure

Required Module Fields​

// invowkmod.cue
module: "com.example.mymodule"  // RDNS naming convention
version: "1.0.0"                // Semantic version

// Optional
description: "My useful module"
requires: [
    {
        git_url: "https://github.com/org/repo.invowkmod.git"
        version: "^1.0.0"
    }
]

Dependency Resolution​

Diagram: architecture/discovery-deps

Transitive Dependency Visibility​

FromCan AccessCannot Access
Module AA's commands, B's commandsC's commands (transitive)
Module BB's commands, C's commands-
Root invowkfileOwn commands, direct depsTransitive deps

Why this restriction?

  • Prevents implicit coupling to transitive dependencies
  • Makes dependencies explicit in each module
  • Enables dependency upgrades without breaking consumers

Includes Configuration​

Additional modules are configured in ~/.config/invowk/config.cue:

includes: [
    {path: "/opt/company-invowk-modules/tools.invowkmod"},
    {path: "/home/shared/invowk/shared.invowkmod"},
]

Entry Processing Order​

Diagram: architecture/discovery-includes

Discovery Caching​

Diagram: architecture/discovery-cache

Common Discovery Issues​

Problem: Command Not Found​

Diagram: architecture/discovery-not-found

Problem: Wrong Command Version​

Diagram: architecture/discovery-wrong-version

Debug Commands​

# List all discovered commands with sources
invowk cmd --ivk-verbose

# Validate workspace discovery (reports all diagnostics)
invowk validate

# Validate a specific module
invowk validate ./mymodule.invowkmod