oh-my-opencode 4.8.0 → 4.9.0

package/packages/shared-skills/skills/lsp-setup/references/php/README.md

@@ -0,0 +1,62 @@
+# PHP — LSP setup
+
+- **Builtin server:** `php` — `intelephense --stdio`
+- **Extensions:** `.php`
+- **Install hint:** `npm install -g intelephense`
+
+## Install
+
+Intelephense is a Node package, so Node.js (and npm) must be installed first.
+
+- **macOS:** `npm install -g intelephense`
+- **Linux:** `npm install -g intelephense`
+- **Windows:** `npm install -g intelephense`
+
+Confirm it resolves:
+
+```bash
+command -v intelephense
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "php": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+Intelephense's premium features (rename, find-all-implementations, declaration providers, etc.) require a licence key. Supply it via `initialization`:
+
+```json
+{
+  "lsp": {
+    "php": {
+      "initialization": {
+        "licenceKey": "YOUR-LICENCE-KEY"
+      }
+    }
+  }
+}
+```
+
+Without a key the server runs fine in free mode.
+
+## Alternatives
+
+- **phpactor** (not builtin): `phpactor language-server`. Pure-PHP, no Node dependency.
+
+## Troubleshooting
+- **PATH:** `intelephense` must be on PATH; reopen the shell after a global npm install. If missing, check `npm bin -g` is on PATH.
+- **No Node:** Intelephense fails to start without Node.js. Install Node, then reinstall.
+- **Wrong PHP version inference:** set `intelephense.environment.phpVersion` via `initialization` to match your project.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.php
+```

package/packages/shared-skills/skills/lsp-setup/references/python/README.md

@@ -0,0 +1,71 @@
+# Python — LSP setup
+
+- **Builtin server:** `basedpyright` — `basedpyright-langserver --stdio`
+- **Extensions:** `.py .pyi`
+- **Install hint:** `pip install basedpyright`
+
+## Install
+
+- **macOS:** `pip install basedpyright` (or `uv tool install basedpyright`)
+- **Linux:** `pip install basedpyright` (or `uv tool install basedpyright`)
+- **Windows:** `pip install basedpyright`
+
+Prefer `uv tool install basedpyright` when the project uses uv — it keeps the
+server isolated from project venvs and always on PATH.
+
+Confirm it resolves:
+
+```bash
+command -v basedpyright-langserver
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "basedpyright": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. Type-check mode is usually set via `pyrightconfig.json`
+or `[tool.basedpyright]` in `pyproject.toml`, not the LSP config.
+
+## Choosing a server
+
+All four are builtin. Type checkers and the linter serve different roles — run a
+type server, and optionally `ruff` ALONGSIDE it (not instead).
+
+| id            | command                       | install                | role                                    |
+| ------------- | ----------------------------- | ---------------------- | --------------------------------------- |
+| `basedpyright`| `basedpyright-langserver --stdio` | `pip install basedpyright` | strictest types, **default**       |
+| `pyright`     | `pyright-langserver --stdio`  | `pip install pyright`  | upstream Microsoft type checker         |
+| `ty`          | `ty server`                   | `pip install ty`       | Astral, very fast, pre-1.0/experimental |
+| `ruff`        | `ruff server`                 | `pip install ruff`     | lint + format only, complements a type server |
+
+Recommended priority: **basedpyright** (default) > pyright > ty (experimental).
+`ruff` complements via priority — it does not type-check, so keep a type server
+enabled.
+
+Enable ruff alongside basedpyright, disabling pyright:
+
+```json
+{ "lsp": {
+  "basedpyright": { "priority": 100 },
+  "ruff": { "priority": 90 },
+  "pyright": { "disabled": true }
+} }
+```
+
+## Troubleshooting
+- **PATH:** `basedpyright-langserver` must be on PATH; reopen shell after install. `uv tool install` writes to `~/.local/bin`.
+- **Wrong interpreter / missing imports:** the server must see the project venv. Set `python.pythonPath` / `venvPath` in `pyrightconfig.json`, or activate the venv before launching.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.py
+```

package/packages/shared-skills/skills/lsp-setup/references/ruby/README.md

