gh-cadrianmae-claude-marketplace-plugins-code-pointer/skills/code-pointer/references/integration_patterns.md

Integration Patterns for Scripts and Skills

Best practices for using VSCode CLI in automation, scripts, and Claude skills.

Safe File Opening Pattern

Always validate before opening:

FILE_PATH="$1"
LINE="${2:-1}"
COLUMN="${3:-0}"

# Validation
if [[ ! -f "$FILE_PATH" ]]; then
    echo "Error: File not found: $FILE_PATH" >&2
    exit 1
fi

# Convert to absolute path
ABS_PATH="$(cd "$(dirname "$FILE_PATH")" && pwd)/$(basename "$FILE_PATH")"

# Open safely
code -g "$ABS_PATH:$LINE:$COLUMN"

Error Location Navigation

Open file at compiler/linter error location:

# Parse error output
ERROR_FILE="src/main.c"
ERROR_LINE="42"
ERROR_COL="15"

# Open at exact error location
echo "Opening error location: $ERROR_FILE:$ERROR_LINE:$ERROR_COL"
code -g "$ERROR_FILE:$ERROR_LINE:$ERROR_COL"

TODO Finding and Navigation

Search for TODOs and open at location:

# Find all TODO(human) markers
grep -n "TODO(human)" *.py | while IFS=: read -r file line content; do
    echo "$file:$line - $content"
done

# Open specific TODO
code -g publisher.py:36

Interactive TODO selection:

# Create numbered list
grep -n "TODO" *.js | nl

# User selects number, open that file:line
selected_todo=$(grep -n "TODO" *.js | sed -n "${TODO_NUM}p")
file=$(echo "$selected_todo" | cut -d: -f1)
line=$(echo "$selected_todo" | cut -d: -f2)

code -g "$file:$line"

Relative to Absolute Path Conversion

Ensure reliable path resolution:

# Convert relative path to absolute
to_absolute_path() {
    local path="$1"

    if [[ "$path" = /* ]]; then
        # Already absolute
        echo "$path"
    else
        # Convert to absolute
        echo "$(cd "$(dirname "$path")" && pwd)/$(basename "$path")"
    fi
}

# Usage
ABS_FILE=$(to_absolute_path "$RELATIVE_FILE")
code -g "$ABS_FILE:$LINE"

Path with Spaces Handling

Always quote paths:

# Safe quoting function
open_at_line() {
    local file="$1"
    local line="$2"

    # Quote the entire file:line argument
    code -g "$file:$line"
}

# Usage
open_at_line "my project/src/app.js" 42

Multiple File Opening with Context

Open related files with informative output:

echo "Opening MQTT publisher and subscriber files:"

echo "  - Publisher TODO at line 36 (connection setup)"
code -g PiPico/publisher.py:36

echo "  - Subscriber TODO at line 45 (callback implementation)"
code -g PiPico/subscriber.py:45

Window Behavior for Skills

Avoid disrupting user's current work:

# Option 1: New window (safest, doesn't disturb current work)
code -n -g "$FILE:$LINE"

# Option 2: Reuse window (convenient, adds as tab)
code -r -g "$FILE:$LINE"

# Option 3: Default behavior (reuses window)
code -g "$FILE:$LINE"

Recommendation for skills: Use default behavior (no -n or -r) to match user expectations.

Error Handling Wrapper

Comprehensive error handling:

safe_open_code() {
    local file="$1"
    local line="${2:-1}"
    local col="${3:-0}"

    # Validate file exists
    if [[ ! -f "$file" ]]; then
        echo "Error: File not found: $file" >&2
        return 1
    fi

    # Validate line is a number
    if ! [[ "$line" =~ ^[0-9]+$ ]]; then
        echo "Error: Line must be a number: $line" >&2
        return 1
    fi

    # Validate column is a number
    if ! [[ "$col" =~ ^[0-9]+$ ]]; then
        echo "Error: Column must be a number: $col" >&2
        return 1
    fi

    # Convert to absolute path
    local abs_path
    abs_path="$(cd "$(dirname "$file")" && pwd)/$(basename "$file")"

    # Open with error handling
    if ! code -g "$abs_path:$line:$col"; then
        echo "Error: Failed to open file in VSCode" >&2
        return 1
    fi

    echo "Opened $file at line $line, column $col"
    return 0
}

# Usage
safe_open_code "src/app.js" 42 10

Grep Integration

Open grep results at specific line:

# Search for pattern and open matches
pattern="$1"
grep -n "$pattern" *.js | while IFS=: read -r file line content; do
    echo "Found in $file at line $line: $content"
    read -p "Open this file? (y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        code -g "$file:$line"
    fi
done

Git Diff Integration

Open files with changes:

# Get list of changed files
git diff --name-only | while read -r file; do
    # Get first changed line number
    first_change=$(git diff "$file" | grep -m1 "^@@" | \
                   sed 's/^@@ -[0-9,]* +\([0-9]*\).*/\1/')

    if [[ -n "$first_change" ]]; then
        echo "Opening $file at line $first_change (first change)"
        code -g "$file:$first_change"
    fi
done

Context Provision

Always provide context when opening files:

# Good: Tells user why file is being opened
echo "Opening authentication logic at the security vulnerability (line 42)"
code -g src/auth.js:42

# Good: Explains what's at this location
echo "Opening publisher.py at line 36 (MQTT connection TODO)"
code -g publisher.py:36

# Less helpful: No context
code -g file.js:42

Batch Opening with Delays

Avoid overwhelming user with many files:

files_to_open=(
    "file1.js:10"
    "file2.js:20"
    "file3.js:30"
)

for file_spec in "${files_to_open[@]}"; do
    echo "Opening $file_spec"
    code -g "$file_spec"
    sleep 0.5  # Brief delay between opens
done

Platform Detection

Handle different operating systems:

# Detect platform and adjust accordingly
case "$(uname -s)" in
    Linux*)     editor_cmd="code" ;;
    Darwin*)    editor_cmd="code" ;;  # macOS
    CYGWIN*|MINGW*|MSYS*)
        # Windows with Git Bash
        editor_cmd="code"
        ;;
    *)
        echo "Unknown platform" >&2
        exit 1
        ;;
esac

# Use detected command
"$editor_cmd" -g "$FILE:$LINE"