@poetora/cli 0.1.9 → 0.1.10

package/src/services/accessibility-check.service.ts

@@ -1,226 +0,0 @@
-import { getConfigObj, getConfigPath } from '@poetora/prebuild';
-import { getBackgroundColors } from '@poetora/shared';
-import path from 'path';
-import {
-  type AccessibilityCheckResult,
-  type ContrastResult,
-  checkDocsColors,
-} from '../accessibility.js';
-import { CMD_EXEC_PATH } from '../constants.js';
-import { type AccessibilityFixAttribute, checkMdxAccessibility } from '../mdxAccessibility.js';
-import { ConsoleLogger } from '../utils/console-logger.js';
-import type { ILogger } from '../utils/logger.interface.js';
-
-/**
- * Service for accessibility checking
- */
-export class AccessibilityCheckService {
-  constructor(private readonly logger: ILogger = new ConsoleLogger()) {}
-
-  /**
-   * Display contrast result with color-coded output
-   */
-  private displayContrastResult(
-    result: ContrastResult | null,
-    label: string,
-    prefix: string = ''
-  ): void {
-    if (!result) return;
-
-    const { recommendation } = result;
-
-    // Custom messages with our own tone
-    let statusText: string;
-    let detailMessage: string;
-
-    if (recommendation === 'pass') {
-      if (result.meetsAAA) {
-        statusText = '✓ Excellent';
-        detailMessage = `ratio ${result.ratio.toFixed(2)}:1 (AAA standard)`;
-      } else {
-        statusText = '✓ Good';
-        detailMessage = `ratio ${result.ratio.toFixed(2)}:1 (AA standard)`;
-      }
-    } else if (recommendation === 'warning') {
-      statusText = '⚠ Acceptable';
-      detailMessage = `ratio ${result.ratio.toFixed(2)}:1 (consider improving)`;
-    } else {
-      statusText = '✗ Poor';
-      detailMessage = `ratio ${result.ratio.toFixed(2)}:1 (below AA standard)`;
-    }
-
-    // Display with label in cyan and status+message in appropriate color
-    const labelText = `${prefix}${label}:`;
-    const statusColor =
-      recommendation === 'pass' ? 'green' : recommendation === 'warning' ? 'yellow' : 'red';
-
-    this.logger.log(`${labelText} ${this.colorize(statusText, statusColor)} ${detailMessage}`);
-  }
-
-  private colorize(text: string, color: 'green' | 'yellow' | 'red'): string {
-    // Use chalk directly for inline coloring
-    const chalk = (text: string, color: 'green' | 'yellow' | 'red') => {
-      const colors: Record<string, string> = {
-        green: '\x1b[32m',
-        yellow: '\x1b[33m',
-        red: '\x1b[31m',
-        reset: '\x1b[0m',
-      };
-      return `${colors[color]}${text}${colors.reset}`;
-    };
-    return chalk(text, color);
-  }
-
-  /**
-   * Check color contrast accessibility
-   */
-  private async checkColorAccessibility(): /* prettier-ignore */ Promise<number> {
-    try {
-      const docsConfigPath = await getConfigPath(CMD_EXEC_PATH);
-
-      if (!docsConfigPath) {
-        this.logger.error(
-          'No configuration file found. Please run this command from a directory with a docs.json file.'
-        );
-        return 1;
-      }
-
-      const config = await getConfigObj(CMD_EXEC_PATH);
-
-      if (!config?.colors) {
-        this.logger.warn('No colors section found in configuration file');
-        return 0;
-      }
-
-      const { colors, navigation } = config;
-      const { lightHex, darkHex } = getBackgroundColors(config);
-
-      const results: AccessibilityCheckResult = checkDocsColors(
-        colors,
-        { lightHex, darkHex },
-        navigation
-      );
-
-      this.logger.log('Checking color accessibility...');
-
-      this.displayContrastResult(
-        results.primaryContrast,
-        `Primary Color (${colors.primary}) vs Light Background`
-      );
-      this.displayContrastResult(
-        results.lightContrast,
-        `Light Color (${colors.light}) vs Dark Background`
-      );
-      this.displayContrastResult(
-        results.darkContrast,
-        `Dark Color (${colors.dark}) vs Dark Background`
-      );
-      this.displayContrastResult(
-        results.darkOnLightContrast,
-        `Dark Color (${colors.dark}) vs Light Background`
-      );
-
-      const anchorsWithResults = results.anchorResults.filter(
-        (anchor) => anchor.lightContrast || anchor.darkContrast
-      );
-
-      if (anchorsWithResults.length > 0) {
-        for (const anchor of anchorsWithResults) {
-          this.displayContrastResult(anchor.lightContrast, `${anchor.name} vs Light Background`);
-          this.displayContrastResult(anchor.darkContrast, `${anchor.name} vs Dark Background`);
-        }
-      }
-
-      // Overall assessment with custom messages
-      let overallDisplay: string;
-      if (results.overallScore === 'fail') {
-        overallDisplay =
-          this.colorize('✗ Action needed:', 'red') +
-          ' Update colors to meet accessibility standards';
-      } else if (results.overallScore === 'warning') {
-        overallDisplay = `${this.colorize('⚠ Room for improvement:', 'yellow')} Consider enhancing color contrast`;
-      } else {
-        overallDisplay = `${this.colorize('✓ All good:', 'green')} Colors meet accessibility guidelines`;
-      }
-
-      this.logger.logNewLine();
-      this.logger.log(overallDisplay);
-
-      return results.overallScore === 'fail' ? 1 : 0;
-    } catch (error) {
-      this.logger.error(`Failed to check color accessibility: ${error}`);
-      return 1;
-    }
-  }
-
-  /**
-   * Check MDX files for accessibility issues
-   */
-  private async checkMdxAccessibility(): /* prettier-ignore */ Promise<number> {
-    try {
-      this.logger.log('Checking mdx files for accessibility issues...');
-
-      const results = await checkMdxAccessibility();
-
-      if (results.missingAltAttributes.length === 0) {
-        this.logger.success('no accessibility issues found');
-        this.logger.info(
-          `Checked ${results.totalFiles} MDX files - all images and videos have alt attributes.`
-        );
-        return 0;
-      }
-
-      const issuesByFile: Record<string, AccessibilityFixAttribute[]> = {};
-      results.missingAltAttributes.forEach((issue) => {
-        if (!issuesByFile[issue.filePath]) {
-          issuesByFile[issue.filePath] = [];
-        }
-        issuesByFile[issue.filePath]?.push(issue);
-      });
-
-      this.logger.log(
-        `Found ${this.logger.highlight?.(results.missingAltAttributes.length.toString()) ?? results.missingAltAttributes.length} accessibility issue${results.missingAltAttributes.length === 1 ? '' : 's'} in ${this.logger.highlight?.(results.filesWithIssues.toString()) ?? results.filesWithIssues} file${results.filesWithIssues === 1 ? '' : 's'}:`
-      );
-
-      for (const [filePath, issues] of Object.entries(issuesByFile)) {
-        const relativePath = path.relative(process.cwd(), filePath);
-        this.logger.log(`${relativePath}:`);
-
-        for (const issue of issues) {
-          const location =
-            issue.line && issue.column ? ` (line ${issue.line}, col ${issue.column})` : '';
-          if (issue.element === 'a') {
-            this.logger.logColor(
-              ` ✗ Missing text attribute ${issue.tagName} element${location}`,
-              'red'
-            );
-          } else {
-            this.logger.logColor(
-              ` ✗ Missing alt attribute on ${issue.tagName} element${location}`,
-              'red'
-            );
-          }
-        }
-      }
-
-      this.logger.warn(
-        'Recommendation: Add alt attributes to all images and videos for better accessibility.'
-      );
-
-      return 1;
-    } catch (error) {
-      this.logger.error(`Failed to check MDX accessibility: ${error}`);
-      return 1;
-    }
-  }
-
-  /**
-   * Run accessibility checks on documentation
-   * @returns Exit code (0 for success, 1 for failure)
-   */
-  async checkAccessibility(): /* prettier-ignore */ Promise<number> {
-    const colorCheckCode = await this.checkColorAccessibility();
-    const mdxCheckCode = await this.checkMdxAccessibility();
-    return colorCheckCode || mdxCheckCode;
-  }
-}

