Skip to main content
Version: 0.1.0-alpha.3

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)Configured includes/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

Includes Configuration​

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

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

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

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