@oml/server 0.14.0

package/README.md

@@ -0,0 +1,94 @@
+<!-- Copyright (c) 2026 Modelware. All rights reserved. -->
+
+# @oml/server
+
+Standalone OML REST server runtime package.
+
+The only user-facing CLI is `oml` from `@oml/cli`. Use `oml server start`, `oml server stop`, and `oml server status` to manage the server.
+
+## Options
+
+- `--host`, `-h`: bind host. Default: `127.0.0.1`
+- `--port`, `-p`: bind port. Default: `8080`
+- `--workspace`, `-w`: workspace root used to initialize the server. Default: current working directory
+- `--token`: bearer token required for REST endpoints (except `/health`)
+- `--refresh-token`: optional refresh token used by server auth refresh
+- `--token-expires-at`: optional access-token expiration time (epoch ms)
+
+## Canonical CLI
+
+From a local checkout:
+
+```bash
+node packages/cli/bin/cli.js server start
+```
+
+When installed from npm:
+
+```bash
+oml server start
+```
+
+Server management commands:
+
+```bash
+oml server start
+oml server status
+oml server stop
+```
+
+If the requested port is already occupied, startup fails immediately with a clear message naming the occupied host and port.
+
+## REST API
+
+The server exposes only these endpoints:
+
+- `GET /health`
+- `GET /openapi.json`
+- `GET /v0/models`
+- `POST /v0/query`
+- `POST /v0/update`
+- `POST /v0/fuzzysearch`
+- `POST /v0/lint`
+- `POST /v0/reason`
+- `POST /v0/validate`
+- `POST /v0/render`
+- `POST /v0/export`
+
+Health check:
+
+```bash
+curl http://127.0.0.1:8080/health
+```
+
+Run a SPARQL query:
+
+```bash
+curl -X POST http://127.0.0.1:8080/v0/query \
+  -H 'content-type: application/json' \
+  -d '{
+    "modelUri": "file:///absolute/path/to/model.oml",
+    "sparql": "SELECT * WHERE { ?s ?p ?o } LIMIT 10"
+  }'
+```
+
+Run update request:
+
+```bash
+curl -X POST http://127.0.0.1:8080/v0/update \
+  -H 'content-type: application/json' \
+  -d '{
+    "operations": []
+  }'
+```
+
+Run fuzzy search:
+
+```bash
+curl -X POST http://127.0.0.1:8080/v0/fuzzysearch \
+  -H 'content-type: application/json' \
+  -d '{
+    "text": "firefighter",
+    "limit": 10
+  }'
+```

package/package.json

@@ -0,0 +1,34 @@
+{
+    "name": "@oml/server",
+    "description": "Standalone OML language server host",
+    "version": "0.14.0",
+    "type": "module",
+    "main": "./out/index.js",
+    "exports": {
+        ".": "./out/index.js",
+        "./lsp/language-server": "./out/lsp/language-server.js",
+        "./lsp/diagram-server": "./out/lsp/diagram-server.js",
+        "./rest/server": "./out/rest/server.js",
+        "./lsp/providers/browser-fs-provider": "./out/lsp/providers/browser-fs-provider.js",
+        "./lsp/providers/hybrid-fs-provider": "./out/lsp/providers/hybrid-fs-provider.js",
+        "./lsp/protocol/reasoner-protocol": "./out/lsp/protocol/reasoner-protocol.js",
+        "./lsp/protocol/browser-fs-protocol": "./out/lsp/protocol/browser-fs-protocol.js",
+        "./package.json": "./package.json"
+    },
+    "scripts": {
+        "clean": "shx rm -fr *.tsbuildinfo out",
+        "build": "echo 'No build step'",
+        "build:clean": "npm run clean && npm run build"
+    },
+    "dependencies": {
+        "@leeoniya/ufuzzy": "^1.0.19",
+        "@oml/language": "0.14.0",
+        "@oml/markdown": "0.14.0",
+        "@oml/owl": "0.14.0",
+        "@oml/platform": "^0.5.0",
+        "@oml/reasoner": "^0.3.0",
+        "langium": "^4.2.1",
+        "langium-cli": "^4.2.0",
+        "vscode-languageserver": "~9.0.1"
+    }
+}

package/src/cli.ts

