@poetora/cli 0.0.1 → 0.1.2

package/bin/services/port.service.js

@@ -0,0 +1,26 @@
+import detect from 'detect-port';
+import { NoAvailablePortError } from '../errors/index.js';
+import { CLI_CONSTANTS } from '../types/index.js';
+export class PortService {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async findAvailablePort(preferredPort) {
+        const startPort = preferredPort ?? CLI_CONSTANTS.PORT.DEFAULT;
+        for (let attempt = 0; attempt < CLI_CONSTANTS.PORT.MAX_ATTEMPTS; attempt++) {
+            const port = startPort + attempt;
+            if (await this.isPortAvailable(port)) {
+                if (attempt > 0 && this.logger) {
+                    this.logger.info(`port ${startPort} is already in use. using ${port} instead`);
+                }
+                return port;
+            }
+        }
+        throw new NoAvailablePortError(`No available port found after ${CLI_CONSTANTS.PORT.MAX_ATTEMPTS} attempts starting from ${startPort}`);
+    }
+    async isPortAvailable(port) {
+        const detectedPort = await detect(port);
+        return detectedPort === port;
+    }
+}

package/bin/services/template.service.d.ts

@@ -0,0 +1,22 @@
+export interface DirectoryStatus {
+    exists: boolean;
+    hasContents: boolean;
+}
+export interface InstallTemplateParams {
+    directory: string;
+    projectName: string;
+    theme: string;
+}
+export declare class TemplateService {
+    private readonly TEMPLATE_URL;
+    private readonly TEMP_ZIP_PATH;
+    private readonly TEMP_EXTRACT_DIR;
+    checkDirectory(directory: string): Promise<DirectoryStatus>;
+    getAvailableThemes(): string[];
+    installTemplate(params: InstallTemplateParams): Promise<void>;
+    private downloadTemplate;
+    private extractTemplate;
+    private copyTemplateFiles;
+    private updateDocsConfig;
+    private cleanup;
+}

package/bin/services/template.service.js

