Skip to main content
Version: 0.1.0-alpha.2

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 invkfile./invkfile.cue
2Local modules./mytools.invkmod/
3User directory~/.invowk/cmds/invkfile.cue
4 (lowest)Search paths/opt/invowk-modules/

Key principle: Closer to the working directory = higher priority.

Module Discovery Details​

Diagram: architecture/discovery-module-structure

Required Module Fields​

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

// Optional
description: "My useful module"
requires: [
    {
        git: "https://github.com/org/repo.git"
        version: "v1.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 invkfileOwn 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

Search Path Configuration​

Search paths are configured in ~/.config/invowk/config.cue:

search_paths: [
    "/opt/company-invowk-modules",
    "/home/shared/invowk",
]

Path Resolution Order​

Diagram: architecture/discovery-search-paths

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 --list --verbose

# Show discovery order and conflicts
invowk internal discovery --debug

# Validate module structure
invowk module validate ./mymodule.invkmod