package/src/services/index.ts

@@ -1,7 +0,0 @@
-export * from './accessibility-check.service.js';
-export * from './link.service.js';
-export * from './openapi-check.service.js';
-export * from './port.service.js';
-export * from './template.service.js';
-export * from './update.service.js';
-export * from './version.service.js';

package/src/services/link.service.ts

@@ -1,65 +0,0 @@
-import {
-  getBrokenInternalLinks,
-  type MdxPath,
-  renameFilesAndUpdateLinksInContent,
-} from '@poetora/link-rot';
-import * as path from 'path';
-
-import type { ILogger } from '../utils/index.js';
-
-/**
- * Service for link management
- */
-export class LinkService {
-  constructor(private readonly logger: ILogger) {}
-
-  /**
-   * Check for broken internal links
-   * @returns Broken links grouped by file
-   */
-  async checkBrokenLinks(): Promise<Record<string, string[]>> {
-    const brokenLinks = await getBrokenInternalLinks();
-
-    if (brokenLinks.length === 0) {
-      this.logger.success('no broken links found');
-      return {};
-    }
-
-    // Group broken links by file
-    const brokenLinksByFile: Record<string, string[]> = {};
-    brokenLinks.forEach((mdxPath: MdxPath) => {
-      const filename = path.join(mdxPath.relativeDir, mdxPath.filename);
-      const brokenLinksForFile = brokenLinksByFile[filename];
-      if (brokenLinksForFile) {
-        brokenLinksForFile.push(mdxPath.originalPath);
-      } else {
-        brokenLinksByFile[filename] = [mdxPath.originalPath];
-      }
-    });
-
-    // Display broken links with highlighted numbers
-    const fileCount = Object.keys(brokenLinksByFile).length;
-    this.logger.log(
-      `found ${this.logger.highlight?.(brokenLinks.length.toString()) ?? brokenLinks.length} broken link${brokenLinks.length === 1 ? '' : 's'} in ${this.logger.highlight?.(fileCount.toString()) ?? fileCount} file${fileCount === 1 ? '' : 's'}`
-    );
-    this.logger.logNewLine();
-
-    for (const [filename, links] of Object.entries(brokenLinksByFile)) {
-      // Underline filename for better visibility
-      this.logger.logColor(filename, 'cyan');
-      links.forEach((link) => {
-        this.logger.logColor(` ⎿  ${link}`, 'gray');
-      });
-      this.logger.logNewLine();
-    }
-
-    return brokenLinksByFile;
-  }
-
-  /**
-   * Rename a file and update all internal link references
-   */
-  async renameFile(from: string, to: string, force: boolean = false): Promise<void> {
-    await renameFilesAndUpdateLinksInContent(from, to, force);
-  }
-}