@@ -0,0 +1,127 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { docsConfigSchema } from '@poetora/validation';
+import AdmZip from 'adm-zip';
+import * as fse from 'fs-extra';
+import { ExternalServiceError, FileSystemError } from '../errors/index.js';
+export class TemplateService {
+    TEMPLATE_URL = 'https://github.com/poetora/starter/archive/refs/heads/main.zip';
+    TEMP_ZIP_PATH = 'poetora-starter.zip';
+    TEMP_EXTRACT_DIR = 'poetora-starter-temp';
+    async checkDirectory(directory) {
+        try {
+            await fse.ensureDir(directory);
+            const files = await fs.promises.readdir(directory);
+            const hasContents = files.length > 0;
+            return {
+                exists: true,
+                hasContents,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    exists: false,
+                    hasContents: false,
+                };
+            }
+            throw new FileSystemError(`Failed to check directory: ${error.message}`);
+        }
+    }
+    getAvailableThemes() {
+        const themes = docsConfigSchema.options
+            .map((option) => {
+            const themeField = option.shape?.theme;
+            if (themeField?._def && 'value' in themeField._def) {
+                return themeField._def.value;
+            }
+            return null;
+        })
+            .filter((theme) => theme !== null);
+        return themes.length > 0 ? themes : ['ora'];
+    }
+    async installTemplate(params) {
+        const { directory, projectName, theme } = params;
+        try {
+            await this.downloadTemplate();
+            await this.extractTemplate();
+            await this.copyTemplateFiles(directory);
+            await this.updateDocsConfig(directory, projectName, theme);
+            await this.cleanup();
+        }
+        catch (error) {
+            await this.cleanup();
+            throw error;
+        }
+    }
+    async downloadTemplate() {
+        try {
+            const response = await fetch(this.TEMPLATE_URL);
+            if (!response.ok) {
+                throw new ExternalServiceError(`Failed to download template: HTTP ${response.status} ${response.statusText}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            const buffer = Buffer.from(arrayBuffer);
+            await fs.promises.writeFile(this.TEMP_ZIP_PATH, buffer);
+        }
+        catch (error) {
+            if (error instanceof ExternalServiceError) {
+                throw error;
+            }
+            throw new ExternalServiceError(`Failed to download template: ${error.message}`);
+        }
+    }
+    async extractTemplate() {
+        try {
+            const zip = new AdmZip(this.TEMP_ZIP_PATH);
+            zip.extractAllTo(this.TEMP_EXTRACT_DIR, true);
+        }
+        catch (error) {
+            throw new FileSystemError(`Failed to extract template: ${error.message}`);
+        }
+    }
+    async copyTemplateFiles(targetDir) {
+        try {
+            const extractedFolder = path.join(this.TEMP_EXTRACT_DIR, 'starter-main');
+            await fse.ensureDir(targetDir);
+            await fse.copy(extractedFolder, targetDir, {
+                overwrite: true,
+                errorOnExist: false,
+            });
+        }
+        catch (error) {
+            throw new FileSystemError(`Failed to copy template files: ${error.message}`);
+        }
+    }
+    async updateDocsConfig(directory, projectName, theme) {
+        try {
+            const configPath = path.join(directory, 'docs.json');
+            let config;
+            try {
+                const configContent = await fs.promises.readFile(configPath, 'utf-8');
+                config = JSON.parse(configContent);
+            }
+            catch {
+                config = {};
+            }
+            config.name = projectName;
+            config.theme = theme;
+            await fs.promises.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+        }
+        catch (error) {
+            throw new FileSystemError(`Failed to update docs.json: ${error.message}`);
+        }
+    }
+    async cleanup() {
+        try {
+            await Promise.all([
+                fse.remove(this.TEMP_ZIP_PATH).catch(() => {
+                }),
+                fse.remove(this.TEMP_EXTRACT_DIR).catch(() => {
+                }),
+            ]);
+        }
+        catch {
+        }
+    }
+}

package/bin/services/update.service.d.ts

@@ -0,0 +1,10 @@
+import type { ILogger } from '../utils/index.js';
+import type { VersionService } from './version.service.js';
+export declare class UpdateService {
+    private readonly logger;
+    private readonly versionService;
+    private readonly packageName;
+    constructor(logger: ILogger, versionService: VersionService, packageName: string);
+    update(): Promise<void>;
+    private detectPackageManager;
+}

package/bin/services/update.service.js

@@ -0,0 +1,57 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ExternalServiceError } from '../errors/index.js';
+const execAsync = promisify(exec);
+export class UpdateService {
+    logger;
+    versionService;
+    packageName;
+    constructor(logger, versionService, packageName) {
+        this.logger = logger;
+        this.versionService = versionService;
+        this.packageName = packageName;
+    }
+    async update() {
+        const spinner = this.logger.spinner('checking for updates...');
+        spinner.start();
+        const existingCliVersion = this.versionService.getCliVersion();
+        const latestCliVersion = this.versionService.getLatestCliVersion(this.packageName);
+        const isUpToDate = existingCliVersion &&
+            latestCliVersion &&
+            latestCliVersion.trim() === existingCliVersion.trim();
+        if (isUpToDate) {
+            spinner.succeed('already up to date');
+            return;
+        }
+        if (existingCliVersion && latestCliVersion.trim() !== existingCliVersion.trim()) {
+            try {
+                spinner.stop();
+                const updateSpinner = this.logger.spinner(`updating ${this.packageName} package...`);
+                updateSpinner.start();
+                const packageManager = await this.detectPackageManager();
+                if (packageManager === 'pnpm') {
+                    await execAsync(`pnpm install -g ${this.packageName}@latest --silent`);
+                }
+                else {
+                    await execAsync(`npm install -g ${this.packageName}@latest --silent`);
+                }
+                updateSpinner.succeed(`updated ${this.packageName} to version ${this.logger.highlight?.(latestCliVersion) ?? latestCliVersion}`);
+            }
+            catch (_err) {
+                throw new ExternalServiceError(`failed to update ${this.packageName}@latest`);
+            }
+        }
+    }
+    async detectPackageManager() {
+        try {
+            const { stdout: packagePath } = await execAsync(`which ${this.packageName}`);
+            if (packagePath.includes('pnpm')) {
+                return 'pnpm';
+            }
+            return 'npm';
+        }
+        catch (_error) {
+            return 'npm';
+        }
+    }
+}

package/bin/services/version.service.d.ts

@@ -0,0 +1,16 @@
+import { type NodeVersion, type ValidationResult } from '../types/index.js';
+export declare class VersionService {
+    private readonly packageName;
+    constructor(packageName?: string);
+    parseNodeVersion(): NodeVersion;
+    checkNodeVersion(): ValidationResult;
+    getCliVersion(): string | undefined;
+    getClientVersion(): string;
+    getVersions(): {
+        cli: string | undefined;
+        client: string;
+    };
+    getLatestCliVersion(packageName: string): string;
+    isVersionUpToDate(currentVersion: string, latestVersion: string): boolean;
+    validateNodeVersion(): void;
+}

package/bin/services/version.service.js

@@ -0,0 +1,102 @@
+import { execSync } from 'node:child_process';
+import { getClientVersion, LOCAL_LINKED_CLI_VERSION } from '@poetora/previewing';
+import yargs from 'yargs';
+import { InvalidEnvironmentError } from '../errors/index.js';
+import { CLI_CONSTANTS } from '../types/index.js';
+export class VersionService {
+    packageName;
+    constructor(packageName = 'poet') {
+        this.packageName = packageName;
+    }
+    parseNodeVersion() {
+        let versionString = process.version;
+        if (versionString.charAt(0) === 'v') {
+            versionString = versionString.slice(1);
+        }
+        const parts = versionString.split('.');
+        const major = parseInt(parts[0] ?? '0', 10);
+        const minor = parseInt(parts[1] ?? '0', 10);
+        const patch = parseInt(parts[2] ?? '0', 10);
+        return {
+            major,
+            minor,
+            patch,
+            raw: versionString,
+        };
+    }
+    checkNodeVersion() {
+        const current = this.parseNodeVersion();
+        const { MIN_MAJOR, MIN_MINOR, MAX_MAJOR, RECOMMENDED_MAJOR, RECOMMENDED_MINOR } = CLI_CONSTANTS.NODE_VERSION;
+        if (current.major < MIN_MAJOR || (current.major === MIN_MAJOR && current.minor < MIN_MINOR)) {
+            return {
+                isValid: false,
+                hasWarning: false,
+                message: `${this.packageName} requires Node.js ${MIN_MAJOR}.${MIN_MINOR}.0 or higher (current version ${current.raw}). Please upgrade Node.js and try again.`,
+            };
+        }
+        if (current.major > MAX_MAJOR) {
+            return {
+                isValid: false,
+                hasWarning: false,
+                message: `${this.packageName} is not supported on Node.js ${current.major}.x. Please use an LTS version (${MIN_MAJOR}-${MAX_MAJOR}).`,
+            };
+        }
+        if (current.major < RECOMMENDED_MAJOR ||
+            (current.major === RECOMMENDED_MAJOR && current.minor < RECOMMENDED_MINOR)) {
+            return {
+                isValid: true,
+                hasWarning: true,
+                message: `Node.js ${RECOMMENDED_MAJOR}.${RECOMMENDED_MINOR}.0 or higher is recommended for best compatibility (current: ${current.raw}).`,
+            };
+        }
+        return {
+            isValid: true,
+            hasWarning: false,
+        };
+    }
+    getCliVersion() {
+        if (process.env.CLI_TEST_MODE === 'true') {
+            return 'test-cli';
+        }
+        const y = yargs();
+        let version;
+        y.showVersion((v) => {
+            version = v;
+            return false;
+        });
+        if (version === 'unknown') {
+            version = LOCAL_LINKED_CLI_VERSION;
+        }
+        return version;
+    }
+    getClientVersion() {
+        return getClientVersion().trim();
+    }
+    getVersions() {
+        return {
+            cli: this.getCliVersion(),
+            client: this.getClientVersion(),
+        };
+    }
+    getLatestCliVersion(packageName) {
+        try {
+            const version = execSync(`npm view ${packageName} version --silent`, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            return version;
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch latest version for ${packageName}: ${error instanceof Error ? error.message : 'unknown error'}`);
+        }
+    }
+    isVersionUpToDate(currentVersion, latestVersion) {
+        return currentVersion.trim() === latestVersion.trim();
+    }
+    validateNodeVersion() {
+        const result = this.checkNodeVersion();
+        if (!result.isValid) {
+            throw new InvalidEnvironmentError(result.message ?? 'Unsupported Node.js version');
+        }
+    }
+}

