Normal Framework Remote

Connect to Normal Framework instances remotely, manage hooks, browse files, and view logs directly from VS Code.

Features

• 🔌 Remote Connection: Connect to NF instances via gRPC (similar to SSH remote development)
• 📁 Remote File System: Browse and edit files on remote NF instances using custom URI scheme (nf://)
• 🪝 Hook Management: Create, edit, and deploy hooks directly from VS Code
• 📊 Log Viewer: Stream and view logs from connected instances
• 🌳 Tree Views: Organized views for instances, hooks, and logs

Development Workflow

1. Initial Setup

cd code/nf-vscode-extension

# Install dependencies (this will automatically configure the Buf registry via .npmrc)
pnpm install

# The extension is now ready for development

2. Development Cycle

Option A: Using VS Code (Recommended)

1. Open the code/nf-vscode-extension folder in VS Code
2. Press F5 to launch the Extension Development Host
3. The extension will compile automatically and open a new VS Code window with the extension loaded
4. Make changes to the code - the watch task will recompile automatically
5. Press Ctrl+R (or Cmd+R on macOS) in the Extension Development Host to reload

Option B: Using Terminal

# Start the watch task for automatic compilation
pnpm run watch

# In another terminal, run the extension
code --extensionDevelopmentPath=$(pwd)

3. Testing the Extension

Once the Extension Development Host is running:

1. Connect to an instance:

   • Press Ctrl+Shift+P (or Cmd+Shift+P)
   • Type "NF: Connect to Instance"
   • Enter instance details (name, host, port)

2. Browse remote files:

   • Open the NF Explorer in the Activity Bar
   • Click on an instance → Files
   • Or use the URI directly: nf://instance-name/path/to/file

3. Create a hook:

   • Run "NF: Create Hook" command
   • Select instance and enter hook name
   • Edit the hook file that opens

4. View logs:

   • Open the Logs view in the NF Explorer
   • Click on a log stream

4. Debugging

• Set breakpoints in your TypeScript code
• The debugger will attach when you press F5
• Use the Debug Console to inspect variables
• Check the Debug Console and Output panel for extension logs

5. Packaging

# Build for production
pnpm run package

# Create VSIX package for distribution
pnpx @vscode/vsce package

Project Structure

code/nf-vscode-extension/
├── src/
│   ├── extension.ts              # Main entry point
│   ├── connection/
│   │   └── connectionManager.ts  # Manages gRPC connections
│   ├── filesystem/
│   │   └── nfFileSystemProvider.ts # Custom filesystem for remote files
│   └── views/
│       ├── instanceTreeProvider.ts  # Instance tree view
│       ├── hooksTreeProvider.ts     # Hooks tree view
│       └── logsTreeProvider.ts      # Logs tree view
├── package.json                  # Extension manifest
├── tsconfig.json                 # TypeScript configuration
└── webpack.config.js             # Build configuration

Feature Roadmap

Phase 1: Core Infrastructure (Start Here) ✅

• Extension scaffold and build system
• gRPC connection management
• Basic tree views for instances, hooks, and logs
• Integrate actual gRPC service definitions from @buf/normalframework_nf.bufbuild_es
• Implement file system operations (read/write/list) via gRPC

Phase 2: Remote File System (Priority)

• Implement readFile() to fetch files from NF instance
• Implement writeFile() to save files back to instance
• Implement readDirectory() to browse remote file structure
• Add file watching/change notifications
• Support for opening workspace folders with nf:// scheme
• File search within remote instance
• Diff/compare local vs remote files

Phase 3: Hook Development

• Hook template generation
• Syntax highlighting and IntelliSense for hook files
• Hook validation before deployment
• Deploy hook to instance via gRPC
• Hot-reload hooks without restarting instance
• Hook debugging support
• Hook execution history and metrics

Phase 4: Log Streaming

• Real-time log streaming via gRPC streaming
• Log filtering and search
• Log levels and colorization
• Export logs to file
• Log following mode (tail -f equivalent)
• Multiple log sources (app, system, hooks)

Phase 5: Enhanced Features

• Connection profiles and saved configurations
• TLS/SSL support for secure connections
• Authentication and authorization
• Multi-instance management
• Instance health monitoring
• Configuration editor for NF settings
• Command palette integration for common tasks

Phase 6: Developer Experience

• Snippets for common hook patterns
• Code completion for NF API
• Documentation hover tooltips
• Quick fixes and refactoring
• Testing framework integration
• Performance profiling tools

Next Steps

1. Review the generated gRPC types:

   # After pnpm install, inspect the generated types
   ls -la node_modules/@buf/normalframework_nf.bufbuild_es/
   

2. Update the connection manager (connectionManager.ts):

   • Import the actual service definitions from the buf package
   • Replace placeholder client with real gRPC client
   • Implement proper service method calls

3. Implement file system operations (nfFileSystemProvider.ts):

   • Map VS Code file operations to gRPC calls
   • Handle errors appropriately
   • Add caching for better performance

4. Test with a running NF instance:

   • Start an NF instance with gRPC enabled
   • Connect from the extension
   • Try opening and editing remote files

gRPC Service Integration

The extension uses the official NF protocol buffers from buf.build:

// After reviewing the generated types, update imports like:
import { FileService } from '@buf/normalframework_nf.bufbuild_es/path/to/file_service_pb';
import { HookService } from '@buf/normalframework_nf.bufbuild_es/path/to/hook_service_pb';
// etc.

Configuration

Add NF instances in VS Code settings (settings.json):

{
  "nf.instances": [
    {
      "name": "local-dev",
      "host": "localhost",
      "port": 50051,
      "useTLS": false
    },
    {
      "name": "staging",
      "host": "staging.example.com",
      "port": 443,
      "useTLS": true
    }
  ]
}

Troubleshooting

• Extension not loading: Check the Debug Console for errors
• gRPC connection fails: Verify the NF instance is running and accessible
• File operations not working: Ensure the gRPC service methods are properly implemented
• TypeScript errors: Run pnpm install to ensure all dependencies are installed

Contributing

This extension is part of the Normal Framework ecosystem. Contributions are welcome!

License

See the main Normal Framework license.