Alp IDE — VS Code extension

First-class IDE support for projects built against the Alp SDK:

board.yaml LSP-native editing. Inline diagnostics, completion, hover, symbols, quick fixes, and effective-config preview run through the language server.
alp_project.py loader commands. Generate Zephyr-conf / DTS overlay / CMake-args / Yocto-conf from board.yaml directly from the command palette.
west workflow wrappers where build runs validate board.yaml -> generate all -> west build, plus dedicated flash / run wrappers with progress reporting.
Debug-aware orchestration. Inspect, doctor, preflight, launch-profile planning, and support-bundle surfaces are available without embedding debugger implementation into the extension.
Models / edge-AI panel — hidden at this pin. A full-tab preview over the tan model CLI whose build action runs tan model build and whose Model Zoo gallery runs tan model zoo / add (#699). The pinned tan 0.8.0 implements all nine model subcommands (tan-cli#674), but its NPU-coverage badge (full-eligible / partial / cpu-only / undetermined), Prep Model, Run Model and A-B Compare screens are not wired to them yet, so the panel says so instead of running them; both of its commands, Alp: Models and Alp: Build Model, are hidden from the command palette (#525). The intent is to re-expose the whole surface once the panel is wired to those subcommands (#524): a before-you-build eligibility badge, INT8 quantization against a calibration folder with an fp32-vs-int8 accuracy report, host-reference single and A-B runs, and a "runs on your SoM" zoo gallery. Even then the badge is a conservative offline estimate and a host run is a reference, not the target SoM's measured performance — power and on-device measurement are hardware-gated.

Screenshots

ALP IDE Hub

ALP IDE Hub overview dashboard

Workspace readiness at a glance — environment, west workspace and Alp SDK status, board-configurator / hardware-explorer / dependencies panels, and quick actions.

Create a new project

New Project — choose a template

Step 1 — pick a starter template: minimal, sensor, IoT, edge-AI, board-diagnostics, or host-tooling.

New Project — pick an E1M module

Step 2 — choose the target E1M module, grouped by vendor (Alif Ensemble, NXP i.MX 9, Renesas RZ/V2N).

New Project — choose an SDK

Step 3 — scaffold against the active SDK or a pinned release.

New Project — name and location

Step 4 — name the project and choose its parent folder.

New Project — live create-at path

The "will be created at …" path updates live as you type the project name.

New Project — review and create

Step 5 — review template, module, cores, SDK, name and location, then scaffold board.yaml, CMakeLists.txt and a starter src/main.c.

Configure `board.yaml`

Configurator — project and hardware

Project & Hardware — SoM SKU, carrier/board preset, and the resolved compute/inference cores + on-module accelerators.

Configurator — per-core OS and libraries

Cores — per-core OS (Zephyr / Yocto), app directory, inference arena, connectivity, peripherals and libraries.

Configurator — linked chip drivers

Chips — link project-wide chip drivers, filtered to the selected SoM family.

Configurator — diagnostics and logging

Diagnostics — default log level, alp_last_error() storage, and per-module log-level overrides.

Configurator — boot, signing, storage and IPC

Advanced — bootloader, image signing, storage partitions, PSA security, OTA provider, and inter-core IPC / RPMsg carve-outs.

Configurator — validation summary

Review — live "board.yaml is valid" with the effective SoM, board, and active cores.

Configurator — effective config preview

Preview the resolved projectContext + effectiveConfig as JSON before building.

Manage SDK releases

SDK Manager — install and switch

List, install, activate and remove versioned Alp SDK releases, each with an expandable changelog.

Install

VS Code Marketplace: search for "Alp SDK". Or grab the latest .vsix from the Releases page and install via Extensions: Install from VSIX.

Alp Platform releases

An Alp Platform release is one version number (YY.M.MICRO, for example 26.11.0) for a bench-validated set of the Alp SDK, tan, this extension and the GD32 and CC3501E bridge firmware. The first line is 26.11 (November 2026); a new line ships every one to two months.

The extension shows the release from the moment it activates:

the status bar reads Alp Platform 26.11.0 for a pinned workspace, or a muted Alp Platform: none when tan supports platforms but nothing is pinned; with a tan that predates tan platform the item is hidden;
clicking it, or running Alp: Platform Release…, opens a menu with the pin and each component (match / mismatch / unknown, installed against pinned), then Switch platform release…, Re-apply pinned release (tan platform use 26.11.0), Clear platform pin (asks first) and Open manifest (.alp/platform.yaml);
Switch platform release… lists the newest version of each line from tan platform list, with an option to show every version and release candidate, and runs tan platform use <version> in a terminal. While the release repository is private, tan needs GITHUB_TOKEN in its environment; without it the extension offers Use a local manifest file… (tan platform use --manifest <file>);
when the SDK, tan or the extension itself differs from the pinned manifest, a warning names each component with its installed and pinned version, once per distinct mismatch, with a Run tan platform use 26.11 button.

The item refreshes when the workspace folders change, when .alp/platform.yaml is saved, and after every tan platform command the extension runs. It reads the pin through tan doctor, never parses the manifest itself, and changes nothing except through tan.

Repo layout

.
├── README.md                -- this file (the only doc in the root)
├── docs/                    -- all project docs (see "Documentation Map" below)
├── LICENSE                  -- Apache-2.0
├── package.json             -- VS Code extension manifest (workspace root)
├── pnpm-workspace.yaml      -- pnpm workspace config
├── tsconfig.json
├── packages/
│   └── alp-core/            -- @alp-sdk/core: shared domain logic
│       └── src/             -- board, configurator, sdk, wizard, ...
├── src/                     -- VS Code extension TypeScript source
│   ├── README.md            -- source folder/module guide
│   ├── extension.ts         -- activation entry point
│   ├── bootstrap.ts         -- extension bootstrap and service wiring
│   ├── configuratorPanel.ts -- board.yaml panel surface
│   ├── diagnostics.ts       -- diagnostics surface wiring
│   ├── loader.ts            -- loader command surface
│   ├── debug.ts             -- debug command surface
│   ├── west.ts              -- west command surface
│   ├── statusBar.ts         -- status bar surface
│   ├── lsp/                 -- LSP client/server/service/commands
│   ├── validation/          -- validation plans and issue classification
│   ├── loader/              -- generation planning and execution contracts
│   ├── debug/               -- debug models and orchestration logic
│   ├── project/             -- workspace and toolchain context resolution
│   ├── boardSummary/        -- compact board summary parsing
│   ├── configurator/        -- board model parse/normalize/serialize
│   └── west/                -- west plan/orchestration logic
├── test/                    -- service and adapter-core unit tests
├── snippets/                -- board.yaml + main.c snippets
├── media/                   -- icons + walkthrough assets
└── alp-sdk-upstream/        -- git submodule -> alplabai/alp-sdk
                                (single source of truth for schemas)

Documentation Map

ARCHITECTURE_RULES.md: Layering, dependency direction, and testing contracts.
PLAN.md: Product goals and phased roadmap.
BACKLOG.md: Epic and issue checklist with current implementation state.
CLI.md: Proposed CLI command families, output contract, and exit-code policy.
CI_EXAMPLES.md: GitHub Actions and GitLab CI examples for Alp CLI validation/generation/doctor flows.
GETTING_STARTED_VSCODE.md: VS Code first-run workflow from install to validation and generation.
GETTING_STARTED_CLI.md: CLI-first workflow for local terminal and CI usage.
EDITOR_FEATURES.md: LSP/editor capabilities for board.yaml authoring.
GENERATION_OUTPUTS.md: Generation targets, output paths, and deterministic output expectations.
SOURCE_SCAFFOLDING.md: Project bootstrap and module scaffolding workflows.
TROUBLESHOOTING_VALIDATION.md: Validation failure diagnosis and recovery flow.
TROUBLESHOOTING_GENERATION_CONFLICTS.md: Generation/scaffolding conflict handling and overwrite safety.
TROUBLESHOOTING_ENVIRONMENT.md: Runtime/toolchain troubleshooting for CLI and VS Code workflows.
TASK_RECIPES.md: Common GUI/CLI task mapping for daily workflows.
TEST_MATRIX.md: Test coverage map by surface and test type.
COMPATIBILITY_RULES.md: Backward compatibility guarantees for schema, generation targets, and CLI contracts.
RELEASE_GATES.md: Required release checks for core, LSP, UI, CLI, and docs.
PERFORMANCE_BUDGETS.md: Performance budgets and regression-check guidance.
DEBUG.md: Debug support matrix and launch strategy.
CONTRIBUTING.md: Dev setup, the CLI release flow, and rollback playbook.
EXTENSION_CLI_INTEGRATION.md: How the extension consumes the standalone tan CLI (binary resolution + the in-process vs delegated split).
BUILD_ORCHESTRATION.md: Wave C plan — the tan CLI drives the build (materialise/execute/schedule/cache/UX) and wraps west/bitbake/cmake directly, consuming the SDK's alp_orchestrate.py --emit build-plan instead of re-implementing the planner; the consumed BuildPlan contract, parity strategy, and phased rollout.
PROPOSAL-alp-build-core.md: the team-to-team agreement record — the settled CLI/SDK split, why we consume --emit build-plan, and the SDK's committed contract seams.
ALP_IDE_ONBOARDING.md / ALP_IDE_SDK_INSTALLATION.md: IDE Hub onboarding and SDK install flows.
src/README.md: Source module map.
src/lsp/README.md: LSP module responsibilities.
src/debug/README.md: Debug module boundaries.
src/loader/README.md: Loader module responsibilities.
src/validation/README.md: Validation module ownership.
src/project/README.md: Workspace/toolchain context rules.
src/wizard/README.md: First-run project wizard responsibilities.

Why a separate repo

The extension previously lived at alp-sdk/vscode/. Split out because:

Different toolchain. TypeScript + esbuild + vsce against Node 18+; nothing in common with the SDK's CMake / Zephyr / Yocto build context.
Different release cadence. VS Code Marketplace releases follow extension-side changes; SDK quarterly tags lag.
Different contributors. Some folks build extensions, some build firmware -- splitting lowers the barrier for the former.

The alp-sdk consumer still gets a one-line install via the Marketplace; no functionality changed.

Schema-sync

When an SDK is resolved, board.yaml and system-manifest.yaml are validated against that SDK's own schemas at <sdkRoot>/metadata/schemas/, so the editor and tan agree by construction (#493). The extension pins no SDK version, so this is the only way the two can agree; the language-status item on those files names which schema is in force.

The vendored copies at schemas/board.schema.json and schemas/system-manifest-v1.schema.json are the fallback for a customer with no SDK yet — the common first-run state — and they are what package.json::contributes.yamlValidation points at. They ship inside the VSIX (alp-sdk-upstream/** is excluded from the package) and are derived from the alp-sdk submodule's schemas at a pinned TAG. Their presence + structure ($id, required) and their sha256 pins are enforced by test/board.schema.vendored.test.js and the CI "vendored schema" check.

Keeping them current still matters: they are what every first-run user is validated against, and an SDK schema this extension refuses (oversized, not a JSON object, or carrying a remote $ref — see packages/alp-core/src/validation/schemaSafety.ts) falls back to them too.

Schema v2 (requires alp-sdk v0.10.0+): board.yaml now uses schema_version: 2 with a per-core cores: block replacing the top-level os: field. Use the alp-board-min or alp-board-hetero snippet to get a valid starting point.

When alp-sdk cuts a release, re-vendor from its TAG — never from main or dev. test/board.schema.vendored.test.js calls re-vendoring from a moving branch "forward drift" and fails on it by design.

TAG=v0.15.0   # the alp-sdk release you are assessing

git -C alp-sdk-upstream fetch origin --tags
git -C alp-sdk-upstream checkout --detach "$TAG"

# 1. BOTH schemas, always together — packages/alp-core/src/validation/
#    vendoredSchemas.ts pins one tag for the pair, so they can never green
#    while disagreeing. (test/vendored-sdk-tag.js re-exports it for the gates.)
git -C alp-sdk-upstream show "$TAG:metadata/schemas/board.schema.json" \
  > schemas/board.schema.json
git -C alp-sdk-upstream show "$TAG:metadata/schemas/system-manifest-v1.schema.json" \
  > schemas/system-manifest-v1.schema.json

# 2. Recompute BOTH hashes (LF-normalised — portable, no `shasum` on Windows)
#    and put them, with the tag, in
#    packages/alp-core/src/validation/vendoredSchemas.ts — NOT in test/. The
#    extension reads them at runtime to tell the customer which schema is in
#    force when their resolved SDK ships a different one (#493).
node -e "const f=require('fs'),c=require('crypto');for(const p of ['schemas/board.schema.json','schemas/system-manifest-v1.schema.json'])console.log(p,c.createHash('sha256').update(f.readFileSync(p,'utf-8').replace(/\r\n/g,'\n'),'utf-8').digest('hex'))"

# 3. Regenerate BOTH vendored Kconfig artefacts. The .txt fixture carries no
#    submoduleRev and its test only asserts curated ⊆ vendored, so a stale copy
#    stays GREEN — nothing will remind you.
node scripts/vendor-kconfig-metadata.mjs
node scripts/vendor-kconfig-symbols.mjs

# 4. tsc --build is incremental and re-copies src/**/*.json only when a .ts
#    changes, so out/ keeps the PREVIOUS harvest without this. The
#    "compiled metadata copy is not stale" gate catches it if you forget.
pnpm exec tsc --build --force

# 5. The gitlink may carry skip-worktree locally (a per-clone index bit, not
#    committed), in which case `git add alp-sdk-upstream` is a silent no-op and
#    the pin stays behind while the schemas move. Check and clear it first.
git ls-files -v alp-sdk-upstream          # a leading `S` means skip-worktree
git update-index --no-skip-worktree alp-sdk-upstream

git add -A
pnpm run format:check && pnpm run typecheck && node --test test/*.test.js
pnpm run package   # builds the .vsix against the new schema

Then record the release in docs/COMPATIBILITY_RULES.md §5 — that log is the only thing tracking which upstream releases were assessed, and two re-vendors (v0.13.0, v0.14.0) shipped without an entry before this was written down.

Build

git clone --recurse-submodules https://github.com/alplabai/alp-sdk-vscode.git
cd alp-sdk-vscode
pnpm install
pnpm run compile    # tsc -> out/ (extension) + webview (vp build)
pnpm test           # compile + lightweight service / adapter tests
pnpm run package    # vsce package -> alp-sdk-<version>.vsix

Load the local build via Extensions: Install from VSIX.

Development

Use pnpm test as the default verification step while changing the extension. Run pnpm run contract:fetch once first: it downloads tan's published envelope-contract.json into the gitignored test/golden/tan-contract/, and pnpm test FAILS without it rather than skipping the contract gate. Offline, TAN_CONTRACT_OFFLINE=1 pnpm test downgrades that failure to a loud skip (ignored when CI is set).

The current test setup is intentionally lightweight:

pure service modules are tested directly
thin adapter seams with injected dependencies are tested without booting VS Code
compile stays part of the test run so API drift is caught early

When changing architecture-sensitive code, prefer keeping this split:

service for pure decision logic
vscodeAdapter for VS Code, filesystem, and subprocess access
adapterCore for runtime-independent seam logic
surface files such as commands, panels, status bar, and diagnostics for presentation and orchestration only

For the full implementation contract, see ARCHITECTURE_RULES.md.

For slice-level ownership and file conventions, see src/README.md and each module-local README.

License

Apache-2.0, same as the SDK.

Alp IDE

Alp Lab AB