package/bin/types/common.d.ts

@@ -0,0 +1,38 @@
+export declare const CLI_CONSTANTS: {
+    readonly PORT: {
+        readonly DEFAULT: 3000;
+        readonly MAX_ATTEMPTS: 10;
+    };
+    readonly NODE_VERSION: {
+        readonly MIN_MAJOR: 18;
+        readonly MIN_MINOR: 0;
+        readonly MAX_MAJOR: 24;
+        readonly MAX_MINOR: number;
+        readonly RECOMMENDED_MAJOR: 20;
+        readonly RECOMMENDED_MINOR: 17;
+    };
+    readonly TIMEOUT: {
+        readonly PROCESS_KILL: 5000;
+        readonly LOG_RENDER: 50;
+    };
+    readonly UPDATE: {
+        readonly CHECK_INTERVAL: 86400000;
+    };
+};
+export interface NodeVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    raw: string;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    hasWarning: boolean;
+    message?: string;
+}
+export interface LoggerSpinner {
+    start(): void;
+    stop(): void;
+    succeed(message?: string): void;
+    fail(message?: string): void;
+}

package/bin/types/common.js

@@ -0,0 +1,21 @@
+export const CLI_CONSTANTS = {
+    PORT: {
+        DEFAULT: 3000,
+        MAX_ATTEMPTS: 10,
+    },
+    NODE_VERSION: {
+        MIN_MAJOR: 18,
+        MIN_MINOR: 0,
+        MAX_MAJOR: 24,
+        MAX_MINOR: Number.MAX_SAFE_INTEGER,
+        RECOMMENDED_MAJOR: 20,
+        RECOMMENDED_MINOR: 17,
+    },
+    TIMEOUT: {
+        PROCESS_KILL: 5000,
+        LOG_RENDER: 50,
+    },
+    UPDATE: {
+        CHECK_INTERVAL: 86400000,
+    },
+};

