@blokjs/lsp-server 0.2.0

package/src/hover.ts

@@ -0,0 +1,135 @@
+import { type Hover, MarkupKind, Position, Range } from "vscode-languageserver";
+import { FIELD_DOCS, type HoverDoc, STEP_FIELD_DOCS, TRIGGER_DOCS } from "./constants";
+
+/**
+ * Provides hover documentation for Blok workflow JSON files via LSP.
+ *
+ * Shows contextual documentation when hovering over:
+ * - Trigger type keys (http, grpc, cron, queue, etc.)
+ * - Workflow fields (name, version, steps, nodes, etc.)
+ * - Node configuration fields (inputs, conditions, set_var)
+ * - Step fields (node, type, runtime)
+ * - HTTP method values, runtime type values, node packages
+ */
+export function getHover(text: string, line: number, character: number): Hover | null {
+	const lines = text.split("\n");
+	if (line >= lines.length) return null;
+
+	const lineText = lines[line];
+
+	// Find the quoted word at the cursor position
+	const wordInfo = findQuotedWordAt(lineText, character);
+	if (!wordInfo) return null;
+
+	const { word, startChar, endChar } = wordInfo;
+	const range = Range.create(Position.create(line, startChar), Position.create(line, endChar));
+
+	// Check if it's a key (followed by colon)
+	const afterWord = lineText.substring(endChar).trimStart();
+	const isKey = afterWord.startsWith(":");
+
+	if (isKey) {
+		// Trigger type documentation
+		if (TRIGGER_DOCS[word]) {
+			return createDocHover(TRIGGER_DOCS[word], range);
+		}
+
+		// Field documentation
+		if (FIELD_DOCS[word]) {
+			return createDocHover(FIELD_DOCS[word], range);
+		}
+
+		// Step field documentation
+		if (STEP_FIELD_DOCS[word]) {
+			return createDocHover(STEP_FIELD_DOCS[word], range);
+		}
+	}
+
+	// Value-based hover
+	if (!isKey) {
+		// HTTP methods
+		if (["GET", "POST", "PUT", "DELETE", "PATCH", "ANY"].includes(word)) {
+			return {
+				contents: {
+					kind: MarkupKind.Markdown,
+					value: `**HTTP Method: ${word}**\n\nHTTP request method that will trigger this workflow.`,
+				},
+				range,
+			};
+		}
+
+		// Runtime type values (runtime.go, runtime.python3, etc.)
+		if (word.startsWith("runtime.")) {
+			const lang = word.replace("runtime.", "");
+			return {
+				contents: {
+					kind: MarkupKind.Markdown,
+					value: `**Runtime Type: ${lang}**\n\nExecutes this node using the ${lang} runtime adapter. The node code must be written in ${lang} and served via the Blok runtime protocol (HTTP/gRPC).`,
+				},
+				range,
+			};
+		}
+
+		// Common node packages
+		if (word === "@blokjs/api-call") {
+			return {
+				contents: {
+					kind: MarkupKind.Markdown,
+					value:
+						"**@blokjs/api-call**\n\nMakes HTTP API calls to external services.\n\n**Inputs:** `url`, `method`, `headers`, `body`, `responseType`",
+				},
+				range,
+			};
+		}
+		if (word === "@blokjs/if-else") {
+			return {
+				contents: {
+					kind: MarkupKind.Markdown,
+					value:
+						"**@blokjs/if-else**\n\nConditional branching node. Evaluates JavaScript conditions against the workflow context.\n\nConfigure conditions in the `nodes` section using the `conditions` array.",
+				},
+				range,
+			};
+		}
+	}
+
+	return null;
+}
+
+function findQuotedWordAt(
+	line: string,
+	character: number,
+): { word: string; startChar: number; endChar: number } | null {
+	// Find all quoted strings in the line and check if cursor is inside one
+	const regex = /"([^"]*)"/g;
+
+	for (const match of line.matchAll(regex)) {
+		const start = match.index; // position of opening quote
+		const end = match.index + match[0].length; // position after closing quote
+
+		if (character >= start && character <= end) {
+			return {
+				word: match[1],
+				startChar: start,
+				endChar: end,
+			};
+		}
+	}
+
+	return null;
+}
+
+function createDocHover(doc: HoverDoc, range: Range): Hover {
+	let value = `**${doc.title}**\n\n${doc.description}\n\n`;
+	if (doc.example) {
+		value += "```json\n" + doc.example + "\n```";
+	}
+
+	return {
+		contents: {
+			kind: MarkupKind.Markdown,
+			value,
+		},
+		range,
+	};
+}

