The PiLot Studio repository is a TypeScript VS Code extension with a Svelte 5 webview. It uses pnpm, esbuild, Vite, and a layered verification script.

Prerequisites

Node.js 24 for development (the shipped extension supports the Node bundled with VS Code 1.105+).
pnpm 11.8.0, the version declared in package.json (packageManager).
VS Code 1.105+ for the integration tests.
On Linux, xvfb if you want the VS Code integration suite to run without opening windows.

The PI SDK is a development dependency but is not bundled. At runtime the loader resolves it from the user's global PI installation.

Clone and install

git clone https://github.com/Printaga/PiLot.git
cd PiLot
pnpm install

pnpm install runs a small postinstall patch script. Keep pnpm-lock.yaml; the project does not use npm or Yarn.

Build

pnpm run build

This runs two builds:

pnpm run webview:build — Vite compiles the Svelte webview into dist/webview/.
pnpm run bundle — esbuild bundles src/extension.ts into dist/extension.cjs and copies loader.cjs and loader-version.cjs into dist/.

The extension's main is dist/loader.cjs. The loader resolves the global PI SDK, checks the 1.4.0 floor, and then requires dist/extension.cjs.

Watch mode

pnpm run webview:dev   # rebuild the webview on change
pnpm run bundle:watch  # rebuild the extension and loader on change

Reload the VS Code window (or the webview) after a rebuild. pnpm run webview:serve starts Vite on port 5173 for browser-side component work, but the VS Code host API is not present there, so host-dependent panels need mocks or a real extension host.

Verification

The repository has two verification levels.

pnpm verify        # fast, deterministic checks
pnpm verify:full   # fast checks + build + VS Code integration tests

`pnpm verify`

Runs, in order:

pnpm run check — tsc plus svelte-check.
pnpm run lint — ESLint.
pnpm run format:check — Prettier.
pnpm run test:unit — Node tests compiled with tsconfig.test.json.
pnpm run test:webview — Svelte component tests in Node + jsdom.
pnpm run fallow:audit — changed-code structural audit against the base branch.

`pnpm verify:full`

Runs the fast checks, then builds before the test stages (the real-host CSP suite loads the shipped dist/webview and the E2E suite needs the bundle), then runs the VS Code integration suite with pnpm test:e2e.

The integration runner:

finds a desktop VS Code installation or uses VSCODE_PATH;
uses xvfb-run on Linux when available;
keeps VS Code logs on failure when PILOT_KEEP_VSCODE_LOGS=1;
can initialize a temporary Git workspace for the commit-message tests.

Individual test suites

pnpm run test:unit
pnpm run test:webview
pnpm run test:e2e

Unit tests cover host logic. Webview tests cover Svelte components. The E2E suite boots a real VS Code window and exercises the extension, including the webview CSP.

Code conventions

TypeScript is strict, with noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride, noImplicitReturns, and noFallthroughCasesInSwitch.
The webview uses Svelte 5 runes. Avoid legacy stores in new components.
Keep changes scoped. Do not weaken types or swallow errors to make a check pass.
Tests must be deterministic: no real network calls, no wall-clock assumptions, no shared mutable state.
pnpm only. Do not create npm or Yarn lockfiles.
The repo uses Husky and lint-staged on commit.

Linting, formatting, and structure

pnpm run lint
pnpm run lint:fix
pnpm run format
pnpm run format:check

The project also uses Fallow for changed-code structural review:

pnpm run fallow:review
pnpm run fallow:audit

fallow:audit emits JSON on stdout and exits non-zero on findings. It resolves its base branch from FALLOW_BASE_REF, then origin/main, then main.

Packaging a VSIX

pnpm run package

This builds the webview and extension, then runs vsce package --no-dependencies. The result is a .vsix you can install with Extensions: Install from VSIX….

The manifest's vscode:prepublish script runs the webview build and bundle automatically when vsce packages the extension.

Continuous integration

The CI workflow runs on pushes to main and pull requests:

checkout with full history for the Fallow audit;
pnpm from packageManager;
Node 24;
pnpm install --frozen-lockfile;
type check, lint, format check;
build;
unit and webview tests;
Fallow audit;
install xvfb and run the VS Code integration suite;
upload VS Code logs on failure, clean temporary profiles on success.

A separate audit workflow runs pnpm audit and the OSV scanner. Dependabot updates are reviewed rather than auto-merged.

Adding a feature

A practical loop:

Read AGENTS.md, the relevant host module, and the webview component that owns the UI.
Add the smallest test that proves the behavior. Host logic belongs in a Node test; webview state belongs in a component test; end-to-end behavior belongs in the VS Code suite.
Implement the host change first, then the webview message and rendering.
Update the message types in src/protocol/types.ts and src/webview/types/index.ts if the bridge changes.
Run the narrowest test, then pnpm verify, then pnpm verify:full if the UI or runtime behavior changed.
Update CHANGELOG.md for user-facing changes.

For a new setting, add it to package.json under contributes.configuration, read it in the host (not just the manifest), document it in Settings, and add a test. A setting that is declared but never read is invisible to users and easy to mistake for a bug.

Releasing

The release process is repository-specific, but the artifacts are standard:

Update package.json and CHANGELOG.md.
Run pnpm verify:full.
Run pnpm run package.
Install the VSIX locally for a smoke test.
Publish to the VS Code Marketplace and Open VSX using your publisher credentials.

The extension requires VS Code 1.105+ and PI 1.4.0+. Do not lower those floors without checking the PI SDK's engines and the loader's minimum version.

License and contributions

PiLot Studio is Apache-2.0. Open issues and pull requests at github.com/Printaga/PiLot. For behavior that belongs to PI itself, the Pi CLI documentation is the upstream reference.