Deployment Guide

Overview

This guide covers deployment, installation, configuration, and operational aspects of the Warcraft II Notifications Plugin for OpenCode.

Table of Contents

• Installation
• Configuration
• Platform-Specific Setup
• Deployment Architecture
• CI/CD Pipeline
• Monitoring
• Troubleshooting
• Maintenance
• Security

Configuration

Configuration Hierarchy

Project-Specific Configuration

Location: <project>/.opencode/plugin.json

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "soundsDir": "/path/to/project/sounds",
    "faction": "alliance"
  }
}

Use Case: Different sound preferences per project

Global Configuration

Location: ~/.config/opencode/plugin.json

{
  "@pantheon-ai/opencode-warcraft-notifications": {
    "soundsDir": "/home/user/.cache/warcraft-sounds",
    "faction": "horde"
  }
}

Use Case: User-wide default preferences

Environment Variables

# Override data directory
export SOUNDS_DATA_DIR=/custom/sounds/path

# Enable debug logging
export DEBUG_OPENCODE=1

# Override base URL (legacy)
export SOUNDS_BASE_URL=https://custom-cdn.com/sounds

Configuration Options

soundsDir

Type: string (optional)
Description: Custom directory for sound file storage
Default: Platform-specific (see Platform-Specific Setup)

Example:

{
  "soundsDir": "/custom/sounds/path"
}

faction

Type: 'alliance' | 'horde' | 'both' (optional)
Description: Which faction sounds to play
Default: 'both'

Options:

• 'alliance': Play only Alliance unit sounds
• 'horde': Play only Horde unit sounds
• 'both': Play random sounds from both factions

Example:

{
  "faction": "horde"
}

---

Platform-Specific Setup

macOS

Default Locations

# Configuration
~/.config/opencode/plugin.json

# Sound storage
~/Library/Application Support/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/

Required Commands

# Audio playback (built-in)
afplay

# Notifications (built-in)
osascript

Verification

# Test audio playback
afplay /System/Library/Sounds/Glass.aiff

Note: The plugin uses OpenCode’s built-in toast notification system, so no additional notification setup is required.

Linux

Default Locations

# Configuration
~/.config/opencode/plugin.json

# Sound storage (XDG compliant)
~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/

Required Commands

# Audio playback
sudo apt-get install libcanberra-gtk-module  # Ubuntu/Debian
sudo dnf install libcanberra-gtk3            # Fedora
sudo pacman -S libcanberra                   # Arch

Verification

# Test audio playback
canberra-gtk-play --id=message

Note: The plugin uses OpenCode’s built-in toast notification system, so no additional notification setup is required.

Windows

Default Locations

# Configuration
%APPDATA%\opencode\plugin.json

# Sound storage
%APPDATA%\opencode\storage\plugin\opencode-warcraft-notifications\

Status

Note: Windows support is planned for a future release. Currently supported: macOS and Linux.

---

Deployment Architecture

Package Distribution

Package Structure

@pantheon-ai/opencode-warcraft-notifications/
├── index.ts                 # Entry point
├── src/                     # Source code
│   ├── notification.ts
│   ├── plugin-config.ts
│   ├── sounds.ts
│   ├── bundled-sounds.ts
│   └── sound-data/
├── data/                    # Bundled sounds (50+ MB)
│   ├── alliance/
│   └── horde/
├── docs/                    # Documentation
│   └── schemas/
├── package.json
└── README.md

Installation Flow

---

CI/CD Pipeline

Workflow Overview

Workflows

1. Version Update

Trigger: Push to main branch (code changes only)
Purpose: Automatically determine semantic version bump using conventional commits

Steps:

1. Analyze commits since last tag
2. Use conventional commit patterns to determine version type
3. Create version bump PR with updated package.json
4. Auto-merge PR (workflow 3)
5. Create git tag (workflow 4)
6. Tag triggers release (workflow 5)

Version Types:

• MAJOR: Breaking changes (BREAKING CHANGE, !:)
• MINOR: New features (feat:)
• PATCH: Bug fixes, improvements (fix:, chore:, docs:)

2. Release & Publish

Trigger: New git tag (v*)
Purpose: Build and publish package to npm

Steps:

1. Checkout code at tag
2. Install dependencies
3. Run tests
4. Build package
5. Publish to npm
6. Create GitHub release with changelog

3. PR Validation

Trigger: Pull request creation/update
Purpose: Validate code quality before merge

Steps:

1. Run all tests
2. Check linting
3. Verify type checking
4. Check formatting
5. Validate schemas

4. Auto-Merge Bot

Trigger: Version sync PRs
Purpose: Automatically merge version synchronization PRs

Conditions:

• PR created by GitHub Actions
• Title contains “sync package.json version”
• All checks pass

5. Cleanup Workflows

