solo-doc 0.0.3 → 0.1.0

package/README.md

@@ -1,61 +1,84 @@
 # Solo-Doc CLI
 
-Solo-Doc is a powerful Node.js CLI tool designed to crawl complex documentation sites and convert them into a single, hierarchically structured Markdown file.
+Solo-Doc 是一个强大的 Node.js CLI 工具，旨在爬取复杂的文档站点并将其转换为单一的、保留层级结构的 Markdown 文件。
 
-**Name Origin**: "Solo" represents the capability to consolidate multiple documentation pages into a "single" (solo) file, and "Doc" stands for documentation.
+**命名由来**："Solo" 代表将多个文档页面整合为“单一”（solo）文件的能力，"Doc" 代表文档。
 
-## Features
+## ✨ 功能特性
 
-- **Multi-Strategy Support**: Specialized strategies for different documentation frameworks:
-  - **OCP (Red Hat OpenShift)**: Optimised for static single-page HTML documentation.
-  - **ACP (Alauda Container Platform)**: Optimised for dynamic, client-side rendered (Rspress-based) documentation using Puppeteer.
-- **Hierarchy Preservation**: Maintains the original directory structure (1, 1.1, 1.1.1...) of the documentation.
-- **Clean Output**: Removes navigation bars, sidebars, headers, and footers, keeping only the relevant content.
-- **Single File Output**: Merges all crawled pages into one comprehensive Markdown file.
+- **🧠 智能探测**:
+  - **自动策略识别**: 根据 URL 自动检测文档类型（Red Hat OpenShift 或 Alauda）。
+  - **自动命名**: 基于文档路径智能生成输出文件名（例如 `acp-building_application.md`），无需手动指定。
+- **🏗 多策略支持**: 针对不同文档框架的专用策略：
+  - **OCP (Red Hat OpenShift)**: 针对静态单页 HTML 文档进行了优化。
+  - **ACP (Alauda Container Platform)**: 针对使用 Puppeteer 的动态客户端渲染（基于 Rspress）文档进行了优化。
+- **🌲 保持层级结构**: 完整保留文档的原始目录结构（1, 1.1, 1.1.1...）。
+- **✨ 纯净输出**: 移除导航栏、侧边栏、页眉和页脚，仅保留核心内容。
+- **📄 单文件输出**: 将所有爬取的页面合并为一个完整的 Markdown 文件。
 
-## Installation
+## 📦 安装
 
-### From NPM (Recommended)
+### 通过 NPM 安装（推荐）
 
-Once published, you can install the tool globally:
+你可以全局安装此工具：
 
 ```bash
 npm install -g solo-doc
 ```
 
-## Usage
+## 🚀 使用指南
 
-Once installed globally, you can run the `solo-doc` command from any terminal window.
+全局安装后，你可以在任何终端窗口运行 `solo-doc` 命令。
 
-### 1. Crawl OpenShift (OCP) Docs
+### 基础用法（自动探测）
 
-For Red Hat OpenShift documentation (HTML Single format):
+只需提供 URL。Solo-Doc 会自动识别站点类型并生成有意义的文件名。
 
 ```bash
-solo-doc ocp "https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/building_applications/index" -o openshift_docs.md
+# 爬取 Alauda 文档
+# 输出文件: acp-building_application.md
+solo-doc "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html"
+
+# 爬取 Red Hat 文档
+# 输出文件: ocp-building_applications.md
+solo-doc "https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/building_applications/index"
 ```
 
-### 2. Crawl Alauda (ACP) Docs
+### 📝 自定义输出文件名
 
-For Alauda Container Platform documentation (Rspress format):
+使用 `-o` 参数指定自定义输出路径。
 
 ```bash
-solo-doc acp "https://docs.alauda.io/container_platform/4.2/developer/building_application/index.html" -o alauda_docs.md
+solo-doc "https://docs.alauda.io/..." -o my-manual.md
 ```
 