@@ -0,0 +1,53 @@
+# Ruby — LSP setup
+
+- **Builtin server:** `ruby-lsp` — `rubocop --lsp`
+- **Extensions:** `.rb .rake .gemspec .ru`
+- **Install hint:** `gem install ruby-lsp`
+
+> **Note:** the builtin id is `ruby-lsp`, but the executable actually invoked is **`rubocop`** (`rubocop --lsp`). RuboCop must be installed: `gem install rubocop`.
+
+## Install
+
+- **macOS:** `gem install rubocop` (and `gem install ruby-lsp` for the install hint's gem)
+- **Linux:** `gem install rubocop`
+- **Windows:** `gem install rubocop`
+
+In a Bundler project, prefer adding `rubocop` to the `Gemfile` and running via `bundle exec`.
+
+Confirm it resolves (check `rubocop`, since that is what runs):
+
+```bash
+command -v rubocop
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "ruby-lsp": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. Behavior is driven by your `.rubocop.yml`; the server surfaces RuboCop diagnostics, formatting, and code actions over LSP.
+
+## Alternatives
+
+- **`ruby-lsp` gem server** (not builtin) — the standalone Shopify Ruby LSP binary (`ruby-lsp` executable), richer navigation than RuboCop alone. Configure as a custom server with `command: ["ruby-lsp"]` in the USER config.
+- **`solargraph`** (not builtin) — older completion/type server; install with `gem install solargraph`, custom `command: ["solargraph", "stdio"]`.
+
+## Troubleshooting
+
+- **PATH:** `rubocop` on PATH (that is the invoked binary, not `ruby-lsp`); reopen shell after install.
+- **`rubocop` not found:** the builtin fails even if the `ruby-lsp` gem is installed — install RuboCop with `gem install rubocop`.
+- **Bundler mismatch:** if the project pins RuboCop in its `Gemfile`, run inside the bundle so versions match.
+- **No diagnostics:** check `.rubocop.yml` is valid and not disabling everything.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.rb
+```

package/packages/shared-skills/skills/lsp-setup/references/rust/README.md

@@ -0,0 +1,59 @@
+# Rust — LSP setup
+
+- **Builtin server:** `rust` — `rust-analyzer`
+- **Extensions:** `.rs`
+- **Install hint:** `rustup component add rust-analyzer`
+
+## Install
+
+- **macOS:** `rustup component add rust-analyzer` (or `brew install rust-analyzer`)
+- **Linux:** `rustup component add rust-analyzer`
+- **Windows:** `rustup component add rust-analyzer`
+
+The rustup component is the recommended path — it stays pinned to your toolchain.
+`rust-analyzer` also needs the `rust-src` component to index the standard library
+(`rustup component add rust-src`).
+
+Confirm it resolves:
+
+```bash
+command -v rust-analyzer
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "rust": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. To switch the check command to clippy:
+
+```json
+{ "lsp": { "rust": { "initialization": { "check": { "command": "clippy" } } } } }
+```
+
+## Alternatives
+
+None — `rust-analyzer` is the official and sole Rust language server.
+
+## Troubleshooting
+- **PATH:** `rust-analyzer` must be on PATH; reopen shell after install. The rustup shim lives in `~/.cargo/bin`.
+- **Exits while loading rust-src:** if rust-analyzer crashes during stdlib indexing, reinstall the source component:
+
+  ```bash
+  rustup component remove rust-src && rustup component add rust-src
+  ```
+
+- **No proc-macro / build script support:** ensure the project builds with `cargo check`; rust-analyzer reuses the same toolchain.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.rs
+```

package/packages/shared-skills/skills/lsp-setup/references/swift/README.md

@@ -0,0 +1,51 @@
+# Swift — LSP setup
+
+- **Builtin server:** `sourcekit-lsp` — `sourcekit-lsp`
+- **Extensions:** `.swift .objc .objcpp`
+- **Install hint:** `Included with Xcode or the Swift toolchain`
+
+## Install
+
+`sourcekit-lsp` ships with the Swift toolchain — no separate install.
+
+- **macOS:** `xcode-select --install` (or install full Xcode). It resolves to the active toolchain selected by `xcode-select`.
+- **Linux:** Install a swift.org toolchain (`sourcekit-lsp` ships inside it); add the toolchain's `usr/bin` to PATH.
+- **Windows:** Install the swift.org Windows toolchain; `sourcekit-lsp` is bundled.
+
+Confirm it resolves:
+
+```bash
+command -v sourcekit-lsp
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "sourcekit-lsp": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. For best results the project needs a **SwiftPM `Package.swift`** or a `compile_commands.json` compilation database so the server can resolve modules. Pure-Xcode-project files without these resolve poorly.
+
+## Alternatives
+
+- **No mainstream alternative.** `sourcekit-lsp` is the official Apple/swift.org server and the only practical choice.
+
+## Troubleshooting
+
+- **PATH:** `sourcekit-lsp` on PATH; reopen shell after install (or after `xcode-select -s`).
+- **Wrong toolchain (macOS):** point `xcode-select` at the right Xcode/toolchain; mismatches cause stale or missing results.
+- **No `Package.swift` / compile db:** add a SwiftPM manifest or generate `compile_commands.json` for accurate indexing.
+- **Objective-C (`.objc`/`.objcpp`):** needs a compilation database to resolve headers and frameworks.
+- **First build slow:** the server builds the module graph on first open; wait for it.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/File.swift
+```

package/packages/shared-skills/skills/lsp-setup/references/terraform/README.md

@@ -0,0 +1,62 @@
+# Terraform — LSP setup
+
+- **Builtin server:** `terraform` — `terraform-ls serve`
+- **Extensions:** `.tf .tfvars`
+- **Install hint:** See https://github.com/hashicorp/terraform-ls
+
+An alias id `terraform-ls` exists with the identical command; either id works.
+
+## Install
+
+- **macOS:** `brew install hashicorp/tap/terraform-ls`
+- **Linux:** download a release from https://github.com/hashicorp/terraform-ls/releases and place `terraform-ls` on PATH (or `apt`/`dnf` via the HashiCorp repo)
+- **Windows:** `choco install terraform-ls` (or download a release zip)
+
+`terraform-ls` requires the `terraform` binary itself to be installed and on PATH.
+
+Confirm both resolve:
+
+```bash
+command -v terraform-ls
+command -v terraform
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "terraform": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. Provider/module completion comes from schemas generated by `terraform init`. Run it in each module root before expecting full completion:
+
+```bash
+terraform init
+```
+
+To force schema indexing, you can set experimental features via `initialization`:
+
+```json
+{ "lsp": { "terraform": { "initialization": { "experimentalFeatures": { "validateOnSave": true } } } } }
+```
+
+## Alternatives
+
+- `tflint` standalone for opinionated linting (complements the LSP).
+- `terraform fmt` for formatting.
+
+## Troubleshooting
+- **PATH:** `terraform-ls` AND `terraform` both on PATH; reopen shell after install.
+- **No provider completion:** run `terraform init` so the `.terraform/` schema cache exists.
+- **`.tfvars` not analyzed:** open the containing module so the server has root context.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.tf
+```

package/packages/shared-skills/skills/lsp-setup/references/typescript/README.md

@@ -0,0 +1,77 @@
+# TypeScript / JavaScript — LSP setup
+
+- **Builtin server:** `typescript` — `typescript-language-server --stdio`
+- **Extensions:** `.ts .tsx .js .jsx .mjs .cjs .mts .cts`
+- **Install hint:** `npm install -g typescript-language-server typescript`
+
+## Install
+
+- **macOS:** `npm install -g typescript-language-server typescript`
+- **Linux:** `npm install -g typescript-language-server typescript`
+- **Windows:** `npm install -g typescript-language-server typescript` (PowerShell or cmd)
+
+`typescript-language-server` is only a thin wrapper — it needs the `typescript`
+package (`tsserver`) present too, either globally or in the project's
+`node_modules`. Always install both.
+
+Confirm it resolves:
+
+```bash
+command -v typescript-language-server
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "typescript": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required. To favor inlay hints or tweak preferences:
+
+```json
+{ "lsp": { "typescript": { "initialization": { "preferences": { "includeInlayParameterNameHints": "all" } } } } }
+```
+
+## Alternatives
+
+All builtin — pick by toolchain. Raise the alternative's `priority` and/or
+`disabled` the default so the file routes to your choice:
+
+| id           | command                                  | when to choose                          |
+| ------------ | ---------------------------------------- | --------------------------------------- |
+| `deno`       | `deno lsp`                               | Deno projects (handles `.ts/.tsx/.js`)  |
+| `biome`      | `biome lsp-proxy --stdio`                | Biome lint/format as the LSP            |
+| `eslint`     | `vscode-eslint-language-server --stdio`  | ESLint diagnostics (install below)      |
+| `oxlint`     | `oxlint --lsp`                           | fast Oxc-based linting                  |
+| `vue`        | `vue-language-server --stdio`            | `.vue` single-file components           |
+| `svelte`     | `svelteserver --stdio`                   | `.svelte` files                         |
+| `astro`      | `astro-ls --stdio`                       | `.astro` files                          |
+
+`eslint` install: `npm i -g vscode-langservers-extracted`.
+
+Pick Deno or Biome over the default:
+
+```json
+{ "lsp": {
+  "typescript": { "disabled": true },
+  "deno": { "priority": 100 }
+} }
+```
+
+(Swap `"deno"` for `"biome"` to use Biome instead.)
+
+## Troubleshooting
+- **PATH:** `typescript-language-server` must be on PATH; reopen shell after `npm i -g`. Check your global bin with `npm bin -g`.
+- **Missing tsserver:** errors like "Could not find tsserver" mean the `typescript` package is absent — install it globally or in the project.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.ts
+```

package/packages/shared-skills/skills/lsp-setup/references/yaml/README.md

@@ -0,0 +1,70 @@
+# YAML — LSP setup
+
+- **Builtin server:** `yaml-ls` — `yaml-language-server --stdio`
+- **Extensions:** `.yaml .yml`
+- **Install hint:** `npm install -g yaml-language-server`
+
+## Install
+
+- **macOS:** `npm install -g yaml-language-server`
+- **Linux:** `npm install -g yaml-language-server`
+- **Windows:** `npm install -g yaml-language-server` (PowerShell)
+
+Confirm it resolves:
+
+```bash
+command -v yaml-language-server
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "yaml-ls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+Schema association is the main reason to configure yaml-ls. Map globs to a schema URL or local path under `yaml.schemas`:
+
+```json
+{
+  "lsp": {
+    "yaml-ls": {
+      "initialization": {
+        "yaml": {
+          "schemas": {
+            "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml",
+            "https://json.schemastore.org/kustomization.json": "kustomization.yaml",
+            "./schemas/my-config.schema.json": "config/*.yaml"
+          },
+          "validate": true,
+          "completion": true,
+          "format": { "enable": true }
+        }
+      }
+    }
+  }
+}
+```
+
+Set `"yaml.schemaStore": { "enable": true }` to auto-resolve schemas from SchemaStore (catalog at https://www.schemastore.org/). Inline `# yaml-language-server: $schema=<url>` modelines also work without config.
+
+## Alternatives
+
+- `redhat.vscode-yaml` bundles the same server in editors.
+- `yamllint` standalone for style/lint-only checks.
+
+## Troubleshooting
+- **PATH:** `yaml-language-server` on PATH; reopen shell after `npm -g` install.
+- **No validation:** no schema matched — add a `yaml.schemas` glob or a `$schema` modeline.
+- **Wrong schema applied:** SchemaStore guessed by filename; pin explicitly under `yaml.schemas`.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.yaml
+```

package/packages/shared-skills/skills/lsp-setup/references/zig/README.md

@@ -0,0 +1,49 @@
+# Zig — LSP setup
+
+- **Builtin server:** `zls` — `zls`
+- **Extensions:** `.zig .zon`
+- **Install hint:** `https://github.com/zigtools/zls`
+
+## Install
+
+ZLS (the Zig Language Server) must be built against the **same Zig version** you use.
+See `https://github.com/zigtools/zls`.
+
+- **macOS:** `brew install zls`
+- **Linux:** download a prebuilt release matching your Zig version, or `zig build -Doptimize=ReleaseSafe` from the zls source
+- **Windows:** download the matching release from the zls GitHub releases, or build from source
+
+Confirm it resolves:
+
+```bash
+command -v zls
+```
+
+## Configure
+
+Builtin — usually NO config needed (auto-resolved by extension). Configure only to set priority, init options, override extensions, or disable. Same JSON shape in `.codex/lsp-client.json` (Codex) AND `.opencode/lsp.json` (OpenCode/omo):
+
+```json
+{ "lsp": { "zls": { "priority": 100 } } }
+```
+
+For builtin ids in a PROJECT config, `command` is supplied automatically — only set `priority`/`initialization`/`extensions`/`disabled`/`env`. A fully custom (non-builtin) server with its own `command` must go in the USER config (`~/.codex/lsp-client.json`).
+
+### Initialization options (only if commonly needed)
+
+None commonly required.
+
+## Alternatives
+
+None.
+
+## Troubleshooting
+- **VERSION MATCH (critical):** zls version MUST match your zig version — build/install zls against the exact same Zig. A mismatch causes crashes, parse errors, or silent failures. After upgrading Zig, upgrade/rebuild zls too.
+- **PATH:** `zls` must be on PATH; reopen the shell after install.
+- **zig not found:** zls invokes `zig` for builds — make sure `zig` itself is also on PATH.
+
+## Verify
+
+```bash
+bun ../../scripts/verify-lsp.ts path/to/file.zig
+```