package/src/services/openapi-check.service.ts

@@ -1,68 +0,0 @@
-import { getOpenApiDocumentFromUrl, isAllowedLocalSchemaUrl, validate } from '@poetora/shared';
-import * as fs from 'fs';
-import * as yaml from 'js-yaml';
-
-import { FileSystemError, ValidationError } from '../errors/index.js';
-import type { ILogger } from '../utils/index.js';
-
-/**
- * Service for OpenAPI validation
- */
-export class OpenApiCheckService {
-  constructor(private readonly logger: ILogger) {}
-
-  /**
-   * Validate OpenAPI spec from URL or local file
-   */
-  async validateSpec(filename: string, localSchema: boolean = false): Promise<void> {
-    // Check if it's a URL
-    if (isAllowedLocalSchemaUrl(filename, localSchema)) {
-      await getOpenApiDocumentFromUrl(filename);
-      this.logger.success('OpenAPI definition is valid.');
-      return;
-    }
-
-    // Warn for http:// URLs without --local-schema
-    if (filename.startsWith('http://') && !localSchema) {
-      this.logger.warn('include the --local-schema flag to check locally hosted OpenAPI files');
-      this.logger.warn('only https protocol is supported in production');
-      return;
-    }
-
-    // Read and validate local file
-    const document = await this.readLocalOpenApiFile(filename);
-
-    if (!document) {
-      throw new ValidationError(
-        'failed to parse OpenAPI spec: could not parse file correctly, please check for any syntax errors.'
-      );
-    }
-
-    await validate(document);
-    this.logger.success('OpenAPI definition is valid.');
-  }
-
-  /**
-   * Read OpenAPI file from local filesystem
-   */
-  private async readLocalOpenApiFile(filename: string): Promise<unknown> {
-    try {
-      const fileContents = await fs.promises.readFile(filename, 'utf-8');
-
-      // Try to parse as JSON first
-      if (filename.endsWith('.json')) {
-        return JSON.parse(fileContents);
-      }
-
-      // Try YAML parsing
-      return yaml.load(fileContents);
-    } catch (error) {
-      if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
-        throw new FileSystemError(`file not found, please check the path provided: ${filename}`);
-      }
-      throw new ValidationError(
-        `Failed to parse OpenAPI spec: ${error instanceof Error ? error.message : 'unknown error'}`
-      );
-    }
-  }
-}

