@oml/cli 0.13.0 → 0.14.0

package/src/commands/render.ts

@@ -1,1010 +1,38 @@
 // Copyright (c) 2026 Modelware. All rights reserved.
 
 import chalk from 'chalk';
-import * as url from 'node:url';
-import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { createRequire } from 'node:module';
-import { createHash } from 'node:crypto';
-import {
-    MarkdownHandlerRegistry,
-    MarkdownPreviewRuntime,
-    extractLeadingFrontMatter,
-    stripLeadingFrontMatter,
-    type MdBlockExecutionResult,
-    type MdBlockKind,
-    type MdExecutableBlock
-} from '@oml/markdown';
-import { runWithIriLabelSnapshot } from '@oml/markdown/renderers';
-import { STATIC_MARKDOWN_RUNTIME_BUNDLE_FILE, STATIC_MARKDOWN_RUNTIME_CSS } from '@oml/markdown/static';
-import { normalizeFormatExtension } from '../backend/reasoned-output.js';
-import { createBackend } from '../backend/create-backend.js';
-import type { CliBackend } from '../backend/backend-types.js';
 import { failCli } from '../cli-error.js';
 import { formatDuration } from '../util.js';
-import type { ReasonOptions } from './reason.js';
-import { reasonAction } from './reason.js';
-import { resolveCompileOutputRoot, resolveCompileWorkspaceRoot } from './compile.js';
-const markdownRuntime = new MarkdownPreviewRuntime(new MarkdownHandlerRegistry());
-const SUPPORTED_MD_BLOCK_KINDS = new Set<MdBlockKind>([
-    'table',
-    'tree',
-    'graph',
-    'chart',
-    'diagram',
-    'list',
-    'text',
-    'matrix',
-    'table-editor'
-]);
-const LINK_ATTRIBUTE_KEYS = new Set(['href', 'src', 'xlinkHref', 'xlink:href']);
+import { restPost } from './server/rest.js';
+import { lintAction } from './lint.js';
 
 export type RenderOptions = {
-    workspace?: string,
     md: string,
     web: string,
-    owl?: string,
-    format?: string,
     context?: string,
-    clean?: boolean,
-    only?: boolean,
-    pretty?: boolean,
-    uniqueNamesAssumption?: boolean,
-    explanations?: boolean,
-    profile?: boolean
+    authToken?: string
 };
 
