litclaude-ai 0.3.3 → 0.3.7

package/plugins/litclaude/skills/lsp-setup/references/rust/README.md

@@ -0,0 +1,61 @@
+# Rust — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `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
+
+Add a `rust` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "rust": {
+    "command": ["rust-analyzer"],
+    "extensionToLanguage": {
+      ".rs": "rust"
+    }
+  }
+}
+```
+
+Claude Code routes `.rs` edits to `rust-analyzer` via the extension map. Options
+such as switching the check command to clippy live in `rust-analyzer` settings
+consumed by your editor, not in `.lsp.json`.
+
+## 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
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.rs
+# or: bun ../../scripts/verify-lsp.ts path/to/file.rs
+```

package/plugins/litclaude/skills/lsp-setup/references/swift/README.md

@@ -0,0 +1,60 @@
+# Swift — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `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
+
+Add a `swift` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "swift": {
+    "command": ["sourcekit-lsp"],
+    "extensionToLanguage": {
+      ".swift": "swift",
+      ".objc": "objective-c",
+      ".objcpp": "objective-cpp"
+    }
+  }
+}
+```
+
+Claude Code routes these extensions to `sourcekit-lsp` via the map. For best
+results the project needs a **SwiftPM `Package.swift`** or a
+`compile_commands.json` compilation database so the server can resolve modules.
+
+## 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
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/File.swift
+# or: bun ../../scripts/verify-lsp.ts path/to/File.swift
+```

package/plugins/litclaude/skills/lsp-setup/references/terraform/README.md

@@ -0,0 +1,61 @@
+# Terraform — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `terraform-ls serve`
+- **Extensions:** `.tf .tfvars`
+- **Install hint:** See https://github.com/hashicorp/terraform-ls
+
+## 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
+
+Add a `terraform` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "terraform": {
+    "command": ["terraform-ls", "serve"],
+    "extensionToLanguage": {
+      ".tf": "terraform",
+      ".tfvars": "terraform-vars"
+    }
+  }
+}
+```
+
+Claude Code routes `.tf`/`.tfvars` edits to `terraform-ls` via the map.
+Provider/module completion comes from schemas generated by `terraform init`; run
+it in each module root before expecting full completion:
+
+```bash
+terraform init
+```
+
+## 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
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.tf
+# or: bun ../../scripts/verify-lsp.ts path/to/file.tf
+```

package/plugins/litclaude/skills/lsp-setup/references/typescript/README.md

@@ -0,0 +1,77 @@
+# TypeScript / JavaScript — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `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
+
+LitClaude declares language servers in `plugins/litclaude/.lsp.json`. Each entry
+is keyed by language name and holds a `command` array plus an
+`extensionToLanguage` map. TypeScript/JavaScript already ships in the default
+config:
+
+```json
+{
+  "typescript": {
+    "command": ["typescript-language-server", "--stdio"],
+    "extensionToLanguage": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact",
+      ".mjs": "javascript",
+      ".cjs": "javascript"
+    }
+  }
+}
+```
+
+Add `.mts`/`.cts` to `extensionToLanguage` if your project uses them. Claude Code
+resolves the server for an edited file by matching its extension against these
+maps.
+
+## Alternatives
+
+Swap the `command` for your toolchain. Keep the same `.lsp.json` shape and adjust
+`extensionToLanguage` to cover the extensions that server should own:
+
+| command                                   | when to choose                          |
+| ----------------------------------------- | --------------------------------------- |
+| `["deno", "lsp"]`                         | Deno projects (handles `.ts/.tsx/.js`)  |
+| `["biome", "lsp-proxy", "--stdio"]`       | Biome lint/format as the LSP            |
+| `["vscode-eslint-language-server", "--stdio"]` | ESLint diagnostics                 |
+| `["oxlint", "--lsp"]`                     | fast Oxc-based linting                  |
+| `["vue-language-server", "--stdio"]`      | `.vue` single-file components           |
+| `["svelteserver", "--stdio"]`             | `.svelte` files                         |
+| `["astro-ls", "--stdio"]`                 | `.astro` files                          |
+
+`eslint` install: `npm i -g vscode-langservers-extracted`. To run Deno instead
+of the default, replace the `typescript` entry's `command` with `["deno", "lsp"]`.
+
+## 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
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.ts
+# or: bun ../../scripts/verify-lsp.ts path/to/file.ts
+```

package/plugins/litclaude/skills/lsp-setup/references/yaml/README.md

@@ -0,0 +1,60 @@
+# YAML — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `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
+
+Add a `yaml` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "yaml": {
+    "command": ["yaml-language-server", "--stdio"],
+    "extensionToLanguage": {
+      ".yaml": "yaml",
+      ".yml": "yaml"
+    }
+  }
+}
+```
+
+Claude Code routes `.yaml`/`.yml` edits to `yaml-language-server` via the map.
+Schema association is the main reason to tune the server, but those options
+travel through the editor's LSP `initializationOptions` (`yaml.schemas`,
+`yaml.schemaStore`), not `.lsp.json`. An inline
+`# yaml-language-server: $schema=<url>` modeline works without any config:
+
+```yaml
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+```
+
+## 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 `$schema` modeline or a `yaml.schemas` mapping in your editor's init options.
+- **Wrong schema applied:** SchemaStore guessed by filename; pin explicitly with a modeline.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.yaml
+# or: bun ../../scripts/verify-lsp.ts path/to/file.yaml
+```

package/plugins/litclaude/skills/lsp-setup/references/zig/README.md

@@ -0,0 +1,55 @@
+# Zig — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `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
+
+Add a `zig` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "zig": {
+    "command": ["zls"],
+    "extensionToLanguage": {
+      ".zig": "zig",
+      ".zon": "zig"
+    }
+  }
+}
+```
+
+Claude Code routes `.zig`/`.zon` edits to `zls` via the map. No extra
+configuration is normally 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
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.zig
+# or: bun ../../scripts/verify-lsp.ts path/to/file.zig
+```

