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 scripts idempotent (safe to run multiple times)
• Exit 0 for success, non-zero for failure
• Write errors to stderr
• Include helpful error messages

Caching

File-based checks use content hashing:

• Cache stores file path and content hash
• Only re-runs if file contents change
• Persists between runs
• Disable with --no-cache

ScopeReportLocation

Configure where and how bug reports are uploaded.

GitHub Issues

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: github
spec:
  destination:
    githubIssue:
      owner: org-name
      repo: repo-name
  additionalData:
    nodeVersion: node -v
    rubyPath: which ruby

Authentication via environment variables:

• GitHub App: SCOPE_GH_APP_ID + SCOPE_GH_APP_KEY
• Personal Access Token: SCOPE_GH_TOKEN

Local File System

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: local
spec:
  destination:
    local:
      directory: /tmp/scope-reports
  additionalData:
    pwd: pwd
    username: id -un
    scopeVersion: scope version

RustyPaste

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: rustypaste
spec:
  destination:
    rustyPaste:
      url: http://localhost:8000

Additional Data

Capture environment context with arbitrary commands:

additionalData:
  diskSpace: df -h
  gitBranch: git branch --show-current
  envVars: env | sort

Commands execute at report generation time. Scope automatically redacts secrets.

Common Patterns

Version Check Pattern

actions:
  - name: minimum-version
    description: Ensure minimum version installed
    check:
      commands:
        - ./bin/check-version.sh check tool 1.2.3
    fix:
      helpText: |
        You don't have the minimum version installed.
        Check Managed Software Center for updates.

File-Based Check Pattern

actions:
  - name: config-file
    description: Verify config file exists and is valid
    check:
      paths:
        - .config-file
      commands:
        - test -s .config-file
    fix:
      commands:
        - ./bin/setup-config.sh

Service Health Pattern

actions:
  - name: service-running
    description: Ensure service is running
    check:
      commands:
        - ./bin/check-service.sh
    fix:
      commands:
        - ./bin/start-service.sh
      helpText: |
        Service failed to start.
        Check logs: tail "$(brew --prefix)/var/log/service.log"

Dependency Install Pattern

actions:
  - name: install-packages
    description: Install project dependencies
    check:
      paths:
        - package.json
        - yarn.lock
    fix:
      commands:
        - yarn install

Orchestration Pattern

# Main group that just coordinates dependencies
spec:
  needs:
    - environment-setup
    - database-setup
    - language-runtime
  actions: [] # No actions, just orchestration

Workflow: Creating Known Error

1. Identify error pattern

• Capture actual error output
• Find unique identifying text
• Create regex pattern

1. Create files

   mkdir -p {config-root}/known-errors/category
   touch {config-root}/known-errors/category/error-name.yaml
   touch {config-root}/known-errors/category/error-name.txt

1. Write YAML definition

• Use template structure
• Write clear help text with numbered steps
• Add fix commands if automation is possible

1. Create test file

• Put actual error output in .txt file
• Include enough context for pattern matching

1. Test pattern

   scope analyze logs \
     --extra-config {config-root} \
     {config-root}/known-errors/category/error-name.txt

1. Validate schema

   jsonschema validate schema.json error-name.yaml

Workflow: Creating Doctor Group

1. Define problem domain

• What needs checking/fixing?
• What are the dependencies?
• Application or environment level?

1. Create group file

   # Application-level
   touch {config-root}/application/tool.yaml
   
   # Environment-level
   touch {config-root}/environment/tool.yaml
   
   # Project-specific
   touch .scope/tool.yaml

1. Create helper scripts

   mkdir -p .scope/bin
   touch .scope/bin/tool.sh
   chmod +x .scope/bin/tool.sh

1. Write group definition

• Define metadata (name, description)
• List dependencies in needs
• Create actions for each discrete check
• Reference scripts with relative paths

1. Test the group

   scope doctor list                       # Verify detected
   scope doctor run --only tool            # Test execution
   scope doctor run --only tool --no-cache # Test without cache

1. Add to parent group

Update parent group's needs list if this is a new dependency

Debugging

Known Error Not Matching

• Test regex: rg "pattern" test-file.txt
• Check special character escaping
• Verify pattern exists in test file
• Use scope analyze logs --extra-config with test file

Doctor Check Always Running

• Verify paths globs match files
• Check commands exit 0 on success
• Try --no-cache to rule out caching
• Verify script permissions (executable)

Dependency Issues

• Run scope doctor list to see execution order
• Verify all needs items exist
• Check for circular dependencies
• Use --only to test individual groups

Script Path Issues

• Use ./ prefix for relative paths (relative to YAML)
• Ensure scripts have execute permissions
• Use absolute paths or PATH for system commands
• Verify working directory

Security Features

Automatic Redaction

Scope automatically redacts sensitive information:

• GitHub API tokens
• AWS credentials
• SSH keys
• Environment variable values containing secrets
• Uses patterns from ripsecrets

This makes it safe to capture full environment in reports and share debug output publicly.

Reference

Configuration Structure

config-repository/
├── {config-root}/
│   ├── application/          # App-level (ruby, node, postgres)
│   ├── environment/          # System-level (homebrew, docker, github)
│   ├── known-errors/         # Error definitions by category
│   │   ├── docker/
│   │   ├── ruby/
│   │   ├── git/
│   │   └── ...
│   └── reports/              # Report locations

At Scale

Real-world implementations include:

• 70+ known error definitions
• 30+ doctor groups
• Categories: Docker, Ruby, Git, GitHub, MySQL, Postgres, DNS, AWS
• Reduces time-to-resolution for common issues
• Self-service troubleshooting
• Consistent environments across teams

Additional Resources

See references directory for:

• quick-reference.md - Command cheat sheet and pattern examples
• real-world-examples.md - Production-tested configurations
• testing-guide.md - Comprehensive validation workflows