Development Setup

Set up your environment for Spry development.

Prerequisites

Required

Deno 2.5+ - TypeScript runtime

curl -fsSL https://deno.land/install.sh | sh
deno --version  # Verify: deno 2.5.x

Git - Version control

git --version  # Any recent version

Getting the Code

# Clone the repository
git clone https://github.com/programmablemd/spry.git
cd spry

# Verify setup
deno task doctor

Project Structure

spry/
├── bin/                    # CLI entry points
│   └── spry.ts            # Main CLI
├── lib/
│   ├── axiom/             # Core engine
│   │   ├── edge/          # Graph edge rules
│   │   ├── io/            # Resource loading
│   │   ├── mdast/         # AST utilities
│   │   ├── orchestrate/   # Task execution
│   │   ├── projection/    # View builders
│   │   ├── remark/        # Remark plugins
│   │   ├── text-ui/       # CLI interface
│   │   └── fixture/       # Test fixtures
│   ├── universal/         # Shared utilities
│   ├── playbook/          # Domain patterns
│   │   └── sqlpage/       # SQLPage integration
│   └── reflect/           # Reflection utilities
├── support/               # Examples and docs
├── deno.jsonc            # Deno configuration
└── import_map.json       # Import mappings

Development Tasks

Available Deno tasks:

# Initialize development environment
deno task init

# Run all tests
deno task test

# Format code
deno task fmt

# Lint code
deno task lint

# Type check
deno task check

# Run pre-commit checks
deno task git-hook-pre-commit

# Sync import map
deno task sync-import-map

Running the CLI

# Run directly
deno run -A bin/spry.ts --help

# Or create an alias
alias spry-dev="deno run -A $(pwd)/bin/spry.ts"
spry-dev rb run example.md

IDE Setup

Install the Deno extension and configure:

.vscode/settings.json

{
  "deno.enable": true,
  "deno.lint": true,
  "deno.unstable": true,
  "editor.formatOnSave": true,
  "[typescript]": {
    "editor.defaultFormatter": "denoland.vscode-deno"
  }
}

Use coc-deno or nvim-lspconfig for Deno support.

Use the Deno plugin available in the marketplace.

Use the LSP package for Deno integration.

Common Development Workflows

Adding a New Feature

Create a feature branch:

git checkout -b feature/my-feature

Make changes and add tests

Run checks:

deno task fmt
deno task lint
deno task test

Commit and push:

git add .
git commit -m "feat: add my feature"
git push origin feature/my-feature

Testing Changes

# Run all tests
deno task test

# Run specific test file
deno test lib/axiom/edge/rule/contained-in-section_test.ts

# Run tests matching pattern
deno test --filter "graph"

# Run with coverage
deno task test --coverage=coverage/

Debugging

# Run with debugger
deno run --inspect-brk -A bin/spry.ts rb run example.md

# Then attach VS Code debugger or Chrome DevTools

Building Releases

# Compile binary
deno compile -A bin/spry.ts -o spry

# Cross-compile
deno compile -A --target x86_64-unknown-linux-gnu bin/spry.ts -o spry-linux
deno compile -A --target x86_64-apple-darwin bin/spry.ts -o spry-macos
deno compile -A --target x86_64-pc-windows-msvc bin/spry.ts -o spry-windows.exe

Troubleshooting

Import Errors

Sync the import map:

deno task sync-import-map

Cache Issues

Clear the Deno cache:

deno cache --reload bin/spry.ts

Permission Errors

Ensure you're using -A or specific permissions when running Deno commands.

deno run -A bin/spry.ts  # All permissions
# Or
deno run --allow-read --allow-write --allow-run bin/spry.ts

Type Errors

Run type check:

deno task check

How is this guide?