@litfamily/lithermes 1.0.0

package/assets/lithermes-plugin/skills/lsp-setup/references/terraform/README.md

@@ -0,0 +1,66 @@
+# Terraform — LSP setup (Hermes / LitHermes)
+
+- **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 the Hermes LSP config under `lsp.<language>`:
+
+```json
+{
+  "lsp": {
+    "terraform": {
+      "command": [
+        "terraform-ls",
+        "serve"
+      ],
+      "extensions": [
+        ".tf",
+        ".tfvars"
+      ]
+    }
+  }
+}
+```
+
+Hermes routes `.tf`/`.tfvars` edits to `terraform-ls` via the `extensions` list.
+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/assets/lithermes-plugin/skills/lsp-setup/references/typescript/README.md

@@ -0,0 +1,82 @@
+# TypeScript / JavaScript — LSP setup (Hermes / LitHermes)
+
+- **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
+
+Hermes declares language servers under `lsp.<language>`. Each entry
+is keyed by language name and holds a `command` array plus an
+`extensions` list. TypeScript/JavaScript already ships in the default
+config:
+
+```json
+{
+  "lsp": {
+    "typescript": {
+      "command": [
+        "typescript-language-server",
+        "--stdio"
+      ],
+      "extensions": [
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".mjs",
+        ".cjs"
+      ]
+    }
+  }
+}
+```
+
+Add `.mts`/`.cts` to the `extensions` list if your project uses them. Hermes
+resolves the server for an edited file by matching its extension against this
+list.
+
+## Alternatives
+
+Swap the `command` for your toolchain. Keep the same Hermes LSP config shape and adjust
+the `extensions` list 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/assets/lithermes-plugin/skills/lsp-setup/references/yaml/README.md

@@ -0,0 +1,65 @@
+# YAML — LSP setup (Hermes / LitHermes)
+
+- **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 the Hermes LSP config under `lsp.<language>`:
+
+```json
+{
+  "lsp": {
+    "yaml": {
+      "command": [
+        "yaml-language-server",
+        "--stdio"
+      ],
+      "extensions": [
+        ".yaml",
+        ".yml"
+      ]
+    }
+  }
+}
+```
+
+Hermes routes `.yaml`/`.yml` edits to `yaml-language-server` via the `extensions` list.
+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 the Hermes LSP config. 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/assets/lithermes-plugin/skills/lsp-setup/references/zig/README.md

@@ -0,0 +1,59 @@
+# Zig — LSP setup (Hermes / LitHermes)
+
+- **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 the Hermes LSP config under `lsp.<language>`:
+
+```json
+{
+  "lsp": {
+    "zig": {
+      "command": [
+        "zls"
+      ],
+      "extensions": [
+        ".zig",
+        ".zon"
+      ]
+    }
+  }
+}
+```
+
+Hermes routes `.zig`/`.zon` edits to `zls` via the `extensions` list. 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/assets/lithermes-plugin/skills/lsp-setup/scripts/detect-lsp.ts

@@ -0,0 +1,221 @@
+#!/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
+// Hermes LSP config 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)
+}
+
+// The Hermes LSP config keys each server by language name under `lsp`:
+//   { "lsp": { "typescript": { "command": [...], "extensions": [...] } } }
+function parseConfiguredLanguages(path: string): readonly string[] {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf-8"))
+	} catch {
+		return []
+	}
+	if (!isRecord(parsed)) return []
+	const lsp = parsed["lsp"]
+	return isRecord(lsp) ? Object.keys(lsp) : []
+}
+
+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 the Hermes LSP config" : "NOT in the Hermes LSP config"
+		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 the Hermes LSP config."
+			: `${notConfigured.length} language(s) absent from the Hermes LSP config: ${notConfigured.map((m) => m.server.language).join(", ")}`,
+		"Next: read references/<language>/README.md, then add the language under `lsp` in the Hermes LSP config.",
+	)
+	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()

package/assets/lithermes-plugin/skills/lsp-setup/scripts/lsp-server-table.ts

