shennian 0.2.64 → 0.2.66

package/dist/src/session/handlers/fs.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { convertMarkdownToPdf, defaultPdfOutputPath } from '../../tools/markdown-to-pdf.js';
 const FILE_SYSTEM_ROOTS_PATH = '__roots__';
 const MAX_FOLDER_UPLOAD_FILES = 2000;
 const MAX_FOLDER_UPLOAD_TOTAL_SIZE = 1024 * 1024 * 1024;
@@ -23,6 +24,26 @@ function makeFsEntry(entryPath) {
         modifiedAt: stat.mtimeMs,
     };
 }
+function listFileSystemRoots() {
+    if (os.platform() === 'win32') {
+        const entries = [];
+        for (let code = 65; code <= 90; code += 1) {
+            const drive = `${String.fromCharCode(code)}:\\`;
+            if (fs.existsSync(drive))
+                entries.push({ name: drive, path: drive, isDir: true });
+        }
+        return entries;
+    }
+    return [{ name: '/', path: '/', isDir: true }];
+}
+function fsErrorMessage(err, fallbackPath) {
+    const code = typeof err === 'object' && err && 'code' in err ? String(err.code) : '';
+    if (code === 'ENOENT')
+        return `Directory not found: ${fallbackPath}`;
+    if (code === 'EACCES' || code === 'EPERM')
+        return `Permission denied: ${fallbackPath}`;
+    return err instanceof Error ? err.message : String(err);
+}
 function isSafeRelativeUploadPath(relativePath) {
     if (!relativePath || relativePath === '.' || relativePath.trim() !== relativePath)
         return false;
@@ -72,7 +93,12 @@ export async function handleFsLs(runtime, req) {
     const requestedPath = req.params.path || os.homedir();
     const rootPath = req.params.rootPath || requestedPath;
     if (requestedPath === FILE_SYSTEM_ROOTS_PATH) {
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Access denied: filesystem roots are outside the authorized directory' });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: { path: FILE_SYSTEM_ROOTS_PATH, entries: listFileSystemRoots() },
+        });
         return;
     }
     const resolved = runtime.resolveAuthorizedPath(requestedPath, rootPath);
@@ -103,7 +129,7 @@ export async function handleFsLs(runtime, req) {
         });
     }
     catch (err) {
-        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: fsErrorMessage(err, dirPath) });
     }
 }
 export async function handleFsRead(runtime, req) {
@@ -267,6 +293,54 @@ export async function handleFsRename(runtime, req) {
         runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: String(err) });
     }
 }
