Hedhog Permissions Manager

Manage route permissions for your Hedhog NestJS projects directly from VS Code.

Features

• Automatic Project Detection: Detects Hedhog projects by checking for hedhog.json and the apps/api directory
• Route Scanning: Automatically scans your NestJS controllers to discover all API routes
• Visual Permission Management: Toggle role permissions with an intuitive UI showing roles as chips/badges
• Migration Generation: Automatically generates Prisma-compatible SQL migrations when you change permissions
• Database Integration: Connects to your PostgreSQL database to read roles, routes, and existing permissions
• Robust Error Handling: Clear error messages and detailed logging for troubleshooting

Requirements

• VS Code 1.85.0 or higher
• A Hedhog project with:
  • hedhog.json file in the workspace root
  • apps/api directory containing a NestJS application
  • apps/api/.env or apps/api/.env.example with DATABASE_URL configured
• PostgreSQL database with the following tables:
  • role (columns: id, slug, name)
  • route (columns: id, url, method)
  • role_route (columns: role_id, route_id)

Installation

From VSIX File

1. Download the .vsix file
2. Open VS Code
3. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
4. Click the "..." menu at the top of the Extensions view
5. Select "Install from VSIX..."
6. Choose the downloaded .vsix file

From Source

# Clone the repository
git clone https://github.com/your-username/hedhog-permissions.git
cd hedhog-permissions

# Install dependencies
npm install

# Compile the extension
npm run compile

# Package the extension (optional)
npm run vsce:package

Usage

Opening the Panel

Once installed in a Hedhog project, the extension will automatically detect your project and you can:

1. Click the Hedhog icon in the Activity Bar (sidebar)
2. Or use Command Palette (Ctrl+Shift+P / Cmd+Shift+P): Hedhog: Open Permissions Panel

Managing Permissions

The panel displays all detected routes with:

• HTTP Method (GET, POST, PUT, DELETE, etc.) with color-coded badges
• Route URL (e.g., /users, /posts/:id)
• Controller Name
• Role Chips: Clickable badges for each role in your system

To toggle a permission:

1. Click on a role chip next to any route
2. Active permissions are shown with a highlighted badge
3. Inactive permissions appear as outlined badges
4. The extension will generate a migration file automatically

Generated Migrations

Migrations are created in: apps/api/prisma/migrations/{TIMESTAMP}_{name}/migration.sql

Example migration names:

• 20250128120000_add_role_admin_to_get_users
• 20250128120030_remove_role_client_from_delete_posts

The migrations contain SQL to:

• Insert routes into the route table (if not exists)
• Insert or delete records in the role_route table

Important: The extension only generates migration files. You need to apply them using your migration tool (e.g., Prisma).

Refreshing Data

Click the "Refresh" button in the panel header to:

• Re-scan routes from your NestJS controllers
• Reload roles and permissions from the database

Configuration

Database Connection

The extension reads the DATABASE_URL from:

1. apps/api/.env (checked first)
2. apps/api/.env.example (fallback)

Example:

DATABASE_URL="postgresql://user:password@localhost:5432/hedhog_db"

Troubleshooting

Extension Not Activating

Check that your workspace has:

• hedhog.json in the root
• apps/api directory

"DATABASE_URL not found"

Ensure you have either apps/api/.env or apps/api/.env.example with the DATABASE_URL variable defined.

"Failed to connect to database"

• Verify your database server is running
• Check that the connection string is correct
• Ensure your database user has proper permissions
• Check the "Hedhog Logs" output channel for detailed error messages

"Missing database tables"

The extension requires these tables:

• role
• route
• role_route

Run your database migrations to create the schema.

View Logs

Open the Output panel and select "Hedhog Logs" from the dropdown to see detailed logging.

Development

Building from Source

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch for changes
npm run watch

# Run tests
npm run test

Packaging

# Install vsce globally
npm install -g @vscode/vsce

# Package the extension
npm run vsce:package

# This creates a .vsix file you can install

Publishing to Marketplace

Before publishing, you need to:

1. Create a Publisher: Go to VS Code Marketplace and create a publisher account

2. Get a Personal Access Token: From Azure DevOps with Marketplace scope

3. Update package.json: Replace "publisher": "your-publisher" with your actual publisher name

4. Publish:

# Login (first time only)
vsce login your-publisher

# Publish
npm run vsce:publish

# Or manually
vsce publish

For detailed instructions, see the VS Code Publishing Extensions Guide.

Architecture

src/
├── extension.ts              # Main extension entry point
├── panels/
│   └── RoutesPanel.ts       # Webview panel UI
└── services/
    ├── HedhogProjectDetector.ts  # Detects Hedhog projects
    ├── DatabaseService.ts        # PostgreSQL connection & queries
    ├── RouteScanner.ts           # Scans NestJS controllers
    └── MigrationService.ts       # Generates SQL migrations

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki

Changelog

See CHANGELOG.md for release notes.

Enjoy managing your Hedhog permissions! 🦔