kennel 0.1.8

package/dist/schema/validation.js

@@ -0,0 +1,212 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import * as Ajv2020Module from 'ajv/dist/2020.js';
+import * as addFormatsModule from 'ajv-formats';
+import { isObject } from '../shared/object.js';
+import { displayPath } from '../shared/path.js';
+import { documentConfig, findNearestSchema, IGNORED_DIRECTORIES, loadSchemaFor, matchesDocumentSpec, matchesGlob, parseDocument, parserForPath, SCHEMA_FILES, } from './documents.js';
+import { shouldApplyRule, valuesAtPointer } from './pointers.js';
+const schemaCache = new Map();
+export function createAjv(schema) {
+    const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+    const addFormats = addFormatsModule.default ?? addFormatsModule;
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    return ajv.compile(schema);
+}
+export function cachedSchemaFor(targetPath) {
+    const schemaPath = findNearestSchema(targetPath);
+    if (!schemaPath)
+        return null;
+    const cached = schemaCache.get(schemaPath);
+    if (cached)
+        return cached;
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+    const documents = documentConfig(schema);
+    const entry = {
+        schemaPath,
+        schema,
+        validate: createAjv(schema),
+        documentSpecs: documents.specs,
+        usingDefaultDocuments: documents.usingDefault,
+    };
+    schemaCache.set(schemaPath, entry);
+    return entry;
+}
+export function validateFile(filePath, schemaPath, schema, validate, parser = parserForPath(filePath)) {
+    const document = parseDocument(filePath, parser);
+    const schemaValid = validate(document);
+    const kennelErrors = validateKennelRequirements(filePath, schema, document);
+    const errors = [...(validate.errors ?? []), ...kennelErrors];
+    return {
+        filePath,
+        schemaPath,
+        valid: schemaValid && kennelErrors.length === 0,
+        errors,
+    };
+}
+function relativeReferenceIsSafe(filePath) {
+    return !filePath.startsWith('/') && !filePath.split('/').includes('..');
+}
+export function validateKennelRequirements(filePath, schema, document) {
+    const config = schema['x-kennel'];
+    if (!isObject(config))
+        return [];
+    const fileDir = dirname(filePath);
+    const errors = [];
+    const requiredDirectories = Array.isArray(config.requiredDirectories) ? config.requiredDirectories : [];
+    for (const directoryName of requiredDirectories) {
+        if (typeof directoryName !== 'string')
+            continue;
+        const directoryPath = join(fileDir, directoryName);
+        if (!existsSync(directoryPath) || !statSync(directoryPath).isDirectory()) {
+            errors.push({
+                instancePath: '/',
+                message: `missing required directory ${directoryName.replace(/\/?$/, '/')}`,
+            });
+        }
+    }
+    const requiredFiles = Array.isArray(config.requiredFiles) ? config.requiredFiles : [];
+    for (const fileName of requiredFiles) {
+        if (typeof fileName !== 'string')
+            continue;
+        const requiredFilePath = join(fileDir, fileName);
+        if (!existsSync(requiredFilePath) || !statSync(requiredFilePath).isFile()) {
+            errors.push({
+                instancePath: '/',
+                message: `missing required file ${fileName}`,
+            });
+        }
+    }
+    const directoryContents = Array.isArray(config.directoryContents) ? config.directoryContents : [];
+    for (const rule of directoryContents) {
+        if (!isObject(rule) || typeof rule.path !== 'string' || !shouldApplyRule(document, rule))
+            continue;
+        const directoryPath = join(fileDir, rule.path);
+        const label = rule.path.replace(/\/?$/, '/');
+        if (!existsSync(directoryPath) || !statSync(directoryPath).isDirectory()) {
+            errors.push({
+                instancePath: '/',
+                message: `missing required directory ${label}`,
+            });
+            continue;
+        }
+        const glob = typeof rule.glob === 'string' ? rule.glob : '*';
+        const minFiles = Number.isInteger(rule.minFiles) ? Number(rule.minFiles) : 1;
+        const fileCount = readdirSync(directoryPath, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && matchesGlob(entry.name, glob))
+            .length;
+        if (fileCount < minFiles) {
+            errors.push({
+                instancePath: '/',
+                message: `${label} requires at least ${minFiles} ${glob} file${minFiles === 1 ? '' : 's'}`,
+            });
+        }
+    }
+    const fileReferences = Array.isArray(config.fileReferences) ? config.fileReferences : [];
+    for (const rule of fileReferences) {
+        if (!isObject(rule) || typeof rule.pointer !== 'string' || !shouldApplyRule(document, rule))
+            continue;
+        const values = valuesAtPointer(document, rule.pointer);
+        if (values.length === 0 && rule.required === true) {
+            errors.push({
+                instancePath: rule.pointer,
+                message: 'referenced path is required',
+            });
+            continue;
+        }
+        for (const value of values) {
+            if (value === null && rule.allowNull === true)
+                continue;
+            if (value === undefined && rule.required !== true)
+                continue;
+            if (typeof value !== 'string' || value.trim() === '') {
+                errors.push({
+                    instancePath: rule.pointer,
+                    message: 'referenced path must be a non-empty string',
+                });
+                continue;
+            }
+            if (value.startsWith('http://') || value.startsWith('https://'))
+                continue;
+            if (!relativeReferenceIsSafe(value)) {
+                errors.push({
+                    instancePath: rule.pointer,
+                    message: `referenced path must stay inside the document folder (${value})`,
+                });
+                continue;
+            }
+            const requiredType = rule.type === 'directory' ? 'directory' : 'file';
+            const referencedPath = join(fileDir, value);
+            const exists = existsSync(referencedPath);
+            const correctType = exists && (requiredType === 'directory'
+                ? statSync(referencedPath).isDirectory()
+                : statSync(referencedPath).isFile());
+            if (!correctType) {
+                errors.push({
+                    instancePath: rule.pointer,
+                    message: `referenced ${requiredType} does not exist (${value})`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+export function candidateFiles(targetPath) {
+    const target = resolve(targetPath);
+    if (statSync(target).isFile()) {
+        const entry = cachedSchemaFor(target);
+        if (!entry)
+            throw new Error(`No ${SCHEMA_FILES.join(' or ')} found from ${target} upward`);
+        const spec = entry.documentSpecs.find((documentSpec) => (matchesDocumentSpec(target, entry.schemaPath, documentSpec)));
+        if (!spec) {
+            throw new Error(`${target} is not listed in ${entry.schemaPath} x-kennel.documents`);
+        }
+        return [{ filePath: target, schemaEntry: entry, parser: spec.parser }];
+    }
+    const found = [];
+    function walk(directory) {
+        const schemaEntry = cachedSchemaFor(directory);
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('.') || IGNORED_DIRECTORIES.has(entry.name))
+                    continue;
+                walk(join(directory, entry.name));
+                continue;
+            }
+            if (!entry.isFile() || !schemaEntry || SCHEMA_FILES.includes(entry.name))
+                continue;
+            const filePath = join(directory, entry.name);
+            const spec = schemaEntry.documentSpecs.find((documentSpec) => (matchesDocumentSpec(filePath, schemaEntry.schemaPath, documentSpec)));
+            if (spec) {
+                found.push({ filePath, schemaEntry, parser: spec.parser });
+            }
+        }
+    }
+    walk(target);
+    return found.sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+export function validateTarget(targetPath) {
+    const candidates = candidateFiles(targetPath);
+    if (candidates.length === 0)
+        throw new Error(`No schema-declared documents found in ${targetPath}`);
+    const results = candidates.map(({ filePath, schemaEntry, parser }) => {
+        return validateFile(filePath, schemaEntry.schemaPath, schemaEntry.schema, schemaEntry.validate, parser);
+    });
+    for (const result of results) {
+        if (result.valid) {
+            console.log(`ok ${displayPath(result.filePath)}`);
+            continue;
+        }
+        console.log(`not ok ${displayPath(result.filePath)}`);
+        for (const error of result.errors) {
+            console.log(`  - ${error.instancePath || '/'} ${error.message}`);
+        }
+    }
+    console.log(`\n${results.filter((result) => result.valid).length}/${results.length} files valid`);
+    return results.every((result) => result.valid);
+}
+export function schemaFor(targetPath) {
+    const { schemaPath } = loadSchemaFor(targetPath);
+    console.log(schemaPath);
+}

package/dist/shared/json.d.ts

@@ -0,0 +1,4 @@
+export declare function readJson<T = any>(filePath: string): T;
+export declare function stripJsonComments(content: string): string;
+export declare function readJsonc<T = any>(filePath: string): T;
+export declare function writeJson(filePath: string, value: unknown): void;

package/dist/shared/json.js

@@ -0,0 +1,56 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+export function readJson(filePath) {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+export function stripJsonComments(content) {
+    let output = '';
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < content.length; index += 1) {
+        const char = content[index];
+        const next = content[index + 1];
+        if (inString) {
+            output += char;
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            output += char;
+            continue;
+        }
+        if (char === '/' && next === '/') {
+            while (index < content.length && content[index] !== '\n')
+                index += 1;
+            output += '\n';
+            continue;
+        }
+        if (char === '/' && next === '*') {
+            index += 2;
+            while (index < content.length && !(content[index] === '*' && content[index + 1] === '/')) {
+                if (content[index] === '\n')
+                    output += '\n';
+                index += 1;
+            }
+            index += 1;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+export function readJsonc(filePath) {
+    return JSON.parse(stripJsonComments(readFileSync(filePath, 'utf8')));
+}
+export function writeJson(filePath, value) {
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/shared/object.d.ts

@@ -0,0 +1,2 @@
+export type JsonObject = Record<string, unknown>;
+export declare function isObject(value: unknown): value is JsonObject;

package/dist/shared/object.js

@@ -0,0 +1,3 @@
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/shared/package-manager.d.ts

@@ -0,0 +1,11 @@
+type PackageJson = {
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+    peerDependencies?: Record<string, unknown>;
+    optionalDependencies?: Record<string, unknown>;
+};
+export declare function packageManagerFor(root: string): string;
+export declare function runArgsFor(packageManager: string, script: string, scriptArgs: string[]): string[];
+export declare function localBin(root: string, name: string): string | null;
+export declare function hasDependency(pkg: PackageJson, name: string): boolean;
+export {};

package/dist/shared/package-manager.js

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isObject } from './object.js';
+const LOCKFILE_PACKAGE_MANAGERS = [
+    ['bun.lock', 'bun'],
+    ['bun.lockb', 'bun'],
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+];
+export function packageManagerFor(root) {
+    for (const [lockfile, packageManager] of LOCKFILE_PACKAGE_MANAGERS) {
+        if (existsSync(join(root, lockfile)))
+            return packageManager;
+    }
+    return 'npm';
+}
+export function runArgsFor(packageManager, script, scriptArgs) {
+    if (packageManager === 'npm')
+        return ['run', script, '--', ...scriptArgs];
+    return ['run', script, ...scriptArgs];
+}
+export function localBin(root, name) {
+    const suffixes = process.platform === 'win32' ? ['.cmd', '.ps1', ''] : [''];
+    for (const suffix of suffixes) {
+        const binPath = join(root, 'node_modules', '.bin', `${name}${suffix}`);
+        if (existsSync(binPath))
+            return binPath;
+    }
+    return null;
+}
+export function hasDependency(pkg, name) {
+    return [
+        pkg.dependencies,
+        pkg.devDependencies,
+        pkg.peerDependencies,
+        pkg.optionalDependencies,
+    ].some((dependencies) => isObject(dependencies) && dependencies[name] !== undefined);
+}

package/dist/shared/path.d.ts

@@ -0,0 +1,4 @@
+export declare function displayPath(filePath: string): string;
+export declare function nearestFile(startPath: string, fileName: string): string | null;
+export declare function slugifyHostname(value: string): string;
+export declare function normalizeHostname(value: unknown): string;

package/dist/shared/path.js

@@ -0,0 +1,40 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+export function displayPath(filePath) {
+    const resolved = resolve(filePath);
+    const relativePath = relative(process.cwd(), resolved);
+    if (relativePath === '')
+        return '.';
+    if (relativePath.startsWith('..'))
+        return resolved;
+    return relativePath;
+}
+export function nearestFile(startPath, fileName) {
+    let current = resolve(startPath);
+    if (existsSync(current) && statSync(current).isFile())
+        current = dirname(current);
+    while (true) {
+        const filePath = resolve(current, fileName);
+        if (existsSync(filePath) && statSync(filePath).isFile())
+            return filePath;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function slugifyHostname(value) {
+    const withoutScope = value.replace(/^@[^/]+\//, '');
+    return withoutScope
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+export function normalizeHostname(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return '';
+    return value
+        .trim()
+        .replace(/^https?:\/\//, '')
+        .replace(/\/.*$/, '');
+}

package/dist/shared/process.d.ts

@@ -0,0 +1,7 @@
+export type ChildCommand = {
+    command: string;
+    args: string[];
+    cwd?: string;
+};
+export declare function commandExists(command: string): boolean;
+export declare function commandLine(command: string, args: string[]): string;

package/dist/shared/process.js

@@ -0,0 +1,12 @@
+import { spawnSync } from 'node:child_process';
+export function commandExists(command) {
+    const result = spawnSync('sh', ['-c', `command -v ${command} >/dev/null 2>&1`], {
+        stdio: 'ignore',
+    });
+    return result.status === 0;
+}
+export function commandLine(command, args) {
+    return [command, ...args]
+        .map((arg) => (/^[A-Za-z0-9_./:@=-]+$/.test(arg) ? arg : JSON.stringify(arg)))
+        .join(' ');
+}

package/dist/shared/project-config.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_PROJECT_CONFIG = "raggle.json";
+export declare function projectConfigPath(targetPath: string, configFile?: string): string;

package/dist/shared/project-config.js

@@ -0,0 +1,26 @@
+import { existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { nearestFile } from './path.js';
+export const DEFAULT_PROJECT_CONFIG = 'raggle.json';
+function targetDirectory(targetPath) {
+    const target = resolve(targetPath);
+    if (existsSync(target) && statSync(target).isFile())
+        return dirname(target);
+    return target;
+}
+export function projectConfigPath(targetPath, configFile = DEFAULT_PROJECT_CONFIG) {
+    if (!configFile.trim())
+        throw new Error('config file name is required');
+    if (configFile.includes('/') || configFile.includes('\\') || isAbsolute(configFile)) {
+        const configPath = isAbsolute(configFile)
+            ? configFile
+            : resolve(targetDirectory(targetPath), configFile);
+        if (existsSync(configPath) && statSync(configPath).isFile())
+            return configPath;
+        throw new Error(`No ${configFile} found from ${resolve(targetPath)}`);
+    }
+    const configPath = nearestFile(targetPath, configFile);
+    if (configPath)
+        return configPath;
+    throw new Error(`No ${configFile} found from ${resolve(targetPath)} upward`);
+}

package/dist/site/dev.d.ts

@@ -0,0 +1,10 @@
+export type DevOptions = {
+    targetPath: string;
+    port: string;
+    script: string | null;
+    configFile: string;
+    dryRun: boolean;
+    extra: string[];
+};
+export declare function splitDevArgs(input: string[]): DevOptions;
+export declare function dev(input: string[]): void;

package/dist/site/dev.js

@@ -0,0 +1,128 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { readJson } from '../shared/json.js';
+import { normalizeHostname, slugifyHostname } from '../shared/path.js';
+import { DEFAULT_PROJECT_CONFIG, projectConfigPath } from '../shared/project-config.js';
+import { commandLine } from '../shared/process.js';
+import { buildScriptDevCommand, buildVitePressDevCommand, detectedPlatform, displayBasePath, } from './vitepress.js';
+export function splitDevArgs(input) {
+    const options = {
+        targetPath: '.',
+        port: '3000',
+        script: null,
+        configFile: DEFAULT_PROJECT_CONFIG,
+        dryRun: false,
+        extra: [],
+    };
+    const args = [...input];
+    const passthrough = args.indexOf('--');
+    if (passthrough !== -1) {
+        options.extra = args.splice(passthrough + 1);
+        args.pop();
+    }
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--dry-run') {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === '--port') {
+            options.port = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--port=')) {
+            options.port = arg.slice('--port='.length);
+            continue;
+        }
+        if (arg === '--script') {
+            options.script = args[index + 1];
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--script=')) {
+            options.script = arg.slice('--script='.length);
+            continue;
+        }
+        if (arg === '--config') {
+            options.configFile = args[index + 1] ?? '';
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--config=')) {
+            options.configFile = arg.slice('--config='.length);
+            continue;
+        }
+        if (arg.startsWith('-'))
+            throw new Error(`Unknown dev option: ${arg}`);
+        options.targetPath = arg;
+    }
+    if (!options.port)
+        throw new Error('dev requires a port');
+    if (!options.configFile)
+        throw new Error('dev requires a config file name');
+    return options;
+}
+function localDevHost(config, rawName) {
+    const dev = config.dev && typeof config.dev === 'object' && !Array.isArray(config.dev) ? config.dev : {};
+    const host = normalizeHostname(dev.host ?? dev.hostname ?? config.host ?? config.hostname);
+    if (host)
+        return host;
+    const label = slugifyHostname(rawName);
+    if (!label)
+        throw new Error(`Could not derive a local hostname from "${rawName}"`);
+    return `${label}.localhost`;
+}
+function devRoot(configRoot, config) {
+    const dev = config.dev && typeof config.dev === 'object' && !Array.isArray(config.dev) ? config.dev : {};
+    const root = dev.root ?? config.devRoot;
+    if (typeof root !== 'string' || root.trim() === '')
+        return configRoot;
+    return resolve(configRoot, root);
+}
+function devToolRoot(configRoot, config) {
+    const dev = config.dev && typeof config.dev === 'object' && !Array.isArray(config.dev) ? config.dev : {};
+    const root = dev.toolRoot;
+    if (typeof root !== 'string' || root.trim() === '')
+        return null;
+    return resolve(configRoot, root);
+}
+function devScript(config) {
+    const dev = config.dev && typeof config.dev === 'object' && !Array.isArray(config.dev) ? config.dev : {};
+    if (typeof dev.script !== 'string' || dev.script.trim() === '')
+        return null;
+    return dev.script;
+}
+export function dev(input) {
+    const options = splitDevArgs(input);
+    const configPath = projectConfigPath(options.targetPath, options.configFile);
+    const configRoot = dirname(configPath);
+    const config = readJson(configPath);
+    const root = devRoot(configRoot, config);
+    const packagePath = join(root, 'package.json');
+    if (!existsSync(packagePath))
+        throw new Error(`No package.json found for ${configPath} dev root ${root}`);
+    const pkg = readJson(packagePath);
+    const rawName = config.name ?? config.project?.name ?? pkg.name ?? config.title;
+    if (typeof rawName !== 'string' || rawName.trim() === '') {
+        throw new Error(`${configPath} must define name, or package.json must define name`);
+    }
+    const host = localDevHost(config, rawName);
+    const scriptArgs = ['--host', host, '--port', options.port, ...options.extra];
+    const script = options.script ?? devScript(config);
+    const platform = script ? 'script' : detectedPlatform(root, pkg);
+    const toolRoot = devToolRoot(configRoot, config) ?? root;
+    const child = platform === 'vitepress'
+        ? buildVitePressDevCommand(root, options, scriptArgs, toolRoot)
+        : buildScriptDevCommand(root, pkg, { script }, scriptArgs);
+    console.log(commandLine(child.command, child.args));
+    console.log(`http://${host}:${options.port}${displayBasePath(config)}`);
+    if (options.dryRun)
+        return;
+    const result = spawnSync(child.command, child.args, {
+        cwd: child.cwd ?? root,
+        stdio: 'inherit',
+    });
+    process.exit(result.status ?? 1);
+}

package/dist/site/vitepress.d.ts

@@ -0,0 +1,21 @@
+import type { ChildCommand } from '../shared/process.js';
+export type PackageJson = {
+    name?: string;
+    scripts?: Record<string, string>;
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+    peerDependencies?: Record<string, unknown>;
+    optionalDependencies?: Record<string, unknown>;
+};
+export declare function vitepressConfig(root: string): string | null;
+export declare function vitepressOutputDirectory(root: string): string;
+export declare function detectedPlatform(root: string, pkg: PackageJson): 'vitepress' | 'script';
+export declare function displayBasePath(config: {
+    base?: unknown;
+}): string;
+export declare function buildScriptDevCommand(root: string, pkg: PackageJson, options: {
+    script: string | null;
+}, scriptArgs: string[]): ChildCommand;
+export declare function buildVitePressDevCommand(root: string, _options: {
+    script: string | null;
+}, scriptArgs: string[], toolRoot?: string): ChildCommand;

package/dist/site/vitepress.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasDependency, localBin, packageManagerFor, runArgsFor } from '../shared/package-manager.js';
+export function vitepressConfig(root) {
+    const configNames = [
+        '.vitepress/config.mts',
+        '.vitepress/config.ts',
+        '.vitepress/config.mjs',
+        '.vitepress/config.js',
+        'docs/.vitepress/config.mts',
+        'docs/.vitepress/config.ts',
+        'docs/.vitepress/config.mjs',
+        'docs/.vitepress/config.js',
+    ];
+    return configNames.find((configName) => existsSync(join(root, configName))) ?? null;
+}
+export function vitepressOutputDirectory(root) {
+    const configPath = vitepressConfig(root);
+    if (configPath?.startsWith('docs/'))
+        return 'docs/.vitepress/dist';
+    return '.vitepress/dist';
+}
+export function detectedPlatform(root, pkg) {
+    if (vitepressConfig(root) || hasDependency(pkg, 'vitepress'))
+        return 'vitepress';
+    return 'script';
+}
+export function displayBasePath(config) {
+    if (typeof config.base !== 'string' || config.base.trim() === '')
+        return '/';
+    const base = config.base.trim();
+    const normalized = base.replace(/^\/+|\/+$/g, '');
+    if (!normalized)
+        return '/';
+    return `/${normalized}/`;
+}
+export function buildScriptDevCommand(root, pkg, options, scriptArgs) {
+    const scripts = pkg.scripts ?? {};
+    const script = options.script ?? (scripts['docs:dev'] ? 'docs:dev' : 'dev');
+    if (typeof scripts[script] !== 'string') {
+        throw new Error(`${join(root, 'package.json')} does not define script "${script}"`);
+    }
+    const packageManager = packageManagerFor(root);
+    return {
+        command: packageManager,
+        args: runArgsFor(packageManager, script, scriptArgs),
+    };
+}
+export function buildVitePressDevCommand(root, _options, scriptArgs, toolRoot = root) {
+    const siteRoot = toolRoot === root ? '.' : root;
+    const vitepress = localBin(toolRoot, 'vitepress');
+    if (vitepress) {
+        const args = ['dev', siteRoot];
+        args.push(...scriptArgs);
+        return { command: vitepress, args, cwd: toolRoot };
+    }
+    const packageManager = packageManagerFor(toolRoot);
+    if (packageManager === 'npm') {
+        const args = ['exec', '--', 'vitepress', 'dev', siteRoot];
+        args.push(...scriptArgs);
+        return { command: packageManager, args, cwd: toolRoot };
+    }
+    const args = ['x', 'vitepress', 'dev', siteRoot];
+    args.push(...scriptArgs);
+    return { command: packageManager, args, cwd: toolRoot };
+}