@@ -0,0 +1,146 @@
+// Standalone snapshot of the primary language server per supported language,
+// embedded so detect-lsp.ts runs without any external dependency in any project.
+// Each entry mirrors the per-language references/<language>/README.md and the
+// Hermes LSP config shape, which is keyed by language name under `lsp`:
+//   { "lsp": { "<language>": { "command": [...], "extensions": [".ext"] } } }
+// Edit this table when a reference README changes.
+
+export interface LanguageServer {
+	readonly language: string
+	readonly command: readonly string[]
+	readonly extensions: readonly string[]
+	readonly installHint: string
+}
+
+export const LANGUAGES: readonly LanguageServer[] = [
+	{
+		language: "typescript",
+		command: ["typescript-language-server", "--stdio"],
+		extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"],
+		installHint: "npm install -g typescript-language-server typescript",
+	},
+	{
+		language: "python",
+		command: ["basedpyright-langserver", "--stdio"],
+		extensions: [".py", ".pyi"],
+		installHint: "pip install basedpyright (or: uv tool install basedpyright)",
+	},
+	{
+		language: "go",
+		command: ["gopls"],
+		extensions: [".go"],
+		installHint: "go install golang.org/x/tools/gopls@latest",
+	},
+	{
+		language: "rust",
+		command: ["rust-analyzer"],
+		extensions: [".rs"],
+		installHint: "rustup component add rust-analyzer",
+	},
+	{
+		language: "c-cpp",
+		command: ["clangd", "--background-index", "--clang-tidy"],
+		extensions: [".c", ".cpp", ".cc", ".cxx", ".c++", ".h", ".hpp", ".hh", ".hxx", ".h++"],
+		installHint: "macOS: brew install llvm | Linux: apt install clangd | https://clangd.llvm.org/installation",
+	},
+	{
+		language: "java",
+		command: ["jdtls"],
+		extensions: [".java"],
+		installHint: "macOS: brew install jdtls | https://github.com/eclipse-jdtls/eclipse.jdt.ls",
+	},
+	{
+		language: "kotlin",
+		command: ["kotlin-lsp"],
+		extensions: [".kt", ".kts"],
+		installHint: "https://github.com/Kotlin/kotlin-lsp",
+	},
+	{
+		language: "csharp",
+		command: ["csharp-ls"],
+		extensions: [".cs"],
+		installHint: "dotnet tool install -g csharp-ls",
+	},
+	{
+		language: "razor",
+		command: ["roslyn-language-server", "--stdio"],
+		extensions: [".razor", ".cshtml"],
+		installHint: "dotnet tool install -g roslyn-language-server --prerelease (see references/csharp/README.md)",
+	},
+	{
+		language: "swift",
+		command: ["sourcekit-lsp"],
+		extensions: [".swift", ".objc", ".objcpp"],
+		installHint: "Included with Xcode (xcode-select --install) or the Swift toolchain",
+	},
+	{
+		language: "ruby",
+		command: ["rubocop", "--lsp"],
+		extensions: [".rb", ".rake", ".gemspec", ".ru"],
+		installHint: "gem install rubocop (the builtin runs `rubocop --lsp`)",
+	},
+	{
+		language: "php",
+		command: ["intelephense", "--stdio"],
+		extensions: [".php"],
+		installHint: "npm install -g intelephense",
+	},
+	{
+		language: "dart",
+		command: ["dart", "language-server", "--lsp"],
+		extensions: [".dart"],
+		installHint: "Included with the Dart/Flutter SDK",
+	},
+	{
+		language: "elixir",
+		command: ["elixir-ls"],
+		extensions: [".ex", ".exs"],
+		installHint: "https://github.com/elixir-lsp/elixir-ls",
+	},
+	{
+		language: "zig",
+		command: ["zls"],
+		extensions: [".zig", ".zon"],
+		installHint: "https://github.com/zigtools/zls (match zls version to your zig version)",
+	},
+	{
+		language: "lua",
+		command: ["lua-language-server"],
+		extensions: [".lua"],
+		installHint: "macOS: brew install lua-language-server | https://github.com/LuaLS/lua-language-server",
+	},
+	{
+		language: "bash",
+		command: ["bash-language-server", "start"],
+		extensions: [".sh", ".bash", ".zsh", ".ksh"],
+		installHint: "npm install -g bash-language-server",
+	},
+	{
+		language: "yaml",
+		command: ["yaml-language-server", "--stdio"],
+		extensions: [".yaml", ".yml"],
+		installHint: "npm install -g yaml-language-server",
+	},
+	{
+		language: "terraform",
+		command: ["terraform-ls", "serve"],
+		extensions: [".tf", ".tfvars"],
+		installHint: "macOS: brew install hashicorp/tap/terraform-ls | https://github.com/hashicorp/terraform-ls",
+	},
+	{
+		language: "haskell",
+		command: ["haskell-language-server-wrapper", "--lsp"],
+		extensions: [".hs", ".lhs"],
+		installHint: "ghcup install hls",
+	},
+	{
+		language: "julia",
+		command: ["julia", "--startup-file=no", "--history-file=no", "-e", "using LanguageServer; runserver()"],
+		extensions: [".jl"],
+		installHint: "julia -e 'using Pkg; Pkg.add(\"LanguageServer\")' (see references/julia/README.md)",
+	},
+] as const
+
+// The Hermes LSP config file, relative to the project root. detect-lsp.ts also
+// accepts an explicit path so it can be pointed at a different copy.
+export const LSP_CONFIG_FILE = ".lithermes/lsp.json"

package/assets/lithermes-plugin/skills/lsp-setup/scripts/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["ESNext"],
+    "types": ["node"],
+    "allowImportingTsExtensions": true
+  },
+  "include": ["*.ts"]
+}