@zoisythe/codex-codeintel 0.0.0-stage → 0.10.1

package/skills/setup-lsp/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: setup-lsp
+description: Configure, install or repair Codex CodeIntel language servers and project checkers for a project or explicitly requested global defaults. Use for setup tasks; ordinary coding with missing tools only needs a brief setup suggestion.
+---
+
+Set up working CodeIntel capabilities for the requested scope. The display name is **setupLSP** and invocation is **`$setup-lsp`**.
+
+1. Identify scope and conventions. Default to the current project; modify `$CODEX_HOME/lsp-client.json` (default `~/.codex/lsp-client.json`) only when the user requests global setup. Read both existing configurations, applicable repository instructions, language manifests, package-manager/lock files, environments, build files and representative source files. Do not read or change Codex directory trust records. Use the absolute project directory as `workspace`.
+2. Reuse explicit commands, nearest project environments and PATH tools, in that order. Check actual startup before replacing configuration. Repair/report a failing installed command at its current location; do not download another version as a fallback. Install missing tools within the chosen scope using the project's conventions: Python uses uv; Node respects the package manager and otherwise prefers pnpm. Reuse Rust toolchains and C/C++ build systems. If an installation fails, record the unavailable capability and continue independent languages. A system change outside the requested scope needs separate authorization; finish the other configuration work first.
+3. Merge configuration using [configuration.md](references/configuration.md). Preserve unrelated settings and explicitly disabled capabilities; arrays replace rather than merge in the plugin. Put reusable defaults in global configuration only for global setup, and project directories, checker commands and coverage in project configuration. New configurations enable nonblocking `postToolUse="delta"` and `stop="errors"` feedback. Preserve existing automatic-off choices. Never enable `stopGate` automatically, and never put it in project configuration.
+4. Cover the actual project using [languages.md](references/languages.md). Configure Python ty and Ruff independently, appropriate TypeScript LSP and type/lint checks for each package, Go module checks, Cargo workspace checks, and C/C++ compilation databases. Set coverage to the command's actual input set, including exclusions. If the C/C++ checker cannot emit supported JSON/SARIF, keep clangd capabilities and explain the project-check gap. A successful check of one source file does not establish whole-project coverage.
+5. Verify capabilities through the installed plugin. Call `status` with `refresh=true` and representative paths; it only resolves tools and reports state. Run `diagnostics` for those paths, exercise a read-only navigation operation such as definition or symbols, and run `check`, following structured `next` until finished. Diagnose pending, failed or uncovered results. Do not count `command -v` or `--version` alone as completion. Use an isolated fixture when the user project lacks a usable representative; state that verification limit. rename and format only generate plans; apply is the only source writer. Do not call apply unless the user authorized the corresponding edits.
+6. Report exact configuration paths changed, tools installed, verified capabilities, remaining gaps and recovery steps. Automatic feedback requires a current host with native async Hooks and Interrupt. After Hook definitions change, tell the user to review /hooks and start a new session; never modify Hook trust records. Subagents only report independently; only the main Stop may use the user's existing global gate. Partial setup is useful: an unavailable checker never prevents ordinary editing or verification of other languages.
+
+This skill is normally discoverable, but installation/configuration changes belong to setup, installation or repair requests. During ordinary coding, explain missing capability once and suggest `$setup-lsp`; continue the coding task without repeated installs, retries or a setup prerequisite.

package/skills/setup-lsp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "setupLSP"
+  short_description: "Configure and verify project language tools"
+  default_prompt: "Use $setup-lsp to configure and verify CodeIntel tools for this project."

package/skills/setup-lsp/references/configuration.md