package/bin/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './common.js';
+export * from './options.js';

package/bin/types/index.js

@@ -0,0 +1,2 @@
+export * from './common.js';
+export * from './options.js';

package/bin/types/options.d.ts

@@ -0,0 +1,23 @@
+export interface DevOptions {
+    port?: number;
+    open?: boolean;
+    localSchema?: boolean;
+    clientVersion?: string;
+    groups?: string[];
+    disableOpenapi?: boolean;
+}
+export interface InitOptions {
+    directory: string;
+}
+export interface OpenApiCheckOptions {
+    filename: string;
+    localSchema?: boolean;
+}
+export interface RenameOptions {
+    from: string;
+    to: string;
+    force?: boolean;
+}
+export interface UpdateOptions {
+    packageName: string;
+}

package/bin/types/options.js

@@ -0,0 +1 @@
+export {};

package/bin/utils/console-logger.d.ts

@@ -0,0 +1,16 @@
+import type { LoggerSpinner } from '../types/index.js';
+import type { ILogger } from './logger.interface.js';
+export declare class ConsoleLogger implements ILogger {
+    info(message: string): void;
+    success(message: string): void;
+    error(message: string): void;
+    warn(message: string): void;
+    spinner(message: string): LoggerSpinner;
+    log(message: string): void;
+    logColor(message: string, color: 'green' | 'red' | 'yellow' | 'blue' | 'cyan' | 'magenta' | 'gray'): void;
+    logBold(message: string, color?: 'green' | 'red' | 'yellow' | 'blue' | 'cyan' | 'magenta'): void;
+    logSeparator(): void;
+    logNewLine(): void;
+    logHeader(message: string): void;
+    highlight(text: string): string;
+}

package/bin/utils/console-logger.js

@@ -0,0 +1,65 @@
+import chalk from 'chalk';
+import ora from 'ora';
+export class ConsoleLogger {
+    info(message) {
+        console.log(chalk.blue(`ℹ ${message}`));
+    }
+    success(message) {
+        console.log(chalk.green(`✓ ${message}`));
+    }
+    error(message) {
+        console.error(chalk.red(`✗ ${message}`));
+    }
+    warn(message) {
+        console.warn(chalk.yellow(`⚠ ${message}`));
+    }
+    spinner(message) {
+        return new ConsoleSpinner(message);
+    }
+    log(message) {
+        console.log(message);
+    }
+    logColor(message, color) {
+        console.log(chalk[color](message));
+    }
+    logBold(message, color) {
+        if (color) {
+            console.log(chalk[color].bold(message));
+        }
+        else {
+            console.log(chalk.bold(message));
+        }
+    }
+    logSeparator() {
+        console.log(chalk.gray('─'.repeat(50)));
+    }
+    logNewLine() {
+        console.log();
+    }
+    logHeader(message) {
+        console.log();
+        console.log(chalk.bold.cyan(message));
+        console.log();
+    }
+    highlight(text) {
+        return chalk.yellow(text);
+    }
+}
+class ConsoleSpinner {
+    spinner;
+    constructor(message) {
+        this.spinner = ora(message);
+    }
+    start() {
+        this.spinner.start();
+    }
+    stop() {
+        this.spinner.stop();
+    }
+    succeed(message) {
+        this.spinner.succeed(message);
+    }
+    fail(message) {
+        this.spinner.fail(message);
+    }
+}