@@ -0,0 +1,189 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { NodeFileSystem } from 'langium/node';
+import { createConnection } from 'vscode-languageserver/node.js';
+import { startOmlLanguageServer, type OmlLanguageServerRuntime } from './lsp/language-server.js';
+import { startOmlRestServer } from './rest/server.js';
+
+interface RemoteOptions {
+    host: string;
+    port: number;
+    workspaceRoot: string;
+    token?: string;
+}
+
+type ServerLockOwner = 'daemon' | 'extension';
+
+function formatStartupError(error: unknown, host: string, port: number): string {
+    if (error && typeof error === 'object' && 'code' in error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === 'EADDRINUSE') {
+            return `Port ${port} is already in use on ${host}.`;
+        }
+        if (code === 'EACCES') {
+            return `Port ${port} on ${host} cannot be used due to insufficient permissions.`;
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+
+function readOptionValue(argv: string[], index: number, aliases: string[]): string {
+    const current = argv[index];
+    const equalsIndex = current.indexOf('=');
+    if (equalsIndex >= 0) {
+        return current.slice(equalsIndex + 1);
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith('-')) {
+        throw new Error(`Missing value for ${aliases.join('/')}.`);
+    }
+    return next;
+}
+
+function parseRemoteOptions(argv: string[]): RemoteOptions {
+    let portValue: string | undefined;
+    let workspaceValue: string | undefined;
+    let tokenValue: string | undefined;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--node-ipc' || arg.startsWith('--clientProcessId=')) {
+            continue;
+        }
+        if (arg === '--port' || arg === '-p' || arg.startsWith('--port=')) {
+            portValue = readOptionValue(argv, index, ['--port', '-p']).trim();
+            if (!arg.includes('=')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (arg === '--workspace' || arg === '-w' || arg.startsWith('--workspace=')) {
+            workspaceValue = readOptionValue(argv, index, ['--workspace', '-w']).trim();
+            if (!arg.includes('=')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (arg === '--token' || arg.startsWith('--token=')) {
+            tokenValue = readOptionValue(argv, index, ['--token']).trim();
+            if (!arg.includes('=')) {
+                index += 1;
+            }
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown option '${arg}'.`);
+        }
+    }
+
+    const host = '127.0.0.1';
+    const rawPort = Number(portValue ?? process.env.OML_SERVER_PORT ?? '8080');
+    const port = Number.isFinite(rawPort) ? Math.max(0, Math.min(65535, Math.trunc(rawPort))) : 8080;
+    const workspaceRoot = workspaceValue && workspaceValue.length > 0 ? workspaceValue : process.cwd();
+    const token = tokenValue && tokenValue.length > 0 ? tokenValue : undefined;
+    return { host, port, workspaceRoot, token };
+}
+
+function startIpcLanguageServerIfAvailable(): { connection: import('vscode-languageserver').Connection; runtime: OmlLanguageServerRuntime } | undefined {
+    if (typeof process.send !== 'function') {
+        return undefined;
+    }
+    const connection = createConnection();
+    const runtime = startOmlLanguageServer(connection, {
+        fileSystem: NodeFileSystem,
+        registerDiagramHandlers: true,
+        suppressTransientDiagnostics: true,
+        installNodeProcessHandlers: true,
+    });
+    return { connection, runtime };
+}
+
+function workspaceHash(workspaceRoot: string): string {
+    return createHash('sha256').update(path.resolve(workspaceRoot)).digest('hex');
+}
+
+function lockFilePathForWorkspace(workspaceRoot: string): string {
+    return path.join(os.homedir(), '.oml', 'workspaces', workspaceHash(workspaceRoot), 'server.lock');
+}
+
+async function writeServerLock(workspaceRoot: string, port: number, owner: ServerLockOwner): Promise<string> {
+    const lockFile = lockFilePathForWorkspace(workspaceRoot);
+    await fs.mkdir(path.dirname(lockFile), { recursive: true });
+    await fs.writeFile(lockFile, JSON.stringify({ port, pid: process.pid, owner }) + '\n', 'utf-8');
+    return lockFile;
+}
+
+async function removeServerLock(lockFile: string): Promise<void> {
+    await fs.rm(lockFile, { force: true });
+}
+
+function resolveListeningPort(server: import('node:http').Server): number {
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Unable to resolve listening port.');
+    }
+    return address.port;
+}
+
+export function runServerCli(argv: string[] = process.argv.slice(2)): void {
+    let options: RemoteOptions;
+    try {
+        options = parseRemoteOptions(argv);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[oml-server] REST startup failed: ${message}\n`);
+        process.exitCode = 1;
+        process.exit();
+        return;
+    }
+    const ipcServer = startIpcLanguageServerIfAvailable();
+    const owner: ServerLockOwner = ipcServer ? 'extension' : 'daemon';
+    void startOmlRestServer({
+        host: options.host,
+        port: options.port,
+        workspaceRoot: options.workspaceRoot,
+        watchWorkspace: true,
+        authToken: options.token,
+        runtime: ipcServer?.runtime,
+    }).then(async ({ server, updateToken }) => {
+        if (ipcServer) {
+            ipcServer.connection.onNotification('$/tokenRefreshed', (params: { accessToken: string }) => {
+                if (params?.accessToken) {
+                    updateToken(params.accessToken);
+                }
+            });
+        }
+        const listeningPort = resolveListeningPort(server);
+        const lockFile = await writeServerLock(options.workspaceRoot, listeningPort, owner);
+        let shuttingDown = false;
+        const shutdown = (exitCode: number): void => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            server.close(() => {
+                void removeServerLock(lockFile).finally(() => {
+                    process.exit(exitCode);
+                });
+            });
+        };
+
+        process.once('SIGINT', () => shutdown(0));
+        process.once('SIGTERM', () => shutdown(0));
+        server.once('close', () => {
+            void removeServerLock(lockFile);
+        });
+
+        process.stdout.write(`[oml-server] REST listening on http://${options.host}:${listeningPort}\n`);
+    }).catch((error: unknown) => {
+        const message = formatStartupError(error, options.host, options.port);
+        process.stderr.write(`[oml-server] REST startup failed: ${message}\n`);
+        process.exitCode = 1;
+        process.exit();
+    });
+}
+
+runServerCli();

package/src/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+export * from './lsp/language-server.js';
+export * from './lsp/diagram-server.js';
+export * from './rest/server.js';
+export * from './lsp/providers/browser-fs-provider.js';
+export * from './lsp/providers/hybrid-fs-provider.js';
+export * from './lsp/protocol/reasoner-protocol.js';
+export * from './lsp/protocol/browser-fs-protocol.js';

package/src/lsp/diagram-server.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import type { SModelRoot } from 'sprotty-protocol';
+import {
+    computeLaidOutSModelForUri,
+    resolveDefinition,
+    resolveOntologyMemberLabels,
+    type OntologyMemberLabelEntry,
+    type RangeResponse,
+} from '@oml/language';
+import { RequestType } from 'vscode-languageserver-protocol';
+
+type ConnectionLike = {
+    onRequest: (type: RequestType<any, any, any>, handler: (params: any) => any | Promise<any>) => void;
+};
+
+const DiagramModelRequest = new RequestType<{ modelUri: string }, SModelRoot, void>('oml/diagram/model');
+const DefinitionRequest = new RequestType<{ elementId: string; referencingUri?: string }, RangeResponse | null, void>('oml/definition');
+const OntologyLabelsRequest = new RequestType<{ modelUri: string }, OntologyMemberLabelEntry[], void>('oml/labels');
+
+export function registerDiagramRequests(connection: ConnectionLike, shared: any, oml?: any): void {
+    connection.onRequest(DiagramModelRequest, async ({ modelUri }) => {
+        try {
+            return await computeLaidOutSModelForUri(shared, modelUri);
+        } catch (err) {
+            console.error('[oml] diagram model error', err);
+            return { id: 'root', type: 'graph', children: [] } as unknown as SModelRoot;
+        }
+    });
+
+    connection.onRequest(DefinitionRequest, async ({ elementId, referencingUri }) => {
+        try {
+            return await resolveDefinition(shared, elementId, referencingUri);
+        } catch (err) {
+            console.error('[oml] definition error', err);
+            return null;
+        }
+    });
+
+    connection.onRequest(OntologyLabelsRequest, async ({ modelUri }) => {
+        try {
+            return await resolveOntologyMemberLabels(shared, oml, modelUri);
+        } catch (err) {
+            console.error('[oml] labels error', err);
+            return [];
+        }
+    });
+}