package/src/services/port.service.ts

@@ -1,47 +0,0 @@
-import detect from 'detect-port';
-
-import { NoAvailablePortError } from '../errors/index.js';
-import { CLI_CONSTANTS } from '../types/index.js';
-import type { ILogger } from '../utils/index.js';
-
-/**
- * Service for handling port detection and availability checks
- */
-export class PortService {
-  constructor(private readonly logger?: ILogger) {}
-
-  /**
-   * Find an available port starting from the preferred port
-   * @param preferredPort - The preferred port to start from (defaults to 3000)
-   * @returns The first available port found
-   * @throws {NoAvailablePortError} if no port is available after MAX_ATTEMPTS tries
-   */
-  async findAvailablePort(preferredPort?: number): Promise<number> {
-    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}`
-    );
-  }
-
-  /**
-   * Check if a specific port is available
-   * @param port - The port number to check
-   * @returns true if the port is available, false otherwise
-   */
-  private async isPortAvailable(port: number): Promise<boolean> {
-    const detectedPort = await detect(port);
-    return detectedPort === port;
-  }
-}

package/src/services/template.service.ts

@@ -1,203 +0,0 @@
-import { docsConfigSchema } from '@poetora/validation';
-import AdmZip from 'adm-zip';
-import * as fs from 'fs';
-import * as fse from 'fs-extra';
-import * as path from 'path';
-
-import { ExternalServiceError, FileSystemError } from '../errors/index.js';
-
-export interface DirectoryStatus {
-  exists: boolean;
-  hasContents: boolean;
-}
-
-export interface InstallTemplateParams {
-  directory: string;
-  projectName: string;
-  theme: string;
-}
-
-interface DocsConfig {
-  name: string;
-  theme: string;
-  [key: string]: unknown;
-}
-
-/**
- * Service for managing documentation templates
- */
-export class TemplateService {
-  private readonly TEMPLATE_URL = 'https://github.com/poetora/starter/archive/refs/heads/main.zip';
-  private readonly TEMP_ZIP_PATH = 'poetora-starter.zip';
-  private readonly TEMP_EXTRACT_DIR = 'poetora-starter-temp';
-
-  /**
-   * Check if directory exists and has contents
-   */
-  async checkDirectory(directory: string): Promise<DirectoryStatus> {
-    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 as NodeJS.ErrnoException).code === 'ENOENT') {
-        return {
-          exists: false,
-          hasContents: false,
-        };
-      }
-      throw new FileSystemError(`Failed to check directory: ${(error as Error).message}`);
-    }
-  }
-
-  /**
-   * Get available themes from validation package
-   */
-  getAvailableThemes(): string[] {
-    // docsConfigSchema is a discriminated union with 'theme' as the discriminator
-    // Extract theme values from each option's shape.theme field
-    const themes = docsConfigSchema.options
-      .map((option) => {
-        // Each option has a shape with theme field (ZodLiteral)
-        const themeField = (
-          option as unknown as { shape?: { theme?: { _def?: { value?: string } } } }
-        ).shape?.theme;
-        if (themeField?._def && 'value' in themeField._def) {
-          return themeField._def.value as string;
-        }
-        return null;
-      })
-      .filter((theme): theme is string => theme !== null);
-
-    return themes.length > 0 ? themes : ['ora'];
-  }
-
-  /**
-   * Download and install template to target directory
-   */
-  async installTemplate(params: InstallTemplateParams): Promise<void> {
-    const { directory, projectName, theme } = params;
-
-    try {
-      // Download template
-      await this.downloadTemplate();
-
-      // Extract template
-      await this.extractTemplate();
-
-      // Copy files to target directory
-      await this.copyTemplateFiles(directory);
-
-      // Update configuration
-      await this.updateDocsConfig(directory, projectName, theme);
-
-      // Cleanup temporary files
-      await this.cleanup();
-    } catch (error) {
-      // Ensure cleanup on error
-      await this.cleanup();
-      throw error;
-    }
-  }
-
-  private async downloadTemplate(): Promise<void> {
-    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 as Error).message}`);
-    }
-  }
-
-  private async extractTemplate(): Promise<void> {
-    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 as Error).message}`);
-    }
-  }
-
-  private async copyTemplateFiles(targetDir: string): Promise<void> {
-    try {
-      // The extracted folder is typically named "starter-main"
-      const extractedFolder = path.join(this.TEMP_EXTRACT_DIR, 'starter-main');
-
-      // Ensure target directory exists
-      await fse.ensureDir(targetDir);
-
-      // Copy all files from extracted folder to target directory
-      await fse.copy(extractedFolder, targetDir, {
-        overwrite: true,
-        errorOnExist: false,
-      });
-    } catch (error) {
-      throw new FileSystemError(`Failed to copy template files: ${(error as Error).message}`);
-    }
-  }
-
-  private async updateDocsConfig(
-    directory: string,
-    projectName: string,
-    theme: string
-  ): Promise<void> {
-    try {
-      const configPath = path.join(directory, 'docs.json');
-
-      let config: DocsConfig;
-
-      // Try to read existing config
-      try {
-        const configContent = await fs.promises.readFile(configPath, 'utf-8');
-        config = JSON.parse(configContent) as DocsConfig;
-      } catch {
-        // If file doesn't exist or is invalid, create new config
-        config = {} as DocsConfig;
-      }
-
-      // Update config with user choices
-      config.name = projectName;
-      config.theme = theme;
-
-      // Write updated config
-      await fs.promises.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
-    } catch (error) {
-      throw new FileSystemError(`Failed to update docs.json: ${(error as Error).message}`);
-    }
-  }
-
-  private async cleanup(): Promise<void> {
-    try {
-      // Remove temporary files
-      await Promise.all([
-        fse.remove(this.TEMP_ZIP_PATH).catch(() => {
-          /* ignore */
-        }),
-        fse.remove(this.TEMP_EXTRACT_DIR).catch(() => {
-          /* ignore */
-        }),
-      ]);
-    } catch {
-      // Ignore cleanup errors
-    }
-  }
-}

package/src/services/update.service.ts

@@ -1,76 +0,0 @@
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import { ExternalServiceError } from '../errors/index.js';
-import type { ILogger } from '../utils/index.js';
-import type { VersionService } from './version.service.js';
-
-const execAsync = promisify(exec);
-
-/**
- * Service for CLI updates
- */
-export class UpdateService {
-  constructor(
-    private readonly logger: ILogger,
-    private readonly versionService: VersionService,
-    private readonly packageName: string
-  ) {}
-
-  /**
-   * Update CLI to latest version
-   */
-  async update(): Promise<void> {
-    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`);
-      }
-    }
-  }
-
-  /**
-   * Detect which package manager was used to install the CLI
-   */
-  private async detectPackageManager(): Promise<'npm' | 'pnpm'> {
-    try {
-      const { stdout: packagePath } = await execAsync(`which ${this.packageName}`);
-      if (packagePath.includes('pnpm')) {
-        return 'pnpm';
-      }
-      return 'npm';
-    } catch (_error) {
-      return 'npm';
-    }
-  }
-}