Normal Framework VS Code Extension

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)

Open the code/nf-vscode-extension folder in VS Code
Press F5 to launch the Extension Development Host
The extension will compile automatically and open a new VS Code window with the extension loaded
Make changes to the code - the watch task will recompile automatically
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:

Connect to an instance:
- Press Ctrl+Shift+P (or Cmd+Shift+P)
- Type "NF: Connect to Instance"
- Enter instance details (name, host, port)
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
Create a hook:
- Run "NF: Create Hook" command
- Select instance and enter hook name
- Edit the hook file that opens
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) ✅

[x] Extension scaffold and build system
[x] gRPC connection management
[x] 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

Review the generated gRPC types:

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

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
Implement file system operations (nfFileSystemProvider.ts):
- Map VS Code file operations to gRPC calls
- Handle errors appropriately
- Add caching for better performance
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.

Normal Framework Remote

Normal Framework