@zpress/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joggr
+
+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/dist/index.mjs

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+import { cli, command } from "@kidd-cli/core";
+import { createPaths, generateAssets, loadConfig, loadManifest, resolveEntries, sync } from "@zpress/core";
+import { z } from "zod";
+import { execFileSync, spawn } from "node:child_process";
+import { platform } from "node:os";
+import { build, dev, serve } from "@rspress/core";
+import { createRspressConfig } from "@zpress/ui";
+import { match as external_ts_pattern_match } from "ts-pattern";
+import promises from "node:fs/promises";
+import node_fs from "node:fs";
+import node_path from "node:path";
+const DEFAULT_PORT = 6174;
+async function startDevServer(options) {
+    const rspressConfig = createRspressConfig(options);
+    await dev({
+        appDirectory: options.paths.repoRoot,
+        docDirectory: options.paths.contentDir,
+        config: rspressConfig,
+        configFilePath: '',
+        extraBuilderConfig: {
+            server: {
+                port: DEFAULT_PORT
+            }
+        }
+    });
+}
+async function buildSite(options) {
+    const rspressConfig = createRspressConfig(options);
+    await build({
+        docDirectory: options.paths.contentDir,
+        config: rspressConfig,
+        configFilePath: ''
+    });
+}
+async function serveSite(options) {
+    const rspressConfig = createRspressConfig(options);
+    await serve({
+        config: rspressConfig,
+        configFilePath: '',
+        port: DEFAULT_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 cleanTargets(paths) {
+    return [
+        {
+            dir: paths.cacheDir,
+            label: 'cache'
+        },
+        {
+            dir: paths.contentDir,
+            label: 'content'
+        },
+        {
+            dir: paths.distDir,
+            label: 'dist'
+        }
+    ];
+}
+async function 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 results.filter((label)=>null !== label);
+}
+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(paths);
+        if (removed.length > 0) ctx.logger.success(`Removed: ${removed.join(', ')}`);
+        else ctx.logger.info('Nothing to clean');
+        ctx.logger.outro('Done');
+    }
+});
+const buildCommand = command({
+    description: 'Run sync and build the Rspress site',
+    args: z.object({
+        quiet: z.boolean().optional().default(false),
+        clean: z.boolean().optional().default(false)
+    }),
+    handler: async (ctx)=>{
+        const { quiet } = ctx.args;
+        const paths = createPaths(process.cwd());
+        ctx.logger.intro('zpress build');
+        if (ctx.args.clean) {
+            const removed = await 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);
+            process.exit(1);
+        }
+        await sync(config, {
+            paths,
+            quiet
+        });
+        await buildSite({
+            config,
+            paths
+        });
+        ctx.logger.outro('Done');
+    }
+});
+const devCommand = command({
+    description: 'Run sync + watcher and start Rspress dev server',
+    args: z.object({
+        quiet: z.boolean().optional().default(false),
+        clean: 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(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);
+            process.exit(1);
+        }
+        await sync(config, {
+            paths,
+            quiet
+        });
+        const { createWatcher } = await import("./watcher.mjs");
+        const watcher = createWatcher(config, paths);
+        function cleanup() {
+            if (watcher) watcher.close();
+        }
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        await startDevServer({
+            config,
+            paths
+        });
+    }
+});
+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 maybeIsolated(isolated) {
+    if (isolated) return {
+        isolated
+    };
+    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.text,
+        ...maybeLink(entry.link),
+        ...maybeCollapsible(entry.collapsible),
+        ...maybeHidden(entry.hidden),
+        ...maybeIsolated(entry.isolated),
+        ...maybeItems(entry.items)
+    };
+}
+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);
+            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);
+        ctx.output.raw(`${JSON.stringify(tree, null, 2)}\n`);
+    }
+});
+function buildAssetConfig(config) {
+    if (!config.title) return null;
+    return {
+        title: config.title,
+        tagline: config.tagline
+    };
+}
+const generateCommand = command({
+    description: 'Generate banner and logo 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);
+            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');
+    }
+});
+const serveCommand = command({
+    description: 'Preview the built Rspress site',
+    args: z.object({
+        open: z.boolean().optional().default(true)
+    }),
+    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);
+            process.exit(1);
+        }
+        if (ctx.args.open) setTimeout(()=>openBrowser(`http://localhost:${DEFAULT_PORT}`), 2000);
+        await serveSite({
+            config,
+            paths
+        });
+    }
+});
+const CONFIG_FILENAME = 'zpress.config.ts';
+function extractGitRepoName(cwd) {
+    const url = execSilent('git', [
+        'remote',
+        'get-url',
+        'origin'
+    ], cwd);
+    if (!url) return null;
+    const match = url.match(/[/:]([^/:]+?)(?:\.git)?$/);
+    if (!match) return null;
+    return match[1];
+}
+function 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'
+
+export default defineConfig({
+  title: '${escaped}',
+  sections: [
+    {
+      text: 'Getting Started',
+      prefix: '/getting-started',
+      from: 'docs/*.md',
+    },
+  ],
+})
+`;
+}
+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 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');
+    }
+});
+const syncCommand = command({
+    description: 'Sync documentation sources into .zpress/',
+    args: 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);
+            process.exit(1);
+        }
+        await sync(config, {
+            paths,
+            quiet
+        });
+        if (!quiet) ctx.logger.outro('Done');
+    }
+});
+await cli({
+    name: 'zpress',
+    version: "0.1.0",
+    description: 'CLI for building and serving documentation',
+    commands: {
+        sync: syncCommand,
+        dev: devCommand,
+        build: buildCommand,
+        serve: serveCommand,
+        clean: cleanCommand,
+        dump: dumpCommand,
+        setup: setupCommand,
+        generate: generateCommand
+    }
+});

package/dist/watcher.mjs

@@ -0,0 +1,153 @@
+import { existsSync } from "node:fs";
+import node_path from "node:path";
+import { cliLogger } from "@kidd-cli/core/logger";
+import { hasGlobChars, loadConfig, sync } from "@zpress/core";
+import { watch } from "chokidar";
+import { debounce } from "es-toolkit";
+import { match } from "ts-pattern";
+const CONFIG_EXTENSIONS = [
+    '.ts',
+    '.mts',
+    '.cts',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.json'
+];
+const MARKDOWN_EXTENSIONS = [
+    '.md',
+    '.mdx'
+];
+function isMarkdownFile(filePath) {
+    return MARKDOWN_EXTENSIONS.some((ext)=>filePath.endsWith(ext));
+}
+function createWatcher(initialConfig, paths) {
+    const { repoRoot } = paths;
+    const configFiles = CONFIG_EXTENSIONS.map((ext)=>node_path.resolve(repoRoot, `zpress.config${ext}`));
+    let config = initialConfig;
+    const planningDir = node_path.resolve(repoRoot, '.planning');
+    const watchPaths = [
+        ...extractWatchPaths(config.sections, repoRoot),
+        ...(()=>{
+            if (existsSync(planningDir)) return [
+                planningDir
+            ];
+            return [];
+        })(),
+        ...configFiles
+    ];
+    if (0 === watchPaths.length) return void cliLogger.warn('No source paths to watch');
+    cliLogger.info(`Watching ${watchPaths.length} paths: ${watchPaths.map((p)=>node_path.relative(repoRoot, p)).join(', ')}`);
+    let syncing = false;
+    let pendingReloadConfig = null;
+    let consecutiveFailures = 0;
+    const MAX_CONSECUTIVE_FAILURES = 5;
+    const watcher = watch(watchPaths, {
+        ignoreInitial: true,
+        ignored: [
+            '**/node_modules/**',
+            '**/.git/**',
+            '**/.zpress/**',
+            '**/bundle/**'
+        ],
+        awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50
+        }
+    });
+    async function triggerSync(reloadConfig) {
+        if (syncing) {
+            pendingReloadConfig = true === pendingReloadConfig || reloadConfig;
+            return;
+        }
+        syncing = true;
+        try {
+            if (reloadConfig) {
+                const [configErr, newConfig] = await loadConfig(paths.repoRoot);
+                if (configErr) return void cliLogger.error(`Config reload failed: ${configErr.message}`);
+                config = newConfig;
+                cliLogger.info('Config reloaded');
+            }
+            await sync(config, {
+                paths
+            });
+            consecutiveFailures = 0;
+        } catch (error) {
+            consecutiveFailures += 1;
+            const errorMessage = (()=>{
+                if (error instanceof Error) return error.message;
+                return String(error);
+            })();
+            cliLogger.error(`Sync error: ${errorMessage}`);
+        } finally{
+            syncing = false;
+            if (null !== pendingReloadConfig) if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                cliLogger.error(`Sync failed ${consecutiveFailures} consecutive times, dropping pending resync. Will retry on next file change.`);
+                pendingReloadConfig = null;
+                consecutiveFailures = 0;
+            } else {
+                const shouldReload = pendingReloadConfig;
+                pendingReloadConfig = null;
+                triggerSync(shouldReload);
+            }
+        }
+    }
+    const debouncedSync = debounce(()=>triggerSync(false), 150);
+    const debouncedConfigSync = debounce(()=>triggerSync(true), 150);
+    const configFileSet = new Set(configFiles);
+    function isConfigFile(filePath) {
+        return configFileSet.has(node_path.resolve(filePath));
+    }
+    watcher.on('change', (filePath)=>{
+        if (isConfigFile(filePath)) {
+            cliLogger.info(`Config changed: ${node_path.basename(filePath)}`);
+            debouncedConfigSync();
+            return;
+        }
+        if (!isMarkdownFile(filePath)) return;
+        cliLogger.step(`Changed: ${node_path.relative(repoRoot, filePath)}`);
+        debouncedSync();
+    });
+    watcher.on('add', (filePath)=>{
+        if (!isMarkdownFile(filePath)) return;
+        cliLogger.step(`Added: ${node_path.relative(repoRoot, filePath)}`);
+        debouncedSync();
+    });
+    watcher.on('unlink', (filePath)=>{
+        if (!isMarkdownFile(filePath)) return;
+        cliLogger.step(`Removed: ${node_path.relative(repoRoot, filePath)}`);
+        debouncedSync();
+    });
+    return watcher;
+}
+function extractWatchPaths(entries, repoRoot) {
+    const dirs = new Set();
+    const files = new Set();
+    function walk(items) {
+        items.map((entry)=>{
+            if (entry.from) if (hasGlobChars(entry.from)) {
+                const [beforeGlob] = entry.from.split('*');
+                const dir = match(beforeGlob.endsWith('/')).with(true, ()=>beforeGlob.slice(0, -1)).otherwise(()=>node_path.dirname(beforeGlob));
+                dirs.add(node_path.resolve(repoRoot, dir));
+            } else files.add(node_path.resolve(repoRoot, entry.from));
+            if (entry.items) walk(entry.items);
+            return null;
+        });
+    }
+    walk(entries);
+    const sortedDirs = [
+        ...dirs
+    ].toSorted();
+    const dedupedDirs = sortedDirs.filter((dir, index)=>{
+        const previousDirs = sortedDirs.slice(0, index);
+        return !previousDirs.some((parent)=>dir.startsWith(`${parent}${node_path.sep}`));
+    });
+    const extraFiles = [
+        ...files
+    ].filter((file)=>!dedupedDirs.some((dir)=>file.startsWith(dir + node_path.sep)));
+    return [
+        ...dedupedDirs,
+        ...extraFiles
+    ];
+}
+export { createWatcher };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@zpress/cli",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joggrdocs/zpress.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "zpress": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@kidd-cli/core": "^0.2.0",
+    "@rspress/core": "2.0.5",
+    "chokidar": "^5.0.0",
+    "es-toolkit": "^1.45.1",
+    "ts-pattern": "^5.9.0",
+    "zod": "^4.3.6",
+    "@zpress/core": "0.1.0",
+    "@zpress/ui": "0.1.0"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.20.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "node ./dist/index.mjs dev --cwd ../..",
+    "typecheck": "tsc --noEmit"
+  }
+}