package/src/server.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { TextDocument } from "vscode-languageserver-textdocument";
+import {
+	type CompletionParams,
+	DidChangeConfigurationNotification,
+	type HoverParams,
+	type InitializeParams,
+	type InitializeResult,
+	ProposedFeatures,
+	TextDocumentSyncKind,
+	TextDocuments,
+	createConnection,
+} from "vscode-languageserver/node";
+import { getCompletions } from "./completion";
+import { validateWorkflow } from "./diagnostics";
+import { getHover } from "./hover";
+
+/**
+ * Blok Workflow Language Server
+ *
+ * Provides workflow intelligence for any LSP-compatible editor:
+ * - Diagnostics: Real-time validation of workflow JSON files
+ * - Completion: Contextual auto-completion for triggers, steps, runtimes, etc.
+ * - Hover: Rich documentation on hover for workflow fields and values
+ *
+ * Communication: stdio (default) or TCP
+ * File types: JSON files matching `**​/workflows/**​/*.json` or `blok.workflow.json`
+ */
+
+// Create connection and document manager
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+
+let hasConfigurationCapability = false;
+let hasWorkspaceFolderCapability = false;
+
+// Server settings
+interface BlokLspSettings {
+	workflowGlob: string;
+	maxDiagnostics: number;
+}
+
+const defaultSettings: BlokLspSettings = {
+	workflowGlob: "**/workflows/**/*.json",
+	maxDiagnostics: 100,
+};
+
+let globalSettings: BlokLspSettings = defaultSettings;
+const documentSettings = new Map<string, BlokLspSettings>();
+
+connection.onInitialize((params: InitializeParams): InitializeResult => {
+	const capabilities = params.capabilities;
+
+	hasConfigurationCapability = !!(capabilities.workspace && capabilities.workspace.configuration);
+	hasWorkspaceFolderCapability = !!(capabilities.workspace && capabilities.workspace.workspaceFolders);
+
+	const result: InitializeResult = {
+		capabilities: {
+			textDocumentSync: TextDocumentSyncKind.Incremental,
+			completionProvider: {
+				resolveProvider: false,
+				triggerCharacters: ['"', ":"],
+			},
+			hoverProvider: true,
+		},
+	};
+
+	if (hasWorkspaceFolderCapability) {
+		result.capabilities.workspace = {
+			workspaceFolders: {
+				supported: true,
+			},
+		};
+	}
+
+	return result;
+});
+
+connection.onInitialized(() => {
+	if (hasConfigurationCapability) {
+		connection.client.register(DidChangeConfigurationNotification.type, undefined);
+	}
+});
+
+// Configuration handling
+connection.onDidChangeConfiguration((change) => {
+	if (hasConfigurationCapability) {
+		documentSettings.clear();
+	} else {
+		globalSettings = change.settings?.blok || defaultSettings;
+	}
+
+	// Revalidate all open documents
+	for (const doc of documents.all()) {
+		validateDocument(doc);
+	}
+});
+
+function getDocumentSettings(resource: string): BlokLspSettings {
+	if (!hasConfigurationCapability) {
+		return globalSettings;
+	}
+	let result = documentSettings.get(resource);
+	if (!result) {
+		result = globalSettings;
+		documentSettings.set(resource, result);
+	}
+	return result;
+}
+
+// Document validation
+function isWorkflowFile(uri: string): boolean {
+	// Match workflow files by path pattern
+	return /workflows?[/\\].*\.json$/i.test(uri) || /\.workflow\.json$/i.test(uri) || /blok\.json$/i.test(uri);
+}
+
+function validateDocument(document: TextDocument): void {
+	if (!isWorkflowFile(document.uri)) return;
+
+	const text = document.getText();
+	const diagnostics = validateWorkflow(text);
+	const settings = getDocumentSettings(document.uri);
+
+	// Limit diagnostics if configured
+	const limited = diagnostics.slice(0, settings.maxDiagnostics);
+	connection.sendDiagnostics({ uri: document.uri, diagnostics: limited });
+}
+
+// Validate on open and change
+documents.onDidChangeContent((change) => {
+	validateDocument(change.document);
+});
+
+documents.onDidClose((event) => {
+	documentSettings.delete(event.document.uri);
+	connection.sendDiagnostics({ uri: event.document.uri, diagnostics: [] });
+});
+
+// Completion
+connection.onCompletion((params: CompletionParams) => {
+	const document = documents.get(params.textDocument.uri);
+	if (!document) return [];
+	if (!isWorkflowFile(document.uri)) return [];
+
+	const text = document.getText();
+	const offset = document.offsetAt(params.position);
+	return getCompletions(text, offset);
+});
+
+// Hover
+connection.onHover((params: HoverParams) => {
+	const document = documents.get(params.textDocument.uri);
+	if (!document) return null;
+	if (!isWorkflowFile(document.uri)) return null;
+
+	const text = document.getText();
+	return getHover(text, params.position.line, params.position.character);
+});
+
+// Start listening
+documents.listen(connection);
+connection.listen();

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"target": "ES2022",
+		"outDir": "dist",
+		"rootDir": "src",
+		"lib": ["ES2022"],
+		"sourceMap": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true,
+		"declaration": true,
+		"moduleResolution": "node"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		globals: false,
+		environment: "node",
+		include: ["src/__tests__/**/*.test.ts"],
+	},
+});