GWF Build Tools

GWF Build Tools is the VSCode frontend for gwf-build.

The extension does not carry build rules by itself. Project discovery, SDK sync, log lookup, validation, local build, and remote release request flows are all delegated to the repository root entrypoint gwf-build plus Tools/BuildPlatform/config/*.yaml.

Architecture

• Thin frontend, thick backend
• Project metadata comes from gwf-build projects --json
• Single-project detail lookup comes from gwf-build project --project <id> --json
• Platform validation comes from gwf-build validate --json
• Latest log lookup comes from gwf-build logs --project <id> --latest --json
• Project log list lookup comes from gwf-build logs --project <id> --json
• Release request list lookup comes from gwf-build requests --project <id> --json
• Generate, SDK sync, local build, deploy, and remote release all call gwf-build

This keeps build logic in one place and avoids duplicating platform rules in the extension layer.

Current Commands

The extension currently exposes:

• GWF: Refresh Projects
• GWF: Validate Platform
• GWF: Show Project Details
• GWF: Generate Project
• GWF: Preview Generate
• GWF: Sync SDK
• GWF: Local Build
• GWF: Preview Local Build
• GWF: Create Remote Release Request
• GWF: Preview Remote Release
• GWF: Deploy Project
• GWF: Preview Deploy
• GWF: Browse Release Requests
• GWF: Open Latest Log
• GWF: Browse Project Logs

The GWF Projects explorer view shows:

• project type
• local-dev dependency mode
• blocker count
• sdk/source dependency summary in tooltip
• remote-release mode summary
• remote launch host information when configured

Use GWF: Show Project Details to open the live project descriptor as JSON. Use GWF: Browse Project Logs to pick a recent log file from a list. Use GWF: Browse Release Requests to open a historical remote release request.

The extension also provides dedicated side views:

• GWF Recent Logs
• GWF Release Requests

These views follow the currently selected project in GWF Projects. If no project is selected, they fall back to the active editor's project when possible.

Prerequisites

Before using the extension:

• open the gwframework repository root in VSCode
• ensure gwf-build.py exists in the repository root
• on Windows, keep gwf-build.ps1 available in the repository root
• ensure a local Python runtime is available
• ensure Tools/BuildPlatform/config contains valid platform, workspace, toolchain, and project configuration

Command invocation policy:

• Windows: prefer gwf-build.ps1
• Linux/macOS: use gwf-build.py

All command output is written to the GWF Build output channel.

Useful settings:

• gwfBuild.defaultSdkMode
• gwfBuild.autoSyncSdk
• gwfBuild.recentLogLimit
• gwfBuild.recentRequestLimit

Recommended Workflow

For local development:

1. Open the gwframework repository root.
2. Run GWF: Refresh Projects.
3. Run GWF: Validate Platform.
4. Optionally run GWF: Show Project Details.
5. Select a target project in the GWF Projects view.
6. Optionally run GWF: Preview Generate.
7. Run GWF: Sync SDK.
8. Optionally run GWF: Preview Local Build.
9. Run GWF: Local Build.
10. If the build fails, run GWF: Open Latest Log or GWF: Browse Project Logs.

For remote release request creation:

1. Select the target project in the explorer view.
2. Optionally run GWF: Preview Remote Release.
3. Optionally run GWF: Preview Deploy.
4. Run GWF: Create Remote Release Request.
5. Enter the baseline and optional notes.
6. Let gwf-build remote-release generate the manifest.
7. Use GWF: Browse Release Requests to reopen previous manifests.

For direct remote deployment:

1. Select the target project in the explorer view.
2. Optionally run GWF: Preview Deploy.
3. Run GWF: Deploy Project.
4. Enter host, user, optional source/target directories, and optional SSH key.
5. Confirm the deploy target before the extension runs gwf-build deploy.
6. Use GWF: Open Latest Log or GWF: Browse Project Logs to inspect the deploy log.

Onboarding a New Subsystem

Adding a new App or Data subsystem should normally not require extension code changes.

Recommended integration steps:

1. Add a new project descriptor under Tools/BuildPlatform/config/projects/.
2. Define project_root, supported_targets, and legacy.adapter.
3. Define workspace_modes.local-dev.
4. Define workspace_modes.remote-release.
5. Add sdk_dependencies if the project should build against staged SDK content.
6. Run gwf-build validate --json.
7. Run GWF: Refresh Projects in VSCode.

If the project descriptor is correct, the new subsystem should appear automatically in the project tree.

Relation To Permission Isolation

This extension is part of the permission-isolation strategy, but it is not the enforcement point by itself.

The intended model is:

• local developers work through local-dev
• dependencies are staged into SDK workspaces whenever possible
• the extension exposes a unified entrypoint instead of full internal build orchestration
• full source integration and packaging stay in remote-release

This allows engineers with subsystem permissions to compile through:

• VSCode extension
• gwf-build
• project configuration

without exposing the full platform internals directly in day-to-day workflows.

Development And Packaging

Key files:

• package.json
• extension.js

Static syntax check:

node -c .\extension.js

Extension Host smoke test for Deploy Project:

npm run smoke:deploy

Live deploy validation for team reuse:

.\smoke\run-live-deploy.ps1 -Project app.converter -SshHost 172.168.1.121

Detailed usage, safety defaults, and team examples are documented in smoke/README.md.

If vsce is available, package the extension with:

npm run package:no-deps

Expected artifact:

gwf-build-tools-0.1.0.vsix

Next Steps

Useful next backend and extension improvements:

• add CI checks and VSIX packaging automation