package/plugins/litclaude/skills/lsp-setup/scripts/detect-lsp.ts

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// detect-lsp.ts <targetDir> [--json] [--config=<path>] — scan a directory for
+// source languages and report, per detected language: the recommended language
+// server, whether its executable is on PATH, an install hint, and whether the
+// LitClaude .lsp.json already declares that language.
+//
+// Runtime: Node 22.6+ with `node --experimental-strip-types`, or `bun`.
+//   node --experimental-strip-types scripts/detect-lsp.ts <dir>
+//   bun scripts/detect-lsp.ts <dir>
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { delimiter, extname, join, sep } from "node:path"
+import process from "node:process"
+
+import { LANGUAGES, type LanguageServer, LSP_CONFIG_FILE } from "./lsp-server-table.ts"
+
+const SKIP_DIRECTORIES = new Set<string>([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	".next",
+	"out",
+	"target",
+	".venv",
+	"venv",
+	"vendor",
+	".cache",
+	"__pycache__",
+	".turbo",
+	"coverage",
+])
+
+const MAX_FILES = 50_000
+
+interface ConfigState {
+	readonly path: string
+	readonly exists: boolean
+	readonly languages: readonly string[]
+}
+
+interface DetectionResult {
+	readonly server: LanguageServer
+	readonly executable: string
+	readonly installed: boolean
+	readonly resolvedPath: string | null
+	readonly configured: boolean
+}
+
+function collectExtensions(root: string): ReadonlySet<string> {
+	const found = new Set<string>()
+	const stack: string[] = [root]
+	let visited = 0
+
+	while (stack.length > 0) {
+		const current = stack.pop()
+		if (current === undefined) break
+
+		let entries: string[]
+		try {
+			entries = readdirSync(current)
+		} catch {
+			continue
+		}
+
+		for (const entry of entries) {
+			if (visited >= MAX_FILES) return found
+			const fullPath = join(current, entry)
+
+			let kind: "dir" | "file" | "other" = "other"
+			try {
+				const stat = statSync(fullPath)
+				kind = stat.isDirectory() ? "dir" : stat.isFile() ? "file" : "other"
+			} catch {
+				continue
+			}
+
+			if (kind === "dir") {
+				if (!SKIP_DIRECTORIES.has(entry)) stack.push(fullPath)
+			} else if (kind === "file") {
+				visited += 1
+				const ext = extname(entry).toLowerCase()
+				if (ext.length > 0) found.add(ext)
+			}
+		}
+	}
+
+	return found
+}
+
+function pathDirectories(): readonly string[] {
+	return (process.env["PATH"] ?? "").split(delimiter).filter((dir: string) => dir.length > 0)
+}
+
+function resolveExecutable(command: string): string | null {
+	const extensions =
+		process.platform === "win32" ? (process.env["PATHEXT"]?.split(";") ?? [".EXE", ".CMD", ".BAT"]) : [""]
+	const bases =
+		command.includes("/") || command.includes(sep)
+			? [command]
+			: pathDirectories().map((dir: string) => join(dir, command))
+
+	for (const base of bases) {
+		for (const ext of extensions) {
+			const candidate = ext.length > 0 ? `${base}${ext}` : base
+			try {
+				if (existsSync(candidate) && statSync(candidate).isFile()) return candidate
+			} catch {
+				continue
+			}
+		}
+	}
+	return null
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// LitClaude .lsp.json is keyed by language name:
+//   { "typescript": { "command": [...], "extensionToLanguage": {...} } }
+function parseConfiguredLanguages(path: string): readonly string[] {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf-8"))
+	} catch {
+		return []
+	}
+	if (!isRecord(parsed)) return []
+	return Object.keys(parsed)
+}
+
+function readConfigState(configPath: string): ConfigState {
+	if (!existsSync(configPath)) return { path: configPath, exists: false, languages: [] }
+	return { path: configPath, exists: true, languages: parseConfiguredLanguages(configPath) }
+}
+
+function detect(root: string, configured: readonly string[]): readonly DetectionResult[] {
+	const extensions = collectExtensions(root)
+	const configuredSet = new Set(configured)
+	const results: DetectionResult[] = []
+
+	for (const server of LANGUAGES) {
+		if (!server.extensions.some((ext: string) => extensions.has(ext))) continue
+
+		const executable = server.command[0] ?? server.language
+		const resolvedPath = resolveExecutable(executable)
+		results.push({
+			server,
+			executable,
+			installed: resolvedPath !== null,
+			resolvedPath,
+			configured: configuredSet.has(server.language),
+		})
+	}
+
+	return results
+}
+
+function renderReport(root: string, results: readonly DetectionResult[], config: ConfigState): string {
+	const lines: string[] = [`LSP setup scan: ${root}`]
+	lines.push(
+		`Config file: ${config.path} (${config.exists ? `present: ${config.languages.length} language(s)` : "absent"})`,
+		"",
+	)
+
+	if (results.length === 0) {
+		lines.push("No languages with a recommended LSP server were detected here.")
+		return lines.join("\n")
+	}
+
+	lines.push("DETECTED LANGUAGES (recommended server per language)")
+	for (const result of results) {
+		const mark = result.installed ? "OK  " : "MISS"
+		const state = result.installed ? `installed (${result.resolvedPath})` : "NOT installed"
+		const config = result.configured ? "declared in .lsp.json" : "NOT in .lsp.json"
+		lines.push(
+			`[${mark}] ${result.server.language.padEnd(12)} exe=${result.executable}  ${state}  ${config}`,
+		)
+		if (!result.installed) lines.push(`        install: ${result.server.installHint}`)
+	}
+
+	const missing = results.filter((result) => !result.installed)
+	const notConfigured = results.filter((result) => !result.configured)
+	lines.push(
+		"",
+		missing.length === 0
+			? `All ${results.length} detected server(s) installed.`
+			: `${missing.length}/${results.length} server(s) NOT installed: ${missing.map((m) => m.server.language).join(", ")}`,
+		notConfigured.length === 0
+			? "All detected languages are declared in .lsp.json."
+			: `${notConfigured.length} language(s) absent from .lsp.json: ${notConfigured.map((m) => m.server.language).join(", ")}`,
+		"Next: read references/<language>/README.md, then add the language to plugins/litclaude/.lsp.json.",
+	)
+	return lines.join("\n")
+}
+
+function main(): void {
+	const args = process.argv.slice(2)
+	const wantsJson = args.includes("--json")
+	const configFlag = args.find((arg: string) => arg.startsWith("--config="))
+	const configPath = configFlag ? configFlag.slice("--config=".length) : LSP_CONFIG_FILE
+	const root = args.find((arg: string) => !arg.startsWith("--")) ?? process.cwd()
+
+	if (!existsSync(root)) {
+		process.stderr.write(`detect-lsp: target directory does not exist: ${root}\n`)
+		process.exit(2)
+	}
+
+	const config = readConfigState(configPath)
+	const results = detect(root, config.languages)
+
+	if (wantsJson) {
+		process.stdout.write(`${JSON.stringify({ root, config, results }, null, 2)}\n`)
+		return
+	}
+	process.stdout.write(`${renderReport(root, results, config)}\n`)
+}
+
+main()