@oml/cli 0.14.17 → 0.16.0

package/src/cli.ts

@@ -15,6 +15,7 @@ import { notifyIfCliUpdateAvailable } from './update.js';
 import { validateAction } from './commands/validate.js';
 import { CliExitError } from './cli-error.js';
 import { trackCommand } from './auth/platform.js';
+import { readWorkspaceSettings } from '@oml/server/workspace-settings';
 
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 let debugEnabled = false;
@@ -28,20 +29,20 @@ export interface CliCommandInfo {
 export function getWorkspaceCommands(): CliCommandInfo[] {
     return [
         { name: 'lint', description: 'lints OML files and prints any syntax or validation errors' },
-        { 
-            name: 'render [options]', 
+        {
+            name: 'render [options]',
             description: 'lint the workspace, then render markdown files to static html',
-            usage: 'render -m <input-folder> -b <output-folder> [--clean] [-c <ontology-iri>]'
+            usage: 'render -m <input-folder> -b <output-folder> [-c <ontology-iri>]'
         },
-        { 
-            name: 'export [options]', 
+        {
+            name: 'export [options]',
             description: 'export asserted OWL files (no reasoning)',
-            usage: 'export [-o <dir>] [-f <ext>] [--clean] [--pretty]'
+            usage: 'export [-o <dir>] [-f <ext>] [--pretty]'
         },
-        { 
-            name: 'reason [options]', 
+        {
+            name: 'reason [options]',
             description: 'run workspace consistency checks (or persist assertions/entailments with --owl)',
-            usage: 'reason [-o <dir>] [-f <ext>] [--clean] [--pretty] [-e <true|false>]'
+            usage: 'reason [-o <dir>] [-f <ext>] [--pretty] [-e <true|false>]'
         },
         { 
             name: 'validate [options]', 
@@ -94,14 +95,20 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .option('-w, --workspace <workspace>', 'workspace root used by REST facade initialize (default: cwd)')
         .description('start an OML server')
         .action(async (port: string | undefined, options: { port?: string; workspace?: string }) => {
+            const [entitlementCache, deviceId] = await Promise.all([
+                authService.getEntitlementCache().then((c) => c ?? undefined),
+                authService.getDeviceId().catch(() => undefined),
+            ]);
             if (process.env.OML_PLATFORM_API_KEY?.trim()) {
-                await serverStartAction(port, { ...options, auth: await resolveServerStartAuth() });
+                await serverStartAction(port, { ...options, auth: await resolveServerStartAuth(), entitlementCache });
                 return;
             }
             await serverRunAction(port, {
                 ...options,
                 authService,
                 auth: await resolveServerRunAuth(authService),
+                entitlementCache,
+                deviceId,
             });
         });
 
@@ -146,19 +153,26 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('render')
-        .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('--clean', 'remove output folder before render')
+        .option('-m, --md <input-folder>', 'folder containing markdown files to render')
+        .option('-b, --web <output-folder>', 'folder where rendered static site files are written')
         .option('-c, --context <model-path>', 'workspace-relative .oml model path 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 {
                 const authToken = resolveServerRequestToken();
-                await renderAction({
-                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
-                    authToken,
-                } as Parameters<typeof renderAction>[0]);
+                const cliOpts = args[0] as Record<string, unknown> | undefined ?? {};
+                const wsSettings = await readWorkspaceSettings(process.cwd());
+                const md = cliOpts['md'] ?? wsSettings.defaults?.render?.md;
+                const web = cliOpts['web'] ?? wsSettings.defaults?.render?.web;
+                if (!md) {
+                    throw new CliExitError('Missing required option: -m, --md <input-folder>. Provide it on the command line or set defaults.render.md in .oml/settings.yml.');
+                }
+                if (!web) {
+                    throw new CliExitError('Missing required option: -b, --web <output-folder>. Provide it on the command line or set defaults.render.web in .oml/settings.yml.');
+                }
+                const context = cliOpts['context'] ?? wsSettings.defaults?.render?.context;
+                await renderAction({ md, web, context, authToken } as Parameters<typeof renderAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -170,15 +184,21 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .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 export')
         .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks')
         .description('export asserted OWL files (no reasoning)')
         .action(async (...args: unknown[]) => {
             const done = trackCommand('oml-export');
             try {
                 const authToken = resolveServerRequestToken();
+                const cliOpts = args[0] as Record<string, unknown> | undefined ?? {};
+                const wsSettings = await readWorkspaceSettings(process.cwd());
+                const owl = cliOpts['owl'] ?? wsSettings.defaults?.build?.owl;
+                if (!owl) {
+                    throw new CliExitError('Missing required option: -o, --owl <dir>. Provide it on the command line or set defaults.build.owl in .oml/settings.yml.');
+                }
                 await exportAction({
-                    ...(args[0] as Record<string, unknown> | undefined ?? {}),
+                    ...cliOpts,
+                    owl,
                     authToken,
                 } as Parameters<typeof exportAction>[0]);
                 done();
@@ -192,7 +212,6 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .command('reason')
         .option('-o, --owl <dir>', 'persist assertions/entailments to folder (default: check-only with no persistence)')
         .option('-f, --format <ext>', 'RDF format extension: ttl, trig, nt, nq, or n3', 'ttl')
-        .option('--clean', 'remove output folder before reason (only when --owl is provided)')
         .option('--pretty', 'pretty-print Turtle/TriG output with blank lines between top-level blocks (only when --owl is provided)')
         .option('-u, --unique-names-assumption [value]', 'enable or disable the unique names assumption', parseBooleanOption, true)
         .option('-e, --explanation [value]', 'enable or disable inconsistency explanations', parseBooleanOption, false)
@@ -202,7 +221,13 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
             try {
                 const { reasonAction } = await import('./commands/reason.js');
                 const authToken = resolveServerRequestToken();
-                await reasonAction({ ...(opts as Record<string, unknown>), authToken } as Parameters<typeof reasonAction>[0]);
+                const cliOpts = opts as Record<string, unknown>;
+                const wsSettings = await readWorkspaceSettings(process.cwd());
+                const owl = cliOpts['owl'] ?? wsSettings.defaults?.build?.owl;
+                if (!owl) {
+                    throw new CliExitError('Missing required option: -o, --owl <dir>. Provide it on the command line or set defaults.build.owl in .oml/settings.yml.');
+                }
+                await reasonAction({ ...cliOpts, owl, authToken } as Parameters<typeof reasonAction>[0]);
                 done();
             } catch (err) {
                 done(err);
@@ -240,6 +265,9 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         ) {
             return;
         }
+        if (!process.env.OML_PLATFORM_API_KEY?.trim() && !(await authService.hasStoredCredential())) {
+            throw new CliExitError('OML CLI authentication is required. Run \'oml login\' and retry.');
+        }
         await assertServerRunning();
     });
 
@@ -322,29 +350,21 @@ 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. For interactive use, run \'oml start\'. ' +
-            'For non-interactive use, set OML_PLATFORM_API_KEY and retry.'
+            'OML_PLATFORM_API_KEY is required for non-interactive server start. ' +
+            'Unset it and run \'oml start\' again to use interactive OAuth login instead.'
         );
     }
     return { accessToken: apiKey };
 }
 
-async function resolveServerRunAuth(authService: OmlCliAuthService): Promise<{
-    accessToken: string;
-}> {
-    let snapshot;
-    try {
-        snapshot = await authService.getServerAuthSnapshot();
-    } catch {
+async function resolveServerRunAuth(authService: OmlCliAuthService): Promise<{ accessToken: string }> {
+    if (!(await authService.hasStoredCredential())) {
+        console.error(chalk.cyan('Authentication required to start the server. Signing in...'));
         await authService.login({});
-        snapshot = await authService.getServerAuthSnapshot();
     }
-    return {
-        accessToken: snapshot.accessToken,
-    };
+    return { accessToken: (await authService.getServerAuthSnapshot()).accessToken };
 }
 
-
 function formatDetailedError(error: unknown): string {
     if (!(error instanceof Error)) {
         return String(error);

package/src/commands/export.ts

@@ -10,7 +10,6 @@ import { restPost } from './server/rest.js';
 export type ExportOptions = {
     owl?: string;
     format?: 'ttl' | 'trig' | 'nt' | 'nq' | 'n3' | string;
-    clean?: boolean;
     pretty?: boolean;
     authToken?: string;
 };
@@ -44,7 +43,6 @@ export const exportAction = async (opts: ExportOptions): Promise<void> => {
         {
             owl: opts.owl,
             format,
-            clean: opts.clean,
             pretty: opts.pretty === true,
         } as Record<string, unknown>,
         opts.authToken,

package/src/commands/lint.ts

@@ -71,7 +71,8 @@ export const lintAction = async (opts: LintOptions): Promise<void> => {
         failCli(chalk.red(formatLintSummary(result, elapsedMs)));
     }
     if (result.warnings > 0) {
-        failCli(chalk.yellow(formatLintSummary(result, elapsedMs)));
+        console.warn(chalk.yellow(formatLintSummary(result, elapsedMs)));
+        return;
     }
     console.log(chalk.green(formatLintSummary(result, elapsedMs)));
 };

package/src/commands/reason.ts

@@ -16,7 +16,6 @@ type RdfFormat = 'ttl' | 'trig' | 'nt' | 'nq' | 'n3';
 export type ReasonOptions = {
     owl?: string;
     format?: RdfFormat | string;
-    clean?: boolean;
     pretty?: boolean;
     explanation?: boolean;
     uniqueNamesAssumption?: boolean;
@@ -36,7 +35,6 @@ type AssertionsPayload = {
     files: Array<{
         modelUri: string;
         ontologyIri: string;
-        path: string;
         content: string;
     }>;
 };
@@ -150,8 +148,21 @@ function resolveEntailmentsPath(uri: string): string {
     return trimmed;
 }
 
-function modelUriToRelativePath(modelUri: string): string {
-    const trimmed = modelUri.trim();
+function ontologyIriToTempPath(ontologyIri: string, format: RdfFormat): string {
+    try {
+        const iri = new URL(ontologyIri);
+        const rawPath = iri.pathname.replace(/\/+$/, '');
+        const segments = rawPath.split('/').filter(Boolean);
+        const stem = segments.at(-1) || 'index';
+        const dirSegs = iri.host ? [iri.host, ...segments.slice(0, -1)] : segments.slice(0, -1);
+        return dirSegs.length > 0 ? path.join(...dirSegs, `${stem}.${format}`) : `${stem}.${format}`;
+    } catch {
+        return ontologyIri.replace(/[^a-zA-Z0-9_/-]/g, '_') + '.' + format;
+    }
+}
+
+function modelUriToRelativePath(modelUri: string | undefined): string {
+    const trimmed = (modelUri ?? '').trim();
     if (trimmed.startsWith('file://')) {
         const absolute = fileURLToPath(trimmed);
         const relative = path.relative(process.cwd(), absolute);
@@ -190,9 +201,7 @@ export const reasonAction = async (opts: ReasonOptions): Promise<void> => {
         : undefined;
     const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'oml-reason-cli-'));
     if (outputDir) {
-        if (opts.clean === true) {
-            await fs.rm(outputDir, { recursive: true, force: true });
-        }
+        await fs.rm(outputDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     }
     const orderedFiles = sortFilesLeafToRoot(assertions.files);
     let firstInconsistent: { file: AssertionsPayload['files'][number]; result: Record<string, unknown> } | undefined;
@@ -200,12 +209,12 @@ export const reasonAction = async (opts: ReasonOptions): Promise<void> => {
     let entailmentsProduced = 0;
     try {
         for (const file of orderedFiles) {
-            const target = path.join(tempRoot, file.path);
+            const target = path.join(tempRoot, ontologyIriToTempPath(file.ontologyIri, outputFormat));
             await fs.mkdir(path.dirname(target), { recursive: true });
             await fs.writeFile(target, prettyPrintRdf(file.content, outputFormat), 'utf-8');
         }
         for (const file of orderedFiles) {
-            const target = path.join(tempRoot, file.path);
+            const target = path.join(tempRoot, ontologyIriToTempPath(file.ontologyIri, outputFormat));
             try {
                 const result = await checkConsistency({
                     input: target,
@@ -257,7 +266,9 @@ export const reasonAction = async (opts: ReasonOptions): Promise<void> => {
         failCli(chalk.red(`reason failed: ${modelUri}: ${firstFailure.error}`));
     }
     if (firstInconsistent) {
-        const where = modelUriToRelativePath(firstInconsistent.file.modelUri);
+        const where = modelUriToRelativePath(firstInconsistent.file.modelUri)
+            || firstInconsistent.file.ontologyIri.trim()
+            || '<unknown>';
         if (opts.explanation === true) {
             failCli(chalk.red(`Inconsistency found in: ${where}\n${JSON.stringify(firstInconsistent.result, null, 2)}`));
         }

package/src/commands/render.ts

@@ -10,7 +10,6 @@ import { restPost } from './server/rest.js';
 export type RenderOptions = {
     md: string;
     web: string;
-    clean?: boolean;
     context?: string;
     authToken?: string;
 };

package/src/commands/server/actions.ts

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 import { spawn, execFile, type ChildProcess } from 'node:child_process';
 import { promisify } from 'node:util';
 import type { OmlCliAuthService } from '../../auth/auth.js';
+import { readWorkspaceSettings } from '@oml/server/workspace-settings';
 
 const DEFAULT_HOST = '127.0.0.1';
 const STARTUP_TIMEOUT_MS = 15_000;
@@ -17,12 +18,19 @@ const SHUTDOWN_TIMEOUT_MS = 3000;
 const POLL_INTERVAL_MS = 100;
 const execFileAsync = promisify(execFile);
 
+type EntitlementCache = {
+    expiry: number;
+    featureIds: string[];
+    token?: string;
+};
+
 type StartServerOptions = {
     port?: number | string;
     workspace?: string;
     auth?: {
         accessToken: string;
     };
+    entitlementCache?: EntitlementCache;
 };
 
 type ServerStatePaths = {
@@ -63,6 +71,7 @@ function getServerStatePaths(workspace?: string): ServerStatePaths {
 
 async function cleanupStateFile(paths: ServerStatePaths): Promise<void> {
     await fs.rm(paths.lockFile, { force: true });
+    await fs.rm(paths.dir, { recursive: true, force: true });
 }
 
 function parseServerLock(raw: string): ServerLockState | undefined {
@@ -128,6 +137,7 @@ async function listRunningServers(): Promise<RunningServer[]> {
         }
         if (!isProcessAlive(state.pid)) {
             await fs.rm(lockFile, { force: true });
+            await fs.rm(path.dirname(lockFile), { recursive: true, force: true });
             continue;
         }
         servers.push({
@@ -279,6 +289,7 @@ function spawnServerProcess(
     options: {
         workspace?: string;
         auth?: { accessToken: string };
+        entitlementCache?: EntitlementCache;
     },
 ): ChildProcess {
     const args = [serverMainScript, `--port=${port}`];
@@ -289,6 +300,13 @@ function spawnServerProcess(
     if (options.auth?.accessToken) {
         args.push(`--token=${options.auth.accessToken}`);
     }
+    if (options.entitlementCache) {
+        args.push(`--entitlement-expiry=${options.entitlementCache.expiry}`);
+        args.push(`--entitlement-features=${JSON.stringify(options.entitlementCache.featureIds)}`);
+        if (options.entitlementCache.token) {
+            args.push(`--entitlement-token=${options.entitlementCache.token}`);
+        }
+    }
 
     return spawn(process.execPath, args, {
         detached,
@@ -327,7 +345,10 @@ export async function serverStartAction(portArg: number | string | undefined, op
     if (portArg !== undefined && options.port !== undefined && String(portArg) !== String(options.port)) {
         throw new Error(`Conflicting port values '${portArg}' and '${options.port}'. Use either the positional port or --port, not both.`);
     }
-    const port = normalizeStartPort(options.port ?? portArg);
+    const workspaceRoot = options.workspace ?? process.cwd();
+    const wsSettings = await readWorkspaceSettings(workspaceRoot);
+    const settingsPort = wsSettings.server?.port;
+    const port = normalizeStartPort(options.port ?? portArg ?? settingsPort);
     const serverMainScript = resolveServerMainScript();
     const scriptExists = await canReadFile(serverMainScript);
     if (!scriptExists) {
@@ -352,6 +373,7 @@ async function serverStartDetached(
     const child = spawnServerProcess(serverMainScript, port, true, 'ignore', {
         workspace: options.workspace,
         auth: options.auth,
+        entitlementCache: options.entitlementCache,
     });
     if (!child.pid) {
         throw new Error('Failed to launch server process.');
@@ -449,13 +471,10 @@ export type RunServerOptions = {
     auth: {
         accessToken: string;
     };
+    entitlementCache?: EntitlementCache;
+    deviceId?: string;
 };
 
-function sendLspNotification(childStdin: NodeJS.WritableStream, method: string, params: unknown): void {
-    const message = JSON.stringify({ jsonrpc: '2.0', method, params });
-    const header = `Content-Length: ${Buffer.byteLength(message, 'utf-8')}\r\n\r\n`;
-    childStdin.write(header + message, 'utf-8');
-}
 
 export async function serverRunAction(portArg: number | string | undefined, options: RunServerOptions): Promise<void> {
     if (process.env.OML_PLATFORM_API_KEY?.trim()) {
@@ -486,13 +505,23 @@ export async function serverRunAction(portArg: number | string | undefined, opti
         args.push(`--workspace=${path.resolve(options.workspace)}`);
     }
     args.push(`--token=${options.auth.accessToken}`);
+    if (options.entitlementCache) {
+        args.push(`--entitlement-expiry=${options.entitlementCache.expiry}`);
+        args.push(`--entitlement-features=${JSON.stringify(options.entitlementCache.featureIds)}`);
+        if (options.entitlementCache.token) {
+            args.push(`--entitlement-token=${options.entitlementCache.token}`);
+        }
+    }
+    if (options.deviceId) {
+        args.push(`--device-id=${options.deviceId}`);
+    }
 
     const child = spawn(process.execPath, args, {
         detached: false,
-        stdio: ['pipe', 'inherit', 'inherit'],
+        stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
     });
 
-    if (!child.pid || !child.stdin) {
+    if (!child.pid) {
         throw new Error('Failed to launch server process.');
     }
 
@@ -510,7 +539,17 @@ export async function serverRunAction(portArg: number | string | undefined, opti
     process.stdout.write(`OML server running on http://${DEFAULT_HOST}:${state.port} (pid ${state.pid})\n`);
     process.stdout.write('Press Ctrl-C to stop.\n');
 
-    const stdin = child.stdin;
+    child.on('message', (msg: unknown) => {
+        if (msg && typeof msg === 'object' && (msg as Record<string, unknown>).type === 'entitlementsCached') {
+            const { expiry, featureIds, entitlementsToken } = msg as { expiry?: unknown; featureIds?: unknown; entitlementsToken?: unknown };
+            const expiryNum = Number(expiry);
+            const token = typeof entitlementsToken === 'string' ? entitlementsToken : undefined;
+            if (Number.isFinite(expiryNum) && Array.isArray(featureIds) && featureIds.every((x) => typeof x === 'string')) {
+                void options.authService.saveEntitlementCache(expiryNum, featureIds as string[], token);
+            }
+        }
+    });
+
     const REFRESH_INTERVAL_MS = 60 * 60 * 1000;
     const REFRESH_RETRY_BASE_MS = 15_000;
     const REFRESH_RETRY_MAX_MS = 5 * 60 * 1000;
@@ -538,7 +577,7 @@ export async function serverRunAction(portArg: number | string | undefined, opti
             const snapshot = await options.authService.getServerAuthSnapshot();
             if (snapshot.accessToken !== currentAccessToken) {
                 currentAccessToken = snapshot.accessToken;
-                sendLspNotification(stdin, '$/tokenRefreshed', { accessToken: snapshot.accessToken });
+                child.send({ type: 'tokenRefreshed', accessToken: snapshot.accessToken });
             }
             refreshFailureCount = 0;
             scheduleRefresh(REFRESH_INTERVAL_MS);

package/src/commands/server/rest.ts

@@ -14,6 +14,7 @@ const CLI_DEBUG_ENABLED = false;
 type ServerState = {
     pid: number;
     port: number;
+    owner?: 'cli' | 'extension' | 'unknown';
 };
 
 type Envelope<T> = {
@@ -76,7 +77,7 @@ function isProcessAlive(pid: number): boolean {
 
 function parseServerState(raw: string): ServerState | undefined {
     try {
-        const parsed = JSON.parse(raw) as { pid?: unknown; port?: unknown };
+        const parsed = JSON.parse(raw) as { pid?: unknown; port?: unknown; owner?: unknown };
         const pid = Number(parsed.pid);
         const port = Number(parsed.port);
         if (!Number.isFinite(pid) || !Number.isFinite(port)) {
@@ -87,7 +88,9 @@ function parseServerState(raw: string): ServerState | undefined {
         if (pidInt <= 0 || portInt <= 0 || portInt > 65535) {
             return undefined;
         }
-        return { pid: pidInt, port: portInt };
+        const owner = typeof parsed.owner === 'string' ? parsed.owner.trim().toLowerCase() : '';
+        const normalizedOwner = owner === 'cli' || owner === 'extension' ? owner : 'unknown';
+        return { pid: pidInt, port: portInt, owner: normalizedOwner };
     } catch {
         return undefined;
     }
@@ -178,7 +181,8 @@ function buildResponseLike(response: HttpJsonResponse): { ok: boolean; status: n
 
 export async function restGet<T>(route: string, authToken?: string): Promise<T> {
     void authToken;
-    const baseUrl = ensureServerBaseUrl(await readRunningState());
+    const state = await readRunningState();
+    const baseUrl = ensureServerBaseUrl(state);
     debugCli('rest.get.begin', { route, baseUrl });
     let response: HttpJsonResponse;
     try {
@@ -190,7 +194,7 @@ export async function restGet<T>(route: string, authToken?: string): Promise<T>
     const responseLike = buildResponseLike(response);
     const payload = parseJsonResponse<T & ErrorEnvelope>(response.status, response.statusText, response.body);
     if (!responseLike.ok) {
-        const message = normalizeServerError(payload.error);
+        const message = normalizeServerError(payload.error, state?.owner);
         debugCli('rest.get.failed', { route, status: responseLike.status, message: message ?? 'n/a' });
         throw new Error(message ?? `Server request failed: GET ${route} (${responseLike.status}).`);
     }
@@ -200,7 +204,8 @@ export async function restGet<T>(route: string, authToken?: string): Promise<T>
 
 export async function restPost<T>(route: string, body: Record<string, unknown>, authToken?: string): Promise<T> {
     void authToken;
-    const baseUrl = ensureServerBaseUrl(await readRunningState());
+    const state = await readRunningState();
+    const baseUrl = ensureServerBaseUrl(state);
     debugCli('rest.post.begin', { route, baseUrl });
     let response: HttpJsonResponse;
     try {
@@ -212,12 +217,12 @@ export async function restPost<T>(route: string, body: Record<string, unknown>,
     const responseLike = buildResponseLike(response);
     const payload = parseJsonResponse<Envelope<T> & ErrorEnvelope>(response.status, response.statusText, response.body);
     if (!responseLike.ok) {
-        const message = normalizeServerError(payload.error);
+        const message = normalizeServerError(payload.error, state?.owner);
         debugCli('rest.post.failed', { route, status: responseLike.status, message: message ?? 'n/a' });
         throw new Error(message ?? `Server request failed: POST ${route} (${responseLike.status}).`);
     }
     if (payload.ok === false) {
-        const message = normalizeServerError(payload.error);
+        const message = normalizeServerError(payload.error, state?.owner);
         debugCli('rest.post.notok', { route, message: message ?? 'n/a' });
         throw new Error(message ?? `Server request failed: POST ${route}.`);
     }
@@ -229,14 +234,17 @@ export async function restPost<T>(route: string, body: Record<string, unknown>,
     return payload.result;
 }
 
-function normalizeServerError(error: ErrorEnvelope['error']): string | undefined {
+function normalizeServerError(error: ErrorEnvelope['error'], serverOwner?: ServerState['owner']): string | undefined {
     if (typeof error === 'string' && error.trim().length > 0) {
         return error.trim();
     }
     if (error && typeof error === 'object') {
         const code = typeof error.code === 'string' ? error.code.trim().toLowerCase() : '';
         if (code === 'auth_required') {
-            return "OML server authentication is required. Sign in and restart the server with 'oml start'.";
+            if (serverOwner === 'extension') {
+                return 'OML server authentication is required. Sign in using the OML Code extension and try again.';
+            }
+            return "OML server authentication is required. Sign in using the CLI ('oml login') and try again.";
         }
         if (code === 'entitlements_pending') {
             return 'OML entitlements are still loading. Retry in a moment.';

package/src/commands/validate.ts

@@ -31,7 +31,7 @@ export const validateAction = async (opts: ValidateOptions): Promise<void> => {
     }>('/v0/validate', {}, opts.authToken);
 
     if (result.filesChecked === 0) {
-        console.log(chalk.yellow('No markdown/table-editor targets found in server workspace.'));
+        console.log(chalk.yellow('No SHACL validation targets found in server workspace.'));
         return;
     }
     printLintDiagnostics({
@@ -77,16 +77,18 @@ export const validateAction = async (opts: ValidateOptions): Promise<void> => {
     if (result.errors > 0) {
         const failingItems = Number(result.failingItems ?? 0);
         if (failingItems > 0) {
-            failCli(chalk.red(`validate: ${result.filesChecked} table-editor block(s) scanned [${formatDuration(validateElapsedMs)}]; ${failingItems} failing block(s), ${result.errors} error(s), ${result.warnings} warning(s)`));
+            failCli(chalk.red(`validate: ${result.filesChecked} SHACL target(s) scanned [${formatDuration(validateElapsedMs)}]; ${failingItems} failing block(s), ${result.errors} error(s), ${result.warnings} warning(s)`));
         }
-        failCli(chalk.red(`validate: ${result.filesChecked} item(s) checked with ${result.errors} error(s) and ${result.warnings} warning(s). [${formatDuration(validateElapsedMs)}]`));
+        failCli(chalk.red(`validate: ${result.filesChecked} SHACL target(s) checked with ${result.errors} error(s) and ${result.warnings} warning(s). [${formatDuration(validateElapsedMs)}]`));
     }
     if (result.warnings > 0) {
         const failingItems = Number(result.failingItems ?? 0);
         if (failingItems > 0) {
-            failCli(chalk.yellow(`validate: ${result.filesChecked} table-editor block(s) scanned [${formatDuration(validateElapsedMs)}]; ${failingItems} failing block(s), ${result.errors} error(s), ${result.warnings} warning(s)`));
+            console.warn(chalk.yellow(`validate: ${result.filesChecked} SHACL target(s) scanned [${formatDuration(validateElapsedMs)}]; ${failingItems} failing block(s), ${result.errors} error(s), ${result.warnings} warning(s)`));
+        } else {
+            console.warn(chalk.yellow(`validate: ${result.filesChecked} SHACL target(s) checked with ${result.warnings} warning(s). [${formatDuration(validateElapsedMs)}]`));
         }
-        failCli(chalk.yellow(`validate: ${result.filesChecked} item(s) checked with ${result.warnings} warning(s). [${formatDuration(validateElapsedMs)}]`));
+        return;
     }
-    console.log(chalk.green(`validate: ${result.filesChecked} table-editor block(s) scanned [${formatDuration(validateElapsedMs)}]`));
+    console.log(chalk.green(`validate: ${result.filesChecked} SHACL target(s) scanned [${formatDuration(validateElapsedMs)}]`));
 };