-export const renderAction = async (
-    opts: RenderOptions
-): Promise<void> => {
-    const workspaceRoot = resolveCompileWorkspaceRoot(opts.workspace);
-    const owlOutputRoot = resolveCompileOutputRoot(workspaceRoot, opts.owl);
-    const rdfFormat = normalizeFormatExtension(opts.format);
-    if (!opts.only) {
-        const reasonOpts: ReasonOptions = {
-            workspace: workspaceRoot,
-            owl: owlOutputRoot,
-            format: rdfFormat,
-            clean: opts.clean,
-            pretty: opts.pretty,
-            only: false,
-            checkOnly: false,
-            uniqueNamesAssumption: opts.uniqueNamesAssumption,
-            explanations: opts.explanations,
-            profile: opts.profile,
-        };
-        await reasonAction(reasonOpts);
-    }
-    const backend = createBackend({
-        owlOutputRoot,
-        rdfFormat,
-    });
-    try {
-        const renderStartedAt = Date.now();
-        const markdownRoot = path.resolve(workspaceRoot, opts.md);
-        const output = path.resolve(opts.web);
-        const workspaceStat = await fs.stat(workspaceRoot).catch(() => undefined);
-        if (!workspaceStat || !workspaceStat.isDirectory()) {
-            failCli(chalk.red(`Workspace folder does not exist: ${workspaceRoot}`));
-        }
-        const markdownStat = await fs.stat(markdownRoot).catch(() => undefined);
-        if (!markdownStat || !markdownStat.isDirectory()) {
-            failCli(chalk.red(`Markdown folder does not exist: ${markdownRoot}`));
-        }
-
-        if (isSameOrDescendant(markdownRoot, output)) {
-            failCli(chalk.red('Web output folder cannot be inside the markdown folder.'));
-        }
-
-        if (opts.clean) {
-            await fs.rm(output, { recursive: true, force: true });
-        }
-
-        const renderableMarkdownFiles = await discoverRenderableMarkdownFiles(markdownRoot, output);
-        const discoveredWorkspaceMarkdownFiles = await discoverMarkdownFiles(workspaceRoot, output);
-        const templateFiles = await discoverTemplateMarkdownFiles(discoveredWorkspaceMarkdownFiles);
-        const templateCatalog = buildTemplateCatalog(templateFiles);
-        const explicitContextModelUri = resolveModelUriOption(opts.context, workspaceRoot);
-        const templateGenerationEnabled = explicitContextModelUri !== undefined;
-        const memberLabelSnapshot = await backend.getWorkspaceMemberLabelSnapshot(workspaceRoot);
-        const wikiPageIndex = buildWikiPageIndex(renderableMarkdownFiles, markdownRoot, output);
-        const generatedInstancePages = new Set<string>();
-        const instancePageByIri = new Map<string, string>();
-        const attemptedInstanceIris = new Set<string>();
-        const workspaceAssetFiles = new Set<string>();
-        const staticAssets = await writeStaticAssets(output);
-        let blockArtifactFiles = 0;
-        for (const file of renderableMarkdownFiles) {
-            const relative = path.relative(markdownRoot, file);
-            const outputFile = path.join(output, relative.replace(/\.md$/i, '.html'));
-            const rendered = await renderMarkdownFile(
-                backend,
-                workspaceRoot,
-                markdownRoot,
-                output,
-                file,
-                outputFile,
-                staticAssets.runtimeScriptFile,
-                staticAssets.stylesheetFile,
-                templateGenerationEnabled,
-                explicitContextModelUri,
-                memberLabelSnapshot,
-                wikiPageIndex,
-                templateCatalog,
-                generatedInstancePages,
-                instancePageByIri,
-                attemptedInstanceIris
-            );
-            const referencedWorkspaceAssets = rendered.workspaceAssets;
-            for (const asset of referencedWorkspaceAssets) {
-                workspaceAssetFiles.add(asset);
-            }
-            blockArtifactFiles += rendered.blockArtifactFiles;
-        }
-        for (const file of workspaceAssetFiles) {
-            const workspaceRelative = path.relative(workspaceRoot, file);
-            if (workspaceRelative.startsWith('..') || path.isAbsolute(workspaceRelative)) {
-                continue;
-            }
-            if (workspaceRelative.toLowerCase().endsWith('.md')) {
-                continue;
-            }
-            const markdownRelative = path.relative(markdownRoot, file);
-            const isInsideMarkdownRoot = !markdownRelative.startsWith('..') && !path.isAbsolute(markdownRelative);
-            const outputRelative = isInsideMarkdownRoot ? markdownRelative : workspaceRelative;
-            const target = path.join(output, outputRelative);
-            await fs.mkdir(path.dirname(target), { recursive: true });
-            await fs.copyFile(file, target);
-        }
-
-        if (renderableMarkdownFiles.length === 0) {
-            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)}]`));
-    } finally {
-        await backend.dispose();
-    }
-};
-
-function isSameOrDescendant(parent: string, candidate: string): boolean {
-    const relative = path.relative(parent, candidate);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-
-type TemplateFile = {
-    filePath: string;
-    typeIri: string;
-    priority: number;
-};
-
-type TemplateCatalog = {
-    byType: Map<string, TemplateFile[]>;
-};
-
-async function discoverTemplateMarkdownFiles(markdownFiles: ReadonlyArray<string>): Promise<TemplateFile[]> {
-    const templateFiles: TemplateFile[] = [];
-    for (const filePath of markdownFiles) {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const frontMatter = extractLeadingFrontMatter(content);
-        const rawType = frontMatter?.data?.type;
-        if (typeof rawType === 'string' && rawType.trim().length > 0) {
-            const priorityValue = frontMatter?.data?.priority;
-            const priority = typeof priorityValue === 'number'
-                ? priorityValue
-                : Number.parseInt(String(priorityValue ?? '0'), 10);
-            templateFiles.push({
-                filePath,
-                typeIri: normalizeTemplateTypeIri(rawType),
-                priority: Number.isFinite(priority) ? priority : 0
-            });
-        }
-    }
-    return templateFiles;
-}
-
-function normalizeTemplateTypeIri(value: string): string {
-    return value.trim().replace(/^<|>$/g, '');
-}
-
-function buildTemplateCatalog(templateFiles: ReadonlyArray<TemplateFile>): TemplateCatalog {
-    const byType = new Map<string, TemplateFile[]>();
-    for (const template of templateFiles) {
-        const list = byType.get(template.typeIri) ?? [];
-        list.push(template);
-        byType.set(template.typeIri, list);
-    }
-    for (const list of byType.values()) {
-        list.sort((left, right) => (left.priority - right.priority) || left.filePath.localeCompare(right.filePath));
-    }
-    return { byType };
-}
-
-function resolveModelUriOption(value: string | undefined, workspaceRoot: string): string | undefined {
-    if (!value) {
-        return undefined;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    if (trimmed.startsWith('workspace:/')) {
-        const resolved = resolveWorkspacePath(workspaceRoot, trimmed);
-        return resolved ? url.pathToFileURL(resolved).toString() : undefined;
-    }
-    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
-        return trimmed;
-    }
-    const absolute = path.isAbsolute(trimmed)
-        ? trimmed
-        : path.resolve(workspaceRoot, trimmed);
-    return url.pathToFileURL(absolute).toString();
-}
-
-async function discoverRenderableMarkdownFiles(root: string, outputRoot: string): Promise<string[]> {
-    const markdownFiles = await discoverMarkdownFiles(root, outputRoot);
-    const renderableFiles: string[] = [];
-    for (const filePath of markdownFiles) {
-        const content = await fs.readFile(filePath, 'utf-8');
-        const frontMatter = extractLeadingFrontMatter(content);
-        const rawType = frontMatter?.data?.type;
-        if (typeof rawType === 'string' && rawType.trim().length > 0) {
-            continue;
-        }
-        renderableFiles.push(filePath);
-    }
-    return renderableFiles;
-}
-
-async function discoverMarkdownFiles(root: string, outputRoot: string): Promise<string[]> {
-    const entries = await fs.readdir(root, { withFileTypes: true });
-    const markdownFiles: string[] = [];
-    for (const entry of entries) {
-        const fullPath = path.join(root, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
-                continue;
-            }
-            if (isSameOrDescendant(outputRoot, fullPath)) {
-                continue;
-            }
-            markdownFiles.push(...await discoverMarkdownFiles(fullPath, outputRoot));
-            continue;
-        }
-        if (!entry.isFile()) {
-            continue;
-        }
-        if (entry.name.toLowerCase().endsWith('.md')) {
-            markdownFiles.push(fullPath);
-        }
-    }
-    return markdownFiles;
-}
-
-async function renderMarkdownFile(
-    backend: CliBackend,
-    workspaceRoot: string,
-    inputRoot: string,
-    outputRoot: string,
-    inputFile: string,
-    outputFile: string,
-    runtimeScriptFile: string,
-    stylesheetFile: string,
-    templateGenerationEnabled: boolean,
-    defaultContextModelUri: string | undefined,
-    memberLabelSnapshot: Record<string, string>,
-    wikiPageIndex: ReadonlyMap<string, string>,
-    templateCatalog: TemplateCatalog,
-    generatedInstancePages: Set<string>,
-    instancePageByIri: Map<string, string>,
-    attemptedInstanceIris: Set<string>,
-    currentPageStack: Set<string> = new Set<string>(),
-    explicitMarkdown?: string,
-    forcedModelUri?: string
-): Promise<{ workspaceAssets: Set<string>; blockArtifactFiles: number }> {
-    const markdown = explicitMarkdown ?? await fs.readFile(inputFile, 'utf-8');
-    const inlineContextUri = extractLeadingFrontMatter(markdown)?.contextUri;
-    const modelUri = forcedModelUri ?? resolveContextModelUri(inputFile, inlineContextUri, workspaceRoot) ?? defaultContextModelUri;
-    const prepared = runWithIriLabelSnapshot(memberLabelSnapshot, () => markdownRuntime.prepare(markdown));
-    const rewriteResult = rewriteRenderedLinks(prepared.renderedHtml, {
-        workspaceRoot,
-        inputRoot,
-        inputFile,
-        outputRoot,
-        outputFile,
-    });
-    const executableBlocks = toExecutableBlocks(prepared.codeBlocks);
-    const optionsByBlockId = new Map(prepared.codeBlocks.map((block) => [block.id, block.options] as const));
-    const blockResults = executableBlocks.length === 0
-        ? []
-        : (await backend.executeMarkdownBlocks({
-            documentUri: url.pathToFileURL(path.resolve(inputFile)).toString(),
-            modelUri,
-            blocks: executableBlocks
-        }, workspaceRoot)).results;
-    const renderedBlockResults: RenderedBlockResult[] = blockResults.map((result) => ({
-        ...result,
-        options: optionsByBlockId.get(result.blockId)
-    }));
-    const blockRewriteResult = rewriteBlockResultLinks(renderedBlockResults, {
-        workspaceRoot,
-        inputRoot,
-        inputFile,
-        outputRoot,
-        outputFile,
-    });
-    const blockArtifacts = await writeBlockArtifacts(outputFile, blockRewriteResult.results);
-    const pageWikilinkIris = collectWikilinkIrisFromHtml(rewriteResult.html);
-    const iriAliasHrefByIri = templateGenerationEnabled && modelUri
-        ? await generateInstanceTemplatePages(
-            backend,
-            workspaceRoot,
-            inputRoot,
-            outputRoot,
-            outputFile,
-            runtimeScriptFile,
-            stylesheetFile,
-            templateGenerationEnabled,
-            modelUri,
-            memberLabelSnapshot,
-            pageWikilinkIris,
-            renderedBlockResults,
-            wikiPageIndex,
-            templateCatalog,
-            generatedInstancePages,
-            instancePageByIri,
-            attemptedInstanceIris,
-            currentPageStack
-        )
-        : {};
-    const runtimeScriptRelative = toRelativeWebPath(path.dirname(outputFile), runtimeScriptFile);
-    const stylesheetRelative = toRelativeWebPath(path.dirname(outputFile), stylesheetFile);
-    const wikiLinkHrefByKey = buildWikiLinkHrefMapForPage(wikiPageIndex, outputFile);
-    const resolvedInstanceLinks = Object.fromEntries(
-        [...instancePageByIri.entries()].map(([iri, absolute]) => [iri, toRelativeWebPath(path.dirname(outputFile), absolute)])
-    );
-    const html = wrapHtml(
-        rewriteResult.html,
-        runtimeScriptRelative,
-        stylesheetRelative,
-        blockArtifacts.manifest,
-        blockRewriteResult.results,
-        wikiLinkHrefByKey,
-        { ...resolvedInstanceLinks, ...iriAliasHrefByIri },
-        templateGenerationEnabled && Boolean(modelUri),
-        memberLabelSnapshot
-    );
-    await fs.mkdir(path.dirname(outputFile), { recursive: true });
-    await fs.writeFile(outputFile, html, 'utf-8');
-    const workspaceAssets = new Set<string>(rewriteResult.workspaceAssets);
-    for (const asset of blockRewriteResult.workspaceAssets) {
-        workspaceAssets.add(asset);
-    }
-    return { workspaceAssets, blockArtifactFiles: blockArtifacts.count };
-}
-
-type RenderedBlockResult = MdBlockExecutionResult & {
-    options?: Record<string, unknown>;
-};
-
-function toExecutableBlocks(codeBlocks: ReadonlyArray<{
-    id: string;
-    language: string;
-    content: string;
-    meta?: string;
-    options?: Record<string, unknown>;
-    lineStart: number;
-    lineEnd: number;
-}>): MdExecutableBlock[] {
-    const executable: MdExecutableBlock[] = [];
-    for (const block of codeBlocks) {
-        const kind = toMdBlockKind(block.language);
-        if (!kind) {
-            continue;
-        }
-        executable.push({
-            id: block.id,
-            kind,
-            source: block.content,
-            meta: block.meta,
-            options: block.options,
-            lineStart: block.lineStart,
-            lineEnd: block.lineEnd
-        });
-    }
-    return executable;
-}
-
-function toMdBlockKind(language: string): MdBlockKind | undefined {
-    return SUPPORTED_MD_BLOCK_KINDS.has(language as MdBlockKind) ? (language as MdBlockKind) : undefined;
-}
-
-function resolveContextModelUri(documentFile: string, contextUri: string | undefined, workspaceRoot: string): string | undefined {
-    if (!contextUri) {
-        return undefined;
-    }
-    const trimmed = contextUri.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    if (trimmed.startsWith('workspace:/')) {
-        const resolved = resolveWorkspacePath(workspaceRoot, trimmed);
-        return resolved ? url.pathToFileURL(resolved).toString() : undefined;
-    }
-    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) {
-        return trimmed;
-    }
-    if (trimmed.startsWith('/')) {
-        return url.pathToFileURL(path.resolve(workspaceRoot, trimmed.replace(/^\/+/, ''))).toString();
-    }
-    return url.pathToFileURL(path.resolve(path.dirname(documentFile), trimmed)).toString();
-}
-
-async function writeStaticAssets(outputRoot: string): Promise<{
-    runtimeScriptFile: string;
-    stylesheetFile: string;
-}> {
-    const runtimeBundle = await loadStaticRuntimeBundle();
-    const sourceStylesheet = await loadCodeBlockStylesheet();
-    const mergedStylesheet = `${sourceStylesheet}\n\n${STATIC_MARKDOWN_RUNTIME_CSS}\n`;
-    const runtimeVersion = createHash('sha1').update(runtimeBundle).digest('hex').slice(0, 12);
-    const stylesheetVersion = createHash('sha1').update(mergedStylesheet).digest('hex').slice(0, 12);
-    const runtimeFile = path.join(outputRoot, 'assets', `markdown-static-${runtimeVersion}.js`);
-    const stylesheetFile = path.join(outputRoot, 'assets', `markdown-webview-${stylesheetVersion}.css`);
-    await fs.mkdir(path.dirname(runtimeFile), { recursive: true });
-    await fs.writeFile(runtimeFile, runtimeBundle, 'utf-8');
-    await fs.writeFile(stylesheetFile, mergedStylesheet, 'utf-8');
-    return { runtimeScriptFile: runtimeFile, stylesheetFile };
-}
-
-async function loadStaticRuntimeBundle(): Promise<string> {
-    const require = createRequire(import.meta.url);
-    const staticEntry = require.resolve('@oml/markdown/static');
-    const bundlePath = path.join(path.dirname(staticEntry), STATIC_MARKDOWN_RUNTIME_BUNDLE_FILE);
-    try {
-        return await fs.readFile(bundlePath, 'utf-8');
-    } catch {
-        throw new Error(
-            `Unable to load markdown static runtime bundle at '${bundlePath}'. `
-            + 'Run the markdown package build to generate it.'
-        );
-    }
-}
-
-async function loadCodeBlockStylesheet(): Promise<string> {
-    const require = createRequire(import.meta.url);
-    const staticEntry = require.resolve('@oml/markdown/static');
-    const stylesheetPath = path.resolve(path.dirname(staticEntry), '..', '..', 'src', 'static', 'markdown-webview.css');
-    try {
-        return await fs.readFile(stylesheetPath, 'utf-8');
-    } catch {
-        throw new Error(
-            `Unable to load markdown webview stylesheet at '${stylesheetPath}'. `
-            + 'The installed @oml/markdown package is missing a required static asset.'
-        );
-    }
-}
-
-async function writeBlockArtifacts(outputFile: string, results: ReadonlyArray<RenderedBlockResult>): Promise<{
-    count: number;
-    manifest: Array<{ blockId: string; path: string }>;
-}> {
-    if (results.length === 0) {
-        return { count: 0, manifest: [] };
-    }
-    const blockDirName = `${path.basename(outputFile, '.html')}.blocks`;
-    const blockDir = path.join(path.dirname(outputFile), blockDirName);
-    await fs.mkdir(blockDir, { recursive: true });
-    const manifest: Array<{ blockId: string; path: string }> = [];
-    for (const result of results) {
-        const safeId = sanitizeBlockId(result.blockId);
-        const fileName = `${safeId}.json`;
-        const filePath = path.join(blockDir, fileName);
-        await fs.writeFile(filePath, JSON.stringify(result, null, 2), 'utf-8');
-        manifest.push({
-            blockId: result.blockId,
-            path: `./${blockDirName}/${fileName}`
-        });
-    }
-    return { count: results.length, manifest };
-}
-
-function rewriteBlockResultLinks(
-    results: ReadonlyArray<RenderedBlockResult>,
-    context: {
-        workspaceRoot: string;
-        inputRoot: string;
-        inputFile: string;
-        outputRoot: string;
-        outputFile: string;
-    }
-): {
-    results: RenderedBlockResult[];
-    workspaceAssets: Set<string>;
-} {
-    const workspaceAssets = new Set<string>();
-    const rewrittenResults = results.map((result) => rewriteLinkValue(result, context, workspaceAssets));
-    return { results: rewrittenResults, workspaceAssets };
-}
-
-function rewriteLinkValue<T>(
-    value: T,
-    context: {
-        workspaceRoot: string;
-        inputRoot: string;
-        inputFile: string;
-        outputRoot: string;
-        outputFile: string;
-    },
-    workspaceAssets: Set<string>,
-    parentKey?: string
-): T {
-    if (typeof value === 'string') {
-        if (parentKey && LINK_ATTRIBUTE_KEYS.has(parentKey)) {
-            return rewriteHref(value, context, workspaceAssets) as T;
-        }
-        return value;
-    }
-    if (Array.isArray(value)) {
-        return value.map((entry) => rewriteLinkValue(entry, context, workspaceAssets)) as T;
-    }
-    if (!value || typeof value !== 'object') {
-        return value;
-    }
-    const source = value as Record<string, unknown>;
-    const rewritten: Record<string, unknown> = {};
-    for (const [key, entry] of Object.entries(source)) {
-        rewritten[key] = rewriteLinkValue(entry, context, workspaceAssets, key);
-    }
-    return rewritten as T;
-}
-
-function sanitizeBlockId(value: string): string {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return 'block';
-    }
-    return trimmed.replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
-function rewriteRenderedLinks(
-    content: string,
-    context: {
-        workspaceRoot: string;
-        inputRoot: string;
-        inputFile: string;
-        outputRoot: string;
-        outputFile: string;
-    }
-): {
-    html: string;
-    workspaceAssets: Set<string>;
-} {
-    const workspaceAssets = new Set<string>();
-    const html = content.replace(/(\b(?:href|src)\s*=\s*)(["'])([^"']+)\2/gi, (_match, prefix: string, quote: string, rawHref: string) => {
-        const rewritten = rewriteHref(rawHref, context, workspaceAssets);
-        return `${prefix}${quote}${rewritten}${quote}`;
-    });
-    return { html, workspaceAssets };
-}
-
-function rewriteHref(
-    href: string,
-    context: {
-        workspaceRoot: string;
-        inputRoot: string;
-        inputFile: string;
-        outputRoot: string;
-        outputFile: string;
-    },
-    workspaceAssets: Set<string>
-): string {
-    const parts = splitHref(href);
-    if (!parts.path) {
-        return href;
-    }
-
-    const trimmedPath = parts.path.trim();
-    if (!trimmedPath || trimmedPath.startsWith('#') || trimmedPath.startsWith('//')) {
-        return href;
-    }
-
-    if (trimmedPath.startsWith('workspace:/')) {
-        const resolved = resolveWorkspacePath(context.workspaceRoot, trimmedPath);
-        if (!resolved) {
-            return href;
-        }
-        if (!resolved.toLowerCase().endsWith('.md')) {
-            workspaceAssets.add(resolved);
-        }
-        const workspaceRelative = path.relative(context.workspaceRoot, resolved);
-        const inputRelative = path.relative(context.inputRoot, resolved);
-        const isInsideInput = !inputRelative.startsWith('..') && !path.isAbsolute(inputRelative);
-        const outputRelative = isInsideInput ? inputRelative : workspaceRelative;
-        const targetInOutput = path.join(
-            context.outputRoot,
-            resolved.toLowerCase().endsWith('.md')
-                ? outputRelative.replace(/\.md$/i, '.html')
-                : outputRelative
-        );
-        const rewrittenPath = toRelativeWebPath(path.dirname(context.outputFile), targetInOutput);
-        return `${rewrittenPath}${parts.query}${parts.fragment}`;
-    }
-
-    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmedPath)) {
-        return href;
-    }
-
-    if (!trimmedPath.startsWith('/')) {
-        const resolved = path.resolve(path.dirname(context.inputFile), trimmedPath);
-        const workspaceRelative = path.relative(context.workspaceRoot, resolved);
-        if (!workspaceRelative.startsWith('..') && !path.isAbsolute(workspaceRelative) && !resolved.toLowerCase().endsWith('.md')) {
-            workspaceAssets.add(resolved);
-        }
-    }
-
-    const rewrittenPath = trimmedPath.toLowerCase().endsWith('.md')
-        ? trimmedPath.slice(0, -3) + '.html'
-        : trimmedPath;
-    return `${rewrittenPath}${parts.query}${parts.fragment}`;
-}
-
-function resolveWorkspacePath(workspaceRoot: string, hrefPath: string): string | undefined {
-    const relative = hrefPath.slice('workspace:/'.length).replace(/^\/+/, '');
-    const resolved = path.resolve(workspaceRoot, relative);
-    const relativeToWorkspace = path.relative(workspaceRoot, resolved);
-    if (relativeToWorkspace.startsWith('..') || path.isAbsolute(relativeToWorkspace)) {
-        return undefined;
-    }
-    return resolved;
-}
-
-function splitHref(href: string): { path: string; query: string; fragment: string } {
-    const hashIndex = href.indexOf('#');
-    const pathAndQuery = hashIndex >= 0 ? href.slice(0, hashIndex) : href;
-    const fragment = hashIndex >= 0 ? href.slice(hashIndex) : '';
-    const queryIndex = pathAndQuery.indexOf('?');
-    return {
-        path: queryIndex >= 0 ? pathAndQuery.slice(0, queryIndex) : pathAndQuery,
-        query: queryIndex >= 0 ? pathAndQuery.slice(queryIndex) : '',
-        fragment
-    };
-}
-
-function toRelativeWebPath(fromDir: string, toFile: string): string {
-    const relative = path.relative(fromDir, toFile).split(path.sep).join('/');
-    if (!relative || relative === '.') {
-        return '.';
-    }
-    return relative.startsWith('.') ? relative : `./${relative}`;
-}
-
-function normalizeWikiPathKey(raw: string): string {
-    const normalized = raw.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+/g, '/');
-    if (!normalized) {
-        return '';
-    }
-    const withoutHtml = normalized.replace(/\.html$/i, '');
-    return withoutHtml.replace(/^\.\//, '').toLowerCase();
-}
-
-function buildWikiPageIndex(markdownFiles: ReadonlyArray<string>, inputRoot: string, outputRoot: string): Map<string, string> {
-    const index = new Map<string, string>();
-    for (const markdownFile of markdownFiles) {
-        const relativeInput = path.relative(inputRoot, markdownFile).split(path.sep).join('/');
-        const normalizedRelative = normalizeWikiPathKey(relativeInput.replace(/\.md$/i, ''));
-        if (!normalizedRelative) {
-            continue;
-        }
-        const outputFile = path.join(outputRoot, relativeInput.replace(/\.md$/i, '.html'));
-        index.set(normalizedRelative, outputFile);
-    }
-    return index;
-}
-
-function buildWikiLinkHrefMapForPage(
-    wikiPageIndex: ReadonlyMap<string, string>,
-    outputFile: string
-): Record<string, string> {
-    const map: Record<string, string> = {};
-    for (const [key, targetFile] of wikiPageIndex.entries()) {
-        map[key] = toRelativeWebPath(path.dirname(outputFile), targetFile);
-    }
-    return map;
-}
-
-function collectFragmentIrisFromValue(value: unknown, collected: Set<string>): void {
-    if (typeof value === 'string') {
-        const trimmed = value.trim();
-        if (trimmed.length > 0) {
-            const iriPattern = /[a-z][a-z0-9+.-]*:[^\s<>"')\]]+/gi;
-            for (const match of trimmed.matchAll(iriPattern)) {
-                let iri = (match[0] ?? '').trim();
-                iri = iri.replace(/[.,;:!?]+$/, '');
-                if (/^[a-z][a-z0-9+.-]*:/i.test(iri)) {
-                    collected.add(iri);
-                }
-            }
-        }
+export const renderAction = async (opts: RenderOptions): Promise<void> => {
+    await lintAction({ authToken: opts.authToken });
+    const renderStartedAt = Date.now();
+    const result = await restPost<{
+        success: boolean;
+        filesRendered: number;
+        outputDir: string;
+        error?: string;
+    }>('/v0/render', {
+        ...opts,
+        only: true,
+    } as unknown as Record<string, unknown>, opts.authToken);
+
+    if (!result.success) {
+        failCli(chalk.red(result.error?.trim() || 'render failed.'));
+    }
+    if (result.filesRendered === 0) {
+        console.log(chalk.yellow(`No markdown files found.`));
         return;
     }
-    if (Array.isArray(value)) {
-        for (const entry of value) {
-            collectFragmentIrisFromValue(entry, collected);
-        }
-        return;
-    }
-    if (value && typeof value === 'object') {
-        for (const entry of Object.values(value)) {
-            collectFragmentIrisFromValue(entry, collected);
-        }
-    }
-}
-
-function collectWikilinkIrisFromResults(results: ReadonlyArray<RenderedBlockResult>): Set<string> {
-    const collected = new Set<string>();
-    for (const result of results) {
-        collectFragmentIrisFromValue(result, collected);
-    }
-    return collected;
-}
-
-function collectWikilinkIrisFromHtml(renderedHtml: string): Set<string> {
-    const collected = new Set<string>();
-    const pattern = /<a\b[^>]*\bclass=(["'])[^"']*\bwikilink\b[^"']*\1[^>]*\biri=(["'])([^"']+)\2/gi;
-    for (const match of renderedHtml.matchAll(pattern)) {
-        const iri = (match[3] ?? '').trim();
-        if (iri) {
-            collected.add(iri);
-        }
-    }
-    return collected;
-}
-
-function sanitizePathSegment(value: string): string {
-    const decoded = decodeURIComponent(value);
-    const trimmed = decoded.trim();
-    if (!trimmed) {
-        return 'instance';
-    }
-    return encodeURIComponent(trimmed);
-}
-
-function resolveInstanceOutputFile(outputRoot: string, iri: string): string | undefined {
-    let parsed: URL;
-    try {
-        parsed = new URL(iri);
-    } catch {
-        return undefined;
-    }
-    if (!parsed.hostname) {
-        return undefined;
-    }
-    const host = parsed.hostname.toLowerCase();
-    const pathSegments = parsed.pathname
-        .split('/')
-        .map((segment) => segment.trim())
-        .filter((segment) => segment.length > 0)
-        .map((segment) => sanitizePathSegment(segment));
-    const fragment = parsed.hash.replace(/^#/, '').trim();
-    const fileSegments = [host, ...pathSegments];
-    if (fragment.length > 0) {
-        fileSegments.push(sanitizePathSegment(fragment));
-    } else if (fileSegments.length === 1) {
-        fileSegments.push('index');
-    }
-    if (fileSegments.length === 0) {
-        return undefined;
-    }
-    return path.join(outputRoot, ...fileSegments) + '.html';
-}
-
-function selectTemplateForTypes(catalog: TemplateCatalog, typeIris: ReadonlySet<string>): TemplateFile | undefined {
-    const candidates: TemplateFile[] = [];
-    for (const typeIri of typeIris) {
-        const templates = catalog.byType.get(typeIri);
-        if (!templates || templates.length === 0) {
-            continue;
-        }
-        candidates.push(...templates);
-    }
-    if (candidates.length === 0) {
-        return undefined;
-    }
-    candidates.sort((left, right) => (left.priority - right.priority) || left.filePath.localeCompare(right.filePath));
-    return candidates[0];
-}
-
-async function queryRdfTypesForIris(
-    backend: CliBackend,
-    workspaceRoot: string,
-    modelUri: string,
-    iris: ReadonlyArray<string>
-): Promise<Map<string, Set<string>>> {
-    const byIri = new Map<string, Set<string>>();
-    if (iris.length === 0) {
-        return byIri;
-    }
-    const valuesClause = iris.map((iri) => `<${iri}>`).join(' ');
-    const query = `PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
-SELECT ?s ?type
-WHERE {
-  VALUES ?s { ${valuesClause} }
-  GRAPH ?g { ?s rdf:type ?type . }
-}`;
-    const result = await backend.executeMarkdownBlocks({
-        documentUri: 'file:///__oml_cli_wikilink_types__.md',
-        modelUri,
-        blocks: [{
-            id: '__oml_cli_wikilink_types__',
-            kind: 'table',
-            source: query,
-            lineStart: 0,
-            lineEnd: 0,
-        }]
-    }, workspaceRoot);
-    const block = result.results[0];
-    if (!block || block.status !== 'ok' || block.format !== 'table' || !block.payload) {
-        return byIri;
-    }
-    const subjectIndex = block.payload.columns.findIndex((column) => column === 's');
-    const typeIndex = block.payload.columns.findIndex((column) => column === 'type');
-    const left = subjectIndex >= 0 ? subjectIndex : 0;
-    const right = typeIndex >= 0 ? typeIndex : 1;
-    for (const row of block.payload.rows) {
-        const subject = (row[left] ?? '').trim();
-        const typeIri = (row[right] ?? '').trim().replace(/^<|>$/g, '');
-        if (!subject || !typeIri) {
-            continue;
-        }
-        const types = byIri.get(subject) ?? new Set<string>();
-        types.add(typeIri);
-        byIri.set(subject, types);
-    }
-    return byIri;
-}
-
-function buildTemplatePageMarkdown(templateMarkdown: string, focusIri: string, queryContextOption: string): string {
-    const body = stripLeadingFrontMatter(templateMarkdown).split('${contextIri}').join(focusIri);
-    const escapedContext = JSON.stringify(queryContextOption);
-    return `---
-contextUri: ${escapedContext}
----
-${body}`;
-}
-
-async function generateInstanceTemplatePages(
-    backend: CliBackend,
-    workspaceRoot: string,
-    inputRoot: string,
-    outputRoot: string,
-    pageOutputFile: string,
-    runtimeScriptFile: string,
-    stylesheetFile: string,
-    templateGenerationEnabled: boolean,
-    queryContextModelUri: string,
-    memberLabelSnapshot: Record<string, string>,
-    pageWikilinkIris: ReadonlySet<string>,
-    results: ReadonlyArray<RenderedBlockResult>,
-    wikiPageIndex: ReadonlyMap<string, string>,
-    templateCatalog: TemplateCatalog,
-    generatedInstancePages: Set<string>,
-    instancePageByIri: Map<string, string>,
-    attemptedInstanceIris: Set<string>,
-    currentPageStack: Set<string>
-): Promise<Record<string, string>> {
-    const iriToHref: Record<string, string> = {};
-    if (!templateGenerationEnabled) {
-        return iriToHref;
-    }
-    const wikilinkIris = [...new Set<string>([
-        ...pageWikilinkIris,
-        ...collectWikilinkIrisFromResults(results),
-    ])];
-    const unresolved = wikilinkIris.filter((iri) => !attemptedInstanceIris.has(iri));
-    for (const iri of unresolved) {
-        attemptedInstanceIris.add(iri);
-    }
-    const typesByIri = await queryRdfTypesForIris(backend, workspaceRoot, queryContextModelUri, unresolved);
-    for (const iri of unresolved) {
-        const types = typesByIri.get(iri) ?? new Set<string>();
-        const template = selectTemplateForTypes(templateCatalog, types);
-        if (!template) {
-            continue;
-        }
-        const instanceOutputFile = resolveInstanceOutputFile(outputRoot, iri);
-        if (!instanceOutputFile) {
-            continue;
-        }
-        instancePageByIri.set(iri, instanceOutputFile);
-        if (generatedInstancePages.has(instanceOutputFile) || currentPageStack.has(instanceOutputFile)) {
-            continue;
-        }
-        generatedInstancePages.add(instanceOutputFile);
-        const templateMarkdown = await fs.readFile(template.filePath, 'utf-8');
-        const instantiatedMarkdown = buildTemplatePageMarkdown(templateMarkdown, iri, queryContextModelUri);
-        const nextStack = new Set(currentPageStack);
-        nextStack.add(instanceOutputFile);
-        await renderMarkdownFile(
-            backend,
-            workspaceRoot,
-            inputRoot,
-            outputRoot,
-            template.filePath,
-            instanceOutputFile,
-            runtimeScriptFile,
-            stylesheetFile,
-            templateGenerationEnabled,
-            queryContextModelUri,
-            memberLabelSnapshot,
-            wikiPageIndex,
-            templateCatalog,
-            generatedInstancePages,
-            instancePageByIri,
-            attemptedInstanceIris,
-            nextStack,
-            instantiatedMarkdown,
-            queryContextModelUri
-        );
-    }
-    for (const iri of wikilinkIris) {
-        const absolute = instancePageByIri.get(iri);
-        if (!absolute) {
-            continue;
-        }
-        iriToHref[iri] = toRelativeWebPath(path.dirname(pageOutputFile), absolute);
-    }
-    return iriToHref;
-}
-
-function wrapHtml(
-    content: string,
-    runtimeScriptPath: string,
-    stylesheetPath: string,
-    blockManifest: Array<{ blockId: string; path: string }>,
-    blockResults: ReadonlyArray<RenderedBlockResult>,
-    wikiLinkHrefByKey: Record<string, string>,
-    iriAliasHrefByIri: Record<string, string>,
-    linkingEnabled: boolean,
-    memberLabelSnapshot?: Record<string, string>
-): string {
-    const escapedManifest = escapeJsonForScript(JSON.stringify(blockManifest));
-    const inlineResults = Object.fromEntries(blockResults.map((result) => [result.blockId, result]));
-    const escapedInlineResults = escapeJsonForScript(JSON.stringify(inlineResults));
-    const escapedWikiIndex = escapeJsonForScript(JSON.stringify(wikiLinkHrefByKey));
-    const escapedIriAliasIndex = escapeJsonForScript(JSON.stringify(iriAliasHrefByIri));
-    const escapedLinkingConfig = escapeJsonForScript(JSON.stringify({ linkingEnabled }));
-    const escapedMemberLabels = escapeJsonForScript(JSON.stringify(memberLabelSnapshot ?? {}));
-    return `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>OML Markdown</title>
-  <link rel="stylesheet" href="${escapeAttribute(stylesheetPath)}">
-</head>
-<body>
-${content}
-<script id="oml-md-block-manifest" type="application/json">${escapedManifest}</script>
-<script id="oml-md-block-inline-results" type="application/json">${escapedInlineResults}</script>
-<script id="oml-md-wikilink-index" type="application/json">${escapedWikiIndex}</script>
-<script id="oml-md-wikilink-iri-aliases" type="application/json">${escapedIriAliasIndex}</script>
-<script id="oml-md-wikilink-config" type="application/json">${escapedLinkingConfig}</script>
-<script id="oml-md-member-labels" type="application/json">${escapedMemberLabels}</script>
-<script src="${escapeAttribute(runtimeScriptPath)}"></script>
-</body>
-</html>
-`;
-}
-
-function escapeAttribute(value: string): string {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
-function escapeJsonForScript(value: string): string {
-    return value.replace(/</g, '\\u003c');
-}
+    console.log(chalk.green(`render: ${result.filesRendered} markdown file(s) rendered in ${path.relative(process.cwd(), result.outputDir) || result.outputDir} [${formatDuration(Date.now() - renderStartedAt)}]`));
+};