Cleanup Old Releases:

• Runs weekly
• Keeps last 10 releases
• Deletes older releases

Cleanup Merged Branches:

• Runs on PR merge
• Deletes merged feature branches

Deployment Checklist

• All tests pass
• Linting passes
• Type checking passes
• Documentation updated
• Version bump appropriate
• No breaking changes (unless MAJOR)
• Changelog generated

---

Monitoring

Health Checks

Plugin Installation

# Check if plugin is installed
ls -la ~/.cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications/

# Check plugin version
cat ~/.cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications/package.json | grep version

Sound Files

# Check sound directory
ls -la ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/

# Count alliance sounds
ls -1 ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/alliance/ | wc -l

# Count horde sounds
ls -1 ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/horde/ | wc -l

Configuration

# Check project config
cat .opencode/plugin.json

# Check global config
cat ~/.config/opencode/plugin.json

# Check environment variables
echo $SOUNDS_DATA_DIR
echo $DEBUG_OPENCODE

Debug Logging

Enable debug mode:

DEBUG_OPENCODE=1 opencode

Debug Output:

• Configuration loading attempts
• Sound installation progress
• File operation results
• Event handling
• Error details

Performance Metrics

Plugin Load Time: < 100ms
Sound Installation Time: < 5s (first run)
Event Response Time: < 50ms
Memory Footprint: < 10MB

---

Troubleshooting

Common Issues

1. Sound Not Playing

Symptoms: No sound when session goes idle

Diagnosis:

# Check if sound files exist
ls -la ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/alliance/

# Check platform commands
which afplay        # macOS
which canberra-gtk-play  # Linux

# Test sound playback manually
afplay ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/alliance/human_selected1.wav

Solutions:

1. Files missing: Reinstall plugin or manually copy from data/
2. Permission issues: chmod 644 *.wav
3. Command missing: Install required packages (see Platform-Specific Setup)

2. Wrong Faction Playing

Symptoms: Horde sounds play when Alliance is configured

Diagnosis:

# Check configuration
cat .opencode/plugin.json
cat ~/.config/opencode/plugin.json

Solutions:

1. Verify faction setting in configuration
2. Check configuration precedence (project > global > default)
3. Restart OpenCode after configuration changes

3. Configuration Not Loading

Symptoms: Custom configuration ignored

Diagnosis:

# Validate JSON syntax
cat .opencode/plugin.json | jq .

# Check file permissions
ls -la .opencode/plugin.json

Solutions:

1. Fix JSON syntax errors
2. Ensure file is readable: chmod 644 .opencode/plugin.json
3. Verify plugin name matches exactly: @pantheon-ai/opencode-warcraft-notifications

4. Plugin Not Loading

Symptoms: Plugin doesn’t activate

Diagnosis:

# Check if plugin is installed
ls -la ~/.cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications/

# Check OpenCode config
cat ~/.config/opencode/opencode.json

Solutions:

1. Verify plugin is in opencode.json configuration
2. Reinstall plugin: Remove from cache and restart OpenCode
3. Check OpenCode logs for errors

5. Notification Not Showing

Symptoms: Sound plays but no notification appears

Diagnosis:

# Test notification manually
osascript -e 'display notification "Test" with title "OpenCode"'  # macOS
notify-send 'OpenCode' 'Test'  # Linux

Solutions:

1. macOS: Check System Preferences > Notifications > Script Editor
2. Linux: Install libnotify-bin package
3. Check notification permissions

Debug Workflow

---

Maintenance

Updates

Automatic Updates

Note: OpenCode does NOT auto-update plugins

Manual Update

# Remove plugin from cache
cd ~
sed -i.bak '/"@pantheon-ai\/opencode-warcraft-notifications"/d' .cache/opencode/package.json
rm -rf .cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications

# Restart OpenCode (reinstalls latest)
opencode

Check for Updates

# Check current version
cat ~/.cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications/package.json | grep version

# Check latest version
npm view @pantheon-ai/opencode-warcraft-notifications version

Backup

Configuration Backup

# Backup project config
cp .opencode/plugin.json .opencode/plugin.json.backup

# Backup global config
cp ~/.config/opencode/plugin.json ~/.config/opencode/plugin.json.backup

Sound Files Backup

# Backup sound directory
tar -czf warcraft-sounds-backup.tar.gz ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/

Cleanup

Remove Plugin

# Remove from OpenCode config
# Edit ~/.config/opencode/opencode.json and remove plugin entry

# Remove cached plugin
rm -rf ~/.cache/opencode/node_modules/@pantheon-ai/opencode-warcraft-notifications

# Remove sound files (optional)
rm -rf ~/.local/share/opencode/storage/plugin/@pantheon-ai/opencode-warcraft-notifications/sounds/

Clear Cache

