Ghost: Replay - VSCode Extension

A VSCode extension for the Ghost error replay system that allows you to browse and replay captured errors directly in your editor.

Features

Explorer Panel: Browse captured error replays organized by function name
Replay Actions: Right-click to replay errors and see results in the output channel
Inspect Inputs: View serialized function inputs with JSON syntax highlighting
CLI Integration: Seamless integration with @sapphy/ghost core library and CLI
Configuration: Customize storage path and behavior via VSCode settings

Installation

From VSIX (Development)

Download the .vsix file from releases
Open VSCode
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Type "Extensions: Install from VSIX"
Select the downloaded .vsix file

From Marketplace (Coming Soon)

Search for "Ghost: Replay" in the VSCode Extensions marketplace.

Usage

Prerequisites

Make sure you have a project using @sapphy/ghost with captured error replays:

npm install @sapphy/ghost

Basic Usage

Open the Explorer: The "Ghost Replays" panel appears in the Explorer sidebar when replays are available
Browse Replays: Replays are organized by function name, then by timestamp
Replay Error: Right-click a replay → "Replay Error" to re-execute with captured inputs
Inspect Inputs: Right-click a replay → "Inspect Inputs" to view the JSON data
Copy Inputs: Right-click a replay → "Copy Inputs JSON" to copy to clipboard

Commands

Available via Command Palette (Ctrl+Shift+P):

Ghost: Refresh Replays - Reload the replay list
Ghost: Clear All Replays - Remove all stored replays (with confirmation)
Ghost: Enable Explorer - Show the Ghost Replays panel

Tree View Structure

FunctionA
  └── 2025-01-15 10:42:33 → TypeError: Cannot read property...
  └── 2025-01-14 16:21:15 → ReferenceError: x is not defined
FunctionB
  └── 2025-01-13 14:55:22 → Error: Invalid input parameter

Configuration

Configure the extension via VSCode Settings (Ctrl+,):

{
  "ghost.storagePath": ".ghost/",
  "ghost.autoRefresh": true
}

Settings

ghost.storagePath: Path to Ghost storage directory relative to workspace root (default: .ghost/)
ghost.autoRefresh: Automatically refresh replay list when files change (default: true)

Integration with Ghost Library

This extension integrates with:

@sapphy/ghost: Core library for error capturing and replay
@sapphy/ghost-cli: Command-line interface (optional)

Example Code

import { withGhost, registerFunction } from '@sapphy/ghost'

// Wrap functions with Ghost
const riskyFunction = withGhost('riskyFunction', (x: number) => {
  if (x < 0) throw new Error('Negative numbers not allowed')
  return x * 2
})

// Register for replay capability
registerFunction('riskyFunction', riskyFunction)

// Errors are automatically captured and available in VSCode
riskyFunction(-5) // This will be captured

Output Channel

Results and logs are displayed in the "Ghost: Replay" output channel:

Replay execution results
Success/failure status
Execution time
Error details and stack traces

Development

Building from Source

# Clone repository
git clone https://github.com/feizk/ghost.git
cd ghost/vscode

# Install dependencies
npm install

# Build extension
npm run build

# Package extension
npm run package

Development Mode

# Watch mode for development
npm run dev

# Type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

Troubleshooting

No Replays Visible

Ensure your project uses @sapphy/ghost
Check that functions are registered with registerFunction()
Verify storage path in settings matches your project structure
Try refreshing with the refresh button

Replay Fails

Ensure original functions are registered for replay
Check the output channel for detailed error messages
Verify function names match between capture and replay

Performance Issues

Clear old replays using "Clear All Replays"
Adjust storage path to avoid large directories
Disable auto-refresh if needed

Contributing

Fork the repository
Create a feature branch
Make changes with tests
Submit a pull request

License

MIT - see LICENSE file for details.

Ghost: Replay

ghost-vscode