@oml/cli 0.7.0 → 0.9.0

package/src/auth.ts

@@ -1,16 +1,22 @@
 // Copyright (c) 2026 Modelware. All rights reserved.
 
+import { exchangeGitHubToken, refreshSupabaseAccessToken } from '@oml/platform';
 import chalk from 'chalk';
 import * as fs from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
-
-const DEFAULT_WHITELIST_URL = 'https://www.modelware.io/oml-code/auth/permissions.json';
-const CACHE_DURATION_MS = 5 * 60 * 1000;
+import {
+    DEFAULT_API_BASE_URL,
+    DEFAULT_SUPABASE_ANON_KEY,
+    DEFAULT_SUPABASE_URL
+} from './platform-constants.js';
 const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
 const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token';
 const GITHUB_USER_URL = 'https://api.github.com/user';
 const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liQkHYczdOAvHp5P';
+const API_BASE_URL_ENV = 'OML_PLATFORM_API_URL';
+const SUPABASE_URL_ENV = 'OML_SUPABASE_URL';
+const SUPABASE_ANON_KEY_ENV = 'OML_SUPABASE_ANON_KEY';
 
 type Provider = 'github';
 
@@ -18,37 +24,29 @@ type StoredSession = {
     provider: Provider;
     userId: string;
     userLabel?: string;
+    email: string | null;
+    tier?: string;
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+    expiresIn: number;
     signedInAt: string;
 };
 
 type LoginOptions = {
 };
 
-type AuthStatus = {
-    session: StoredSession;
-    authorized: boolean;
-};
-
 export class OmlCliAuthService {
-    private whitelistCache: Set<string> | null = null;
-    private whitelistCacheTime = 0;
 
     async login(options: LoginOptions): Promise<void> {
         const session = await this.authenticate();
-
-        const authorized = await this.isAuthorized(session);
-        if (!authorized) {
-            throw new Error('Sign in succeeded, but this account is not authorized.');
-        }
-
         await writeSession(session);
-        const summary = session.userLabel ? `${session.userLabel} (${session.userId})` : session.userId;
+        const summary = session.userLabel ?? session.email ?? 'signed-in user';
         console.error(chalk.green(`Signed in as ${summary} via ${session.provider}.`));
     }
 
     async logout(): Promise<void> {
         await deleteSession();
-        this.clearWhitelistCache();
         console.error(chalk.green('Signed out.'));
     }
 
@@ -58,69 +56,57 @@ export class OmlCliAuthService {
             console.error(chalk.yellow('Not signed in.'));
             return;
         }
-        const authorized = await this.isAuthorized(session);
         console.error(`Provider: ${session.provider}`);
         console.error(`User ID: ${session.userId}`);
         console.error(`User label: ${session.userLabel ?? '(not set)'}`);
+        console.error(`Email: ${session.email ?? '(not set)'}`);
+        console.error(`Tier: ${session.tier ?? '(not set)'}`);
         console.error(`Signed in at: ${session.signedInAt}`);
-        console.error(`Authorized: ${authorized ? 'yes' : 'no'}`);
     }
 