-**Options:**
-- `-o, --output <path>`: Specify output file path (default: `[strategy]-docs.md`).
-- `--limit <number>`: Limit the number of pages to crawl (useful for testing).
-- `--no-headless`: Run browser in visible mode (for ACP debugging).
+### 🔧 强制指定策略类型
+
+如果 URL 无法被自动识别（例如私有 IP 或自定义域名），你可以使用 `--type` 强制指定策略。
+
+```bash
+# 针对私有部署强制使用 ACP 策略
+solo-doc "http://10.1.2.3/docs/index.html" --type acp
+```
+
+## ⚙️ 选项参数
+
+| 选项 | 描述 | 默认值 |
+|--------|-------------|---------|
+| `<url>` | 要爬取的文档 URL | (必填) |
+| `-o, --output <path>` | 输出文件路径。如果省略，将根据 URL 自动生成文件名。 | `[type]-[path-segment].md` |
+| `-t, --type <type>` | 强制指定策略类型 (`ocp` 或 `acp`)。 | 自动探测 |
+| `--limit <number>` | 限制爬取的页面数量 (用于测试/调试)。 | 无限制 |
+| `--no-headless` | 在可见模式下运行浏览器 (仅限 ACP，用于调试)。 | Headless (无头模式) |
 
-## Requirements
+## ✅ 环境要求
 
-- Node.js >= 18
-- Google Chrome (for ACP crawling)
+- Node.js >= 20
+- Google Chrome (用于 ACP 爬取)
 
-## Development
+## 💻 开发
 
 ```bash
-# Run in development mode
-npm run dev -- acp "url" ...
+# 在开发模式下运行
+npm run dev -- "https://docs.alauda.io/..."
 ```

package/dist/bin/solo-doc.js

@@ -8,37 +8,74 @@ const commander_1 = require("commander");
 const CrawlerContext_1 = require("../src/CrawlerContext");
 const OCPStrategy_1 = require("../src/strategies/OCPStrategy");
 const ACPStrategy_1 = require("../src/strategies/ACPStrategy");
+const StrategyDetector_1 = require("../src/utils/StrategyDetector");
+const chalk_1 = __importDefault(require("chalk"));
 const path_1 = __importDefault(require("path"));
 const program = new commander_1.Command();
 program
     .name('solo-doc')
     .description('CLI to crawl documentation sites and convert to single Markdown file')
-    .version('1.0.0');
-program
-    .command('ocp <url>')
-    .description('Crawl Red Hat OpenShift documentation')
-    .option('-o, --output <path>', 'Output file path', 'ocp-docs.md')
-    .option('--limit <number>', 'Limit number of pages (for debug)', parseInt)
-    .action(async (url, options) => {
-    const strategy = new OCPStrategy_1.OCPStrategy();
-    const context = new CrawlerContext_1.CrawlerContext(strategy);
-    const outputPath = path_1.default.resolve(process.cwd(), options.output);
-    await context.run(url, { output: outputPath, limit: options.limit });
-});
-program
-    .command('acp <url>')
-    .description('Crawl Alauda Container Platform documentation')
-    .option('-o, --output <path>', 'Output file path', 'acp-docs.md')
+    .version('1.0.0')
+    .argument('<url>', 'The documentation URL to crawl')
+    .option('-t, --type <type>', 'Force specify strategy type (ocp, acp)')
+    .option('-o, --output <path>', 'Output file path')
     .option('--limit <number>', 'Limit number of pages (for debug)', parseInt)
