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.

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.

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.

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).

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

Configuration Resources

All Scope configurations use Kubernetes-inspired YAML format:

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

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

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:

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

Test pattern matching:

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

Additional Resources

• Complete example with fix and prompt
• ScopeKnownError model documentation

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

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

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:

#!/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 scrip