-    async ensureAuthenticated(operationName: string): Promise<AuthStatus> {
+    async ensureAuthenticated(operationName: string): Promise<void> {
         const session = await readSession();
         if (!session) {
             throw new Error(`${operationName} requires authentication. Run 'oml login' first.`);
         }
-
-        const authorized = await this.isAuthorized(session);
-        if (!authorized) {
-            throw new Error(`${operationName} requires authorization. Your account is not authorized.`);
-        }
-
-        return { session, authorized };
     }
 
-    private async isAuthorized(session: StoredSession): Promise<boolean> {
-        const whitelist = await this.fetchWhitelist();
-        if (!whitelist) {
-            return true;
+    async getAccessToken(): Promise<string> {
+        const session = await readSession();
+        if (!session?.accessToken) {
+            throw new Error('OML CLI authentication is required. Run \'oml login\' first.');
         }
-        const userId = session.userId.toLowerCase();
-        return whitelist.has(userId);
+        return session.accessToken;
     }
 
-    private async fetchWhitelist(): Promise<Set<string> | null> {
-        const whitelistUrl = process.env.OML_AUTH_WHITELIST_URL ?? DEFAULT_WHITELIST_URL;
-        if (!whitelistUrl) {
-            return null;
-        }
-
-        const now = Date.now();
-        if (this.whitelistCache && (now - this.whitelistCacheTime) < CACHE_DURATION_MS) {
-            return this.whitelistCache;
+    async refreshAccessToken(): Promise<string> {
+        const session = await readSession();
+        if (!session?.refreshToken) {
+            throw new Error('OML CLI authentication is required. Run \'oml login\' first.');
         }
 
+        let refreshed;
         try {
-            const response = await fetch(whitelistUrl);
-            if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-            }
-            const data = await response.json();
-            const userList = extractWhitelistEntries(data);
-            this.whitelistCache = new Set(userList.map((id) => String(id).toLowerCase()));
-            this.whitelistCacheTime = now;
-            return this.whitelistCache;
-        } catch (error) {
-            console.error(chalk.yellow(
-                `OML: Could not verify authorization. ${error instanceof Error ? error.message : String(error)}`
-            ));
-            return null;
+            refreshed = await refreshSupabaseAccessToken(
+                resolveSupabaseUrl(),
+                resolveSupabaseAnonKey(),
+                session.refreshToken
+            );
+        } catch {
+            throw new Error('Authentication refresh failed. Check your network connection or sign in again with \'oml login\'.');
         }
-    }
 
-    private clearWhitelistCache(): void {
-        this.whitelistCache = null;
-        this.whitelistCacheTime = 0;
+        const updatedSession: StoredSession = {
+            ...session,
+            accessToken: refreshed.access_token,
+            refreshToken: refreshed.refresh_token,
+            tokenType: refreshed.token_type,
+            expiresIn: refreshed.expires_in,
+            email: refreshed.email ?? session.email,
+        };
+
+        await writeSession(updatedSession);
+        return updatedSession.accessToken;
     }
 
     private async authenticate(): Promise<StoredSession> {
@@ -128,22 +114,6 @@ export class OmlCliAuthService {
     }
 }
 
-function extractWhitelistEntries(data: unknown): string[] {
-    if (Array.isArray(data)) {
-        return data.map((value) => String(value));
-    }
-    if (typeof data === 'object' && data !== null) {
-        const record = data as { allowedUsers?: unknown; users?: unknown };
-        if (Array.isArray(record.allowedUsers)) {
-            return record.allowedUsers.map((value) => String(value));
-        }
-        if (Array.isArray(record.users)) {
-            return record.users.map((value) => String(value));
-        }
-    }
-    throw new Error('Invalid whitelist format. Expected array or object with "allowedUsers" or "users" property.');
-}
-
 async function readSession(): Promise<StoredSession | undefined> {
     try {
         const content = await fs.readFile(getSessionPath(), 'utf-8');
@@ -151,13 +121,25 @@ async function readSession(): Promise<StoredSession | undefined> {
         if (!data.userId || !data.provider || !data.signedInAt) {
             return undefined;
         }
-        if (data.provider !== 'github' && data.provider !== 'microsoft') {
+        if (!data.accessToken) {
+            return undefined;
+        }
+        if (!data.refreshToken || !data.tokenType || typeof data.expiresIn !== 'number') {
+            return undefined;
+        }
+        if (data.provider !== 'github') {
             return undefined;
         }
         return {
             provider: data.provider,
             userId: data.userId,
             userLabel: data.userLabel,
+            email: data.email ?? null,
+            tier: data.tier,
+            accessToken: data.accessToken,
+            refreshToken: data.refreshToken,
+            tokenType: data.tokenType,
+            expiresIn: data.expiresIn,
             signedInAt: data.signedInAt
         };
     } catch {
@@ -189,7 +171,7 @@ async function authenticateWithGitHub(): Promise<StoredSession> {
     const clientId = resolveClientId();
     const params = new URLSearchParams({
         client_id: clientId,
-        scope: 'read:user'
+        scope: 'read:user user:email'
     });
     const response = await fetch(GITHUB_DEVICE_CODE_URL, {
         method: 'POST',
@@ -223,10 +205,18 @@ async function authenticateWithGitHub(): Promise<StoredSession> {
         throw new Error('GitHub user lookup did not return a login name.');
     }
 
+    const platformSession = await exchangeGitHubToken(resolveApiBaseUrl(), token);
+
     return {
         provider: 'github',
-        userId: user.login,
+        userId: platformSession.user_id,
         userLabel: user.login,
+        email: platformSession.email,
+        tier: platformSession.tier,
+        accessToken: platformSession.access_token,
+        refreshToken: platformSession.refresh_token,
+        tokenType: platformSession.token_type,
+        expiresIn: platformSession.expires_in,
         signedInAt: new Date().toISOString()
     };
 }
@@ -292,6 +282,18 @@ function resolveClientId(): string {
     );
 }
 
+function resolveApiBaseUrl(): string {
+    return process.env[API_BASE_URL_ENV]?.trim() || DEFAULT_API_BASE_URL;
+}
+
+function resolveSupabaseUrl(): string {
+    return process.env[SUPABASE_URL_ENV]?.trim() || DEFAULT_SUPABASE_URL;
+}
+
+function resolveSupabaseAnonKey(): string {
+    return process.env[SUPABASE_ANON_KEY_ENV]?.trim() || DEFAULT_SUPABASE_ANON_KEY;
+}
+
 function delay(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/cli.ts

@@ -1,6 +1,5 @@
 // Copyright (c) 2026 Modelware. All rights reserved.
 
-import { OmlLanguageMetaData } from '@oml/language';
 import chalk from 'chalk';
 import { Command } from 'commander';
 import * as fs from 'node:fs/promises';
@@ -12,6 +11,7 @@ import { lintAction } from './commands/lint.js';
 import { renderAction } from './commands/render.js';
 import { notifyIfCliUpdateAvailable } from './update.js';
 import { validateAction } from './commands/validate.js';
+import { initializePlatform, disposePlatform, trackCommand } from './platform.js';
 
 const __dirname = url.fileURLToPath(new URL('.', import.meta.url));
 
@@ -27,32 +27,39 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
 
     program
         .command('login')
-        .description('run GitHub device-flow sign-in for CLI authorization checks')
+        .description('sign in with GitHub for CLI authorization')
         .action(async () => {
             await authService.login({});
         });
 
     program
         .command('logout')
-        .description('remove the local beta sign-in session')
+        .description('remove the local sign-in session')
         .action(async () => {
             await authService.logout();
         });
 
     program
         .command('whoami')
-        .description('print the current beta sign-in session and authorization state')
+        .description('print the current sign-in session')
         .action(async () => {
             await authService.whoami();
         });
 
-    const fileExtensions = OmlLanguageMetaData.fileExtensions.join(', ');
     program
         .command('lint')
-        .argument('[file]', `source file (possible file extensions: ${fileExtensions})`)
         .option('-w, --workspace <dir>', 'workspace root used to resolve cross-file references', '.')
         .description('lints OML files and prints any syntax or validation errors')
-        .action(lintAction);
+        .action(async (...args: unknown[]) => {
+            const done = trackCommand('oml-lint');
+            try {
+                await lintAction(...args as Parameters<typeof lintAction>);
+                done();
+            } catch (err) {
+                done(err);
+                throw err;
+            }
+        });
 
     program
         .command('render')
@@ -69,7 +76,16 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .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')
-        .action(renderAction);
+        .action(async (...args: unknown[]) => {
+            const done = trackCommand('oml-render');
+            try {
+                await renderAction(...args as Parameters<typeof renderAction>);
+                done();
+            } catch (err) {
+                done(err);
+                throw err;
+            }
+        });
 
     program
         .command('compile')
@@ -80,7 +96,16 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .option('--only', 'skip lint and compile from the current workspace state')
         .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')
-        .action(compileAction);
+        .action(async (...args: unknown[]) => {
+            const done = trackCommand('oml-compile');
+            try {
+                await compileAction(...args as Parameters<typeof compileAction>);
+                done();
+            } catch (err) {
+                done(err);
+                throw err;
+            }
+        });
 
     program
         .command('reason')
@@ -96,8 +121,15 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .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')
         .action(async (opts) => {
-            const { reasonAction } = await import('./commands/reason.js');
-            await reasonAction(opts);
+            const done = trackCommand('oml-reason');
+            try {
+                const { reasonAction } = await import('./commands/reason.js');
+                await reasonAction(opts);
+                done();
+            } catch (err) {
+                done(err);
+                throw err;
+            }
         });
 
     program
@@ -113,16 +145,33 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
         .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')
-        .action(validateAction);
+        .action(async (...args: unknown[]) => {
+            const done = trackCommand('oml-validate');
+            try {
+                await validateAction(...args as Parameters<typeof validateAction>);
+                done();
+            } catch (err) {
+                done(err);
+                throw err;
+            }
+        });
 
     program.hook('preAction', async (_thisCommand, actionCommand) => {
         if (actionCommand.name() === 'login' || actionCommand.name() === 'logout' || actionCommand.name() === 'whoami') {
             return;
         }
-        await authService.ensureAuthenticated('OML CLI');
+        // Require either GitHub auth or API key, then connect to platform
+        if (!process.env.OML_PLATFORM_API_KEY) {
+            await authService.ensureAuthenticated('OML CLI');
+        }
+        await initializePlatform(authService);
     });
 
-    await program.parseAsync(argv);
+    try {
+        await program.parseAsync(argv);
+    } finally {
+        await disposePlatform();
+    }
     await updateCheck;
 }
 

package/src/commands/compile.ts

@@ -25,7 +25,7 @@ export const compileAction = async (opts: CompileOptions): Promise<void> => {
     const format = normalizeFormatExtension(opts.format);
 
     if (!opts.only) {
-        await lintAction(undefined, { workspace: workspaceRoot });
+        await lintAction({ workspace: workspaceRoot });
     }
 
     const workspaceStat = await fs.stat(workspaceRoot).catch(() => undefined);

package/src/commands/lint.ts

@@ -9,20 +9,16 @@ export type LintOptions = {
     workspaceRoot?: string
 };
 
-export const lintAction = async (fileName: string | undefined, opts: LintOptions): Promise<void> => {
+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(fileName, workspaceRoot);
+        const result = await backend.validate(undefined, workspaceRoot);
         if (result.filesChecked === 0) {
             console.log(chalk.yellow(`No .oml files found under ${workspaceRoot}.`));
             return;
         }
-        if (fileName && result.warnings === 0) {
-            console.log(chalk.green('lint: no syntax or validation errors found.'));
-            return;
-        }
         if (result.warnings > 0) {
             console.log(chalk.yellow(`lint: ${result.filesChecked} OML file(s) checked with ${result.warnings} warning(s). [${formatDuration(Date.now() - startedAt)}]`));
             process.exit(1);

package/src/commands/render.ts

@@ -37,7 +37,6 @@ const SUPPORTED_MD_BLOCK_KINDS = new Set<MdBlockKind>([
     'table-editor'
 ]);
 const LINK_ATTRIBUTE_KEYS = new Set(['href', 'src', 'xlinkHref', 'xlink:href']);
-const RENDER_PROFILE = process.env.OML_RENDER_PROFILE === '1';
 
 export type RenderOptions = {
     workspace?: string,
@@ -163,7 +162,6 @@ export const renderAction = async (
             console.log(chalk.yellow(`No markdown files found under ${markdownRoot}.`));
         }
         console.log(chalk.green(`render: ${renderableMarkdownFiles.length} markdown file(s) rendered in ${path.relative(process.cwd(), output) || output} [${formatDuration(Date.now() - renderStartedAt)}]`));
-        logRenderTiming('render.total', renderStartedAt, `${renderableMarkdownFiles.length} markdown file(s)`);
     } finally {
         await backend.dispose();
     }
@@ -303,7 +301,6 @@ async function renderMarkdownFile(
     explicitMarkdown?: string,
     forcedModelUri?: string
 ): Promise<{ workspaceAssets: Set<string>; blockArtifactFiles: number }> {
-    const pageStartedAt = Date.now();
     const markdown = explicitMarkdown ?? await fs.readFile(inputFile, 'utf-8');
     const prepared = markdownRuntime.prepare(markdown);
     const rewriteResult = rewriteRenderedLinks(prepared.renderedHtml, {
@@ -323,7 +320,6 @@ async function renderMarkdownFile(
             modelUri,
             blocks: executableBlocks
         }, workspaceRoot)).results;
-    logRenderTiming('render.page.blocks', pageStartedAt, path.relative(workspaceRoot, inputFile));
     const renderedBlockResults: RenderedBlockResult[] = blockResults.map((result) => ({
         ...result,
         options: optionsByBlockId.get(result.blockId)
@@ -358,7 +354,6 @@ async function renderMarkdownFile(
             currentPageStack
         )
         : {};
-    logRenderTiming('render.page.templates', pageStartedAt, path.relative(workspaceRoot, inputFile));
     const runtimeScriptRelative = toRelativeWebPath(path.dirname(outputFile), runtimeScriptFile);
     const stylesheetRelative = toRelativeWebPath(path.dirname(outputFile), stylesheetFile);
     const wikiLinkHrefByKey = buildWikiLinkHrefMapForPage(wikiPageIndex, outputFile);
@@ -381,7 +376,6 @@ async function renderMarkdownFile(
     for (const asset of blockRewriteResult.workspaceAssets) {
         workspaceAssets.add(asset);
     }
-    logRenderTiming('render.page.total', pageStartedAt, path.relative(workspaceRoot, inputFile));
     return { workspaceAssets, blockArtifactFiles: blockArtifacts.count };
 }
 
@@ -824,7 +818,6 @@ async function queryRdfTypesForIris(
     modelUri: string,
     iris: ReadonlyArray<string>
 ): Promise<Map<string, Set<string>>> {
-    const startedAt = Date.now();
     const byIri = new Map<string, Set<string>>();
     if (iris.length === 0) {
         return byIri;
@@ -865,7 +858,6 @@ WHERE {
         types.add(typeIri);
         byIri.set(subject, types);
     }
-    logRenderTiming('render.types', startedAt, `${iris.length} iri(s)`);
     return byIri;
 }
 
@@ -897,7 +889,6 @@ async function generateInstanceTemplatePages(
     attemptedInstanceIris: Set<string>,
     currentPageStack: Set<string>
 ): Promise<Record<string, string>> {
-    const startedAt = Date.now();
     const iriToHref: Record<string, string> = {};
     if (!templateGenerationEnabled) {
         return iriToHref;
@@ -958,18 +949,9 @@ async function generateInstanceTemplatePages(
         }
         iriToHref[iri] = toRelativeWebPath(path.dirname(pageOutputFile), absolute);
     }
-    logRenderTiming('render.wikilinks', startedAt, `${unresolved.length} unresolved iri(s)`);
     return iriToHref;
 }
 
-function logRenderTiming(label: string, startedAt: number, detail: string): void {
-    if (!RENDER_PROFILE) {
-        return;
-    }
-    const elapsed = Date.now() - startedAt;
-    console.log(chalk.gray(`[render-profile] ${label} ${elapsed}ms ${detail}`));
-}
-
 function wrapHtml(
     content: string,
     runtimeScriptPath: string,

package/src/platform-constants.ts

@@ -0,0 +1,5 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+export const DEFAULT_API_BASE_URL = 'https://oml-platform-worker.melaasar.workers.dev';
+export const DEFAULT_SUPABASE_URL = 'https://lrbsnujufmasiyvslhmw.supabase.co';
+export const DEFAULT_SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxyYnNudWp1Zm1hc2l5dnNsaG13Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzM3MjM3ODgsImV4cCI6MjA4OTI5OTc4OH0._gip9hlWPMbwxbS_zDIUXWLstWO7KWVev6HPU-5HVsw';

package/src/platform.ts

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+/**
+ * OML Platform integration for the CLI.
+ *
+ * The platform is the sole authorization mechanism. Users must have
+ * a valid API key configured and the platform must be reachable for
+ * commands to execute. No whitelist or other fallback is used.
+ */
+
+import { OmlClient, FileStorageAdapter } from '@oml/platform';
+import type { OmlClientConfig } from '@oml/platform';
+import chalk from 'chalk';
+import { DEFAULT_API_BASE_URL } from './platform-constants.js';
+import { OmlCliAuthService } from './auth.js';
+const API_BASE_URL_ENV = 'OML_PLATFORM_API_URL';
+
+let client: OmlClient | null = null;
+
+export type CommandInvocationTracker = ReturnType<OmlClient['trackInvocation']>;
+
+/**
+ * Initialize the platform client. Call once during CLI startup.
+ * Uses OML_PLATFORM_API_KEY when present, otherwise the stored
+ * OAuth platform session from OML CLI login.
+ * Throws if the platform is unreachable or the chosen auth mode
+ * is not configured.
+ */
+export async function initializePlatform(
+    authService: OmlCliAuthService,
+    apiBaseUrl = DEFAULT_API_BASE_URL
+): Promise<void> {
+    const key = process.env.OML_PLATFORM_API_KEY;
+    const resolvedApiBaseUrl = process.env[API_BASE_URL_ENV]?.trim() || apiBaseUrl;
+
+    const config: OmlClientConfig = {
+        apiBaseUrl: resolvedApiBaseUrl,
+        tool: 'oml-cli',
+        storage: new FileStorageAdapter(),
+        auth: key
+            ? { method: 'api_key', key }
+            : {
+                method: 'oauth',
+                getToken: () => authService.getAccessToken(),
+                refreshToken: () => authService.refreshAccessToken(),
+            },
+        onConcurrencyLimit: (info) => {
+            console.error(chalk.yellow(
+                `OML Platform: concurrent session limit reached `
+                + `(${info.active_sessions}/${info.max_sessions}). `
+                + `Close another instance or upgrade your plan.`
+            ));
+        },
+        onAuthError: (error) => {
+            console.error(chalk.red(
+                `OML Platform: authentication error — ${toGenericPlatformErrorMessage(error)}`
+            ));
+        },
+        debug: process.env.OML_PLATFORM_DEBUG === '1',
+    };
+
+    const platformClient = new OmlClient(config);
+    try {
+        await platformClient.initialize();
+    } catch (error) {
+        throw new Error(`OML CLI could not connect to the authorization service. ${toGenericPlatformErrorMessage(error)}`);
+    }
+    client = platformClient;
+}
+
+/**
+ * Dispose the platform client. Flushes any buffered telemetry
+ * and ends the session. Call at the end of CLI execution.
+ */
+export async function disposePlatform(): Promise<void> {
+    if (client) {
+        await client.dispose();
+        client = null;
+    }
+}
+
+/**
+ * Track a CLI command invocation. Returns a done() callback
+ * that should be called on completion or error.
+ */
+export function trackCommand(
+    featureId: string,
+    metadata?: Record<string, unknown>
+): CommandInvocationTracker {
+    if (!client) {
+        return (() => {}) as CommandInvocationTracker;
+    }
+    return client.trackInvocation(featureId, metadata);
+}
+
+function toGenericPlatformErrorMessage(error: unknown): string {
+    const message = error instanceof Error ? error.message.trim() : String(error).trim();
+    if (!message || message === 'fetch failed') {
+        return 'Check your network connection or sign in again with \'oml login\'.';
+    }
+    return message;
+}