VS Code extension

Official Visual Studio Code extension for .pk template files and .pkc component files, with embedded language servers for every block type.

Overview

The extension speaks LSP to the bundled pikopls binary for <template> blocks (hover, completions, go-to-definition, document symbols). The other block types delegate to dedicated language servers. gopls handles <script type="application/x-go">, the built-in CSS server handles <style>, the JSON server handles <i18n>, and the TypeScript server handles <script lang="ts">.

For Go code, the extension does more than route by block. It proxies hover, completion, go-to-definition, and signature-help requests to gopls through virtual Go documents. Embedded Go gets cross-file IntelliSense as if it lived in a plain .go file. A context-aware comment toggler reads the block and directive under the cursor. It picks HTML comment syntax inside markup and expression comment syntax inside p-if, p-for, and the other directives. It does not guess from the file language alone.

Nine snippets cover routine scaffolding. They build full pages and partials (ppage, ppartial), individual blocks (ptemplate, pscript, pstyle, pi18n), slots (pslot, pslot:), and partial includes (pinclude).

Requirements

VS Code 1.107 or higher.
A Go toolchain matching the project's go.mod.
gopls on PATH (go install golang.org/x/tools/gopls@latest).
Recommended: the official Go extension (ms-vscode.go).

The bundled pikopls proxies Go requests to gopls, which builds against your installed Go toolchain. If go.mod requires a newer Go than the one on PATH, Go features in <script> blocks fail with a go.mod requires go >= X.Y.Z error. Set GOTOOLCHAIN=auto so the toolchain downloads the required version on demand, or upgrade Go to match the project.

Installation

The extension is not yet on the marketplace. Build and install it from the repository.

First build the per-platform pikopls binaries that ship inside the extension. The package looks them up under bin/<os>-<arch>/pikopls, and a missing binary fails at activation with Bundled pikopls binary not found.

make build-lsp-all

Then package and install the extension. vsce package names the file from the manifest version, so the current build produces piko-0.0.0.vsix.

cd plugins/vscode
npm install
npm run compile
npm run package
code --install-extension piko-0.0.0.vsix

Configuration

Settings live under the piko.* namespace in VS Code's settings UI.

Setting	Type	Default	Description
`piko.lspPath`	string	`""`	Custom path to `pikopls`. Empty means use the bundled binary.
`piko.trace.server`	enum	`"off"`	LSP trace level: `"off"`, `"messages"`, or `"verbose"`.
`piko.enableTemplateSupport`	boolean	`true`	Enable the Piko LSP for `<template>` blocks.
`piko.enableFormatting`	boolean	`false`	Experimental document formatting. It has known issues, so leave it disabled.
`piko.enableFileLogging`	boolean	`true`	Write LSP logs to `/tmp/pikopls-<pid>.log`.
`piko.goBinPath`	string	`""`	Path to the Go binary directory. Empty means auto-detect.
`piko.detectGoFromExtension`	boolean	`true`	Read the Go path from the Go extension settings (`go.goroot`, `go.alternateTools`).
`piko.searchGlobalGoLocations`	boolean	`true`	Search common Go install locations such as `/usr/local/go/bin`, Homebrew paths, and `~/sdk/go*/bin`.
`piko.enablePprof`	boolean	`false`	Expose a pprof server for the LSP.
`piko.pprofPort`	number	`6060`	Port for the pprof server.

Go-path discovery runs in layers by default. The extension reads the Go extension's go.goroot and go.alternateTools, then searches the common install locations, so most projects need no manual goBinPath. Set goBinPath only to override the result.

The extension launches pikopls over TCP. The transport settings (piko.useExternalServer, piko.externalServerPort, piko.useStdioTransport) exist for debugging against an external server and are not part of routine setup.

Recommended workspace settings:

{
  "[piko]": {
    "editor.suggest.insertMode": "replace"
  },
  "emmet.includeLanguages": {
    "piko": "html"
  }
}

Commands

Command	Description
Piko: New Piko File	Create a new `.pk` file from a template.
Piko: Restart Language Server	Restart `pikopls`.
Piko: Show Output	Open the LSP output channel.
Piko: Open LSP Logs	Open `/tmp/pikopls-main.log`.