docnest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DocNest contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# DocNest
+
+DocNest 是一个可复用的本地 Markdown 文档中心。文档内容归使用它的项目所有，DocNest 只提供查看、导航、Mermaid 图表、导出和本地 Watch 能力。
+
+## 快速接入
+
+在项目根目录执行：
+
+```bash
+npm install docnest@0.1.0
+```
+
+项目默认读取 `docs/`，可直接启动：
+
+```bash
+npx docnest serve
+```
+
+默认只监听 `127.0.0.1`，从 3000 开始查找可用端口。启动时会自动打开浏览器；使用 `--no-open` 可关闭。
+
+## 配置
+
+复制 `docnest.config.example.mjs` 为项目根目录的 `docnest.config.mjs`，配置项目自己的标题、目录顺序、存储键前缀和 PDF 水印。
+
+水印默认关闭。开启后，PDF 导出弹窗会读取配置文字，并允许本次导出临时修改；临时修改不会写回文件或浏览器存储。
+
+如需显式指定端口、文档目录或监听地址：
+
+```bash
+npx docnest serve --port 3000 --docs-dir docs --host 127.0.0.1
+```
+
+`--host 0.0.0.0` 只应由项目自己的生产启动适配层显式使用；DocNest 不提供远程发布、SSH、Docker、云厂商流水线、SSO、Redis 或对象存储能力。
+
+若宿主项目需要固定生产端口，可在适配层设置 `DOCS_PORT_FALLBACK=false`；普通本地启动保持从起始端口向后查找空闲端口。
+
+## 嵌入现有 Node 服务
+
+需要接入项目自己的鉴权或文档来源时，在加载 `docnest/server` 前注入中间件和文档存储适配器，然后使用导出的 Express/Socket.IO 实例：
+
+```js
+globalThis.__DOCNEST_BEFORE_DOCUMENT_ROUTES__ = [projectAuthMiddleware]
+globalThis.__DOCNEST_DOCUMENT_STORE__ = projectDocumentStore
+process.env.DOCS_AUTOSTART = 'false'
+
+const { app, io, startServer } = require('docnest/server')
+io.use(projectSocketAuth)
+startServer(3000)
+```
+
+存储适配器实现 `name`、`readDir`、`fileExists`、`readFile`、`readAsset`，可选实现 `ready`；这样文档内容仍由宿主项目提供，DocNest 只负责展示和交互。
+
+## 开发
+
+```bash
+npm install
+npm test
+npm run pack:check
+```
+
+最低支持 Node.js 20，验证 Node.js 20 和 22。

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const config_1 = require("./config");
+function parseArgs(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        const next = args[index + 1];
+        if (arg === '--port' && next) {
+            options.port = Number(next);
+            index += 1;
+        }
+        else if (arg === '--host' && next) {
+            options.host = next;
+            index += 1;
+        }
+        else if (arg === '--docs-dir' && next) {
+            options.docsDir = next;
+            index += 1;
+        }
+        else if (arg === '--no-open') {
+            options.openBrowser = false;
+        }
+        else if (arg === '--open') {
+            options.openBrowser = true;
+        }
+        else if (arg === '--no-watch') {
+            options.watch = false;
+        }
+        else if (arg === '--watch') {
+            options.watch = true;
+        }
+    }
+    return options;
+}
+function applyCliOverrides(config, options) {
+    return {
+        ...config,
+        docsDir: options.docsDir ? node_path_1.default.resolve(config.projectRoot, options.docsDir) : config.docsDir,
+        server: {
+            ...config.server,
+            ...(Number.isInteger(options.port) && options.port && options.port > 0 ? { port: options.port } : {}),
+            ...(options.host ? { host: options.host } : {}),
+            ...(typeof options.openBrowser === 'boolean' ? { openBrowser: options.openBrowser } : {}),
+            ...(typeof options.watch === 'boolean' ? { watch: options.watch } : {}),
+        },
+    };
+}
+function exposeConfig(config) {
+    process.env.DOCS_ROOT = config.docsDir;
+    process.env.DOCS_TITLE = config.site.title;
+    process.env.DOCS_SUBTITLE = config.site.subtitle;
+    process.env.DOCS_LOGO = config.site.logo;
+    process.env.DOCS_STORAGE_KEY_PREFIX = config.site.storageKeyPrefix;
+    process.env.DOCS_ROOT_DIRECTORY_ORDER = JSON.stringify(config.navigation.rootDirectoryOrder);
+    process.env.DOCS_WATERMARK_ENABLED = String(config.export.watermark.enabled);
+    process.env.DOCS_WATERMARK_TEXT = config.export.watermark.text;
+    process.env.DOCS_HOST = config.server.host;
+    process.env.DOCS_PORT_START = String(config.server.port);
+    process.env.DOCS_WATCH_ENABLED = String(config.server.watch);
+    process.env.DOCS_OPEN_BROWSER = String(config.server.openBrowser);
+}
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+async function main() {
+    const [command = 'serve', ...args] = process.argv.slice(2);
+    if (command !== 'serve') {
+        throw new Error(`未知命令：${command}。当前仅支持 docnest serve。`);
+    }
+    const config = applyCliOverrides(await (0, config_1.loadConfig)(), parseArgs(args));
+    exposeConfig(config);
+    await dynamicImport(`${(0, node_url_1.pathToFileURL)(node_path_1.default.join(__dirname, 'server.js')).href}?v=${Date.now()}`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`DocNest 启动失败：${message}`);
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+export type DocNestConfig = {
+    docsDir?: string;
+    site?: {
+        title?: string;
+        subtitle?: string;
+        logo?: string;
+        storageKeyPrefix?: string;
+    };
+    navigation?: {
+        rootDirectoryOrder?: string[];
+    };
+    server?: {
+        host?: string;
+        port?: number;
+        watch?: boolean;
+        openBrowser?: boolean;
+    };
+    export?: {
+        watermark?: {
+            enabled?: boolean;
+            text?: string;
+        };
+    };
+};
+export declare function defineConfig(config: DocNestConfig): DocNestConfig;
+export type ResolvedDocNestConfig = Required<DocNestConfig> & {
+    projectRoot: string;
+    docsDir: string;
+    site: Required<NonNullable<DocNestConfig['site']>>;
+    navigation: Required<NonNullable<DocNestConfig['navigation']>>;
+    server: Required<NonNullable<DocNestConfig['server']>>;
+    export: {
+        watermark: Required<NonNullable<NonNullable<DocNestConfig['export']>['watermark']>>;
+    };
+};
+export declare function loadConfig(projectRoot?: string): Promise<ResolvedDocNestConfig>;

package/dist/config.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = defineConfig;
+exports.loadConfig = loadConfig;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+function defineConfig(config) {
+    return config;
+}
+const DEFAULT_CONFIG_FILE = 'docnest.config.mjs';
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+async function readProjectName(projectRoot) {
+    try {
+        const packageJson = JSON.parse(await promises_1.default.readFile(node_path_1.default.join(projectRoot, 'package.json'), 'utf8'));
+        if (typeof packageJson.name === 'string' && packageJson.name.trim()) {
+            return packageJson.name.trim();
+        }
+    }
+    catch {
+        // package.json is optional for a document-only folder.
+    }
+    return node_path_1.default.basename(projectRoot);
+}
+function normalizePort(value, fallback) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return fallback;
+    return port;
+}
+async function loadConfig(projectRoot = process.cwd()) {
+    const configPath = node_path_1.default.join(projectRoot, DEFAULT_CONFIG_FILE);
+    let userConfig = {};
+    try {
+        const loaded = await dynamicImport(`${(0, node_url_1.pathToFileURL)(configPath).href}?v=${Date.now()}`);
+        userConfig = loaded.default ?? {};
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+        if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'ENOENT')
+            throw error;
+    }
+    const projectName = await readProjectName(projectRoot);
+    const site = userConfig.site ?? {};
+    const navigation = userConfig.navigation ?? {};
+    const server = userConfig.server ?? {};
+    const watermark = userConfig.export?.watermark ?? {};
+    const storageKeyPrefix = site.storageKeyPrefix?.trim() || `docnest:${projectName}`;
+    return {
+        projectRoot,
+        docsDir: node_path_1.default.resolve(projectRoot, userConfig.docsDir?.trim() || 'docs'),
+        site: {
+            title: site.title?.trim() || projectName,
+            subtitle: site.subtitle?.trim() || '本地 Markdown 文档服务',
+            logo: site.logo?.trim() || '',
+            storageKeyPrefix,
+        },
+        navigation: {
+            rootDirectoryOrder: Array.isArray(navigation.rootDirectoryOrder)
+                ? navigation.rootDirectoryOrder.filter((item) => typeof item === 'string')
+                : [],
+        },
+        server: {
+            host: server.host?.trim() || '127.0.0.1',
+            port: normalizePort(server.port, 3000),
+            watch: server.watch ?? true,
+            openBrowser: server.openBrowser ?? true,
+        },
+        export: {
+            watermark: {
+                enabled: watermark.enabled ?? false,
+                text: watermark.text?.trim() || site.title?.trim() || projectName,
+            },
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+declare const app: any;
+declare const server: any;
+declare const io: any;
+declare const DOCS_DIR: any;
+declare function startServer(port?: number, attemptsLeft?: number): any;
+export type DocNestDocumentEntry = {
+    name: string;
+    isDirectory: boolean;
+    isFile: boolean;
+};
+export type DocNestDocumentStore = {
+    name: string;
+    rootLabel?: string;
+    readDir: (relativePath: string) => Promise<DocNestDocumentEntry[]>;
+    fileExists: (relativePath: string) => Promise<boolean>;
+    readFile: (relativePath: string) => Promise<string>;
+    readAsset: (relativePath: string) => Promise<Uint8Array>;
+    ready?: () => Promise<void>;
+};
+export { app, io, server, startServer, DOCS_DIR as docsDir, };