@nbtca/prompt 1.2.0 → 1.3.0

package/dist/features/docs.js

@@ -9,7 +9,7 @@ import { spawn, execFileSync } from 'child_process';
 import { URLS } from '../config/data.js';
 import { t, fmt } from '../i18n/index.js';
 import { setVimKeysActive } from '../core/vim-keys.js';
-import { createDocsClient, DocsFetchError } from '@nbtca/docs';
+import { createDocsClient } from '@nbtca/docs';
 function detectTerminalType() {
     const term = (process.env['TERM'] || '').toLowerCase();
     const termProgram = (process.env['TERM_PROGRAM'] || '').toLowerCase();
@@ -57,7 +57,6 @@ function ensureMarkedConfigured() {
 }
 // ─── marked-terminal renderer ─────────────────────────────────────────────────
 function getRendererOptions(type) {
-    // Cap at 80 columns — optimal prose reading width regardless of terminal size
     const width = Math.min(process.stdout.columns || 80, 80);
     const unicodeTableChars = {
         top: '─', 'top-mid': '┬', 'top-left': '┌', 'top-right': '┐',
@@ -75,23 +74,16 @@ function getRendererOptions(type) {
         width,
         emoji: true,
         unescape: true,
-        // Heading hierarchy: h1 cyan, h2+ white bold
         firstHeading: chalk.bold.cyan,
         heading: chalk.bold.white,
-        // Inline code: bright yellow, distinct from prose
         codespan: chalk.yellowBright,
-        // Block code: yellow (marked-terminal applies per-line)
         code: chalk.yellow,
-        // Blockquotes: italic gray, visually recessed
         blockquote: chalk.italic.gray,
-        // Prose emphasis
         strong: chalk.bold,
         em: chalk.italic,
         del: chalk.dim.strikethrough,
-        // Links: cyan underline
         link: chalk.cyan,
         href: chalk.cyan.underline,
-        // Tables with Unicode borders (fallback to ASCII on basic terminals)
         tableOptions: {
             chars: type === 'basic' ? asciiTableChars : unicodeTableChars
         }
@@ -101,17 +93,6 @@ const RENDER_CACHE_TTL_MS = 10 * 60 * 1000;
 const RENDER_CACHE_MAX = 50;
 const renderCache = new Map();
 let docsClient = createDocsClient();
-function getDocCategories() {
-    const trans = t();
-    return [
-        { name: trans.docs.categoryTutorial, path: 'tutorial' },
-        { name: trans.docs.categoryRepairLogs, path: '维修日' },
-        { name: trans.docs.categoryEvents, path: '相关活动举办' },
-        { name: trans.docs.categoryProcess, path: 'process' },
-        { name: trans.docs.categoryRepair, path: 'repair' },
-        { name: trans.docs.categoryArchived, path: 'archived' },
-    ];
-}
 function getFreshRender(key) {
     const entry = renderCache.get(key);
     return entry && entry.expiresAt > Date.now() ? entry.value : null;
@@ -131,18 +112,6 @@ export function clearDocsCache() {
     docsClient.clear();
     renderCache.clear();
 }
-async function fetchDirectory(path = '') {
-    try {
-        return await docsClient.listDir(path);
-    }
-    catch (err) {
-        const trans = t();
-        const msg = err instanceof DocsFetchError
-            ? (err.status === 403 ? `${trans.docs.githubForbidden}\n${trans.docs.githubTokenHint}` : `HTTP ${err.status}`)
-            : String(err);
-        throw new Error(fmt(trans.docs.fetchDirFailed, { error: msg }));
-    }
-}
 async function fetchFileContent(path) {
     try {
         return await docsClient.getFile(path);
@@ -167,14 +136,12 @@ function cleanMarkdownContent(content, type = getTerminalType()) {
     c = c.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
     c = c.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
     // 3. VitePress containers → blockquote with icon
-    //    ::: warning Title\ncontent\n:::
     c = c.replace(/^:::\s*(info|tip|warning|danger|details)\s*(.*?)\n([\s\S]*?)^:::\s*$/gm, (_m, type, title, body) => {
         const label = (title.trim() || type.charAt(0).toUpperCase() + type.slice(1));
         const icon = pickIcon(CONTAINER_ICONS_UNICODE[type] ?? '', CONTAINER_ICONS_ASCII[type] ?? '');
         const quoted = body.trimEnd().split('\n').map(l => `> ${l}`).join('\n');
         return `> ${icon} **${label}**\n>\n${quoted}\n`;
     });
-    // Remaining bare ::: markers
     c = c.replace(/^:::\s*\w*.*$/gm, '');
     // 4. GitHub / GitLab callout alerts  (> [!NOTE])
     c = c.replace(/^>\s*\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*$/gim, (_, type) => `> **${type.charAt(0) + type.slice(1).toLowerCase()}:**`);
@@ -200,32 +167,111 @@ function cleanMarkdownContent(content, type = getTerminalType()) {
     return c.trim();
 }
 function extractDocTitle(rawContent, cleanedContent) {
-    // 1. Try YAML frontmatter title: field (before it was stripped)
     const fmMatch = rawContent.match(/^---\n[\s\S]*?\n---/m);
     if (fmMatch) {
         const titleMatch = fmMatch[0].match(/^title:\s*['"]?(.+?)['"]?\s*$/m);
         if (titleMatch?.[1])
             return titleMatch[1].trim();
     }
-    // 2. Fallback to first # H1 heading in cleaned content
     const h1Match = cleanedContent.match(/^#\s+(.+)$/m);
     return h1Match?.[1]?.trim() ?? null;
 }
 /** Approximate reading time: ~200 words/min for technical Chinese/English prose. */
 function estimateReadTime(text) {
-    const cjkChars = (text.match(/[\u3400-\u9fff]/g) || []).length;
-    const nonCjk = text.replace(/[\u3400-\u9fff]/g, ' ');
+    const cjkChars = (text.match(/[㐀-鿿]/g) || []).length;
+    const nonCjk = text.replace(/[㐀-鿿]/g, ' ');
     const words = nonCjk.trim().split(/\s+/).filter(Boolean).length;
-    // Rough equivalence: 2 CJK chars ~= 1 "word" unit
     const units = words + cjkChars / 2;
     const mins = Math.max(1, Math.ceil(units / 220));
     return mins === 1 ? '~1 min' : `~${mins} min`;
 }
-// ─── Pager layer ──────────────────────────────────────────────────────────────
+/** Extract h2/h3 headings for TOC display (skips the h1 title). */
+function extractTOC(content) {
+    const lines = content.split('\n').filter(l => /^#{2,3}\s/.test(l));
+    return lines.map(l => {
+        const m = l.match(/^(#+)/);
+        const level = m?.[1]?.length ?? 2;
+        const text = l.replace(/^#+\s+/, '').trim();
+        return (level === 3 ? '  ' : '') + text;
+    });
+}
+/** True if the markdown source contains a table (pipe-delimited with separator row). */
+function hasMarkdownTable(content) {
+    return /^\|.+\|/m.test(content) && /^\|[-: |]+\|/m.test(content);
+}
+// ─── Document tree ────────────────────────────────────────────────────────────
+const TOP_SECTION_ORDER = ['tutorial', 'process', 'repair', 'archived'];
+const TOP_SECTION_SKIP = new Set(['docs', 'index.md', 'README.md']);
 /**
- * Display markdown via `glow` (Charmbracelet) if available — best-in-class
- * terminal markdown rendering with built-in pager and mouse support.
+ * Convert a kebab-case filename to a display-friendly title.
+ * Preserves Chinese characters and date prefixes.
  */
+function cleanFileName(name) {
+    const base = name.replace(/\.md$/, '');
+    if (/^[\d.]/.test(base))
+        return base;
+    return base
+        .replace(/[-_]/g, ' ')
+        .replace(/\b([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Group flat DocItem list into top-level sections. */
+function buildSections(all) {
+    const trans = t();
+    const labelMap = {
+        tutorial: trans.docs.categoryTutorial,
+        process: trans.docs.categoryProcess,
+        repair: trans.docs.categoryRepair,
+        archived: trans.docs.categoryArchived,
+    };
+    const groups = new Map();
+    for (const item of all) {
+        const parts = item.path.split('/');
+        if (parts.length < 2)
+            continue;
+        const top = parts[0];
+        if (TOP_SECTION_SKIP.has(top))
+            continue;
+        if (!TOP_SECTION_ORDER.includes(top))
+            continue;
+        if (!groups.has(top))
+            groups.set(top, []);
+        groups.get(top).push(item);
+    }
+    return TOP_SECTION_ORDER
+        .filter(k => groups.has(k))
+        .map(k => ({
+        key: k,
+        label: labelMap[k] ?? k,
+        count: groups.get(k).length,
+        files: groups.get(k),
+    }));
+}
+/** Group archived files by their second path component (year / manual / etc.). */
+function getArchivedGroups(files) {
+    const groups = new Map();
+    for (const item of files) {
+        const group = item.path.split('/')[1] ?? 'other';
+        if (!groups.has(group))
+            groups.set(group, []);
+        groups.get(group).push(item);
+    }
+    return groups;
+}
+async function loadSections() {
+    const trans = t();
+    const s = createSpinner(trans.docs.loading);
+    try {
+        const all = await docsClient.listAll();
+        const sections = buildSections(all);
+        s.stop();
+        return sections;
+    }
+    catch {
+        s.error(trans.docs.loadError);
+        return null;
+    }
+}
+// ─── Pager layer ──────────────────────────────────────────────────────────────
 async function displayWithGlow(cleanedMarkdown) {
     const cols = String(Math.min(process.stdout.columns || 80, 80));
     return new Promise(resolve => {
@@ -235,33 +281,34 @@ async function displayWithGlow(cleanedMarkdown) {
         child.stdin.write(cleanedMarkdown, 'utf-8');
         child.stdin.end();
         child.on('close', resolve);
-        child.on('error', resolve); // glow vanished mid-run — caller handles fallback
+        child.on('error', resolve);
     });
 }
-/**
- * Display rendered markdown via `less` with a structured document frame.
- * Flags:
- *   -R  pass raw ANSI codes through
- *   -F  exit immediately if content fits on one screen
- *   -X  don't clear the screen on exit
- *   -i  case-insensitive search (/ to search)
- *   -j4 place search hits 4 lines from the top (less jarring)
- */
-async function displayWithLess(rendered, title, filePath, readTime) {
+async function displayWithLess(rendered, title, filePath, readTime, toc) {
     const trans = t();
     const cols = Math.min(process.stdout.columns || 80, 80);
-    const rule = chalk.dim('-'.repeat(cols));
+    const rule = chalk.dim('─'.repeat(cols));
+    const tocBlock = toc.length >= 3
+        ? [
+            chalk.dim(`  ${trans.docs.tocTitle}`),
+            chalk.dim(`  ${'─'.repeat(36)}`),
+            ...toc.map(h => chalk.dim(`  ${h}`)),
+            chalk.dim(`  ${'─'.repeat(36)}`),
+            '',
+        ].join('\n')
+        : '';
     const header = [
         '',
         chalk.bold.cyan(`  ${title}`),
-        chalk.dim(`  ${filePath}`) + chalk.dim(`  |  ${readTime}`),
+        chalk.dim(`  ${filePath}`) + chalk.dim(`  ·  ${readTime}`),
         rule,
+        ...(tocBlock ? [tocBlock] : []),
         '',
     ].join('\n');
     const footer = [
         '',
         rule,
-        chalk.dim(`  ${trans.docs.endOfDocument}  |  / to search`),
+        chalk.dim(`  ${trans.docs.endOfDocument}  ·  / to search`),
         '',
     ].join('\n');
     const fullContent = header + rendered + footer;
@@ -286,66 +333,75 @@ async function displayWithLess(rendered, title, filePath, readTime) {
         }
     });
 }
-// ─── Directory browser ────────────────────────────────────────────────────────
-async function browseDirectory(initialPath = '') {
-    let currentPath = initialPath;
-    while (true) {
-        const trans = t();
-        let items;
-        try {
-            const s = createSpinner(currentPath ? `${trans.docs.loadingDir}: ${currentPath}` : trans.docs.loading);
-            items = await fetchDirectory(currentPath);
-            s.stop(currentPath || trans.docs.chooseDoc);
-        }
-        catch (err) {
-            error(trans.docs.loadError);
-            const errMsg = err instanceof Error ? err.message : String(err);
-            console.log(chalk.gray(`  ${trans.docs.errorHint}: ${errMsg}`));
-            setVimKeysActive(false);
-            const retry = await confirm({ message: trans.docs.retry });
-            setVimKeysActive(true);
-            if (!isCancel(retry) && retry)
-                continue;
-            return;
-        }
-        if (items.length === 0) {
-            warning(trans.docs.emptyDir);
-            if (currentPath) {
-                currentPath = currentPath.split('/').slice(0, -1).join('/');
-                continue;
-            }
-            return;
-        }
-        const options = [
-            ...(currentPath ? [{ value: '__back__', label: chalk.dim(trans.docs.upToParent) }] : []),
-            ...items.map(item => ({
-                value: item.path,
-                label: item.type === 'dir'
-                    ? chalk.cyan(`${item.name}/`)
-                    : item.name,
-                hint: item.type === 'dir' ? 'dir' : undefined,
-            })),
-            { value: '__exit__', label: chalk.dim(trans.docs.returnToMenu) },
-        ];
-        const selected = await select({
-            message: currentPath ? `${trans.docs.currentDir}: ${currentPath}` : trans.docs.chooseDoc,
-            options,
-        });
-        if (isCancel(selected) || selected === '__exit__')
-            return;
-        if (selected === '__back__') {
-            currentPath = currentPath.split('/').slice(0, -1).join('/');
-            continue;
-        }
-        const item = items.find(i => i.path === selected);
-        if (item?.type === 'dir') {
-            currentPath = selected;
-            continue;
-        }
-        if (item?.type === 'file') {
-            await viewMarkdownFile(selected);
-        }
+// ─── Section browsers ─────────────────────────────────────────────────────────
+/** Show a flat file list for tutorial / process / repair. */
+async function showDocSection(section) {
+    const trans = t();
+    if (section.key === 'archived') {
+        await showArchivedSection(section.files);
+        return;
     }
+    const files = section.files.filter(f => f.name !== 'index.md' && !f.name.startsWith('index.'));
+    if (files.length === 0)
+        return;
+    const selected = await select({
+        message: section.label,
+        options: [
+            ...files.map(f => {
+                const parts = f.path.split('/');
+                const hint = parts.length > 2 ? parts.slice(1, -1).join('/') : '';
+                return { value: f.path, label: cleanFileName(f.name), hint };
+            }),
+            { value: '__back__', label: chalk.dim(trans.common.back) },
+        ],
+    });
+    if (isCancel(selected) || selected === '__back__')
+        return;
+    await viewMarkdownFile(selected);
+}
+/** Show archived docs grouped by year, then files within the year. */
+async function showArchivedSection(files) {
+    const trans = t();
+    const groups = getArchivedGroups(files);
+    const sortedKeys = [...groups.keys()].sort((a, b) => {
+        const aYear = /^\d{4}$/.test(a);
+        const bYear = /^\d{4}$/.test(b);
+        if (aYear && bYear)
+            return Number(b) - Number(a);
+        if (aYear)
+            return -1;
+        if (bYear)
+            return 1;
+        return a.localeCompare(b);
+    });
+    const groupKey = await select({
+        message: trans.docs.categoryArchived,
+        options: [
+            ...sortedKeys.map(k => ({
+                value: k,
+                label: k,
+                hint: `${groups.get(k).length} docs`,
+            })),
+            { value: '__back__', label: chalk.dim(trans.common.back) },
+        ],
+    });
+    if (isCancel(groupKey) || groupKey === '__back__')
+        return;
+    const groupFiles = groups.get(groupKey) ?? [];
+    const fileSelected = await select({
+        message: `${trans.docs.categoryArchived} / ${groupKey}`,
+        options: [
+            ...groupFiles.map(f => ({
+                value: f.path,
+                label: cleanFileName(f.name),
+                hint: f.path.split('/').slice(2, -1).join('/'),
+            })),
+            { value: '__back__', label: chalk.dim(trans.common.back) },
+        ],
+    });
+    if (isCancel(fileSelected) || fileSelected === '__back__')
+        return;
+    await viewMarkdownFile(fileSelected);
 }
 // ─── Document viewer ──────────────────────────────────────────────────────────
 async function viewMarkdownFile(filePath) {
@@ -363,28 +419,31 @@ async function viewMarkdownFile(filePath) {
             }
             else {
                 const cleaned = cleanMarkdownContent(rawContent, getTerminalType());
-                const title = extractDocTitle(rawContent, cleaned) || filePath.split('/').pop() || filePath;
+                const title = extractDocTitle(rawContent, cleaned) || cleanFileName(filePath.split('/').pop() ?? filePath);
                 const readTime = estimateReadTime(cleaned);
                 const rendered = await marked(cleaned);
                 renderedDoc = { fingerprint, cleaned, rendered, title, readTime };
                 setRender(filePath, renderedDoc);
             }
             s.stop(`${chalk.bold(renderedDoc.title)}  ${chalk.dim(renderedDoc.readTime)}`);
+            const toc = extractTOC(renderedDoc.cleaned);
             if (hasGlow()) {
                 await displayWithGlow(renderedDoc.cleaned);
             }
             else {
-                await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime);
+                await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
             }
             console.log();
             success(trans.docs.docCompleted);
             console.log();
+            const hasTable = hasMarkdownTable(rawContent);
             const action = await select({
                 message: trans.docs.chooseAction,
                 options: [
                     { value: 'back', label: trans.docs.backToList },
                     { value: 'reread', label: trans.docs.reread },
-                    { value: 'browser', label: trans.docs.openBrowser },
+                    { value: 'browser', label: trans.docs.openBrowser,
+                        hint: hasTable ? trans.docs.tableHint : undefined },
                 ],
             });
             if (isCancel(action) || action === 'back')
@@ -393,7 +452,7 @@ async function viewMarkdownFile(filePath) {
                 await openDocsInBrowser(filePath);
                 return;
             }
-            // action === 'reread' → continue loop
+            // 'reread' → loop
         }
         catch (err) {
             error(trans.docs.loadError);
@@ -452,7 +511,7 @@ async function searchDocs() {
             options: [
                 ...results.map(r => ({
                     value: r.path,
-                    label: r.name,
+                    label: cleanFileName(r.name),
                     hint: r.path.includes('/') ? r.path.split('/').slice(0, -1).join('/') : '',
                 })),
                 { value: '__back__', label: chalk.dim(trans.docs.returnToMenu) },
@@ -468,19 +527,24 @@ async function searchDocs() {
 }
 // ─── Menu ─────────────────────────────────────────────────────────────────────
 export async function showDocsMenu() {
+    let sections = await loadSections();
+    if (!sections)
+        return;
     while (true) {
         const trans = t();
-        const categories = getDocCategories();
-        const options = [
-            ...categories.map(cat => ({ value: cat.path, label: cat.name })),
-            { value: 'search', label: chalk.dim(trans.docs.searchPrompt.replace(':', '')) },
-            { value: 'refresh-cache', label: chalk.dim(trans.docs.refreshCache) },
-            { value: 'browser', label: chalk.dim(trans.docs.openBrowser) },
-            { value: 'back', label: chalk.dim(trans.docs.returnToMenu) },
-        ];
         const action = await select({
             message: trans.docs.chooseCategory,
-            options,
+            options: [
+                ...sections.map(sec => ({
+                    value: sec.key,
+                    label: sec.label,
+                    hint: `${sec.count} docs`,
+                })),
+                { value: 'search', label: chalk.dim(trans.docs.searchPrompt.replace(':', '')) },
+                { value: 'refresh-cache', label: chalk.dim(trans.docs.refreshCache) },
+                { value: 'browser', label: chalk.dim(trans.docs.openBrowser) },
+                { value: 'back', label: chalk.dim(trans.docs.returnToMenu) },
+            ],
         });
         if (isCancel(action) || action === 'back')
             return;
@@ -489,13 +553,16 @@ export async function showDocsMenu() {
         }
         else if (action === 'refresh-cache') {
             clearDocsCache();
+            sections = (await loadSections()) ?? sections;
             success(trans.docs.cacheCleared);
         }
         else if (action === 'browser') {
             await openDocsInBrowser();
         }
         else {
-            await browseDirectory(action);
+            const section = sections.find(s => s.key === action);
+            if (section)
+                await showDocSection(section);
         }
     }
 }

package/dist/i18n/locales/en.json

@@ -92,6 +92,8 @@
     "browserError": "Failed to open browser",
     "browserErrorHint": "Please visit manually: https://docs.nbtca.space",
     "retry": "Retry?",
+    "tocTitle": "Table of Contents",
+    "tableHint": "tables render better in browser",
     "endOfDocument": "End of document - Press q to quit",
     "githubRateLimited": "GitHub API rate limit reached. Resets at {time}.",
     "githubForbidden": "GitHub API access denied (403).",

package/dist/i18n/locales/zh.json

@@ -92,6 +92,8 @@
     "browserError": "无法打开浏览器",
     "browserErrorHint": "请手动访问: https://docs.nbtca.space",
     "retry": "是否重试？",
+    "tocTitle": "目录",
+    "tableHint": "表格在浏览器中效果更佳",
     "endOfDocument": "文档结束 - 按 q 退出",
     "githubRateLimited": "GitHub API 速率限制已达上限，将在 {time} 重置。",
     "githubForbidden": "GitHub API 拒绝访问 (403)。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nbtca/prompt",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "main": "dist/index.js",
   "exports": {