Unix Goto Development

unix-goto Development Expert

Comprehensive development expertise for the unix-goto shell navigation system - a high-performance Unix navigation tool with natural language support, sub-100ms cached navigation, and 100% test coverage.

When to Use This Skill

Use this skill when:

• Developing new features for unix-goto shell navigation system
• Implementing cache-based navigation optimizations
• Adding bookmarks, history, or navigation commands
• Following the standard 9-step feature addition workflow
• Integrating with Linear project management
• Writing comprehensive test suites (100% coverage required)
• Optimizing performance to meet <100ms targets
• Creating API documentation for shell modules
• Debugging navigation or cache issues

Do NOT use this skill for:

• General bash scripting (use generic bash skills)
• Non-navigation shell tools
• Projects without performance requirements
• Simple one-off shell scripts

Project Overview

unix-goto System Architecture

unix-goto is a high-performance Unix navigation system designed with five core principles:

1. Simple - ONE-line loading (source goto.sh), minimal configuration
2. Fast - Sub-100ms navigation performance
3. Lean - No bloat, no unnecessary dependencies
4. Tested - 100% test coverage for core features
5. Documented - Clear, comprehensive documentation

Key Performance Metrics

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      User Interface                         │
│  goto, bookmark, recent, back, goto list, goto benchmark   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Core Navigation                          │
│  goto-function.sh - Main routing and path resolution        │
└─────────────────────────────────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│  Cache System    │ │  Bookmarks   │ │  History         │
│  cache-index.sh  │ │  bookmark-   │ │  history-        │
│                  │ │  command.sh  │ │  tracking.sh     │
│  O(1) lookup     │ │              │ │                  │
│  Auto-refresh    │ │  Add/Remove  │ │  Track visits    │
└──────────────────┘ └──────────────┘ └──────────────────┘

Module Dependencies

Critical Load Order (dependencies must load before dependents):

goto.sh (loader)
  ├── history-tracking.sh (no dependencies)
  ├── back-command.sh (depends on: history-tracking.sh)
  ├── recent-command.sh (depends on: history-tracking.sh)
  ├── bookmark-command.sh (no dependencies)
  ├── cache-index.sh (no dependencies)
  ├── list-command.sh (depends on: bookmark-command.sh)
  ├── benchmark-command.sh (depends on: cache-index.sh)
  ├── benchmark-workspace.sh (no dependencies)
  └── goto-function.sh (depends on: all above)

Core Knowledge

The 9-Step Feature Addition Workflow

This is the STANDARD process for adding any feature to unix-goto. Follow ALL nine steps.

Step 1: Plan Your Feature

Before writing ANY code, answer these questions:

Planning Questions:

• What problem does this solve?
• What's the user interface (commands/flags)?
• What's the expected performance?
• What dependencies exist?
• What tests are needed?
• What documentation is required?

Planning Template:

Feature: [Name]
Problem: [User pain point]
Interface: [Commands/flags]
Performance: [Target metrics]
Dependencies: [Module dependencies]
Tests: [Test scenarios]
Docs: [API.md, README.md sections]

Example - Recent Directories Feature (CET-77):

Feature: Recent Directories Command
Problem: Users can't quickly revisit recently navigated directories
Interface: goto recent [n]
Performance: <10ms for history retrieval
Dependencies: history-tracking.sh
Tests:
  - List recent directories
  - Handle empty history
  - Limit to N entries
  - Navigate to recent directory by number
Docs: Add to API.md and README.md

Step 2: Create Module (if needed)

Module Template:

#!/bin/bash
# unix-goto - [Module purpose]
# https://github.com/manutej/unix-goto

# Storage location
GOTO_MODULE_FILE="${GOTO_MODULE_FILE:-$HOME/.goto_module}"

# Main function
goto_module() {
    local subcommand="$1"
    shift

    case "$subcommand" in
        list)
            # Implementation
            ;;
        add)
            # Implementation
            ;;
        --help|-h|help|"")
            echo "goto module - [Description]"
            echo ""
            echo "Usage:"
            echo "  goto module list     [Description]"
            echo "  goto module add      [Description]"
            ;;
        *)
            echo "Unknown command: $subcommand"
            return 1
            ;;
    esac
}

Key Module Patterns:

1. Function Naming:

• Public functions: no prefix (goto, bookmark, recent)
• Internal functions: double underscore (__goto_navigate_to, __goto_cache_lookup)
• Variables: UPPERCASE for globals, lowercase for locals

1. Environment Variables: ``bash # Always provide defaults GOTO_INDEX_FILE="${GOTO_INDEX_FILE:-$HOME/.goto_index}" GOTO_CACHE_TTL="${GOTO_CACHE_TTL:-86400}" GOTO_SEARCH_DEPTH="${GOTO_SEARCH_DEPTH:-3}" ``

1. Return Codes:

• 0 - Success
• 1 - General error (not found, invalid input)
• 2 - Multiple matches found (cache lookup only)

Step 3: Add to Loader

Edit goto.sh to load your module in the correct dependency order:

# Add to load sequence (respect dependencies)
source "$GOTO_LIB_DIR/history-tracking.sh"
source "$GOTO_LIB_DIR/module.sh"  # NEW - add after dependencies
source "$GOTO_LIB_DIR/back-command.sh"

Dependency Rules:

• Modules with no dependencies load first
• Modules depending on others load AFTER dependencies
• Main goto-function.sh loads LAST (depends on everything)

Step 4: Integrate with Main Function

Edit lib/goto-function.sh to route commands to your module:

goto() {
    case "$1" in
        module)  # NEW
            if command -v goto_module &> /dev/null; then
                shift
                goto_module "$@"
            else
                echo "⚠️  Module command not loaded"
            fi
            return
            ;;
    esac
}

Step 5: Add Tests (100% Coverage Required)

Test File Template:

#!/bin/bash
# Test suite for [feature] functionality

set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "$SCRIPT_DIR/lib/module.sh"

# Test counters
TESTS_PASSED=0
TESTS_FAILED=0

# Test helper
pass() {
    echo "✓ PASS: $1"
    ((TESTS_PASSED++))
}

fail() {
    echo "✗ FAIL: $1"
    ((TESTS_FAILED++))
}

# Test 1: [Description]
test_feature() {
    # Arrange
    local input="test"

    # Act
    local result=$(function_under_test "$input")

    # Assert
    if [[ "$result" == "expected" ]]; then
        pass "Feature works"
    else
        fail "Feature failed: got '$result'"
    fi
}

# Run tests
test_feature

# Summary
echo ""
echo "Tests passed: $TESTS_PASSED"
echo "Tests failed: $TESTS_FAILED"

[ $TESTS_FAILED -eq 0 ] && exit 0 || exit 1

Test Categories (ALL Required):

1. Unit Tests - Test individual functions
2. Integration Tests - Test module interaction
3. Edge Cases - Test boundary conditions
4. Performance Tests - Validate speed requirements

Example from CET-77 (Recent Directories):