Discovery

Discovery Skill

This skill covers the discovery system in Invowk, which locates and aggregates commands from multiple sources with clear precedence rules and collision detection.

Use this skill when working on:

• internal/discovery/ - Discovery and aggregation logic
• Module resolution and dependency handling
• Command collision detection and disambiguation
• Source tracking and precedence

Discovery Precedence Order

The discovery system implements a strict 4-level precedence hierarchy:

Key Behavior:

• Non-module sources (current dir, user dir, config paths): First source shadows later ones
• Module commands: All included with ambiguity flagging for transparent namespace

File Discovery Algorithm

Discovery has two parallel tracks:

Track A: Invkfile Discovery

// Single-level check (current directory)
discoverInDir(dir)  // Looks for invkfile.cue OR invkfile

// Recursive search (user dir, config paths)
discoverInDirRecursive(dir)  // Uses filepath.WalkDir()

File Priority: .cue extension preferred over non-suffixed invkfile

Track B: Module Discovery

// Non-recursive - only immediate subdirectories
discoverModulesInDir(dir)

Module Validation:

• Uses invkmod.IsModule() to verify directory structure
• Skips reserved module name "invkfile" (reserved for canonical namespace)
• Graceful degradation: Invalid modules are silently skipped

Source Tracking Types

Source Enum

const (
    SourceCurrentDir   Source = iota  // "current directory"
    SourceUserDir                     // "user commands (~/.invowk/cmds)"
    SourceConfigPath                  // "configured search path"
    SourceModule                      // "module" (from .invkmod)
)

DiscoveredFile

Captures discovery metadata for each found file:

type DiscoveredFile struct {
    Path     string           // Absolute path
    Source   Source           // Which source type
    Invkfile *invkfile.Invkfile  // Parsed content (lazy-loaded)
    Error    error            // Parse errors if applicable
    Module   *invkmod.Module  // Non-nil if from .invkmod
}

CommandInfo

Output of command aggregation:

type CommandInfo struct {
    Name        string  // Full name with prefix (e.g., "foo build")
    SimpleName  string  // Unprefixed name (e.g., "build")
    Source      Source
    SourceID    string  // "invkfile" or module short name
    ModuleID    string  // Full module ID (e.g., "io.invowk.sample")
    IsAmbiguous bool    // True if SimpleName conflicts across sources
    FilePath    string  // Absolute path to invkfile
    Command     *invkfile.Command
    Invkfile    *invkfile.Invkfile
}

Command Aggregation & Collision Detection

The aggregation system uses a two-phase process with transparent namespace:

Phase 1: Flatten & Index

// Get all commands with proper namespacing
commands := invkfile.FlattenCommands()

// Modules have commands prefixed:
// Module "foo" with command "build" → "foo build"

Phase 2: Conflict Analysis

The DiscoveredCommandSet provides:

Precedence vs. Collision Handling

IsAmbiguous Flag: Set to true when a simple name conflicts across sources. This enables:

• Transparent namespace for unambiguous commands: invowk cmd build
• Explicit disambiguation for ambiguous ones: invowk cmd @foo build

Module Dependency Handling

Module Identity & Visibility

type Module struct {
    Path    string          // Filesystem location
    Invkmod *invkmod.Invkmod  // Parsed metadata from invkmod.cue
}

// Module commands are automatically namespaced
// Module "foo" → commands like "foo build", "foo deploy"

Module Collision Detection

When two modules have the same ID in different sources:

type ModuleCollisionError struct {
    ModuleID string
    Sources  []string
}

// Validation
err := discovery.CheckModuleCollisions()
// Returns actionable guidance: "invowk module alias <source> <new-alias>"

Module Aliases: Configured in config.ModuleAliases map to disambiguate collisions.

Command Scope Rules

Commands can only call:

1. Commands from the same module
2. Commands from globally installed modules (~/.invowk/modules/)
3. Commands from first-level requirements (direct dependencies in invkmod.cue:requires)

CRITICAL: Transitive dependencies are NOT accessible. Commands cannot call dependencies of dependencies. This enforces explicit, auditable dependency chains.

Validation

Command Tree Validation

ValidateCommandTree() enforces the leaf-only args rule:

// A command cannot have both positional args AND subcommands
// Positional args would be unreachable if subcommands exist

type ArgsSubcommandConflictError struct {
    CommandPath []string  // Path to the conflicting command
    ArgNames    []string  // The args that conflict
}

Usage Patterns

Simple Command Execution

disc := discovery.New(cfg)
commands, err := disc.DiscoverCommands()  // Flat list, sorted

CLI Listing with Grouping

cmdSet, err := disc.DiscoverCommandSet()

for _, sourceID := range cmdSet.SourceOrder {
    for _, cmd := range cmdSet.BySource[sourceID] {
        if cmd.IsAmbiguous {
            // Show with disambiguation prefix
        } else {
            // Show with transparent namespace
        }
    }
}

Validation Before Execution

commands, err := disc.DiscoverAndValidateCommands()  // Includes tree validation

Get Specific Command

cmdInfo, err := disc.GetCommand("foo build")
// Returns Command, Invkfile, Module metadata

Design Decisions

File Organization

Common Pitfalls