# Clear Bun cache
bun pm cache rm

# Clear npm cache
npm cache clean --force

---

Security

Security Considerations

1. File System Security

Measures:

• No file overwrites (existing files preserved)
• Path validation before operations
• Respect system permissions
• No arbitrary code execution

2. Configuration Security

Measures:

• Configuration is pure JSON (no code execution)
• Path sanitization
• Environment variable scoping
• No sensitive data in configuration

3. Network Security

Measures:

• No runtime network operations
• All sounds bundled with package
• No external API calls
• No telemetry or tracking

4. Dependency Security

Measures:

• Minimal dependencies
• Regular dependency updates
• Automated security scanning (GitHub Dependabot)
• No known vulnerabilities

Security Best Practices

1. Keep plugin updated: Install security patches promptly
2. Verify configuration: Review plugin.json for unexpected changes
3. Monitor file permissions: Ensure sound files have appropriate permissions
4. Use official sources: Install only from npm registry or official GitHub repository

Reporting Security Issues

Do NOT open public issues for security vulnerabilities.

Contact: security@pantheon-ai.com

Include:

• Description of vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

---

Operational Procedures

Deployment Checklist

• Version bump appropriate
• All tests pass
• Documentation updated
• Changelog generated
• No breaking changes (unless MAJOR)
• Security scan clean
• Performance acceptable

Rollback Procedure

If a release has critical issues:

1. Identify last good version:

   npm view @pantheon-ai/opencode-warcraft-notifications versions

2. Install specific version:

   # In opencode.json (example version)
   {
     "plugin": ["@pantheon-ai/opencode-warcraft-notifications@latest"]
   }

3. Report issue: Create GitHub issue with details

4. Fix and release: Follow normal release process

Monitoring Checklist

• Plugin installation successful
• Sound files present
• Configuration loaded correctly
• Events triggering properly
• No errors in logs
• Performance acceptable

---

Documentation Deployment

GitHub Pages

The project documentation is automatically deployed to GitHub Pages at:

URL: https://pantheon-org.github.io/opencode-warcraft-notifications/

Deployment Architecture

The documentation uses GitHub Actions with Astro’s official action:

Key Benefits:

• Official Astro Action: Uses withastro/action@v3 for optimized builds
• No branch management: No need to maintain a separate docs or gh-pages branch
• Automatic on releases: Documentation updates with every release
• Artifact-based: Uses GitHub’s native Pages deployment
• Concurrent safe: Built-in concurrency control prevents conflicts
• Link verification: Validates all internal links before deployment

Deployment Sources:

• ./docs/ - Source markdown documentation files on main branch
• ./pages/ - Astro static site generator configuration
• Builds are completely ephemeral - no tracking of generated artifacts

Automatic Deployment

Documentation is automatically deployed when:

• Releases are published - Documentation updates with each release
• Changes are pushed to main branch in the docs/** or pages/** directories
• Manual workflow dispatch is triggered

Workflow: .github/workflows/deploy-docs.yml

Key Features:

• Static Site Generator: Astro with Starlight theme
• Build Tool: Bun (fast package management and builds)
• Deployment Method: Astro GitHub Action (withastro/action@v3) with native Pages deployment
• Link Verification: Validates all internal links before deployment
• Concurrency Control: Single pages group prevents overlapping deployments
• Permissions: Minimal required permissions (contents: read, pages: write, id-token: write)

Manual Deployment

To manually trigger documentation deployment:

1. Navigate to GitHub Actions
2. Click “Run workflow”
3. Select branch (usually main)
4. Click “Run workflow” button

Expected Duration: 2-5 minutes

Initial Setup

Required: Repository administrator must configure GitHub Pages:

1. Go to repository Settings → Pages
2. Under Build and deployment, select:
   • Source: GitHub Actions
3. Save (if required)

Important:

• No branch selection is needed - deployment uses Actions artifacts
• First deployment creates the github-pages environment automatically
• The workflow requires pages: write and id-token: write permissions
• The Astro action handles build, upload, and artifact management automatically

Verification

After deployment completes (typically 2-5 minutes):

# Check site is live
curl -I https://pantheon-org.github.io/opencode-warcraft-notifications/ | grep "200 OK"

# Open in browser
open https://pantheon-org.github.io/opencode-warcraft-notifications/

# Check deployment status
gh api repos/:owner/:repo/pages/deployments --jq '.[0] | {status, environment, created_at}'

Verification Checklist:

• Documentation site loads at production URL
• Navigation menu works correctly
• All internal links function properly
• Search functionality works
• Images and assets load correctly
• CSS styling is applied
• Mobile view renders correctly
• github-pages environment shows successful deployment

Build Process

The documentation build process consists of two jobs:

Job 1: Build

1. Setup: Checkout repository and setup Bun runtime
2. Dependencies: Install dependencies with frozen lockfile
3. Playwright: Install Playwright browsers for testing
4. Transform: pages/transform-docs.js syncs ./docs/ → ./pages/src/content/docs/
5. Build & Upload: Astro action (withastro/action@v3) handles:
   • Compiling markdown to HTML with Starlight theme
   • Generating static site in ./pages/dist/
   • Uploading build artifacts as Pages artifact
6. Verification: Validate all internal links in the built site

Job 2: Deploy

1. Download: Retrieve Pages artifact from build job
2. Deploy: GitHub Actions deploys to Pages service using actions/deploy-pages@v4
3. Environment: Creates/updates github-pages environment
4. Summary: Generates deployment summary with URL and build details

Build Configuration: pages/astro.config.mjs

export default defineConfig({
  site: 'https://pantheon-org.github.io',
  base: '/opencode-warcraft-notifications',
  outDir: './dist',
  integrations: [
    starlight({
      title: 'Warcraft Notifications',
      description: 'OpenCode plugin for Warcraft II notification sounds',
      // ... sidebar configuration
    }),
  ],
});

Troubleshooting

Site not accessible:

1. Verify GitHub Pages source is set to GitHub Actions (Settings → Pages → Source)
2. Check workflow run status in Actions tab
3. Verify deployment to github-pages environment succeeded
4. Check workflow has required permissions (pages: write, id-token: write)
5. Wait 2-5 minutes for deployment to complete

Build failures:

1. Check workflow logs in Actions tab (both build and deploy jobs)
2. Review Astro build output for errors
3. Verify all markdown files have valid frontmatter
4. Check for broken internal links
5. Ensure dependencies are up to date in pages/bun.lock

Content not updating:

1. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
2. Verify changes were committed to docs/** or pages/** on main branch
3. Check workflow was triggered (Actions tab)
4. Verify both build and deploy jobs completed successfully
5. Check deployment environment shows latest deployment

Permissions errors:

1. Go to Settings → Actions → General
2. Under “Workflow permissions”, ensure:
   • “Read and write permissions” is selected, OR
   • Pages deployment permissions are explicitly granted
3. Manually trigger workflow to retry

Link verification failures:

If internal link verification fails:

# Run link verification locally
cd pages
bun run verify

# Check for broken links in the output
# Fix any broken links in the source markdown files in ./docs/

# Test the build locally
bun run build

Build artifacts in main branch:

Build artifacts should never appear in the main branch. If you see dist/ or .astro/:

# Ensure .gitignore contains build artifacts
echo "dist/" >> .gitignore
echo ".astro/" >> .gitignore
echo "pages/dist/" >> .gitignore
echo "pages/.astro/" >> .gitignore

# Remove from tracking if accidentally committed
git rm -r --cached dist/ pages/dist/ pages/.astro/ .astro/ 2>/dev/null || true
git commit -m "chore: Remove build artifacts from version control"
git push origin main

# Clean local working directory
rm -rf dist/ pages/dist/ pages/.astro/ .astro/

Monitoring

Monitor documentation deployment health:

• Workflow status: GitHub Actions
• Deployment history: Environments → github-pages
• Site availability: Regular HTTP 200 checks
• Build time: Typical deployment takes 2-5 minutes (build + deploy)
• Artifact retention: Build artifacts retained for 90 days

Monitoring Commands:

# Check latest deployment status
gh api repos/:owner/:repo/pages/deployments --jq '.[0]'

# Check workflow runs
gh run list --workflow=deploy-docs.yml --limit 5

# View environment deployments
gh api repos/:owner/:repo/environments/github-pages/deployments --jq '.[]| {created_at, environment, state}'

Migration History

Previous Deployment Method (deprecated):

The project previously used peaceiris/actions-gh-pages@v4 to deploy to a docs branch. This has been replaced with the official Astro GitHub Action.

Current Deployment Method:

Uses withastro/action@v3 which provides:

• Optimized Astro builds
• Automatic artifact upload
• Better caching
• Native GitHub Pages integration
• Built-in link verification

Benefits of Current Approach:

• No branch to maintain or track
• Better concurrency control
• Cleaner git history
• Official Astro support
• Faster builds with caching
• Automatic link verification

Related Documentation

• CI/CD Pipeline - Complete pipeline documentation
• Development Guide - Local documentation development
• GitHub Workflows - Workflow architecture and details

---

Support

Documentation

• README - Quick start guide
• API Documentation - API reference
• Architecture - System design
• Development Guide - Development workflows
• Live Documentation Site - GitHub Pages

Community

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and discussions

Contact

• Email: support@pantheon-ai.com
• GitHub: @pantheon-org

---

Document Version: 1.0
Last Updated: 2025-11-10
Maintained By: Pantheon AI Team