@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lsp-setup/scripts/detect-lsp.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+// detect-lsp.ts <targetDir> [--json] — scan a directory for source languages and
+// report, per detected language: the advisory LSP server, whether its executable
+// is on PATH, an install hint, and whether a project LSP config references it.
+
+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, PROJECT_CONFIG_FILES } from "./lsp-server-table"
+
+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
+
+// Historical advisory behavior: extensionless Dockerfile/Containerfile resolve to .dockerfile
+// (exact-case basenames) for the standalone inventory report.
+const BASENAME_EXTENSIONS: Record<string, string> = {
+	Dockerfile: ".dockerfile",
+	Containerfile: ".dockerfile",
+}
+
+interface ConfigFileState {
+	readonly path: string
+	readonly exists: boolean
+	readonly serverIds: readonly string[]
+}
+
+interface DetectionResult {
+	readonly server: LanguageServer
+	readonly executable: string
+	readonly installed: boolean
+	readonly resolvedPath: string | null
+	readonly configuredIn: readonly string[]
+}
+
+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 = (BASENAME_EXTENSIONS[entry] ?? 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)
+}
+
+function parseConfiguredServerIds(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(root: string): readonly ConfigFileState[] {
+	return PROJECT_CONFIG_FILES.map((relative: string): ConfigFileState => {
+		const path = join(root, relative)
+		if (!existsSync(path)) return { path: relative, exists: false, serverIds: [] }
+		return { path: relative, exists: true, serverIds: parseConfiguredServerIds(path) }
+	})
+}
+
+function detect(root: string, configState: readonly ConfigFileState[]): readonly DetectionResult[] {
+	const extensions = collectExtensions(root)
+	const results: DetectionResult[] = []
+
+	for (const server of LANGUAGES) {
+		if (!server.extensions.some((ext: string) => extensions.has(ext))) continue
+
+		const executable = server.command[0] ?? server.serverId
+		const resolvedPath = resolveExecutable(executable)
+		const configuredIn = configState
+			.filter((state) => state.serverIds.includes(server.serverId))
+			.map((state) => state.path)
+
+		results.push({ server, executable, installed: resolvedPath !== null, resolvedPath, configuredIn })
+	}
+
+	return results
+}
+
+function renderReport(root: string, results: readonly DetectionResult[], configState: readonly ConfigFileState[]): string {
+	const lines: string[] = [`LSP setup scan: ${root}`]
+	const configSummary = configState
+		.map((state) => `${state.path} (${state.exists ? `present: ${state.serverIds.length} server(s)` : "absent"})`)
+		.join(", ")
+	lines.push(`Config files: ${configSummary}`, "")
+
+	if (results.length === 0) {
+		lines.push("No languages with an advisory LSP server were detected here.")
+		return lines.join("\n")
+	}
+
+	lines.push("DETECTED LANGUAGES (advisory server per language; LitCodex runtime unavailable)")
+	for (const result of results) {
+		const mark = result.installed ? "OK  " : "MISS"
+		const state = result.installed ? `installed (${result.resolvedPath})` : "NOT installed"
+		const config = result.configuredIn.length > 0 ? `mentioned in ${result.configuredIn.join(", ")}` : "not configured"
+		lines.push(`[${mark}] ${result.server.language.padEnd(12)} server=${result.server.serverId}  exe=${result.executable}  ${state}  ${config}`)
+		if (!result.installed) lines.push(`        install: ${result.server.installHint}`)
+	}
+
+	const missing = results.filter((result) => !result.installed)
+	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(", ")}`,
+		"Next: read references/<language>/README.md only for editor/CI setup; LitCodex does not start LSP servers in this build.",
+	)
+	return lines.join("\n")
+}
+
+function main(): void {
+	const args = process.argv.slice(2)
+	const wantsJson = args.includes("--json")
+	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 configState = readConfigState(root)
+	const results = detect(root, configState)
+
+	if (wantsJson) {
+		process.stdout.write(`${JSON.stringify({ root, configState, results }, null, 2)}\n`)
+		return
+	}
+	process.stdout.write(`${renderReport(root, results, configState)}\n`)
+}
+
+main()

package/marketplace/plugins/litcodex/skills/lsp-setup/scripts/lsp-server-table.ts

@@ -0,0 +1,175 @@
+// Hand-maintained server table for detect-lsp.ts and verify-lsp.ts.
+//
+// detect-lsp.ts reads these entries as package/install hints. verify-lsp.ts resolves a command from
+// them and spawns it directly, so a wrong command here becomes a real roundtrip failure.
+
+export interface LanguageServer {
+	readonly language: string
+	readonly serverId: string
+	readonly command: readonly string[]
+	readonly extensions: readonly string[]
+	readonly installHint: string
+}
+
+export const LANGUAGES: readonly LanguageServer[] = [
+	{
+		language: "typescript",
+		serverId: "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",
+		serverId: "basedpyright",
+		command: ["basedpyright-langserver", "--stdio"],
+		extensions: [".py", ".pyi"],
+		installHint: "pip install basedpyright (or: uv tool install basedpyright)",
+	},
+	{
+		language: "go",
+		serverId: "gopls",
+		command: ["gopls"],
+		extensions: [".go"],
+		installHint: "go install golang.org/x/tools/gopls@latest",
+	},
+	{
+		language: "rust",
+		serverId: "rust",
+		command: ["rust-analyzer"],
+		extensions: [".rs"],
+		installHint: "rustup component add rust-analyzer",
+	},
+	{
+		language: "c-cpp",
+		serverId: "clangd",
+		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",
+		serverId: "jdtls",
+		command: ["jdtls"],
+		extensions: [".java"],
+		installHint: "macOS: brew install jdtls | https://github.com/eclipse-jdtls/eclipse.jdt.ls",
+	},
+	{
+		language: "kotlin",
+		serverId: "kotlin-ls",
+		command: ["kotlin-lsp"],
+		extensions: [".kt", ".kts"],
+		installHint: "https://github.com/Kotlin/kotlin-lsp",
+	},
+	{
+		language: "csharp",
+		serverId: "csharp",
+		command: ["csharp-ls"],
+		extensions: [".cs"],
+		installHint: "dotnet tool install -g csharp-ls",
+	},
+	{
+		language: "razor",
+		serverId: "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",
+		serverId: "sourcekit-lsp",
+		command: ["sourcekit-lsp"],
+		extensions: [".swift", ".objc", ".objcpp"],
+		installHint: "Included with Xcode (xcode-select --install) or the Swift toolchain",
+	},
+	{
+		language: "ruby",
+		serverId: "ruby-lsp",
+		command: ["rubocop", "--lsp"],
+		extensions: [".rb", ".rake", ".gemspec", ".ru"],
+		installHint: "gem install ruby-lsp (advisory default runs `rubocop --lsp`; gem install rubocop)",
+	},
+	{
+		language: "php",
+		serverId: "php",
+		command: ["intelephense", "--stdio"],
+		extensions: [".php"],
+		installHint: "npm install -g intelephense",
+	},
+	{
+		language: "dart",
+		serverId: "dart",
+		command: ["dart", "language-server", "--lsp"],
+		extensions: [".dart"],
+		installHint: "Included with the Dart/Flutter SDK",
+	},
+	{
+		language: "elixir",
+		serverId: "elixir-ls",
+		command: ["elixir-ls"],
+		extensions: [".ex", ".exs"],
+		installHint: "https://github.com/elixir-lsp/elixir-ls",
+	},
+	{
+		language: "zig",
+		serverId: "zls",
+		command: ["zls"],
+		extensions: [".zig", ".zon"],
+		installHint: "https://github.com/zigtools/zls (match zls version to your zig version)",
+	},
+	{
+		language: "lua",
+		serverId: "lua-ls",
+		command: ["lua-language-server"],
+		extensions: [".lua"],
+		installHint: "macOS: brew install lua-language-server | https://github.com/LuaLS/lua-language-server",
+	},
+	{
+		language: "bash",
+		serverId: "bash",
+		command: ["bash-language-server", "start"],
+		extensions: [".sh", ".bash", ".zsh", ".ksh"],
+		installHint: "npm install -g bash-language-server",
+	},
+	{
+		language: "yaml",
+		serverId: "yaml-ls",
+		command: ["yaml-language-server", "--stdio"],
+		extensions: [".yaml", ".yml"],
+		installHint: "npm install -g yaml-language-server",
+	},
+	{
+		language: "terraform",
+		serverId: "terraform",
+		command: ["terraform-ls", "serve"],
+		extensions: [".tf", ".tfvars"],
+		installHint: "macOS: brew install hashicorp/tap/terraform-ls | https://github.com/hashicorp/terraform-ls",
+	},
+	{
+		language: "dockerfile",
+		serverId: "dockerfile",
+		command: ["docker-langserver", "--stdio"],
+		extensions: [".dockerfile"],
+		installHint: "npm install -g dockerfile-language-server-nodejs",
+	},
+	{
+		language: "haskell",
+		serverId: "haskell-language-server",
+		command: ["haskell-language-server-wrapper", "--lsp"],
+		extensions: [".hs", ".lhs"],
+		installHint: "ghcup install hls",
+	},
+	{
+		language: "julia",
+		serverId: "julials",
+		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
+
+export const PROJECT_CONFIG_FILES: readonly string[] = [
+	".codex/lsp-client.json",
+	".litcodex/lsp.json",
+	".litcodex/lsp-client.json",
+] as const

package/marketplace/plugins/litcodex/skills/lsp-setup/scripts/tsconfig.json

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

package/marketplace/plugins/litcodex/skills/lsp-setup/scripts/verify-lsp.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env bun
+// verify-lsp.ts <file> [--timeout=ms] [--config=<path>] — perform a real LSP
+// diagnostics roundtrip for <file>: resolve the server for the file extension
+// (from a project LSP config when present, else the embedded table), spawn it,
+// run the JSON-RPC initialize -> initialized -> didOpen handshake over stdio,
+// wait for textDocument/publishDiagnostics, and report OK / FAIL / SKIP.
+//
+// Dependency-free: only node builtins, so no bundled diagnostics engine is
+// required and this runs under both `bun` and `node --experimental-strip-types`.
+//
+// Exit codes: 0 OK, 1 FAIL (server error / not installed / timeout), 2 usage,
+// 3 SKIP (no server known for this extension).
+
+import { spawn } from "node:child_process"
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { extname, isAbsolute, join, resolve } from "node:path"
+import process from "node:process"
+import { pathToFileURL } from "node:url"
+
+import { LANGUAGES, PROJECT_CONFIG_FILES } from "./lsp-server-table.ts"
+
+const DEFAULT_TIMEOUT_MS = 60_000
+
+interface ResolvedServer {
+	readonly language: string
+	readonly command: readonly string[]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string")
+}
+
+// A project config overrides only the command, and is keyed by serverId under
+// `lsp` — the same shape detect-lsp.ts inventories.
+function configuredCommand(configPath: string, serverId: string): readonly string[] | null {
+	if (!existsSync(configPath)) return null
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(readFileSync(configPath, "utf-8"))
+	} catch {
+		return null
+	}
+	if (!isRecord(parsed)) return null
+	const lsp = parsed["lsp"]
+	if (!isRecord(lsp)) return null
+	const entry = lsp[serverId]
+	if (!isRecord(entry)) return null
+	const command = entry["command"]
+	return isStringArray(command) ? command : null
+}
+
+function resolveServer(ext: string, explicitConfig: string | null): ResolvedServer | null {
+	const server = LANGUAGES.find((entry) => entry.extensions.includes(ext))
+	if (server === undefined) return null
+
+	const candidates =
+		explicitConfig !== null ? [explicitConfig] : PROJECT_CONFIG_FILES.map((rel) => join(process.cwd(), rel))
+	for (const candidate of candidates) {
+		const override = configuredCommand(candidate, server.serverId)
+		if (override !== null) return { language: server.language, command: override }
+	}
+	return { language: server.language, command: [...server.command] }
+}
+
+interface JsonRpcMessage {
+	readonly method?: string
+	readonly id?: number
+	readonly params?: unknown
+	readonly result?: unknown
+}
+
+function encode(message: unknown): Buffer {
+	const body = Buffer.from(JSON.stringify(message), "utf-8")
+	return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii"), body])
+}
+
+// Incremental LSP framing parser: pulls complete Content-Length messages off a
+// growing buffer and skips frames it cannot parse.
+function makeReader(onMessage: (message: JsonRpcMessage) => void): (chunk: Buffer) => void {
+	let buffer = Buffer.alloc(0)
+	return (chunk: Buffer): void => {
+		buffer = Buffer.concat([buffer, chunk])
+		while (true) {
+			const headerEnd = buffer.indexOf("\r\n\r\n")
+			if (headerEnd === -1) return
+			const header = buffer.subarray(0, headerEnd).toString("ascii")
+			const match = /content-length:\s*(\d+)/i.exec(header)
+			if (!match) {
+				buffer = buffer.subarray(headerEnd + 4)
+				continue
+			}
+			const length = Number.parseInt(match[1] ?? "0", 10)
+			const start = headerEnd + 4
+			if (buffer.length < start + length) return
+			const body = buffer.subarray(start, start + length).toString("utf-8")
+			buffer = buffer.subarray(start + length)
+			try {
+				onMessage(JSON.parse(body) as JsonRpcMessage)
+			} catch {
+				// ignore malformed frame
+			}
+		}
+	}
+}
+
+function languageId(ext: string): string {
+	return LANGUAGES.find((entry) => entry.extensions.includes(ext))?.language ?? ext.replace(/^\./, "")
+}
+
+async function run(filePath: string, timeoutMs: number, explicitConfig: string | null): Promise<number> {
+	const absolute = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath)
+	const ext = extname(absolute).toLowerCase()
+	const server = resolveServer(ext, explicitConfig)
+
+	if (server === null) {
+		process.stderr.write(`SKIP ${absolute}: no language server known for "${ext}". See references/.\n`)
+		return 3
+	}
+
+	const [bin, ...binArgs] = server.command
+	if (bin === undefined) {
+		process.stderr.write(`SKIP ${absolute}: empty command for ${server.language}.\n`)
+		return 3
+	}
+
+	const text = readFileSync(absolute, "utf-8")
+	const uri = pathToFileURL(absolute).href
+
+	return await new Promise<number>((resolveResult) => {
+		let child: ReturnType<typeof spawn>
+		try {
+			child = spawn(bin, binArgs, { stdio: ["pipe", "pipe", "pipe"] })
+		} catch {
+			process.stdout.write(`FAIL ${absolute}: language server not installed (${bin})\n`)
+			resolveResult(1)
+			return
+		}
+
+		let settled = false
+		let stderr = ""
+		const finish = (code: number, line: string): void => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			try {
+				child.kill("SIGKILL")
+			} catch {
+				/* already gone */
+			}
+			process.stdout.write(`${line}\n`)
+			resolveResult(code)
+		}
+
+		const timer = setTimeout(() => {
+			finish(1, `FAIL ${absolute}: timed out after ${timeoutMs}ms waiting for diagnostics`)
+		}, timeoutMs)
+
+		child.on("error", (error: NodeJS.ErrnoException) => {
+			if (error.code === "ENOENT") finish(1, `FAIL ${absolute}: language server not installed (${bin})`)
+			else finish(1, `FAIL ${absolute}: ${error.message}`)
+		})
+		child.on("exit", (code) => {
+			finish(1, `FAIL ${absolute}: server exited (code ${code ?? "?"})\n${stderr.trim()}`)
+		})
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString("utf-8")
+		})
+
+		const send = (message: unknown): void => {
+			child.stdin?.write(encode(message))
+		}
+
+		const read = makeReader((message) => {
+			if (message.id === 1 && message.result !== undefined) {
+				send({ jsonrpc: "2.0", method: "initialized", params: {} })
+				send({
+					jsonrpc: "2.0",
+					method: "textDocument/didOpen",
+					params: { textDocument: { uri, languageId: languageId(ext), version: 1, text } },
+				})
+			}
+			if (message.method === "textDocument/publishDiagnostics" && isRecord(message.params)) {
+				if (message.params["uri"] !== uri) return
+				const diagnostics = message.params["diagnostics"]
+				const count = Array.isArray(diagnostics) ? diagnostics.length : 0
+				finish(0, `OK ${absolute}: LSP roundtrip succeeded (${count} diagnostic(s)) via ${server.language}`)
+			}
+		})
+		child.stdout?.on("data", read)
+
+		send({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: {
+				processId: process.pid,
+				rootUri: pathToFileURL(process.cwd()).href,
+				capabilities: { textDocument: { publishDiagnostics: {} } },
+			},
+		})
+	})
+}
+
+function parseTimeout(args: readonly string[]): number {
+	const flag = args.find((arg) => arg.startsWith("--timeout="))
+	if (flag === undefined) return DEFAULT_TIMEOUT_MS
+	const parsed = Number.parseInt(flag.slice("--timeout=".length), 10)
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2)
+	const configFlag = args.find((arg) => arg.startsWith("--config="))
+	const filePath = args.find((arg) => !arg.startsWith("--"))
+
+	if (filePath === undefined) {
+		process.stderr.write("Usage: verify-lsp.ts <file> [--timeout=ms] [--config=<path>]\n")
+		process.exit(2)
+	}
+	if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+		process.stderr.write(`verify-lsp: not a file: ${filePath}\n`)
+		process.exit(2)
+	}
+
+	process.exit(await run(filePath, parseTimeout(args), configFlag ? configFlag.slice("--config=".length) : null))
+}
+
+await main()