scope

What this skill does

# Scope - Developer Environment Management

Scope is a DevEx tool that helps maintain consistent development environments through automated checks, error detection, and fixes.

## Core Commands

### scope doctor

Run automated environment checks and fixes.

```bash
scope doctor run                   # Run all checks
scope doctor run --only group-name # Run specific group
scope doctor run --fix=false       # Check only, no fixes
scope doctor run --no-cache        # Disable caching
scope doctor list                  # List available checks
```

### scope analyze

Detect known errors in logs or command output.

```bash
scope analyze logs file.log                # Analyze log file
scope analyze command -- cmd args          # Analyze command output
scope analyze --extra-config path file.log # Use additional configs
```

### scope report

Generate bug reports with automatic secret redaction.

```bash
scope report ./script.sh     # Run and report on script
scope report -- command args # Run and report on command
```

### scope-intercept

Monitor script execution in real-time (used as shebang).

```bash
#!/usr/bin/env scope-intercept bash
# Script content here
```

## Configuration Resources

All Scope configurations use Kubernetes-inspired YAML format:

```yaml
apiVersion: scope.github.com/v1alpha
kind: <ResourceType>
metadata:
  name: unique-identifier
  description: Human-readable description
spec:
  # Resource-specific configuration
```

## ScopeKnownError

Define error patterns and provide automated help/fixes for common issues.

### Structure

```yaml
apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: descriptive-error-name
  description: Brief description of what this error means
spec:
  pattern: 'regex pattern to match the error'
  help: |
    Clear explanation of the issue.

    Steps to resolve:
    1. First step
    2. Second step
    3. Where to get help if needed
  fix:
    prompt:
      text: User-friendly prompt asking permission
    commands:
      - first-fix-command
      - second-fix-command
```

### Key Fields

- **pattern**: Regex pattern using ripgrep syntax to match error text
- **help**: Multi-line markdown explanation with resolution steps
- **fix** (optional): Automated remediation configuration
  - **commands**: List of commands to run to fix the error (required)
  - **helpText**: Descriptive text shown if the fix fails (optional)
  - **helpUrl**: Documentation link for manual resolution (optional)
  - **prompt**: User approval before running fix (optional)
    - **text**: Question asking for user permission
    - **extraContext**: Additional context about what the fix does and why approval is needed

**Note:** When a fix is defined, it only runs when the error pattern is detected. The fix is optional - if not provided, only the help text is shown.

### File Organization

Place files in categorized directories:

- Location: `{config-root}/known-errors/{category}/{error-name}.yaml`
- Common categories: `docker/`, `ruby/`, `git/`, `github/`, `mysql/`, `postgres/`, `dns/`, `aws/`
- Include matching `.txt` file with example error for testing

### Example

```yaml
apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: gem-missing-file
  description: A gem source file is missing and fails to be loaded
spec:
  pattern: "/lib/ruby/.* `require': cannot load such file --.*/lib/ruby/gems/.*(LoadError)"
  help: |
    A gem source file is missing. The solution is to reinstall the gems:
    1. Run `bundle pristine`
  fix:
    commands:
      - bundle pristine
    helpText: |
      Bundle pristine failed. Try these steps:
      1. Check your bundle config: bundle config list
      2. Reinstall bundler: gem install bundler
      3. Contact #help-ruby if issues persist
    helpUrl: https://bundler.io/man/bundle-pristine.1.html
    prompt:
      text: |-
        This will reinstall all gems from your Gemfile.
        Do you wish to continue?
      extraContext: >-
        bundle pristine reinstalls gems without changing versions,
        which resolves missing file errors but preserves your lock file
```

### Validation

Validate schema structure:

```bash
brew install sourcemeta/apps/jsonschema
jsonschema validate schema.json known-error.yaml
```

Test pattern matching:

```bash
scope analyze logs --extra-config config-dir/ test-error.txt
```

### Additional Resources

- [Complete example with fix and prompt](https://github.com/oscope-dev/scope/blob/main/examples/.scope/known-error-with-fix.yaml)
- [ScopeKnownError model documentation](https://oscope-dev.github.io/scope/docs/models/ScopeKnownError)

### Pattern Writing Tips

- Use ripgrep regex syntax (similar to PCRE)
- Escape special characters: `\\.`, `\\[`, `\\(`
- Use character classes: `[[:digit:]]`, `[[:alpha:]]`
- Test patterns: `echo "error text" | rg "pattern"`
- Balance specificity vs flexibility to avoid false positives/negatives

## ScopeDoctorGroup

Define environment setup and maintenance checks with automated fixes.

### Structure

```yaml
apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: tool-name
  description: Brief description of what this group does
spec:
  include: when-required # or "by-default"
  needs:
    - dependency-1
    - dependency-2
  actions:
    - name: action-name
      description: What this action checks/fixes
      required: true # default true; false for optional checks
      check:
        paths:
          - 'file-to-watch.txt'
          - '**/*.config'
        commands:
          - ./bin/check-script.sh
      fix:
        commands:
          - ./bin/fix-script.sh
        helpText: |
          What to do if the fix fails.
          Where to get help.
        helpUrl: https://docs.example.com/help
```

### Key Components

#### Include Modes

- **by-default**: Always runs with `scope doctor run`
- **when-required**: Only runs when explicitly specified or as dependency

#### Dependencies

List other groups that must run first in `needs` array. Creates execution graph.

#### Actions

Each action is an atomic check/fix operation that runs in order.

#### Check Logic

Determines if fix should run. Fix runs when:

- **No check defined**: Fix always runs
- **paths specified**: Any file changed or no files match globs
- **commands specified**: Any command exits non-zero
- Both can be combined (OR logic)

#### Fix Section

- **commands**: List of commands to run in order
- **helpText**: Shown if fix fails (markdown supported)
- **helpUrl**: Optional link to documentation

### File Organization

- Application setup: `{config-root}/application/`
- Environment setup: `{config-root}/environment/`
- Project-specific: `.scope/` in project root

### Example

```yaml
apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: ruby-version
  description: Set up Ruby with correct version
spec:
  include: when-required
  needs:
    - ruby-manager
    - homebrew
  actions:
    - name: install
      description: Ensures correct version of ruby is installed
      check:
        paths:
          - '{{ working_dir }}/.ruby-version'
        commands:
          - ./bin/ruby-version.sh verify
      fix:
        commands:
          - ./bin/ruby-version.sh install
        helpText: |
          Ruby installation failed.
          Contact: #help-channel
```

### Script Conventions

Create helper scripts following check/fix pattern:

```bash
#!/usr/bin/env bash
set -euo pipefail

ACTION="${1:-check}"

check() {
  # Return 0 if check passes, non-zero if fix needed
  if [[ condition ]]; then
    echo "Check passed"
    return 0
  else
    echo "Check failed" >&2
    return 1
  fi
}

fix() {
  # Perform fix, return 0 on success
  echo "Running fix..."
  # Fix commands here
  return 0
}

case "$ACTION" in
  check) check ;;
  fix) fix ;;
  *)
    echo "Usage: $0 [check|fix]" >&2
    exit 1
    ;;
esac
```

Script best practices:

- Use relative paths with `./` prefix (relative to YAML file)
- Make scri