-    .option('--no-headless', 'Run in headful mode (show browser)')
+    .option('--no-headless', 'Run in headful mode (show browser) - Only for ACP')
     .action(async (url, options) => {
-    const strategy = new ACPStrategy_1.ACPStrategy();
-    const context = new CrawlerContext_1.CrawlerContext(strategy);
-    const outputPath = path_1.default.resolve(process.cwd(), options.output);
-    await context.run(url, {
-        output: outputPath,
-        limit: options.limit,
-        headless: options.headless
-    });
+    try {
+        // 1. Determine Strategy
+        let type = options.type;
+        if (!type) {
+            const detected = StrategyDetector_1.StrategyDetector.detect(url);
+            if (detected !== StrategyDetector_1.StrategyType.UNKNOWN) {
+                type = detected;
+                console.log(chalk_1.default.blue(`[Solo-Doc] Auto-detected strategy: ${type.toUpperCase()}`));
+            }
+        }
+        if (!type || (type !== 'ocp' && type !== 'acp')) {
+            console.error(chalk_1.default.red('Error: Could not detect documentation type.'));
+            console.error(chalk_1.default.yellow('Please use --type <ocp|acp> to specify the documentation type manually.'));
+            process.exit(1);
+        }
+        // 2. Instantiate Strategy
+        let strategy;
+        // Helper function to generate default filename from URL
+        const generateDefaultFilename = (urlStr, typePrefix) => {
+            try {
+                const u = new URL(urlStr);
+                // Get the last path segment that isn't 'index.html' or 'index' or empty
+                const segments = u.pathname.split('/').filter(s => s && s !== 'index.html' && s !== 'index');
+                const lastSegment = segments.length > 0 ? segments[segments.length - 1] : 'docs';
+                // Sanitize filename
+                const safeName = lastSegment.replace(/[^a-zA-Z0-9-_]/g, '_');
+                return `${typePrefix}-${safeName}.md`;
+            }
+            catch (e) {
+                return `${typePrefix}-docs.md`;
+            }
+        };
+        let defaultOutput;
+        if (type === 'ocp' || type === StrategyDetector_1.StrategyType.OCP) {
+            strategy = new OCPStrategy_1.OCPStrategy();
+            defaultOutput = generateDefaultFilename(url, 'ocp');
+        }
+        else {
+            strategy = new ACPStrategy_1.ACPStrategy();
+            defaultOutput = generateDefaultFilename(url, 'acp');
+        }
+        // 3. Prepare Context
+        const context = new CrawlerContext_1.CrawlerContext(strategy);
+        const outputPath = path_1.default.resolve(process.cwd(), options.output || defaultOutput);
+        // 4. Run
+        await context.run(url, {
+            output: outputPath,
+            limit: options.limit,
+            headless: options.headless
+        });
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`[Solo-Doc] Failed: ${error.message}`));
+        process.exit(1);
+    }
 });
 program.parse(process.argv);

package/dist/src/strategies/OCPStrategy.js

@@ -47,6 +47,23 @@ class OCPStrategy {
         this.name = 'OCP (Red Hat OpenShift)';
     }
     async execute(url, options) {
+        // Optimisation: Try to convert multi-page URL (/html/) to single-page URL (/html-single/)
+        // Example: .../html/building_applications/index -> .../html-single/building_applications/index
+        if (url.includes('/html/') && !url.includes('/html-single/')) {
+            const singlePageUrl = url.replace('/html/', '/html-single/');
+            console.log(chalk_1.default.blue(`[OCP] Detected multi-page URL. Attempting to switch to single-page version for better results...`));
+            console.log(chalk_1.default.gray(`Original: ${url}`));
+            console.log(chalk_1.default.cyan(`Optimized: ${singlePageUrl}`));
+            try {
+                // Verify if the single page exists
+                await axios_1.default.head(singlePageUrl);
+                url = singlePageUrl;
+                console.log(chalk_1.default.green(`[OCP] Successfully switched to single-page version.`));
+            }
+            catch (e) {
+                console.log(chalk_1.default.yellow(`[OCP] Single-page version not found. Falling back to original URL.`));
+            }
+        }
         const spinner = (0, ora_1.default)('Fetching OCP content...').start();
         try {
             // 1. Fetch the single page HTML

package/dist/src/utils/StrategyDetector.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StrategyDetector = exports.StrategyType = void 0;
+var StrategyType;
+(function (StrategyType) {
+    StrategyType["OCP"] = "ocp";
+    StrategyType["ACP"] = "acp";
+    StrategyType["UNKNOWN"] = "unknown";
+})(StrategyType || (exports.StrategyType = StrategyType = {}));
+class StrategyDetector {
+    static detect(url) {
+        try {
+            // Add protocol if missing to ensure URL parsing works
+            if (!url.startsWith('http://') && !url.startsWith('https://')) {
+                url = 'https://' + url;
+            }
+            const urlObj = new URL(url);
+            const hostname = urlObj.hostname;
+            if (hostname.includes('redhat.com') || hostname.includes('openshift.com')) {
+                return StrategyType.OCP;
+            }
+            if (hostname.includes('alauda.io') || hostname.includes('alauda.cn')) {
+                return StrategyType.ACP;
+            }
+            return StrategyType.UNKNOWN;
+        }
+        catch (e) {
+            return StrategyType.UNKNOWN;
+        }
+    }
+}
+exports.StrategyDetector = StrategyDetector;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solo-doc",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "main": "dist/bin/solo-doc.js",
   "bin": {
     "solo-doc": "dist/bin/solo-doc.js"