Skip to content

Latest commit

 

History

History
119 lines (86 loc) · 4.65 KB

AGENTS.md

File metadata and controls

119 lines (86 loc) · 4.65 KB

ImmyBot VSCode Extension - Agents.md

Project Overview

This is a VSCode web extension that allows users to edit ImmyBot scripts directly from VS Code. The extension provides:

  • Authentication with ImmyBot instances via Microsoft OAuth
  • Tree view for browsing local and global script repositories
  • In-memory file system for editing scripts using immyfs:// scheme
  • PowerShell language server integration
  • Script management capabilities (create, edit, save, delete)

Architecture

Core Components

Development Setup

Prerequisites

  • Node.js >= 20.0.0
  • npm
  • VSCode
  • PowerShell

Installation

npm install

Development Commands

  • Build: npm run compile-web - Compiles TypeScript to JavaScript
  • Package: npm run package-web - Production build
  • Lint: npm run lint - Runs oxlint + eslint
  • Test: npm run test - Runs web extension tests

Testing Code Changes

IMPORTANT: Always use Test-ImmyBotExtension.ps1 to test code changes instead of manually running individual commands or attempting to gather logs yourself.

Usage

# Test with default 15-second timeout
./Test-ImmyBotExtension.ps1

# Test with custom timeout
./Test-ImmyBotExtension.ps1 -TimeoutSeconds 30

Why Use This Script

The script automatically:

  1. Builds the extension and exits on failure
  2. Creates an isolated VSCode environment with fresh logs
  3. Launches VSCode with the extension loaded
  4. Waits for extension activation and operation
  5. Analyzes logs for extension activity and errors
  6. Cleans up processes and temporary files

This provides a complete test cycle in one command with proper log analysis, eliminating the need for manual build commands, log hunting, or process management.

API Integration

The extension integrates with the ImmyBot REST API:

  • Scripts: /api/v1/scripts/local, /api/v1/scripts/global
  • Authentication: Microsoft OAuth with JWT tokens
  • Categories: Software Detection (0), Software Version Action (2), Function (7), Module (11), Integration (13)
  • Contexts: Metascript (2), CloudScript (4), System (0), User (1)

File Structure

immybot-vscode/
├── src/web/                    # Extension source code
│   ├── extension.ts           # Main entry point
│   ├── authentication.ts      # OAuth authentication
│   ├── immyBotFileSystemProvider.ts  # Virtual file system
│   ├── treeProvider.ts        # Tree view providers
│   ├── scriptManager.ts       # Script management
│   ├── commands.ts            # Command handlers
│   ├── immyBotClient.ts       # API client
│   ├── languageServer.ts      # Language server setup
│   └── types.ts               # TypeScript definitions
├── Test-ImmyBotExtension.ps1  # Testing script
├── package.json               # Extension manifest
└── README.md                  # Basic documentation

Contributing Guidelines

  1. Code Style: Uses oxlint + eslint for linting
  2. Testing: Always use Test-ImmyBotExtension.ps1 for testing changes
  3. Architecture: Follow single responsibility principle
  4. State Management: Centralized state through ExtensionState interface

Security Considerations

  • OAuth tokens stored securely in VSCode's secret storage
  • API keys never logged or exposed in plain text
  • Instance URLs validated against HTTPS pattern
  • User data isolated per VSCode instance

This extension enables seamless ImmyBot script development directly within VSCode, providing a familiar development environment for PowerShell automation scripts.