@oml/cli 0.13.0 → 0.14.0

package/src/cli.ts

@@ -5,19 +5,56 @@ import { Command } from 'commander';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as url from 'node:url';
-import { OmlCliAuthService } from './auth.js';
-import { compileAction } from './commands/compile.js';
+import { OmlCliAuthService } from './auth/auth.js';
+import { exchangeApiToken } from '@oml/platform';
+import { DEFAULT_API_BASE_URL } from './auth/constants.js';
+import { exportAction } from './commands/export.js';
 import { lintAction } from './commands/lint.js';
 import { renderAction } from './commands/render.js';
+import { serverStartAction, serverRunAction, serverStatusAction, serverStopAction } from './commands/server/actions.js';
+import { assertServerRunning } from './commands/server/require.js';
 import { notifyIfCliUpdateAvailable } from './update.js';
 import { validateAction } from './commands/validate.js';
 import { CliExitError } from './cli-error.js';
-import { initializePlatform, disposePlatform, trackCommand } from './platform.js';
+import { initializePlatform, disposePlatform, trackCommand } from './auth/platform.js';
 
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 let debugEnabled = false;
 
+export interface CliCommandInfo {
+    name: string;
+    description: string;
+    usage?: string;
+}
+
+export function getWorkspaceCommands(): CliCommandInfo[] {
+    return [
+        { name: 'lint', description: 'lints OML files and prints any syntax or validation errors' },
+        { 
+            name: 'render [options]', 
+            description: 'lint the workspace, then render markdown files to static html',
+            usage: 'render -m <input-folder> -b <output-folder> [-c <ontology-iri>] [--only]'
+        },
+        { 
+            name: 'export [options]', 
+            description: 'export OWL files including reasoned entailments',
+            usage: 'export [-o <dir>] [-f <ext>] [--clean] [--pretty] [--only]'
+        },
+        { 
+            name: 'reason [options]', 
+            description: 'run workspace consistency checks via /v0/reason (check-only)',
+            usage: 'reason [-e <true|false>] [--only]'
+        },
+        { 
+            name: 'validate [options]', 
+            description: 'validate table-editor SHACL blocks in workspace markdown files',
+            usage: 'validate [--only]'
+        },
+    ];
+}
+
 export async function runCli(argv: string[] = process.argv): Promise<void> {
+    assertNoMalformedShortFlags(argv);
     debugEnabled = hasDebugFlag(argv);
     if (debugEnabled) {
         process.env.OML_PLATFORM_DEBUG = '1';
@@ -28,8 +65,8 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
     const updateCheck = notifyIfCliUpdateAvailable(packageJson.version);
 
     const program = new Command();
-    program.version(packageJson.version);
-    program.option('--debug', 'print detailed error diagnostics (stack traces and nested causes)');
+    program.version(packageJson.version, '-v, --version', 'output the version number');
+    program.option('-d, --debug', 'print detailed error diagnostics (stack traces and nested causes)');
     const authService = new OmlCliAuthService();
 
     program
@@ -55,12 +92,15 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('lint')
-        .option('-w, --workspace <dir>', 'workspace root used to resolve cross-file references', '.')
         .description('lints OML files and prints any syntax or validation errors')
         .action(async (...args: unknown[]) => {
             const done = trackCommand('oml-lint');
             try {
-                await lintAction(...args as Parameters<typeof lintAction>);
+                const authToken = await resolveServerRequestToken(authService);
+                await lintAction({
+                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
+                    authToken,
+                });
                 done();
             } catch (err) {
                 done(err);
@@ -70,23 +110,18 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('render')
-        .option('-w, --workspace <workspace-folder>', 'workspace root used to resolve workspace:/ links (default: current directory)')
-        .requiredOption('-md, --md <input-folder>', 'folder containing markdown files to render')
-        .requiredOption('-web, --web <output-folder>', 'folder where rendered static site files are written')
-        .option('-owl, --owl <dir>', 'folder where compiled RDF and entailment files are written')
-        .option('-f, --format <ext>', 'RDF format extension for compile/reason output: ttl, trig, nt, nq, or n3', 'ttl')
-        .option('-c, --context <model-uri>', 'default model URI/path used for markdown files without contextUri; also enables wikilink template page generation')
-        .option('--clean', 'remove output folders before rebuilding')
-        .option('--only', 'skip reason/compile/lint and render from the existing owl output folder')
-        .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks')
-        .option('-u, --unique-names-assumption [value]', 'enable or disable the unique names assumption', parseBooleanOption, true)
-        .option('-e, --explanations [value]', 'enable or disable inconsistency explanations', parseBooleanOption, true)
-        .option('-p, --profile [value]', 'include phase timings in the reasoner result', parseBooleanOption, false)
-        .description('reason the workspace, then render markdown files under the selected markdown folder to static html and copy referenced non-markdown assets')
+        .requiredOption('-m, --md <input-folder>', 'folder containing markdown files to render')
+        .requiredOption('-b, --web <output-folder>', 'folder where rendered static site files are written')
+        .option('-c, --context <ontology-iri>', 'ontology IRI used as default navigation context for wikilinks')
+        .description('lint the workspace, then render markdown files to static html')
         .action(async (...args: unknown[]) => {
             const done = trackCommand('oml-render');
             try {
-                await renderAction(...args as Parameters<typeof renderAction>);
+                const authToken = await resolveServerRequestToken(authService);
+                await renderAction({
+                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
+                    authToken,
+                } as Parameters<typeof renderAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -95,18 +130,20 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         });
 
     program
-        .command('compile')
-        .option('-w, --workspace <dir>', 'workspace root used to resolve and compile OML files', '.')
-        .option('-owl, --owl <dir>', 'folder where compiled RDF files are written')
+        .command('export')
+        .option('-o, --owl <dir>', 'folder where RDF output files are written')
         .option('-f, --format <ext>', 'RDF format extension: ttl, trig, nt, nq, or n3', 'ttl')
-        .option('--clean', 'remove output folder before compiling')
-        .option('--only', 'skip lint and compile from the current workspace state')
+        .option('--clean', 'remove output folder before export')
         .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks')
-        .description('compile OML files to RDF and write them to an output folder')
+        .description('export OWL files including reasoned entailments')
         .action(async (...args: unknown[]) => {
-            const done = trackCommand('oml-compile');
+            const done = trackCommand('oml-export');
             try {
-                await compileAction(...args as Parameters<typeof compileAction>);
+                const authToken = await resolveServerRequestToken(authService);
+                await exportAction({
+                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
+                    authToken,
+                } as Parameters<typeof exportAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -116,22 +153,15 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('reason')
-        .option('-w, --workspace <dir>', 'workspace root used to resolve and compile OML files', '.')
-        .option('-owl, --owl <dir>', 'folder where compiled RDF and entailment files are written')
-        .option('-f, --format <ext>', 'RDF format extension for compile output: ttl, trig, nt, nq, or n3', 'ttl')
-        .option('--clean', 'remove output folder before compiling')
-        .option('--only', 'skip compile/lint and reason from the existing owl output folder')
-        .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks')
-        .option('-c, --check-only', 'only check consistency; skip entailment materialization and file output')
-        .option('-u, --unique-names-assumption [value]', 'enable or disable the unique names assumption', parseBooleanOption, true)
-        .option('-e, --explanations [value]', 'enable or disable inconsistency explanations', parseBooleanOption, true)
-        .option('-p, --profile [value]', 'include phase timings in the reasoner result', parseBooleanOption, false)
-        .description('compile OML files, then run consistency checking for every ontology in dependency order')
+        .option('-e, --explanation [value]', 'enable or disable inconsistency explanations', parseBooleanOption, true)
+        .option('--only', 'skip lint and reason from the current server workspace state')
+        .description('run workspace consistency checks via /v0/reason (check-only)')
         .action(async (opts) => {
             const done = trackCommand('oml-reason');
             try {
                 const { reasonAction } = await import('./commands/reason.js');
-                await reasonAction(opts);
+                const authToken = await resolveServerRequestToken(authService);
+                await reasonAction({ ...(opts as Record<string, unknown>), authToken } as Parameters<typeof reasonAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -141,21 +171,16 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('validate')
-        .requiredOption('-md, --md <input-folder>', 'folder containing markdown files to validate recursively')
-        .option('-w, --workspace <dir>', 'workspace root used to resolve and compile OML files', '.')
-        .option('-owl, --owl <dir>', 'folder where compiled RDF and entailment files are written')
-        .option('-f, --format <ext>', 'RDF format extension for compile output: ttl, trig, nt, nq, or n3', 'ttl')
-        .option('--clean', 'remove output folder before compiling')
-        .option('--only', 'skip compile/lint and reason from the existing owl output folder')
-        .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks')
-        .option('-u, --unique-names-assumption [value]', 'enable or disable the unique names assumption', parseBooleanOption, true)
-        .option('-e, --explanations [value]', 'enable or disable inconsistency explanations', parseBooleanOption, true)
-        .option('-p, --profile [value]', 'include phase timings in the reasoner result', parseBooleanOption, false)
-        .description('compile and reason the workspace, then validate nested markdown table-editor SHACL blocks against their context models')
+        .option('--only', 'skip lint and validate markdown blocks only')
+        .description('validate table-editor SHACL blocks in workspace markdown files')
         .action(async (...args: unknown[]) => {
             const done = trackCommand('oml-validate');
             try {
-                await validateAction(...args as Parameters<typeof validateAction>);
+                const authToken = await resolveServerRequestToken(authService);
+                await validateAction({
+                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
+                    authToken,
+                } as Parameters<typeof validateAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -163,10 +188,55 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
             }
         });
 
+    const server = program
+        .command('server')
+        .description('manage the standalone OML language server daemon');
+
+    server
+        .command('start [port]')
+        .option('-p, --port <port>', 'bind port (default: auto-select free port)')
+        .option('--workspace <workspace>', 'workspace root used by REST facade initialize (default: cwd)')
+        .description('start the OML server as a background daemon (CI/CD, requires OML_PLATFORM_API_KEY)')
+        .action(async (port: string | undefined, options: { port?: string; workspace?: string }) => {
+            await serverStartAction(port, { ...options, auth: await resolveServerStartAuth() });
+        });
+
+    server
+        .command('run [port]')
+        .option('-p, --port <port>', 'bind port (default: auto-select free port)')
+        .option('--workspace <workspace>', 'workspace root (default: cwd)')
+        .description('run the OML server in the foreground with interactive authentication (Ctrl-C to stop)')
+        .action(async (port: string | undefined, options: { port?: string; workspace?: string }) => {
+            await serverRunAction(port, { ...options, auth: await resolveServerRunAuth(authService) });
+        });
+
+    server
+        .command('stop')
+        .description('stop the OML language server daemon')
+        .action(async () => {
+            await serverStopAction();
+        });
+
+    server
+        .command('status')
+        .description('print server daemon status')
+        .action(async () => {
+            await serverStatusAction();
+        });
+
     program.hook('preAction', async (_thisCommand, actionCommand) => {
-        if (actionCommand.name() === 'login' || actionCommand.name() === 'logout' || actionCommand.name() === 'whoami') {
+        if (
+            actionCommand.name() === 'login'
+            || actionCommand.name() === 'logout'
+            || actionCommand.name() === 'whoami'
+            || actionCommand.name() === 'start'
+            || actionCommand.name() === 'run'
+            || actionCommand.name() === 'stop'
+            || actionCommand.name() === 'status'
+        ) {
             return;
         }
+        await assertServerRunning();
         // Require either GitHub auth or API key, then connect to platform
         if (!process.env.OML_PLATFORM_API_KEY) {
             await authService.ensureAuthenticated('OML CLI');
@@ -182,6 +252,36 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
     await updateCheck;
 }
 
+function assertNoMalformedShortFlags(argv: string[]): void {
+    // Enforce explicit short-flag syntax (`-m value`) and long flags (`--md`).
+    // This prevents accidental typos like `-md`, which Commander interprets as `-m d`.
+    let stopOptionParsing = false;
+    for (const token of argv.slice(2)) {
+        if (stopOptionParsing) {
+            continue;
+        }
+        if (token === '--') {
+            stopOptionParsing = true;
+            continue;
+        }
+        if (token.startsWith('---')) {
+            throw new Error(
+                `Malformed flag '${token}'. Use long flags as '--name <value>' or '--name=<value>'.`,
+            );
+        }
+        if (token === '--=' || token.startsWith('--=')) {
+            throw new Error(
+                `Malformed flag '${token}'. Use long flags as '--name <value>' or '--name=<value>'.`,
+            );
+        }
+        if (/^-[^-].+/.test(token) && token.length > 2) {
+            throw new Error(
+                `Malformed flag '${token}'. Use short flags as '-x <value>' or long flags as '--name <value>'.`,
+            );
+        }
+    }
+}
+
 export function reportCliError(error: unknown): number {
     const exitCode = error instanceof CliExitError ? error.exitCode : 1;
     const message = debugEnabled
@@ -193,6 +293,14 @@ export function reportCliError(error: unknown): number {
     return exitCode;
 }
 
+process.on('unhandledRejection', (error) => {
+    const message = debugEnabled
+        ? formatDetailedError(error)
+        : (error instanceof Error ? error.message : String(error));
+    console.error(chalk.red(message));
+    process.exitCode = 1;
+});
+
 function parseBooleanOption(value: string | boolean): boolean {
     if (typeof value === 'boolean') {
         return value;
@@ -207,16 +315,52 @@ function parseBooleanOption(value: string | boolean): boolean {
     throw new Error(`Expected a boolean value, received '${value}'.`);
 }
 
-process.on('unhandledRejection', (error) => {
-    const message = debugEnabled
-        ? formatDetailedError(error)
-        : (error instanceof Error ? error.message : String(error));
-    console.error(chalk.red(message));
-    process.exitCode = 1;
-});
-
 function hasDebugFlag(argv: string[]): boolean {
-    return argv.includes('--debug');
+    return argv.includes('--debug') || argv.includes('-d');
+}
+
+async function resolveServerRequestToken(authService: OmlCliAuthService): Promise<string | undefined> {
+    const apiKey = process.env.OML_PLATFORM_API_KEY?.trim();
+    if (apiKey && apiKey.length > 0) {
+        return apiKey;
+    }
+    const snapshot = await authService.getServerAuthSnapshot();
+    return snapshot.accessToken;
+}
+
+async function resolveServerStartAuth(): Promise<{ accessToken: string }> {
+    const apiKey = process.env.OML_PLATFORM_API_KEY?.trim();
+    if (!apiKey) {
+        throw new CliExitError(
+            'OML_PLATFORM_API_KEY is not set. oml server start requires an API key for non-interactive use. ' +
+            'For interactive use, run \'oml server run\' instead.'
+        );
+    }
+    const oidcToken = process.env.OML_CI_TOKEN?.trim();
+    const apiBaseUrl = process.env.OML_PLATFORM_API_URL?.trim() ?? DEFAULT_API_BASE_URL;
+    const result = await exchangeApiToken(apiBaseUrl, apiKey, oidcToken || undefined);
+    return { accessToken: result.accessToken };
+}
+
+async function resolveServerRunAuth(authService: OmlCliAuthService): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresAtMs: number;
+    onRefresh: (newAccessToken: string, newRefreshToken: string, newExpiresAtMs: number) => Promise<void>;
+}> {
+    await authService.ensureAuthenticated('oml server run');
+    const snapshot = await authService.getServerAuthSnapshot();
+    if (!snapshot.refreshToken || snapshot.expiresAtMs === undefined) {
+        throw new CliExitError('Authentication session is incomplete. Run oml login again.');
+    }
+    return {
+        accessToken: snapshot.accessToken,
+        refreshToken: snapshot.refreshToken,
+        expiresAtMs: snapshot.expiresAtMs,
+        onRefresh: async (newAccessToken, newRefreshToken, newExpiresAtMs) => {
+            await authService.storeRefreshedTokens(newAccessToken, newRefreshToken, newExpiresAtMs);
+        },
+    };
 }
 
 function formatDetailedError(error: unknown): string {

package/src/commands/export.ts

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import chalk from 'chalk';
+import * as path from 'node:path';
+import { failCli } from '../cli-error.js';
+import { formatDuration } from '../util.js';
+import { restPost } from './server/rest.js';
+import { lintAction } from './lint.js';
+
+export type ExportOptions = {
+    owl?: string,
+    format?: string,
+    clean?: boolean,
+    pretty?: boolean,
+    authToken?: string
+};
+
+export const exportAction = async (opts: ExportOptions): Promise<void> => {
+    await lintAction({ authToken: opts.authToken });
+    const startedAt = Date.now();
+
+    const result = await restPost<{
+        success: boolean;
+        error?: string;
+        assertedExport?: {
+            success: boolean;
+            filesWritten: number;
+            outputDir: string;
+            format: string;
+            error?: string;
+        };
+        reason?: {
+            success: boolean;
+            ontologiesReasoned: number;
+            inconsistent: Array<{ modelUri: string; validationWarnings: string[] }>;
+            failed: Array<{ modelUri: string; error: string }>;
+        };
+    }>('/v0/export', {
+        ...opts,
+        only: true,
+    } as unknown as Record<string, unknown>, opts.authToken);
+
+    if (!result.success) {
+        failCli(chalk.red(result.error?.trim() || result.assertedExport?.error?.trim() || 'export failed.'));
+    }
+    const written = Number(result.assertedExport?.filesWritten ?? 0);
+    if (written === 0) {
+        console.log(chalk.yellow('No .oml files found in server workspace.'));
+        return;
+    }
+    const outputDir = result.assertedExport?.outputDir ?? opts.owl ?? path.join(process.cwd(), 'build', 'owl');
+    const reasoned = Number(result.reason?.ontologiesReasoned ?? written);
+    console.log(chalk.green(`export: ${written} OML file(s) exported with entailments (${reasoned} ontology checks) in ${path.relative(process.cwd(), outputDir) || outputDir} [${formatDuration(Date.now() - startedAt)}]`));
+};

package/src/commands/lint.ts

@@ -1,31 +1,101 @@
 // Copyright (c) 2026 Modelware. All rights reserved.
 
 import chalk from 'chalk';
-import { createBackend } from '../backend/create-backend.js';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { failCli } from '../cli-error.js';
 import { formatDuration } from '../util.js';
+import { restPost } from './server/rest.js';
+
+export type LintProblem = {
+    uri: string;
+    line: number;
+    column: number;
+    kind: 'error' | 'warning' | 'information' | 'hint' | 'unknown';
+    message: string;
+};
+
+export type LintPayload = {
+    success: boolean;
+    filesChecked: number;
+    errors: number;
+    warnings: number;
+    elapsedMs?: number;
+    returnedProblems?: number;
+    totalProblems?: number;
+    truncated?: boolean;
+    problems?: LintProblem[];
+    error?: string;
+};
 
 export type LintOptions = {
-    workspace?: string,
-    workspaceRoot?: string
+    authToken?: string
 };
 
+export function printLintDiagnostics(result: LintPayload): void {
+    const problems = Array.isArray(result.problems) ? result.problems : [];
+    if (problems.length === 0) {
+        return;
+    }
+    for (const problem of problems) {
+        const location = `${formatProblemUri(problem.uri)}:${Math.max(1, Number(problem.line ?? 1))}:${Math.max(1, Number(problem.column ?? 1))}`;
+        const kind = String(problem.kind ?? 'unknown').toLowerCase();
+        const kindLabel = kind === 'error'
+            ? chalk.red(kind)
+            : (kind === 'warning'
+                ? chalk.yellow(kind)
+                : chalk.cyan(kind));
+        console.log(`${location} ${kindLabel} ${String(problem.message ?? '').trim()}`);
+    }
+    if (result.truncated) {
+        const returned = Number(result.returnedProblems ?? problems.length);
+        const total = Number(result.totalProblems ?? returned);
+        console.log(chalk.yellow(`lint: showing ${returned} of ${total} problem(s); increase lint limit to see all.`));
+    }
+}
+
+export function formatLintSummary(result: LintPayload, elapsedMs: number): string {
+    if (result.errors > 0 || result.warnings > 0) {
+        return `lint: ${result.filesChecked} OML file(s) checked with ${result.errors} error(s) and ${result.warnings} warning(s). [${formatDuration(elapsedMs)}]`;
+    }
+    return `lint: ${result.filesChecked} OML file(s) checked. [${formatDuration(elapsedMs)}]`;
+}
+
 export const lintAction = async (opts: LintOptions): Promise<void> => {
     const startedAt = Date.now();
-    const workspaceRoot = opts.workspace ?? opts.workspaceRoot ?? '.';
-    const backend = createBackend();
-    try {
-        const result = await backend.validate(undefined, workspaceRoot);
-        if (result.filesChecked === 0) {
-            console.log(chalk.yellow(`No .oml files found under ${workspaceRoot}.`));
-            return;
-        }
-        if (result.warnings > 0) {
-            failCli(chalk.yellow(`lint: ${result.filesChecked} OML file(s) checked with ${result.warnings} warning(s). [${formatDuration(Date.now() - startedAt)}]`));
-        } else {
-            console.log(chalk.green(`lint: ${result.filesChecked} OML file(s) checked. [${formatDuration(Date.now() - startedAt)}]`));
-        }
-    } finally {
-        await backend.dispose();
+    const result = await restPost<LintPayload>('/v0/lint', {}, opts.authToken);
+    if (result.error && result.error.trim().length > 0) {
+        failCli(chalk.red(result.error.trim()));
+    }
+    if (result.filesChecked === 0) {
+        console.log(chalk.yellow('No .oml files found in server workspace.'));
+        return;
+    }
+    printLintDiagnostics(result);
+    const elapsedMs = typeof result.elapsedMs === 'number' && Number.isFinite(result.elapsedMs) && result.elapsedMs >= 0
+        ? result.elapsedMs
+        : Date.now() - startedAt;
+    if (result.errors > 0) {
+        failCli(chalk.red(formatLintSummary(result, elapsedMs)));
     }
+    if (result.warnings > 0) {
+        failCli(chalk.yellow(formatLintSummary(result, elapsedMs)));
+    }
+    console.log(chalk.green(formatLintSummary(result, elapsedMs)));
 };
+
+function formatProblemUri(uri: string): string {
+    const text = String(uri ?? '').trim();
+    if (!text) {
+        return '<unknown>';
+    }
+    if (!text.startsWith('file://')) {
+        return text;
+    }
+    try {
+        const filePath = fileURLToPath(text);
+        return path.relative(process.cwd(), filePath) || '.';
+    } catch {
+        return text;
+    }
+}