@@ -0,0 +1,35 @@
+# CodeIntel configuration
+
+Read `$CODEX_HOME/lsp-client.json` (or `~/.codex/lsp-client.json`) and `<workspace>/.codex/lsp-client.json`. Built-in defaults < global < project. Settings merge by field/language; each language's LSP entry and all arrays replace wholesale. Both files use `schemaVersion: 1`. Preserve unrelated entries and user-off settings. Repair a malformed file according to its existing intent.
+
+A new project feedback configuration can start with:
+
+```json
+{
+  "schemaVersion": 1,
+  "automaticDiagnostics": { "postToolUse": "delta", "stop": "errors" },
+  "projectChecks": "auto",
+  "lsp": { "python": "ty", "typescript": "typescript", "go": "gopls", "cpp": "clangd", "rust": "rust" },
+  "lint": { "python": "auto", "javascript": "auto" }
+}
+```
+
+Limit language additions to the project and preserve existing choices. No configuration means automatic feedback is off while all ten MCP tools remain explicitly callable. `automaticDiagnostics.stop="errors"` is feedback only. Ending gates require a separately authorized **global** `stopGate="introduced-errors"`; setup never enables it automatically. An existing global choice is preserved. Project `stopGate` is ignored. No plugin trust field or environment variable is required.
+
+LSP entries are a built-in name, `false`, or `{command: [program, ...args], extensions: [".ext"], env?: {KEY: "value"}, initialization?: {...}, settings?: {...}, languageId?: "language"}`. Use `.py/.pyi`, `.ts/.tsx/.mts/.cts/.js/.jsx/.mjs/.cjs`, `.c/.h/.cpp/.hpp` and `.rs` as appropriate for custom servers; do not conflict with enabled built-in extensions. Explicit relative commands resolve from the workspace and never fall back. Built-ins resolve the nearest project environment, then PATH; automatic work never downloads missing tools.
+
+`settings` supplies section-keyed workspace configuration and configuration-change notifications. `languageId` overrides the extension-derived document language for that server. For MATLAB `.m` setup and real-tool validation, read [local LSP acceptance](../../../docs/testing/local-lsp.md).
+
+`lint.python` accepts `auto/ruff/off`; `lint.javascript` accepts `auto/biome/eslint/off`. Lint-off does not disable explicitly requested formatting. `formatting` accepts `tabSize` (1–16) and `insertSpaces`. `exclude` is an array of relative forward-slash globs, without `..`, absolute paths or negation.
+
+For multi-package or custom checks, replace `projectChecks` with the complete desired array. Each entry has a unique `name`, relative `cwd`, nonempty `command` array, `parser`, and nonempty `coverage` globs relative to that cwd. Relative command paths resolve from that cwd. Automatic commands must check without dependency installation or source modification. Output parsers: `tsc`, concise `ty`, JSON `go`/`cargo`, `ruff`, `eslint`, `biome`, `sarif`, and custom `json`:
+
+```json
+{
+  "diagnostics": [
+    { "path": "src/main.c", "line": 1, "column": 1, "severity": "error", "source": "compiler/rule", "message": "description" }
+  ]
+}
+```
+
+Diagnostic paths are relative to the check cwd; positions are 1-based. An empty custom result is `{"diagnostics":[]}`. Coverage must match actual inputs and exclusions, not merely desired coverage. Explicit checks replace automatic discovery, so keep needed checks for every language. See the [usage guide](../../../docs/usage.md#configuration) and [multi-package example](../../../docs/examples/lsp-client.project-checks.json).

package/skills/setup-lsp/references/languages.md

@@ -0,0 +1,40 @@
+# Language setup decisions
+
+Read only the relevant language guidance. Work in the requested project/global scope and verify with real MCP requests after configuration.
+
+## Python
+
+Reuse configured ty commands, package `.venv` executables and PATH installations; Ruff is a separate capability. For an existing uv project, missing project tools can use `uv add --dev ty ruff`, respecting its dependency groups and lockfile. For a project without a managed environment, use `uv venv .venv` then `uv pip install --python .venv/bin/python ty ruff` (use `.venv/Scripts/python.exe` on Windows). Explicit global setup can use `uv tool install ty` and `uv tool install ruff`. Do not synchronize or replace an existing environment merely to repair one executable. Respect the chosen Python version.
+
+Use `"python": "ty"`. Root `pyproject.toml` or `ty.toml` enables auto project type checking. For nested packages or custom scope, use separate checks:
+
+- Types: `[".venv/bin/ty", "check", "--output-format", "concise", "--color", "never"]`, parser `ty`.
+- Lint: `[".venv/bin/ruff", "check", "--no-fix", "--no-fix-only", "--output-format", "json", "src"]`, parser `ruff`.
+
+Set cwd to the package and coverage to its checked Python inputs, respecting ty/Ruff exclusions. Ruff failure should not remove ty diagnostics/navigation; ty failure should not prevent Ruff lint/formatting. Validate types and lint separately when one is missing. Do not infer repair authorization for formatting from a setup request.
+
+## TypeScript / JavaScript
+
+Read `packageManager`, lockfiles, workspace definitions and the effective tsconfig inputs/references. Keep the package manager. With no convention prefer `pnpm`. Choose the LSP that actually starts with the project's installed compiler: the built-in `typescript` uses `typescript-language-server --stdio`; `tsc` uses `tsc --lsp --stdio` and requires native LSP support (TypeScript 7+); `tsgo` requires that executable. An older or incompatible local compiler must be repaired explicitly rather than silently launching a downloaded replacement. Preserve project TypeScript version constraints.
+
+Install only missing project tools with the chosen manager (for example `pnpm add -D typescript-language-server`); global setup uses that manager's user-level global installation conventions. Select Biome or ESLint from existing configuration. Do not invent a new lint system if there is none. Reuse existing scripts only if they check without modifying source and produce a supported format.
+
+For a simple root tsconfig, auto checking reads its effective coverage. For references/multiple packages use explicit per-package type and lint checks. A typical type command is `["node_modules/.bin/tsc", "--noEmit", "--pretty", "false", "-p", "tsconfig.json"]` with parser `tsc`; use actual hoisted/Windows tool paths where appropriate. Biome uses `lint --reporter=json --max-diagnostics=none`; ESLint uses `--format json`. JS type coverage requires both `allowJs` and `checkJs`. Derive globs from each command's actual config, files, include and exclude. Verify representative files from each package.
+
+## Go
+
+Reuse the project's Go version, gopls, modules/workspaces and build flags. Configure `lsp.go="gopls"`; do not replace the module/toolchain to make setup pass. A root go.mod enables `go vet -mod=readonly -json ./...` with parser `go`. Automatic scope is derived from `go list` Go/Test inputs, including platform and build-tag selection. Multi-module workspaces or custom tags require explicit commands and accurate coverage. Prepare dependencies intentionally during setup; automatic checks disable toolchain and module downloads. Verify real diagnostics, definitions/references, and rename/format plans on representative files; apply only if the user authorized modifying them.
+
+## Rust
+
+Reuse `rust-analyzer`, Cargo, rust-src and the pinned Rustup toolchain. Install missing components within the requested toolchain scope only; avoid a workspace toolchain change as a setup shortcut. Root Cargo auto checking uses `cargo check --workspace --all-targets --message-format=json`. Nested workspaces or special features need explicit checks with their actual cwd, flags and coverage. Prepare dependencies intentionally during setup if needed. Automatic checks disable Rustup auto-install; a missing pinned toolchain remains unavailable. Verify actual diagnostics and navigation after indexing, and CLI checking of the workspace. Explain feature or platform coverage limitations.
+
+## C / C++
+
+Reuse clangd and the configured Clang/LLVM or project toolchain. Reuse `compile_commands.json`; if absent, generate it through the project's existing CMake/Meson/other build process with the project's build options. A fallback `compile_flags.txt` is appropriate only when it matches the actual build. Supply clangd's `--compile-commands-dir` via an explicit custom entry if the database is in an undiscovered build directory.
+
+Project checks need structured JSON/SARIF output from a real compiler/checker or an existing read-only wrapper. For a single translation unit on a compatible Clang, `clang -fsyntax-only -fdiagnostics-format=sarif -Wno-sarif-format-unstable` plus the actual compile flags may work with parser `sarif`; restrict coverage to the checked files/headers. Do not concatenate multiple SARIF JSON documents or claim a representative command covers the entire build. Prefer the project's structured checking path for a full build. If unavailable, keep clangd diagnostics/navigation and explain the project-check and reliable-baseline gap. Do not require a new system LLVM installation to finish unrelated language setup.
+
+## Mixed projects and offline failures
+
+Configure each package's cwd and real input coverage. A checker failing in one language does not cancel verification of other languages. Preserve working local tools. If an offline install fails, stop retrying that install, retain usable configuration and explicitly report the missing capability; do not disable the whole workspace or turn on a gate. Verify in isolated project and `CODEX_HOME` directories when evaluating setup examples, so user global configuration remains untouched.