Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/setup-node/action.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: "Setup Node.js"
description: "Sets up Node.js environment and installs dependencies."
inputs:
node_version:
description: "Node.js version to use, e.g. 20.x"
description: "Node.js version to use, e.g. 24.x"
required: false
default: "24.12.0"
pnpm_version:
Expand Down
51 changes: 39 additions & 12 deletions context/PROJECT_OVERVIEW.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,14 @@ The **FastEdge VSCode Extension** is a development tool that enables developers
## Supported Languages

### Rust

- **SDK**: [FastEdge-sdk-rust](https://github.com/G-Core/FastEdge-sdk-rust)
- **Build Tool**: `cargo build --target wasm32-wasip1`
- **Requirements**: `rustup target add wasm32-wasip1`
- **Output**: WASM binary from Cargo.toml configuration

### JavaScript/TypeScript

- **SDK**: [FastEdge-sdk-js](https://github.com/G-Core/FastEdge-sdk-js)
- **Build Tool**: `fastedge-build` (part of SDK)
- **Requirements**: `npm install --save-dev @gcoredev/fastedge-sdk-js`
Expand All @@ -37,6 +39,7 @@ The **FastEdge VSCode Extension** is a development tool that enables developers
The extension registers as a VS Code debugger with type `"fastedge"`. F5 triggers a build → bundled server start → webview panel open flow.

The only launch.json field the extension uses is `"entrypoint"`:

```json
{
"type": "fastedge",
Expand All @@ -47,6 +50,7 @@ The only launch.json field the extension uses is `"entrypoint"`:
```

**Key Features:**

- F5 to launch debug session
- Automatic compilation before running
- Per-app isolated debugger server (port range 5179–5188)
Expand All @@ -56,12 +60,12 @@ The only launch.json field the extension uses is `"entrypoint"`:

The extension provides several VS Code commands:

| Command | Purpose |
|---------|---------|
| `Debug: FastEdge App (Current File)` | Builds active file → starts server → opens debugger panel |
| Command | Purpose |
| ------------------------------------- | ----------------------------------------------------------------- |
| `Debug: FastEdge App (Current File)` | Builds active file → starts server → opens debugger panel |
| `Debug: FastEdge App (Package Entry)` | Builds `package.json` main entry (JS only) → opens debugger panel |
| `FastEdge (Generate mcp.json)` | Adds FastEdge MCP server to workspace |
| `FastEdge (Setup Codespace Secrets)` | Configures GitHub Codespaces secrets |
| `FastEdge (Generate mcp.json)` | Adds FastEdge MCP server to workspace |
| `FastEdge (Setup Codespace Secrets)` | Configures GitHub Codespaces secrets |

### 3. Configuration System

Expand All @@ -76,12 +80,14 @@ Runtime config is managed in two places:
### 4. Compilation System

**Rust Compilation:**

- Locates nearest `Cargo.toml`
- Runs `cargo build --target wasm32-wasip1`
- Extracts binary path from Cargo.toml `[package.name]`
- Output: `target/wasm32-wasip1/debug/{package-name}.wasm`

**JavaScript Compilation:**

- Current File mode: Uses active editor file as entrypoint
- Workspace mode: Uses `package.json` "main" field as entrypoint
- Runs `fastedge-build <input> <output>`
Expand All @@ -90,6 +96,7 @@ Runtime config is managed in two places:
### 5. Runtime Execution

Once compiled, the extension:

1. Starts (or reuses) the per-app bundled debugger server
2. Auto-loads the compiled WASM into the debugger via REST API
3. Opens a webview panel with the debugger UI
Expand All @@ -104,18 +111,21 @@ The debugger server internally uses the bundled `fastedge-run` CLI with configur
## Tech Stack

### Core Technologies

- **Language**: TypeScript
- **Platform**: VS Code Extension API (v1.106.0+)
- **Node**: 20-24.x.x
- **Node**: 22-24.x.x
- **Debugger**: Bundled Node server + webview UI (no DAP)
- **Build Tool**: esbuild (for extension bundling)
- **Package Manager**: pnpm

### Key Dependencies

- `toml` - Parsing Cargo.toml files
- `tree-kill` - Process management

### Development Tools

- TypeScript 5.9+
- ESLint
- VS Code Extension Testing
Expand Down Expand Up @@ -180,6 +190,7 @@ FastEdge-vscode/
## How It Works (High-Level Flow)

### Extension Activation

1. VS Code loads extension on `onStartupFinished`
2. Extension registers:
- Debug configuration provider (F5 `"entrypoint"` routing)
Expand All @@ -188,6 +199,7 @@ FastEdge-vscode/
4. Per-app server/webview instances created lazily on first debug command

### Debug Session Flow

1. User presses F5 or runs `Debug: FastEdge App (Current File / Package Entry)`
2. App roots resolved: `resolveConfigRoot()` + `resolveBuildRoot()` from active file
3. Compilation:
Expand All @@ -201,6 +213,7 @@ FastEdge-vscode/
8. Closing panel → server stops, port file deleted

### Command Execution

1. User invokes command via palette or keybinding
2. Command handler executes:
- `mcpJson.ts` → Adds MCP server config to `.mcp.json`
Expand All @@ -215,43 +228,47 @@ FastEdge-vscode/

Only the `"entrypoint"` field is used:

| Value | Behaviour |
|-------|-----------|
| `"file"` | Build the active editor file |
| Value | Behaviour |
| ----------- | -------------------------------------------------- |
| `"file"` | Build the active editor file |
| `"package"` | Build from `package.json` `"main"` field (JS only) |

All other properties (`port`, `env`, `secrets`, `headers`, etc.) are ignored — configure those in the debugger UI via `fastedge-config.test.json`.

### Extension Settings

| Setting | Description |
|---------|-------------|
| Setting | Description |
| --------------------- | -------------------------------- |
| `fastedge.cliVersion` | FastEdge-run version (read-only) |
| `fastedge.apiUrl` | Default API URL for MCP server |
| `fastedge.apiUrl` | Default API URL for MCP server |

---

## Development Workflow

### Building the Extension

```bash
pnpm install
pnpm run build # Production build
pnpm run build:dev # Watch mode
```

### Testing Locally

1. Open FastEdge-vscode in VS Code
2. Press F5 to launch Extension Development Host
3. Open a FastEdge project in the new window
4. Test debug functionality

### Packaging

```bash
pnpm run package # Creates .vsix file
```

### Installing from VSIX

- VS Code → Extensions → Install from VSIX
- Or from CLI: `code --install-extension fastedge-X.X.X.vsix`

Expand All @@ -260,23 +277,27 @@ pnpm run package # Creates .vsix file
## Key Design Decisions

### Why Bundle FastEdge-run?

- Ensures consistent runtime across all installations
- No external dependencies for users
- Version is tracked in extension settings
- Users can verify CLI version via settings UI

### Why Support Both "File" and "Workspace" Modes?

- **File mode**: Quick iteration on single files (useful for JS)
- **Workspace mode**: Full project builds (required for Rust)
- Flexibility for different development workflows

### Why Dotenv Hierarchy?

- Separates concerns (env vars vs secrets vs headers)
- Allows .gitignore for sensitive files
- Supports large configuration sets
- Compatible with FastEdge-run's expectations

### Why esbuild?

- Fast builds for extension development
- Single bundled output file
- Tree-shaking for smaller extension size
Expand All @@ -296,24 +317,28 @@ pnpm run package # Creates .vsix file
## Common Use Cases

### 1. Developing a New FastEdge App

1. Create project (Rust or JS)
2. Install FastEdge VSCode extension
3. Open a source file and press F5 (or run `Debug: FastEdge App (Current File)`)
4. Extension compiles to WASM, starts debugger server, opens debugger panel
5. Make changes, F5 to rebuild/rerun

### 2. Using Dotenv for Configuration

1. Create `.env` file in project root (or `.env.variables`, `.env.secrets`, etc.)
2. Add variables with prefixes (`FASTEDGE_VAR_ENV_`, `FASTEDGE_VAR_SECRET_`, etc.) or use specialized files without prefixes
3. Press F5 — dotenv files are auto-discovered from the app's config root

### 3. Setting Up MCP Server

1. Run command: `FastEdge (Generate mcp.json)`
2. Provide API token and other details
3. Extension adds MCP server config to workspace
4. Claude Code can now interact with FastEdge API

### 4. Testing in GitHub Codespaces

1. Open project in Codespaces
2. Run command: `FastEdge (Setup Codespace Secrets)`
3. Configure secrets in Codespaces
Expand All @@ -324,6 +349,7 @@ pnpm run package # Creates .vsix file
## Status: Current Features

**Fully Implemented:**

- ✅ Rust compilation and debugging
- ✅ JavaScript/AssemblyScript compilation and debugging
- ✅ Bundled debugger server (per-app isolation, auto start/stop)
Expand All @@ -333,6 +359,7 @@ pnpm run package # Creates .vsix file
- ✅ Command palette commands

**Planned/Future:**

- See GitHub issues for roadmap items

---
Expand Down
22 changes: 11 additions & 11 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
{
"name": "fastedge",
"displayName": "FastEdge Launcher",
"version": "0.2.7-rc1",
"version": "0.2.8",
"publisher": "g-corelabssa",
"description": "Launcher for FastEdge apps",
"icon": "images/fastedge.png",
"repository": "https://github.com/G-Core/FastEdge-vscode",
"engines": {
"vscode": "^1.106.0",
"node": "20 - 24.x.x",
"node": "22 - 24.x.x",
Comment thread
godronus marked this conversation as resolved.
Comment thread
godronus marked this conversation as resolved.
"npm": "^9 || ^10"
},
"categories": [
Expand All @@ -27,7 +27,7 @@
"build": "npm run check-types && node esbuild/build-ext.js --prod",
"package": "vsce package --no-dependencies",
"lint": "eslint src --ext ts",
"test": "vitest run src/**/*.test.ts",
"test": "vitest run --dir src",
"test:integration": "vitest run test/integration",
"fixtures:install": "npm --prefix test/fixtures/js-app install && npm --prefix test/fixtures/as-app install"
},
Expand Down Expand Up @@ -153,20 +153,20 @@
]
},
"devDependencies": {
"@types/node": "^25.0.10",
"@types/node": "^25.9.6",
"@types/vscode": "^1.106.0",
"@typescript-eslint/eslint-plugin": "^8.58.1",
"@typescript-eslint/parser": "^8.58.1",
"@typescript-eslint/eslint-plugin": "^8.70.0",
"@typescript-eslint/parser": "^8.70.0",
"@vscode/vsce": "^3.9.2",
"esbuild": "^0.28.1",
"eslint": "^9.39.4",
"esbuild": "^0.28.2",
"eslint": "^9.39.5",
"typescript": "^5.9.3",
"vite": "^6.4.2",
"vitest": "^4.1.4"
"vite": "^6.4.3",
"vitest": "^4.1.11"
},
"dependencies": {
"jsonc-parser": "^3.3.1",
"toml": "^3.0.0",
"toml": "^5.0.0",
"tree-kill": "^1.2.2"
}
}
Loading
Loading