+export async function handleFsExportMarkdownPdf(runtime, req) {
+    const requestedPath = req.params.path;
+    const rootPath = req.params.rootPath || path.dirname(requestedPath || '.');
+    const title = typeof req.params.title === 'string' ? req.params.title : undefined;
+    if (!requestedPath) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'path is required' });
+        return;
+    }
+    const resolved = runtime.resolveAuthorizedPath(requestedPath, rootPath);
+    if (!resolved.ok) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: resolved.error });
+        return;
+    }
+    if (!/\.mdx?$/i.test(resolved.path)) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: 'Only Markdown files can be exported to PDF' });
+        return;
+    }
+    const outputPath = defaultPdfOutputPath(resolved.path);
+    const checkedOutput = runtime.resolveAuthorizedPath(outputPath, rootPath);
+    if (!checkedOutput.ok) {
+        runtime.client.sendRes({ type: 'res', id: req.id, ok: false, error: checkedOutput.error });
+        return;
+    }
+    try {
+        const result = await convertMarkdownToPdf(resolved.path, {
+            outputPath: checkedOutput.path,
+            title,
+        });
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: true,
+            payload: {
+                sourcePath: resolved.path,
+                outputPath: result.outputPath,
+                entry: makeFsEntry(result.outputPath),
+            },
+        });
+    }
+    catch (err) {
+        runtime.client.sendRes({
+            type: 'res',
+            id: req.id,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 export async function handleFsTransfer(runtime, req) {
     const { name, targetPath, data, direct } = req.params;
     if (!name || !data) {

package/dist/src/session/manager.js

@@ -8,7 +8,7 @@ import { handleAgentsRefresh, handleModelsRefresh } from './handlers/agents.js';
 import { handleAgentConfigClear, handleAgentConfigGet, handleAgentConfigTest, handleAgentConfigUpsert, } from './handlers/agent-config.js';
 import { handleChatAbort, handleChatSend } from './handlers/chat.js';
 import { handleSessionRefresh } from './handlers/session-refresh.js';
-import { cleanupPendingTransfers, handleFsLs, handleFsRead, handleFsRename, handleFsWrite, handleFsTransfer, handleFsTransferAbort, handleFsTransferChunk, handleFsTransferFinish, handleFsTransferStart, } from './handlers/fs.js';
+import { cleanupPendingTransfers, handleFsLs, handleFsRead, handleFsRename, handleFsWrite, handleFsTransfer, handleFsTransferAbort, handleFsTransferChunk, handleFsTransferFinish, handleFsTransferStart, handleFsExportMarkdownPdf, } from './handlers/fs.js';
 import { handleSkillInstall, handleSkillList, handleSkillUse } from './handlers/skills.js';
 import { handleRegionProbe, handleRegionSwitch, handleUpgradeSetPolicy } from './handlers/control.js';
 import { ManagerRuntimeService, setManagerRuntimeService } from '../manager/runtime.js';
@@ -117,6 +117,9 @@ export class SessionManager {
                 case 'fs.write':
                     await handleFsWrite(runtime, req);
                     break;
+                case 'fs.export.markdown-pdf':
+                    await handleFsExportMarkdownPdf(runtime, req);
+                    break;
                 case 'fs.rename':
                     await handleFsRename(runtime, req);
                     break;

package/dist/src/session/queue.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { resolveShennianPath } from '../config/index.js';
 import { mergeProjectedSessions } from './projection.js';
+import { materializeRemoteChatAttachments } from './remote-attachments.js';
 const QUEUE_FILE = resolveShennianPath('chat-queue.json');
 function emptyQueue() {
     return { sessions: {} };
@@ -93,6 +94,10 @@ export class ChatQueueManager {
             });
             return;
         }
+        const normalizedAttachments = normalizeAttachments(params.attachments);
+        const materialized = normalizedAttachments?.length
+            ? await materializeRemoteChatAttachments({ text: params.text, attachments: normalizedAttachments, workDir: params.workDir })
+            : { text: params.text, attachments: normalizedAttachments, localized: false };
         const active = runtime.sessions.get(params.sessionId);
         const isBusy = Boolean(active?.currentRunId);
         if (!isBusy && !(readQueue().sessions[params.sessionId]?.length)) {
@@ -102,15 +107,21 @@ export class ChatQueueManager {
                 method: 'chat.send',
                 params: {
                     ...params,
+                    text: materialized.text,
                     responseId: req.id,
                     clientMessageId: params.clientMessageId ?? params.queueMessageId,
                     waitForDispatch: true,
+                    attachments: materialized.attachments,
                 },
             });
             return;
         }
         const queue = readQueue();
-        const message = queueMessageFromParams(params);
+        const message = queueMessageFromParams({
+            ...params,
+            text: materialized.text,
+            attachments: materialized.attachments,
+        });
         queue.sessions[params.sessionId] = [...(queue.sessions[params.sessionId] ?? []), message];
         writeQueue(queue);
         this.broadcast(params.sessionId);
@@ -118,7 +129,12 @@ export class ChatQueueManager {
             type: 'res',
             id: req.id,
             ok: true,
-            payload: { queued: true, queueMessageId: message.id, queue: this.getSnapshot(params.sessionId) },
+            payload: {
+                queued: true,
+                queueMessageId: message.id,
+                queue: this.getSnapshot(params.sessionId),
+                ...(materialized.localized ? { localizedAttachments: true } : {}),
+            },
         });
     }
     async handleGet(req) {

package/dist/src/session/remote-attachments.d.ts

@@ -0,0 +1,15 @@
+export type ChatAttachmentInput = {
+    path: string;
+    name: string;
+    mimeType: string;
+    previewData?: string;
+};
+export declare function materializeRemoteChatAttachments(input: {
+    text: string;
+    attachments?: ChatAttachmentInput[];
+    workDir: string;
+}): Promise<{
+    text: string;
+    attachments?: ChatAttachmentInput[];
+    localized: boolean;
+}>;

package/dist/src/session/remote-attachments.js

@@ -0,0 +1,72 @@
+// @arch docs/architecture/app/chat-attachments-preview.md
+// @test src/__tests__/session-manager.test.ts
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_REMOTE_ATTACHMENT_BYTES = Number(process.env.SHENNIAN_REMOTE_ATTACHMENT_MAX_BYTES || 50 * 1024 * 1024);
+function safeFileName(name) {
+    const cleaned = path.basename(name || 'attachment')
+        .normalize('NFKC')
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .replace(/_+/g, '_')
+        .replace(/^[ ._]+|[ ._]+$/g, '');
+    return cleaned || 'attachment';
+}
+function uniquePath(dir, name, hash) {
+    const safe = safeFileName(name);
+    const ext = path.extname(safe);
+    const stem = ext ? safe.slice(0, -ext.length) : safe;
+    const candidate = path.join(dir, safe);
+    if (!fs.existsSync(candidate))
+        return candidate;
+    return path.join(dir, `${stem}-${hash.slice(0, 8)}${ext}`);
+}
+function isHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+async function downloadRemoteAttachment(attachment, workDir) {
+    if (!isHttpUrl(attachment.path))
+        return attachment;
+    const response = await fetch(attachment.path);
+    if (!response.ok)
+        return attachment;
+    const contentLength = Number(response.headers.get('content-length') || 0);
+    if (contentLength > MAX_REMOTE_ATTACHMENT_BYTES)
+        return attachment;
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (!buffer.byteLength || buffer.byteLength > MAX_REMOTE_ATTACHMENT_BYTES)
+        return attachment;
+    const hash = crypto.createHash('sha256').update(buffer).digest('hex');
+    const uploadDir = path.join(workDir, '.uploads');
+    fs.mkdirSync(uploadDir, { recursive: true });
+    const filePath = uniquePath(uploadDir, attachment.name, hash);
+    if (!fs.existsSync(filePath))
+        fs.writeFileSync(filePath, buffer);
+    return {
+        ...attachment,
+        path: filePath,
+        mimeType: attachment.mimeType || response.headers.get('content-type') || 'application/octet-stream',
+    };
+}
+function replaceAttachmentRefs(text, before, after) {
+    if (before.path === after.path || !before.path || !after.path)
+        return text;
+    return text.split(before.path).join(after.path);
+}
+export async function materializeRemoteChatAttachments(input) {
+    if (!input.attachments?.length)
+        return { text: input.text, attachments: input.attachments, localized: false };
+    const materialized = [];
+    let text = input.text;
+    let localized = false;
+    for (const attachment of input.attachments) {
+        const next = await downloadRemoteAttachment(attachment, input.workDir).catch(() => attachment);
+        if (next.path !== attachment.path && isHttpUrl(attachment.path))
+            localized = true;
+        text = replaceAttachmentRefs(text, attachment, next);
+        materialized.push(next);
+    }
+    return { text, attachments: materialized, localized };
+}

package/dist/src/tools/markdown-to-pdf.d.ts

@@ -0,0 +1,20 @@
+export type MarkdownToPdfOptions = {
+    outputPath?: string;
+    title?: string;
+    keepHtml?: boolean;
+    chromePath?: string;
+};
+export type MarkdownToPdfResult = {
+    inputPath: string;
+    outputPath: string;
+    htmlPath: string | null;
+    browserPath: string;
+};
+export declare function defaultPdfOutputPath(inputPath: string): string;
+export declare function renderMarkdownBody(markdown: string, sourceDir?: string): string;
+export declare function renderMarkdownHtml(markdown: string, options?: {
+    title?: string;
+    sourceDir?: string;
+}): string;
+export declare function findChromiumExecutable(explicitPath?: string): Promise<string>;
+export declare function convertMarkdownToPdf(inputPath: string, options?: MarkdownToPdfOptions): Promise<MarkdownToPdfResult>;

package/dist/src/tools/markdown-to-pdf.js

@@ -0,0 +1,303 @@
+// @arch docs/features/markdown-pdf-export.md
+// @test src/__tests__/markdown-to-pdf.test.ts
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const FENCED_CODE_RE = /^```(\S*)\s*$/;
+function isWindowsAbsolutePath(value) {
+    return /^[A-Za-z]:([\\/]|$)/.test(value) || /^\\\\[^\\]+\\[^\\]+/.test(value);
+}
+function pathApiForPath(value) {
+    return isWindowsAbsolutePath(value) ? path.win32 : path;
+}
+export function defaultPdfOutputPath(inputPath) {
+    const api = pathApiForPath(inputPath);
+    const parsed = api.parse(inputPath);
+    return api.join(parsed.dir, `${parsed.name}.pdf`);
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/<[^>]+>/g, '')
+        .replace(/[^\p{L}\p{N}]+/gu, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function renderInline(markdown, sourceDir) {
+    let text = escapeHtml(markdown);
+    text = text.replace(/`([^`]+)`/g, '<code>$1</code>');
+    text = text.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+    text = text.replace(/__([^_]+)__/g, '<strong>$1</strong>');
+    text = text.replace(/\*([^*]+)\*/g, '<em>$1</em>');
+    text = text.replace(/_([^_]+)_/g, '<em>$1</em>');
+    text = text.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_match, alt, rawUrl) => {
+        const url = rawUrl.trim().replace(/^&lt;|&gt;$/g, '');
+        const src = toSafeAssetUrl(url, sourceDir);
+        return `<img src="${escapeHtml(src)}" alt="${alt}" />`;
+    });
+    text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, label, rawUrl) => {
+        const url = rawUrl.trim().replace(/^&lt;|&gt;$/g, '');
+        return `<a href="${escapeHtml(url)}">${label}</a>`;
+    });
+    return text;
+}
+function toSafeAssetUrl(rawUrl, sourceDir) {
+    if (/^(https?:|data:|file:)/i.test(rawUrl))
+        return rawUrl;
+    const withoutAnchor = rawUrl.split('#')[0].split('?')[0];
+    const resolved = path.resolve(sourceDir, decodeURIComponent(withoutAnchor));
+    const relative = path.relative(sourceDir, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        return '';
+    return pathToFileURL(resolved).href;
+}
+function renderTable(lines, sourceDir) {
+    if (lines.length < 2)
+        return null;
+    const separator = lines[1].trim();
+    if (!/^\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?$/.test(separator))
+        return null;
+    const parseRow = (line) => line.trim().replace(/^\||\|$/g, '').split('|').map((cell) => cell.trim());
+    const header = parseRow(lines[0]);
+    const rows = lines.slice(2).map(parseRow);
+    return [
+        '<table>',
+        '<thead><tr>',
+        ...header.map((cell) => `<th>${renderInline(cell, sourceDir)}</th>`),
+        '</tr></thead>',
+        '<tbody>',
+        ...rows.map((row) => `<tr>${row.map((cell) => `<td>${renderInline(cell, sourceDir)}</td>`).join('')}</tr>`),
+        '</tbody></table>',
+    ].join('');
+}
+export function renderMarkdownBody(markdown, sourceDir = process.cwd()) {
+    const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let paragraph = [];
+    let list = null;
+    let code = null;
+    const flushParagraph = () => {
+        if (paragraph.length === 0)
+            return;
+        out.push(`<p>${renderInline(paragraph.join(' '), sourceDir)}</p>`);
+        paragraph = [];
+    };
+    const flushList = () => {
+        if (!list)
+            return;
+        const tag = list.ordered ? 'ol' : 'ul';
+        out.push(`<${tag}>${list.items.map((item) => `<li>${renderInline(item, sourceDir)}</li>`).join('')}</${tag}>`);
+        list = null;
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const fence = line.match(FENCED_CODE_RE);
+        if (code) {
+            if (fence) {
+                out.push(`<pre><code${code.lang ? ` class="language-${escapeHtml(code.lang)}"` : ''}>${escapeHtml(code.lines.join('\n'))}</code></pre>`);
+                code = null;
+            }
+            else {
+                code.lines.push(line);
+            }
+            continue;
+        }
+        if (fence) {
+            flushParagraph();
+            flushList();
+            code = { lang: fence[1] || '', lines: [] };
+            continue;
+        }
+        if (!line.trim()) {
+            flushParagraph();
+            flushList();
+            continue;
+        }
+        const tableCandidate = lines.slice(i, i + 2);
+        const maybeTable = renderTable(tableCandidate, sourceDir);
+        if (maybeTable) {
+            const tableLines = [line, lines[i + 1]];
+            i += 2;
+            while (i < lines.length && lines[i].includes('|') && lines[i].trim()) {
+                tableLines.push(lines[i]);
+                i += 1;
+            }
+            i -= 1;
+            flushParagraph();
+            flushList();
+            out.push(renderTable(tableLines, sourceDir));
+            continue;
+        }
+        const heading = line.match(/^(#{1,6})\s+(.+)$/);
+        if (heading) {
+            flushParagraph();
+            flushList();
+            const level = heading[1].length;
+            const content = renderInline(heading[2].trim(), sourceDir);
+            const id = slugify(content);
+            out.push(`<h${level}${id ? ` id="${id}"` : ''}>${content}</h${level}>`);
+            continue;
+        }
+        const unordered = line.match(/^\s*[-*+]\s+(.+)$/);
+        const ordered = line.match(/^\s*\d+[.)]\s+(.+)$/);
+        if (unordered || ordered) {
+            flushParagraph();
+            const isOrdered = Boolean(ordered);
+            if (!list || list.ordered !== isOrdered)
+                flushList();
+            if (!list)
+                list = { ordered: isOrdered, items: [] };
+            list.items.push((unordered?.[1] ?? ordered?.[1] ?? '').trim());
+            continue;
+        }
+        const quote = line.match(/^>\s?(.+)$/);
+        if (quote) {
+            flushParagraph();
+            flushList();
+            out.push(`<blockquote>${renderInline(quote[1], sourceDir)}</blockquote>`);
+            continue;
+        }
+        if (/^---+$/.test(line.trim())) {
+            flushParagraph();
+            flushList();
+            out.push('<hr />');
+            continue;
+        }
+        paragraph.push(line.trim());
+    }
+    if (code) {
+        out.push(`<pre><code${code.lang ? ` class="language-${escapeHtml(code.lang)}"` : ''}>${escapeHtml(code.lines.join('\n'))}</code></pre>`);
+    }
+    flushParagraph();
+    flushList();
+    return out.join('\n');
+}
+export function renderMarkdownHtml(markdown, options = {}) {
+    const title = options.title || 'Markdown Export';
+    const body = renderMarkdownBody(markdown, options.sourceDir);
+    return `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>${escapeHtml(title)}</title>
+<style>
+@page { size: A4; margin: 18mm 16mm; }
+* { box-sizing: border-box; }
+body {
+  color: #111827;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.68;
+}
+h1, h2, h3, h4, h5, h6 { line-height: 1.25; margin: 1.4em 0 .55em; page-break-after: avoid; }
+h1 { font-size: 28px; border-bottom: 1px solid #e5e7eb; padding-bottom: 10px; }
+h2 { font-size: 22px; border-bottom: 1px solid #eef2f7; padding-bottom: 6px; }
+h3 { font-size: 18px; }
+p { margin: .65em 0; }
+a { color: #2563eb; text-decoration: none; }
+img { display: block; max-width: 100%; max-height: 240mm; margin: 12px auto; object-fit: contain; }
+pre { background: #f6f8fa; border: 1px solid #e5e7eb; border-radius: 10px; padding: 12px; overflow: hidden; white-space: pre-wrap; word-break: break-word; }
+code { font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace; font-size: .92em; }
+p code, li code, td code { background: #f3f4f6; border-radius: 4px; padding: 1px 4px; }
+blockquote { margin: 1em 0; padding: .6em 1em; border-left: 4px solid #d1d5db; color: #4b5563; background: #f9fafb; }
+table { border-collapse: collapse; width: 100%; margin: 1em 0; font-size: 13px; }
+th, td { border: 1px solid #d1d5db; padding: 7px 9px; vertical-align: top; }
+th { background: #f3f4f6; font-weight: 700; }
+tr { page-break-inside: avoid; }
+hr { border: none; border-top: 1px solid #e5e7eb; margin: 1.6em 0; }
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}
+function executableCandidates() {
+    const envPath = process.env.SHENNIAN_CHROME_PATH;
+    const candidates = envPath ? [envPath] : [];
+    if (process.platform === 'darwin') {
+        candidates.push('/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser');
+    }
+    else if (process.platform === 'win32') {
+        const roots = [
+            process.env.PROGRAMFILES,
+            process.env['PROGRAMFILES(X86)'],
+            process.env.LOCALAPPDATA,
+        ].filter((value) => Boolean(value));
+        for (const root of roots) {
+            candidates.push(path.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'), path.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+        }
+    }
+    else {
+        candidates.push('google-chrome-stable', 'google-chrome', 'chromium-browser', 'chromium', 'microsoft-edge', 'brave-browser');
+    }
+    return candidates;
+}
+export async function findChromiumExecutable(explicitPath) {
+    const candidates = explicitPath ? [explicitPath] : executableCandidates();
+    for (const candidate of candidates) {
+        if (candidate.includes(path.sep) || path.isAbsolute(candidate)) {
+            if (fs.existsSync(candidate))
+                return candidate;
+            continue;
+        }
+        try {
+            await execFileAsync(candidate, ['--version'], { timeout: 5000 });
+            return candidate;
+        }
+        catch {
+            // continue
+        }
+    }
+    throw new Error('No Chrome/Edge/Chromium executable found. Install Chrome/Edge/Chromium or set SHENNIAN_CHROME_PATH.');
+}
+export async function convertMarkdownToPdf(inputPath, options = {}) {
+    const resolvedInput = path.resolve(inputPath);
+    const stat = fs.statSync(resolvedInput);
+    if (!stat.isFile())
+        throw new Error(`Not a file: ${inputPath}`);
+    if (!/\.mdx?$/i.test(resolvedInput))
+        throw new Error('Input must be a Markdown file (.md or .mdx)');
+    const outputPath = path.resolve(options.outputPath || defaultPdfOutputPath(resolvedInput));
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    const markdown = fs.readFileSync(resolvedInput, 'utf8');
+    const html = renderMarkdownHtml(markdown, {
+        title: options.title || path.basename(resolvedInput),
+        sourceDir: path.dirname(resolvedInput),
+    });
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'shennian-mdpdf-'));
+    const htmlPath = options.keepHtml ? outputPath.replace(/\.pdf$/i, '.html') : path.join(tempDir, 'document.html');
+    fs.writeFileSync(htmlPath, html, 'utf8');
+    const browserPath = await findChromiumExecutable(options.chromePath);
+    const args = [
+        '--headless=new',
+        '--disable-gpu',
+        '--no-sandbox',
+        '--disable-dev-shm-usage',
+        '--allow-file-access-from-files',
+        `--print-to-pdf=${outputPath}`,
+        pathToFileURL(htmlPath).href,
+    ];
+    try {
+        await execFileAsync(browserPath, args, { timeout: 120_000, maxBuffer: 1024 * 1024 });
+    }
+    finally {
+        if (!options.keepHtml)
+            fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+    if (!fs.existsSync(outputPath) || fs.statSync(outputPath).size === 0) {
+        throw new Error('PDF export failed: output file was not created');
+    }
+    return { inputPath: resolvedInput, outputPath, htmlPath: options.keepHtml ? htmlPath : null, browserPath };
+}

package/dist/src/upgrade/engine.js

@@ -73,7 +73,7 @@ export function compareVersions(current, latest) {
 }
 // ─── npm global path helpers ──────────────────────────────────────────────────
 function getNpmGlobalRoot() {
-    return execSync('npm root -g', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    return execSync('npm root -g', { encoding: 'utf-8', stdio: 'pipe', windowsHide: true }).trim();
 }
 function getGlobalPkgDir() {
     return path.join(getNpmGlobalRoot(), 'shennian');
@@ -222,7 +222,7 @@ export async function performUpgrade(targetVersion, onProgress, opts = {}) {
     // Step 1: Verify npm is accessible
     onProgress({ step: 'checking' });
     try {
-        execSync('npm --version', { stdio: 'pipe' });
+        execSync('npm --version', { stdio: 'pipe', windowsHide: true });
     }
     catch {
         return { ok: false, error: 'npm is not available in PATH' };
@@ -231,7 +231,7 @@ export async function performUpgrade(targetVersion, onProgress, opts = {}) {
         onProgress({ step: 'verifying', version: targetVersion });
         try {
             const binScript = getGlobalBinScript();
-            const { stdout } = await exec(`node "${binScript}" --version`, { timeout: 10_000 });
+            const { stdout } = await exec(`node "${binScript}" --version`, { timeout: 10_000, windowsHide: true });
             if (!stdout.trim())
                 throw new Error('Empty output from --version check');
         }
@@ -263,7 +263,7 @@ export async function performUpgrade(targetVersion, onProgress, opts = {}) {
     // Step 3: npm install new version
     onProgress({ step: 'installing', version: targetVersion });
     try {
-        await exec(`npm install -g shennian@${targetVersion}`, { timeout: 120_000 });
+        await exec(`npm install -g shennian@${targetVersion}`, { timeout: 120_000, windowsHide: true });
     }
     catch (err) {
         // Restore backup and abort
@@ -281,7 +281,7 @@ export async function performUpgrade(targetVersion, onProgress, opts = {}) {
     onProgress({ step: 'verifying', version: targetVersion });
     try {
         const binScript = getGlobalBinScript();
-        const { stdout } = await exec(`node "${binScript}" --version`, { timeout: 10_000 });
+        const { stdout } = await exec(`node "${binScript}" --version`, { timeout: 10_000, windowsHide: true });
         if (!stdout.trim())
             throw new Error('Empty output from --version check');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shennian",
-  "version": "0.2.64",
+  "version": "0.2.66",
   "description": "Shennian — AI Agent Control Plane CLI",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "commander": "^13.1.0",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.18.1",
-    "@shennian/wire": "0.1.4"
+    "@shennian/wire": "0.1.5"
   },
   "devDependencies": {
     "@types/node": "^20",