@zpress/cli 0.3.3 → 0.4.0

package/dist/145.mjs

@@ -0,0 +1,1031 @@
+import { createRequire } from "node:module";
+import { cli, command } from "@kidd-cli/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, 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 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,
+            vscode: options.vscode,
+            themeOverride: options.theme,
+            colorModeOverride: options.colorMode
+        });
+        try {
+            serverInstance = await dev({
+                appDirectory: paths.repoRoot,
+                docDirectory: paths.contentDir,
+                config: rspressConfig,
+                configFilePath: '',
+                extraBuilderConfig: {
+                    server: {
+                        port,
+                        strictPort: true
+                    }
+                }
+            });
+            return true;
+        } catch (error) {
+            process.stderr.write(`Dev server error: ${toError(error).message}\n`);
+            return false;
+        }
+    }
+    const started = await startServer(options.config);
+    if (!started) process.exit(1);
+    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);
+        if (restarted) process.stdout.write('✅ Dev server restarted\n\n');
+        else process.stderr.write('⚠️  Dev server failed to restart — fix the config and save again\n\n');
+    };
+}
+async function buildSite(options) {
+    const rspressConfig = createRspressConfig({
+        config: options.config,
+        paths: options.paths
+    });
+    await build({
+        docDirectory: options.paths.contentDir,
+        config: rspressConfig,
+        configFilePath: ''
+    });
+}
+async function buildSiteForCheck(options) {
+    const rspressConfig = createRspressConfig({
+        config: options.config,
+        paths: options.paths
+    });
+    await build({
+        docDirectory: options.paths.contentDir,
+        config: rspressConfig,
+        configFilePath: ''
+    });
+}
+async function serveSite(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
+    });
+    return port;
+}
+function openBrowser(url) {
+    const os = platform();
+    const { cmd, args } = external_ts_pattern_match(os).with('darwin', ()=>({
+            cmd: 'open',
+            args: [
+                url
+            ]
+        })).with('win32', ()=>({
+            cmd: 'cmd',
+            args: [
+                '/c',
+                'start',
+                url
+            ]
+        })).otherwise(()=>({
+            cmd: 'xdg-open',
+            args: [
+                url
+            ]
+        }));
+    spawn(cmd, args, {
+        stdio: 'ignore',
+        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';
+const RESET = '\u001B[0m';
+function runConfigCheck(params) {
+    const { config, loadError } = params;
+    if (loadError) return {
+        passed: false,
+        errors: [
+            loadError
+        ]
+    };
+    if (!config) return {
+        passed: false,
+        errors: [
+            configError('empty_sections', 'Config is missing')
+        ]
+    };
+    return {
+        passed: true,
+        errors: []
+    };
+}
+async function runBuildCheck(params) {
+    const { error, captured } = await captureOutput(()=>buildSiteForCheck({
+            config: params.config,
+            paths: params.paths
+        }));
+    if (error) {
+        const { repoRoot } = params.paths;
+        const deadlinks = parseDeadlinks(captured).map((info)=>({
+                file: node_path.relative(repoRoot, info.file),
+                links: info.links
+            }));
+        if (deadlinks.length > 0) return {
+            status: 'failed',
+            deadlinks
+        };
+        return {
+            status: 'error',
+            message: error.message
+        };
+    }
+    return {
+        status: 'passed'
+    };
+}
+function presentResults(params) {
+    const { configResult, buildResult, logger } = params;
+    if (configResult.passed) logger.success('Config valid');
+    else {
+        logger.error('Config validation failed:');
+        configResult.errors.map((err)=>{
+            logger.message(`  ${err.message}`);
+            return null;
+        });
+    }
+    if ('passed' === buildResult.status) logger.success('No broken links');
+    else if ('skipped' === buildResult.status) ;
+    else if ('error' === buildResult.status) logger.error(`Build failed: ${buildResult.message}`);
+    else {
+        const totalLinks = buildResult.deadlinks.reduce((sum, info)=>sum + info.links.length, 0);
+        logger.error(`Found ${totalLinks} broken link(s):`);
+        const block = buildResult.deadlinks.map(formatDeadlinkGroup).join('\n');
+        logger.message(block);
+    }
+    return configResult.passed && 'passed' === buildResult.status;
+}
+function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, '');
+}
+function chunkToString(chunk) {
+    if ('string' == typeof chunk) return chunk;
+    return Buffer.from(chunk).toString('utf8');
+}
+function createInterceptor(chunks) {
+    return function(chunk, encodingOrCb, maybeCb) {
+        const text = chunkToString(chunk);
+        chunks.push(text);
+        if ('function' == typeof encodingOrCb) encodingOrCb();
+        else if ('function' == typeof maybeCb) maybeCb();
+        return true;
+    };
+}
+async function captureOutput(fn) {
+    const chunks = [];
+    const originalStdoutWrite = process.stdout.write;
+    const originalStderrWrite = process.stderr.write;
+    process.stdout.write = createInterceptor(chunks);
+    process.stderr.write = createInterceptor(chunks);
+    try {
+        const result = await fn();
+        return {
+            result,
+            error: null,
+            captured: chunks.join('')
+        };
+    } catch (error) {
+        return {
+            result: null,
+            error: toError(error),
+            captured: chunks.join('')
+        };
+    } finally{
+        process.stdout.write = originalStdoutWrite;
+        process.stderr.write = originalStderrWrite;
+    }
+}
+function flushGroup(results, file, links) {
+    if (file && links.length > 0) return [
+        ...results,
+        {
+            file,
+            links
+        }
+    ];
+    return results;
+}
+function parseDeadlinks(stderr) {
+    const clean = stripAnsi(stderr);
+    const lines = clean.split('\n');
+    const headerPattern = /Dead links found in (.+?):\s*$/;
+    const linkPattern = /"\[\.\.]\(([^)]+)\)"/;
+    const acc = lines.reduce((state, line)=>{
+        const headerMatch = headerPattern.exec(line);
+        if (headerMatch) {
+            const file = headerMatch[1] ?? '';
+            return {
+                results: flushGroup(state.results, state.currentFile, state.currentLinks),
+                currentFile: file,
+                currentLinks: []
+            };
+        }
+        const linkMatch = linkPattern.exec(line);
+        if (linkMatch && state.currentFile) {
+            const link = linkMatch[1] ?? '';
+            return {
+                ...state,
+                currentLinks: [
+                    ...state.currentLinks,
+                    link
+                ]
+            };
+        }
+        return state;
+    }, {
+        results: [],
+        currentFile: null,
+        currentLinks: []
+    });
+    return flushGroup(acc.results, acc.currentFile, acc.currentLinks);
+}
+function formatDeadlinkGroup(info) {
+    const header = `  ${RED}✖${RESET} ${info.file}`;
+    const links = info.links.map((link)=>`      ${DIM}→${RESET} ${link}`);
+    return [
+        header,
+        ...links
+    ].join('\n');
+}
+async function clean_clean(paths) {
+    const results = await Promise.all(cleanTargets(paths).map(async ({ dir, label })=>{
+        const exists = await promises.stat(dir).catch(()=>null);
+        if (exists) {
+            await promises.rm(dir, {
+                recursive: true,
+                force: true
+            });
+            return label;
+        }
+        return null;
+    }));
+    return compact(results);
+}
+const cleanCommand = command({
+    description: 'Remove build artifacts, synced content, and build cache',
+    handler: async (ctx)=>{
+        const paths = createPaths(process.cwd());
+        ctx.logger.intro('zpress clean');
+        const removed = await clean_clean(paths);
+        if (removed.length > 0) ctx.logger.success(`Removed: ${removed.join(', ')}`);
+        else ctx.logger.info('Nothing to clean');
+        ctx.logger.outro('Done');
+    }
+});
+function cleanTargets(paths) {
+    return [
+        {
+            dir: paths.cacheDir,
+            label: 'cache'
+        },
+        {
+            dir: paths.contentDir,
+            label: 'content'
+        },
+        {
+            dir: paths.distDir,
+            label: 'dist'
+        }
+    ];
+}
+const buildCommand = command({
+    description: 'Run sync and build the Rspress site',
+    options: z.object({
+        quiet: z.boolean().optional().default(false),
+        clean: z.boolean().optional().default(false),
+        check: z.boolean().optional().default(true)
+    }),
+    handler: async (ctx)=>{
+        const { quiet, check } = ctx.args;
+        const paths = createPaths(process.cwd());
+        ctx.logger.intro('zpress build');
+        if (ctx.args.clean) {
+            const removed = await clean_clean(paths);
+            if (removed.length > 0 && !quiet) ctx.logger.info(`Cleaned: ${removed.join(', ')}`);
+        }
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.map((err)=>{
+                const path = err.path.join('.');
+                return ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        if (check) {
+            ctx.logger.step('Validating config...');
+            const configResult = runConfigCheck({
+                config,
+                loadError: configErr
+            });
+            ctx.logger.step('Syncing content...');
+            await sync(config, {
+                paths,
+                quiet: true
+            });
+            ctx.logger.step('Building & checking for broken links...');
+            const buildResult = await runBuildCheck({
+                config,
+                paths
+            });
+            const passed = presentResults({
+                configResult,
+                buildResult,
+                logger: ctx.logger
+            });
+            if (!passed) {
+                ctx.logger.outro('Build failed');
+                process.exit(1);
+            }
+            ctx.logger.outro('Done');
+        } else {
+            await sync(config, {
+                paths,
+                quiet
+            });
+            await buildSite({
+                config,
+                paths
+            });
+            ctx.logger.outro('Done');
+        }
+    }
+});
+const checkCommand = command({
+    description: 'Validate config and check for broken links',
+    handler: async (ctx)=>{
+        const paths = createPaths(process.cwd());
+        ctx.logger.intro('zpress check');
+        ctx.logger.step('Validating config...');
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        const configResult = runConfigCheck({
+            config,
+            loadError: configErr
+        });
+        if (configErr || !config) {
+            const buildResult = {
+                status: 'skipped'
+            };
+            presentResults({
+                configResult,
+                buildResult,
+                logger: ctx.logger
+            });
+            ctx.logger.outro('Checks failed');
+            process.exit(1);
+        }
+        ctx.logger.step('Syncing content...');
+        const syncResult = await sync(config, {
+            paths,
+            quiet: true
+        });
+        ctx.logger.success(`Synced (${syncResult.pagesWritten} written, ${syncResult.pagesSkipped} unchanged)`);
+        ctx.logger.step('Checking for broken links...');
+        const buildResult = await runBuildCheck({
+            config,
+            paths
+        });
+        const passed = presentResults({
+            configResult,
+            buildResult,
+            logger: ctx.logger
+        });
+        if (passed) ctx.logger.outro('All checks passed');
+        else {
+            ctx.logger.outro('Checks failed');
+            process.exit(1);
+        }
+    }
+});
+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),
+        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;
+        const paths = createPaths(process.cwd());
+        ctx.logger.intro('zpress dev');
+        if (ctx.args.clean) {
+            const removed = await clean_clean(paths);
+            if (removed.length > 0 && !quiet) ctx.logger.info(`Cleaned: ${removed.join(', ')}`);
+        }
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.forEach((err)=>{
+                const path = err.path.join('.');
+                ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        await sync(config, {
+            paths,
+            quiet
+        });
+        const onConfigReload = await startDevServer({
+            config,
+            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);
+        function cleanup() {
+            watcher.close();
+        }
+        process.on('SIGINT', cleanup);
+        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',
+    options: z.object({
+        type: z.string().optional(),
+        title: z.string().optional(),
+        out: z.string().optional().default('.')
+    }),
+    handler: async (ctx)=>{
+        ctx.logger.intro('zpress draft');
+        const typeArg = ctx.args.type;
+        const hasValidType = external_ts_pattern_match(typeArg).with(P.string.minLength(1), (t)=>registry.has(t)).otherwise(()=>false);
+        const selectedType = await external_ts_pattern_match(hasValidType).with(true, ()=>Promise.resolve(typeArg)).otherwise(()=>ctx.prompts.select({
+                message: 'Select a doc type',
+                options: registry.list().map((t)=>({
+                        value: t.type,
+                        label: t.label,
+                        hint: t.hint
+                    }))
+            }));
+        const template = registry.get(selectedType);
+        if (!template) return void ctx.logger.error(`Unknown template type: ${selectedType}`);
+        const title = await external_ts_pattern_match(ctx.args.title).with(P.string.minLength(1), (t)=>Promise.resolve(t)).otherwise(()=>ctx.prompts.text({
+                message: 'Document title',
+                placeholder: 'e.g. Authentication',
+                validate: (value)=>{
+                    if (!value || 0 === value.trim().length) return 'Title is required';
+                }
+            }));
+        const slug = toSlug(title);
+        if (0 === slug.length) return void ctx.logger.error('Title must include at least one letter or number');
+        const content = render(template, {
+            title
+        });
+        const filename = `${slug}.md`;
+        const outDir = node_path.resolve(process.cwd(), ctx.args.out);
+        const filePath = node_path.join(outDir, filename);
+        const exists = await promises.access(filePath).then(()=>true).catch(()=>false);
+        if (exists) return void ctx.logger.error(`File already exists: ${node_path.relative(process.cwd(), filePath)}`);
+        await promises.mkdir(outDir, {
+            recursive: true
+        });
+        await promises.writeFile(filePath, content, 'utf8');
+        ctx.logger.success(`Created ${node_path.relative(process.cwd(), filePath)}`);
+        ctx.logger.outro('Done');
+    }
+});
+const dumpCommand = command({
+    description: 'Resolve and print the full entry tree as JSON',
+    handler: async (ctx)=>{
+        const paths = createPaths(process.cwd());
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.map((err)=>{
+                const path = err.path.join('.');
+                return ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        const previousManifest = await loadManifest(paths.contentDir);
+        const syncCtx = {
+            repoRoot: paths.repoRoot,
+            outDir: paths.contentDir,
+            config,
+            previousManifest,
+            manifest: {
+                files: {},
+                timestamp: Date.now()
+            },
+            quiet: true
+        };
+        const [resolveErr, resolved] = await resolveEntries(config.sections, syncCtx);
+        if (resolveErr) {
+            ctx.logger.error(resolveErr.message);
+            process.exit(1);
+        }
+        const tree = toTree(resolved);
+        process.stdout.write(`${JSON.stringify(tree, null, 2)}\n`);
+    }
+});
+function maybeLink(link) {
+    if (link) return {
+        link
+    };
+    return {};
+}
+function maybeCollapsible(collapsible) {
+    if (collapsible) return {
+        collapsible
+    };
+    return {};
+}
+function maybeHidden(hidden) {
+    if (hidden) return {
+        hidden
+    };
+    return {};
+}
+function maybeStandalone(standalone) {
+    if (standalone) return {
+        standalone
+    };
+    return {};
+}
+function maybeItems(items) {
+    if (items && items.length > 0) return {
+        items: toTree(items)
+    };
+    return {};
+}
+function toTree(entries) {
+    return entries.map(buildDumpEntry);
+}
+function buildDumpEntry(entry) {
+    return {
+        text: entry.title,
+        ...maybeLink(entry.link),
+        ...maybeCollapsible(entry.collapsible),
+        ...maybeHidden(entry.hidden),
+        ...maybeStandalone(entry.standalone),
+        ...maybeItems(entry.items)
+    };
+}
+const generateCommand = command({
+    description: 'Generate banner, logo, and icon SVG assets from project title',
+    handler: async (ctx)=>{
+        ctx.logger.intro('zpress generate');
+        const paths = createPaths(process.cwd());
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.map((err)=>{
+                const path = err.path.join('.');
+                return ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        const assetConfig = buildAssetConfig(config);
+        if (!assetConfig) {
+            ctx.logger.warn('No title configured — skipping asset generation');
+            ctx.logger.outro('Done');
+            return;
+        }
+        await promises.mkdir(paths.publicDir, {
+            recursive: true
+        });
+        const [err, written] = await generateAssets({
+            config: assetConfig,
+            publicDir: paths.publicDir
+        });
+        if (err) {
+            ctx.logger.error(err.message);
+            ctx.logger.outro('Failed');
+            return;
+        }
+        if (0 === written.length) ctx.logger.info('All assets are user-customized — nothing to generate');
+        else ctx.logger.success(`Generated ${written.join(', ')}`);
+        ctx.logger.outro('Done');
+    }
+});
+function buildAssetConfig(config) {
+    if (!config.title) return null;
+    return {
+        title: config.title,
+        tagline: config.tagline
+    };
+}
+const serveCommand = command({
+    description: 'Preview the built Rspress site',
+    options: z.object({
+        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');
+        const paths = createPaths(process.cwd());
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.map((err)=>{
+                const path = err.path.join('.');
+                return ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        const port = await serveSite({
+            config,
+            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';
+const setupCommand = command({
+    description: 'Initialize a zpress config in the current project',
+    handler: async (ctx)=>{
+        const cwd = process.cwd();
+        const paths = createPaths(cwd);
+        const configPath = node_path.join(paths.repoRoot, CONFIG_FILENAME);
+        ctx.logger.intro('zpress setup');
+        if (node_fs.existsSync(configPath)) {
+            ctx.logger.warn(`${CONFIG_FILENAME} already exists — skipping`);
+            ctx.logger.outro('Done');
+            return;
+        }
+        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
+        });
+        const [assetErr, written] = await generateAssets({
+            config: {
+                title,
+                tagline: void 0
+            },
+            publicDir: paths.publicDir
+        });
+        if (assetErr) {
+            ctx.logger.error(`Asset generation failed: ${assetErr.message}`);
+            process.exit(1);
+        }
+        if (written.length > 0) ctx.logger.success(`Generated ${written.join(', ')}`);
+        ctx.logger.outro('Done');
+    }
+});
+function extractGitRepoName(cwd) {
+    const url = setup_execSilent('git', [
+        'remote',
+        'get-url',
+        'origin'
+    ], cwd);
+    if (!url) return null;
+    const match = url.match(/[/:]([^/:]+?)(?:\.git)?$/);
+    if (!match) return null;
+    return match[1];
+}
+function setup_execSilent(file, args, cwd) {
+    try {
+        return execFileSync(file, [
+            ...args
+        ], {
+            cwd,
+            stdio: 'pipe',
+            encoding: 'utf8'
+        }).trim();
+    } catch  {
+        return null;
+    }
+}
+function deriveTitle(cwd) {
+    const repoName = extractGitRepoName(cwd);
+    if (repoName) return repoName;
+    return node_path.basename(cwd);
+}
+function buildConfigTemplate(title) {
+    const escaped = title.replaceAll("'", String.raw`\'`);
+    return `import { defineConfig } from '@zpress/kit'
+
+export default defineConfig({
+  title: '${escaped}',
+  sections: [
+    {
+      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({
+        quiet: z.boolean().optional().default(false)
+    }),
+    handler: async (ctx)=>{
+        const { quiet } = ctx.args;
+        const paths = createPaths(process.cwd());
+        if (!quiet) ctx.logger.intro('zpress sync');
+        const [configErr, config] = await loadConfig(paths.repoRoot);
+        if (configErr) {
+            ctx.logger.error(configErr.message);
+            if (configErr.errors && configErr.errors.length > 0) configErr.errors.map((err)=>{
+                const path = err.path.join('.');
+                return ctx.logger.error(`  ${path}: ${err.message}`);
+            });
+            process.exit(1);
+        }
+        await sync(config, {
+            paths,
+            quiet
+        });
+        if (!quiet) ctx.logger.outro('Done');
+    }
+});
+await cli({
+    name: 'zpress',
+    version: "0.4.0",
+    description: 'CLI for building and serving documentation',
+    commands: {
+        sync: syncCommand,
+        dev: devCommand,
+        diff: diffCommand,
+        build: buildCommand,
+        check: checkCommand,
+        draft: draftCommand,
+        serve: serveCommand,
+        clean: cleanCommand,
+        dump: dumpCommand,
+        setup: setupCommand,
+        generate: generateCommand
+    }
+});
+export { toError };