package/bin/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './console-logger.js';
+export * from './logger.interface.js';

package/bin/utils/index.js

@@ -0,0 +1,2 @@
+export * from './console-logger.js';
+export * from './logger.interface.js';

package/bin/utils/logger.interface.d.ts

@@ -0,0 +1,15 @@
+import type { LoggerSpinner } from '../types/index.js';
+export interface ILogger {
+    info(message: string): void;
+    success(message: string): void;
+    error(message: string): void;
+    warn(message: string): void;
+    spinner(message: string): LoggerSpinner;
+    log(message: string): void;
+    logColor(message: string, color: 'green' | 'red' | 'yellow' | 'blue' | 'cyan' | 'magenta' | 'gray'): void;
+    logBold(message: string, color?: 'green' | 'red' | 'yellow' | 'blue' | 'cyan' | 'magenta'): void;
+    logSeparator(): void;
+    logNewLine(): void;
+    logHeader(message: string): void;
+    highlight?(text: string): string;
+}

package/bin/utils/logger.interface.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poetora/cli",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "The CLI for Poetora documentation Engine",
   "engines": {
     "node": ">=18.0.0"
@@ -25,41 +25,29 @@
     "poet": "bin/index.js",
     "poetora": "bin/index.js"
   },
-  "scripts": {
-    "dev": "pnpm build && NODE_NO_WARNINGS=1 node bin/index.js",
-    "build": "tsc --project tsconfig.build.json",
-    "clean:build": "rimraf bin",
-    "clean:all": "rimraf node_modules .eslintcache && pnpm clean:build",
-    "watch": "tsc --watch",
-    "test": "vitest run",
-    "type": "tsc --noEmit",
-    "format": "prettier . --write",
-    "format:check": "prettier . --check"
-  },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@poetora/link-rot": "workspace:*",
-    "@poetora/prebuild": "workspace:*",
-    "@poetora/previewing": "workspace:*",
-    "@poetora/shared": "workspace:*",
-    "@poetora/validation": "workspace:*",
     "adm-zip": "0.5.16",
     "chalk": "5.2.0",
     "color": "4.2.3",
     "detect-port": "1.5.1",
     "front-matter": "4.0.2",
     "fs-extra": "11.2.0",
-    "ink": "6.3.0",
     "inquirer": "12.3.0",
     "js-yaml": "4.1.0",
     "mdast-util-mdx-jsx": "3.2.0",
+    "ora": "^9.0.0",
     "react": "19.2.1",
     "semver": "7.7.2",
     "unist-util-visit": "5.0.0",
-    "yargs": "17.7.1"
+    "yargs": "17.7.1",
+    "@poetora/prebuild": "0.1.0",
+    "@poetora/link-rot": "0.0.1",
+    "@poetora/shared": "0.1.0",
+    "@poetora/previewing": "0.1.0",
+    "@poetora/validation": "0.1.0"
   },
   "devDependencies": {
-    "@trivago/prettier-plugin-sort-imports": "4.3.0",
     "@tsconfig/recommended": "1.0.2",
     "@types/adm-zip": "0.5.7",
     "@types/color": "^3.0.3",
@@ -67,17 +55,29 @@
     "@types/fs-extra": "^9.0.13",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "4.0.4",
-    "@types/node": "catalog:",
+    "@types/node": "22.19.2",
     "@types/yargs": "17.0.22",
-    "@typescript-eslint/eslint-plugin": "catalog:",
-    "@typescript-eslint/parser": "catalog:",
-    "eslint": "catalog:",
-    "eslint-config-prettier": "catalog:",
+    "@typescript-eslint/eslint-plugin": "8.49.0",
+    "@typescript-eslint/parser": "8.49.0",
+    "eslint": "9.39.1",
+    "eslint-config-prettier": "10.1.2",
     "openapi-types": "12.1.3",
-    "prettier": "3.1.1",
     "rimraf": "5.0.1",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
+    "typescript": "5.9.3",
+    "vitest": "4.0.15",
     "vitest-mock-process": "1.0.4"
+  },
+  "scripts": {
+    "dev": "pnpm build && NODE_NO_WARNINGS=1 node bin/index.js",
+    "build": "tsc --project tsconfig.build.json",
+    "clean:build": "rimraf bin",
+    "clean:all": "rimraf node_modules .eslintcache && pnpm clean:build",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "type": "tsc --noEmit",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "lint:biome": "biome lint .",
+    "check": "biome check --write ."
   }
-}
+}