@zpress/cli 0.3.4 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
-<div align="center">
-  <img src="https://raw.githubusercontent.com/joggrdocs/zpress/main/assets/banner.svg" alt="zpress" width="90%" />
-  <p><strong>CLI for building and serving zpress documentation sites.</strong></p>
+# @zpress/cli
 
-<a href="https://github.com/joggrdocs/zpress/actions/workflows/ci.yml"><img src="https://github.com/joggrdocs/zpress/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
-<a href="https://www.npmjs.com/package/@zpress/cli"><img src="https://img.shields.io/npm/v/@zpress/cli" alt="npm version" /></a>
-<a href="https://github.com/joggrdocs/zpress/blob/main/LICENSE"><img src="https://img.shields.io/github/license/joggrdocs/zpress" alt="License" /></a>
+CLI for building and serving zpress documentation sites.
 
-</div>
+<span class="zp-badge">
+
+[![CI](https://github.com/joggrdocs/zpress/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/joggrdocs/zpress/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@zpress/cli)](https://www.npmjs.com/package/@zpress/cli)
+[![License](https://img.shields.io/github/license/joggrdocs/zpress)](https://github.com/joggrdocs/zpress/blob/main/LICENSE)
+
+</span>
 
 ## Install
 

package/dist/145.mjs

@@ -1,28 +1,42 @@
+import { createRequire } from "node:module";
 import { cli, command } from "@kidd-cli/core";
-import { configError, createPaths, generateAssets, loadConfig, loadManifest, resolveEntries, sync } from "@zpress/core";
+import { configError, createPaths, generateAssets, hasGlobChars, loadConfig, loadManifest, normalizeInclude, resolveEntries, sync } from "@zpress/core";
 import { z } from "zod";
 import node_path from "node:path";
 import { execFileSync, spawn } from "node:child_process";
+import { once } from "node:events";
+import { Server } from "node:http";
 import { platform } from "node:os";
 import { build, dev, serve } from "@rspress/core";
 import { createRspressConfig } from "@zpress/ui";
+import get_port, { portNumbers } from "get-port";
 import { P, match as external_ts_pattern_match } from "ts-pattern";
 import promises from "node:fs/promises";
-import { compact } from "es-toolkit";
+import { compact, uniq } from "es-toolkit";
 import { createRegistry, render, toSlug } from "@zpress/templates";
 import node_fs from "node:fs";
+globalThis.require = globalThis.require ?? createRequire(import.meta.url);
 function toError(error) {
     if (error instanceof Error) return error;
     return new Error(String(error));
 }
-const DEFAULT_PORT = 6174;
+const DEV_PORT = 6174;
+const DEV_PORT_RANGE = 5;
+const SERVE_PORT = 8080;
 async function startDevServer(options) {
     const { paths } = options;
+    const preferred = options.port ?? DEV_PORT;
+    const port = await get_port({
+        port: portNumbers(preferred, preferred + DEV_PORT_RANGE)
+    });
     let serverInstance = null;
     async function startServer(config) {
         const rspressConfig = createRspressConfig({
             config,
-            paths
+            paths,
+            vscode: options.vscode,
+            themeOverride: options.theme,
+            colorModeOverride: options.colorMode
         });
         try {
             serverInstance = await dev({
@@ -32,7 +46,8 @@ async function startDevServer(options) {
                 configFilePath: '',
                 extraBuilderConfig: {
                     server: {
-                        port: DEFAULT_PORT
+                        port,
+                        strictPort: true
                     }
                 }
             });
@@ -47,11 +62,20 @@ async function startDevServer(options) {
     return async (newConfig)=>{
         process.stdout.write('\n🔄 Config changed — restarting dev server...\n');
         if (serverInstance) {
+            const httpServer = getHttpServer(serverInstance);
+            const closeEvent = createCloseEvent(httpServer);
             try {
                 await serverInstance.close();
             } catch (error) {
                 process.stderr.write(`Error closing server: ${toError(error).message}\n`);
             }
+            if (closeEvent) {
+                const PORT_RELEASE_TIMEOUT = 5000;
+                await Promise.race([
+                    closeEvent,
+                    new Promise((resolve)=>setTimeout(resolve, PORT_RELEASE_TIMEOUT))
+                ]);
+            }
             serverInstance = null;
         }
         const restarted = await startServer(newConfig);
@@ -60,7 +84,10 @@ async function startDevServer(options) {
     };
 }
 async function buildSite(options) {
-    const rspressConfig = createRspressConfig(options);
+    const rspressConfig = createRspressConfig({
+        config: options.config,
+        paths: options.paths
+    });
     await build({
         docDirectory: options.paths.contentDir,
         config: rspressConfig,
@@ -68,7 +95,10 @@ async function buildSite(options) {
     });
 }
 async function buildSiteForCheck(options) {
-    const rspressConfig = createRspressConfig(options);
+    const rspressConfig = createRspressConfig({
+        config: options.config,
+        paths: options.paths
+    });
     await build({
         docDirectory: options.paths.contentDir,
         config: rspressConfig,
@@ -76,12 +106,23 @@ async function buildSiteForCheck(options) {
     });
 }
 async function serveSite(options) {
-    const rspressConfig = createRspressConfig(options);
+    const rspressConfig = createRspressConfig({
+        config: options.config,
+        paths: options.paths,
+        vscode: options.vscode,
+        themeOverride: options.theme,
+        colorModeOverride: options.colorMode
+    });
+    const preferredPort = options.port ?? SERVE_PORT;
+    const port = await get_port({
+        port: portNumbers(preferredPort, preferredPort + DEV_PORT_RANGE)
+    });
     await serve({
         config: rspressConfig,
         configFilePath: '',
-        port: DEFAULT_PORT
+        port
     });
+    return port;
 }
 function openBrowser(url) {
     const os = platform();
@@ -108,6 +149,17 @@ function openBrowser(url) {
         detached: true
     }).unref();
 }
+function createCloseEvent(httpServer) {
+    if (null === httpServer) return null;
+    if (!httpServer.listening) return null;
+    return once(httpServer, 'close');
+}
+function getHttpServer(instance) {
+    const record = instance;
+    const value = record['httpServer'];
+    if (value instanceof Server) return value;
+    return null;
+}
 const ANSI_PATTERN = /\u001B\[[0-9;]*m/g;
 const RED = '\u001B[31m';
 const DIM = '\u001B[2m';
@@ -422,7 +474,11 @@ const devCommand = command({
     description: 'Run sync + watcher and start Rspress dev server',
     options: z.object({
         quiet: z.boolean().optional().default(false),
-        clean: z.boolean().optional().default(false)
+        clean: z.boolean().optional().default(false),
+        port: z.number().optional(),
+        theme: z.string().optional(),
+        colorMode: z.string().optional(),
+        vscode: z.boolean().optional().default(false)
     }),
     handler: async (ctx)=>{
         const { quiet } = ctx.args;
@@ -447,7 +503,11 @@ const devCommand = command({
         });
         const onConfigReload = await startDevServer({
             config,
-            paths
+            paths,
+            port: ctx.args.port,
+            theme: ctx.args.theme,
+            colorMode: ctx.args.colorMode,
+            vscode: ctx.args.vscode
         });
         const { createWatcher } = await import("./watcher.mjs");
         const watcher = createWatcher(config, paths, onConfigReload);
@@ -458,6 +518,164 @@ const devCommand = command({
         process.on('SIGTERM', cleanup);
     }
 });
+const CONFIG_GLOBS = [
+    'zpress.config.ts',
+    'zpress.config.mts',
+    'zpress.config.cts',
+    'zpress.config.js',
+    'zpress.config.mjs',
+    'zpress.config.cjs',
+    'zpress.config.json'
+];
+const diffCommand = command({
+    description: 'Show changed files in configured source directories',
+    options: z.object({
+        pretty: z.boolean().optional().default(false)
+    }),
+    handler: async (ctx)=>{
+        const { pretty } = ctx.args;
+        const paths = createPaths(process.cwd());
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            if (pretty) {
+                ctx.logger.intro('zpress diff');
+                ctx.logger.error(configErr.message);
+                if (configErr.errors && configErr.errors.length > 0) configErr.errors.forEach((err)=>{
+                    const p = err.path.join('.');
+                    ctx.logger.error(`  ${p}: ${err.message}`);
+                });
+            }
+            process.exit(1);
+        }
+        const dirs = collectWatchPaths(config);
+        if (0 === dirs.length) {
+            if (pretty) {
+                ctx.logger.intro('zpress diff');
+                ctx.logger.warn('No source directories found in config');
+                ctx.logger.outro('Done');
+            }
+            return;
+        }
+        const [gitErr, changed] = gitChangedFiles({
+            repoRoot: paths.repoRoot,
+            dirs
+        });
+        if (gitErr) {
+            if (pretty) {
+                ctx.logger.intro('zpress diff');
+                ctx.logger.error(`Git failed: ${gitErr.message}`);
+                ctx.logger.outro('Done');
+            }
+            process.exit(1);
+        }
+        if (0 === changed.length) {
+            if (pretty) {
+                ctx.logger.intro('zpress diff');
+                ctx.logger.success('No changes detected');
+                ctx.logger.outro('Done');
+            }
+            return;
+        }
+        if (pretty) {
+            ctx.logger.intro('zpress diff');
+            ctx.logger.step(`Watching ${dirs.length} path(s)`);
+            ctx.logger.note(changed.join('\n'), `${changed.length} changed file(s)`);
+            ctx.logger.outro('Done');
+            return;
+        }
+        process.stdout.write(`${changed.join(' ')}\n`);
+    }
+});
+function collectWatchPaths(config) {
+    const dirs = flattenIncludePaths(config.sections);
+    return uniq([
+        ...dirs.map(toDirectory),
+        ...CONFIG_GLOBS
+    ]);
+}
+function flattenIncludePaths(sections) {
+    return sections.flatMap(flattenSection);
+}
+function flattenSection(section) {
+    const includes = normalizeInclude(section.include);
+    if (includes.length > 0 && section.items) return [
+        ...includes,
+        ...flattenIncludePaths(section.items)
+    ];
+    if (includes.length > 0) return includes;
+    if (section.items) return flattenIncludePaths(section.items);
+    return [];
+}
+function toDirectory(from) {
+    if (hasGlobChars(from)) {
+        const normalized = from.replaceAll('\\', '/');
+        const segments = normalized.split('/');
+        const dirSegments = segments.filter((s)=>!hasGlobChars(s));
+        return dirSegments.join('/') || '.';
+    }
+    return from;
+}
+const RENAME_SEPARATOR = ' -> ';
+function gitChangedFiles(params) {
+    const [err, output] = execSilent({
+        file: 'git',
+        args: [
+            'status',
+            '--short',
+            '--',
+            ...params.dirs
+        ],
+        cwd: params.repoRoot
+    });
+    if (err) return [
+        err,
+        null
+    ];
+    if (!output) return [
+        null,
+        []
+    ];
+    const files = output.split('\n').filter((line)=>line.length > 0).map(parseStatusLine).filter((p)=>p.length > 0);
+    return [
+        null,
+        files
+    ];
+}
+function parseStatusLine(line) {
+    const filePart = line.slice(3);
+    const renameIdx = filePart.indexOf(RENAME_SEPARATOR);
+    if (-1 !== renameIdx) return stripQuotes(filePart.slice(renameIdx + RENAME_SEPARATOR.length));
+    return stripQuotes(filePart);
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed.slice(1, -1);
+    return trimmed;
+}
+function execSilent(params) {
+    try {
+        const output = execFileSync(params.file, [
+            ...params.args
+        ], {
+            cwd: params.cwd,
+            stdio: 'pipe',
+            encoding: 'utf8'
+        }).trimEnd();
+        return [
+            null,
+            output
+        ];
+    } catch (error) {
+        if (error instanceof Error) return [
+            error,
+            null
+        ];
+        return [
+            new Error(String(error)),
+            null
+        ];
+    }
+}
 const registry = createRegistry();
 const draftCommand = command({
     description: 'Scaffold a new documentation file from a template',
@@ -557,9 +775,9 @@ function maybeHidden(hidden) {
     };
     return {};
 }
-function maybeIsolated(isolated) {
-    if (isolated) return {
-        isolated
+function maybeStandalone(standalone) {
+    if (standalone) return {
+        standalone
     };
     return {};
 }
@@ -578,7 +796,7 @@ function buildDumpEntry(entry) {
         ...maybeLink(entry.link),
         ...maybeCollapsible(entry.collapsible),
         ...maybeHidden(entry.hidden),
-        ...maybeIsolated(entry.isolated),
+        ...maybeStandalone(entry.standalone),
         ...maybeItems(entry.items)
     };
 }
@@ -629,7 +847,11 @@ function buildAssetConfig(config) {
 const serveCommand = command({
     description: 'Preview the built Rspress site',
     options: z.object({
-        open: z.boolean().optional().default(true)
+        open: z.boolean().optional().default(true),
+        port: z.number().optional(),
+        theme: z.string().optional(),
+        colorMode: z.string().optional(),
+        vscode: z.boolean().optional().default(false)
     }),
     handler: async (ctx)=>{
         ctx.logger.intro('zpress serve');
@@ -643,11 +865,15 @@ const serveCommand = command({
             });
             process.exit(1);
         }
-        if (ctx.args.open) setTimeout(()=>openBrowser(`http://localhost:${DEFAULT_PORT}`), 2000);
-        await serveSite({
+        const port = await serveSite({
             config,
-            paths
+            paths,
+            port: ctx.args.port,
+            theme: ctx.args.theme,
+            colorMode: ctx.args.colorMode,
+            vscode: ctx.args.vscode
         });
+        if (ctx.args.open) openBrowser(`http://localhost:${port}`);
     }
 });
 const CONFIG_FILENAME = 'zpress.config.ts';
@@ -666,6 +892,7 @@ const setupCommand = command({
         const title = deriveTitle(cwd);
         node_fs.writeFileSync(configPath, buildConfigTemplate(title), 'utf8');
         ctx.logger.success(`Created ${CONFIG_FILENAME} (title: "${title}")`);
+        await ensureGitignore(paths, ctx.logger);
         await promises.mkdir(paths.publicDir, {
             recursive: true
         });
@@ -685,7 +912,7 @@ const setupCommand = command({
     }
 });
 function extractGitRepoName(cwd) {
-    const url = execSilent('git', [
+    const url = setup_execSilent('git', [
         'remote',
         'get-url',
         'origin'
@@ -695,7 +922,7 @@ function extractGitRepoName(cwd) {
     if (!match) return null;
     return match[1];
 }
-function execSilent(file, args, cwd) {
+function setup_execSilent(file, args, cwd) {
     try {
         return execFileSync(file, [
             ...args
@@ -721,14 +948,43 @@ export default defineConfig({
   title: '${escaped}',
   sections: [
     {
-      text: 'Getting Started',
-      prefix: '/getting-started',
-      from: 'docs/*.md',
+      title: 'Getting Started',
+      path: '/getting-started',
+      include: 'docs/*.md',
     },
   ],
 })
 `;
 }
+const ZPRESS_GITIGNORE_ENTRY = '.zpress/';
+const NESTED_GITIGNORE_CONTENT = `# managed by zpress — ignore everything by default
+*
+
+# to track custom assets (e.g. banners, logos), uncomment the following lines:
+# !public/
+# !public/**
+`;
+async function ensureGitignore(paths, logger) {
+    const rootGitignore = node_path.join(paths.repoRoot, '.gitignore');
+    if (node_fs.existsSync(rootGitignore)) {
+        const content = node_fs.readFileSync(rootGitignore, 'utf8');
+        const lines = content.split('\n');
+        const alreadyIgnored = lines.some((line)=>line.trim() === ZPRESS_GITIGNORE_ENTRY || '.zpress' === line.trim());
+        if (alreadyIgnored) return;
+        const suffix = (()=>{
+            if (content.endsWith('\n')) return '';
+            return '\n';
+        })();
+        node_fs.writeFileSync(rootGitignore, `${content}${suffix}\n# zpress\n${ZPRESS_GITIGNORE_ENTRY}\n`, 'utf8');
+        logger.success('Added .zpress/ to .gitignore');
+        return;
+    }
+    await promises.mkdir(paths.outputRoot, {
+        recursive: true
+    });
+    await promises.writeFile(node_path.join(paths.outputRoot, '.gitignore'), NESTED_GITIGNORE_CONTENT, 'utf8');
+    logger.success('Created .zpress/.gitignore');
+}
 const syncCommand = command({
     description: 'Sync documentation sources into .zpress/',
     options: z.object({
@@ -756,11 +1012,12 @@ const syncCommand = command({
 });
 await cli({
     name: 'zpress',
-    version: "0.3.4",
+    version: "0.4.0",
     description: 'CLI for building and serving documentation',
     commands: {
         sync: syncCommand,
         dev: devCommand,
+        diff: diffCommand,
         build: buildCommand,
         check: checkCommand,
         draft: draftCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zpress/cli",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "CLI for building and serving zpress documentation sites",
   "keywords": [
     "cli",
@@ -34,14 +34,15 @@
     "provenance": true
   },
   "dependencies": {
-    "@kidd-cli/core": "^0.7.0",
-    "@rspress/core": "^2.0.5",
+    "@kidd-cli/core": "^0.10.0",
+    "@rspress/core": "^2.0.6",
     "es-toolkit": "^1.45.1",
+    "get-port": "^7.1.0",
     "ts-pattern": "^5.9.0",
     "zod": "^4.3.6",
-    "@zpress/core": "0.7.0",
+    "@zpress/core": "0.7.1",
     "@zpress/templates": "0.1.1",
-    "@zpress/ui": "0.7.0"
+    "@zpress/ui": "0.8.0"
   },
   "devDependencies": {
     "@rslib/core": "^0.20.0",
@@ -55,6 +56,6 @@
     "build": "rslib build",
     "dev": "node ./dist/index.mjs dev --cwd ../..",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsgo --noEmit"
   }
 }