@poetora/cli 0.0.1 → 0.1.3

package/src/commands/__tests__/init.command.test.ts

@@ -0,0 +1,281 @@
+import { input, select } from '@inquirer/prompts';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ValidationError } from '../../errors/index.js';
+import type { TemplateService } from '../../services/template.service.js';
+import type { InitOptions } from '../../types/index.js';
+import type { ILogger } from '../../utils/index.js';
+import { InitCommand } from '../init.command.js';
+
+vi.mock('@inquirer/prompts');
+
+describe('InitCommand', () => {
+  let command: InitCommand;
+  let mockLogger: ILogger;
+  let mockTemplateService: TemplateService;
+
+  beforeEach(() => {
+    mockLogger = {
+      info: vi.fn(),
+      success: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      spinner: vi.fn().mockReturnValue({
+        start: vi.fn(),
+        succeed: vi.fn(),
+        fail: vi.fn(),
+        stop: vi.fn(),
+      }),
+      log: vi.fn(),
+      logColor: vi.fn(),
+      logBold: vi.fn(),
+      logSeparator: vi.fn(),
+      logNewLine: vi.fn(),
+      logHeader: vi.fn(),
+    };
+
+    mockTemplateService = {
+      checkDirectory: vi.fn(),
+      getAvailableThemes: vi.fn(),
+      installTemplate: vi.fn(),
+    } as unknown as TemplateService;
+
+    command = new InitCommand(mockLogger, mockTemplateService);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('run - empty directory', () => {
+    beforeEach(() => {
+      vi.mocked(mockTemplateService.checkDirectory).mockResolvedValue({
+        exists: true,
+        hasContents: false,
+      });
+
+      vi.mocked(mockTemplateService.getAvailableThemes).mockReturnValue(['ora', 'sol']);
+
+      vi.mocked(input).mockResolvedValue('My Project');
+      vi.mocked(select).mockResolvedValue('ora');
+      vi.mocked(mockTemplateService.installTemplate).mockResolvedValue(undefined);
+    });
+
+    it('should install template directly for empty directory', async () => {
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await command.run(options);
+
+      expect(mockTemplateService.checkDirectory).toHaveBeenCalledWith('.');
+      expect(input).toHaveBeenCalled();
+      expect(select).toHaveBeenCalled();
+      expect(mockTemplateService.installTemplate).toHaveBeenCalledWith({
+        directory: '.',
+        projectName: 'My Project',
+        theme: 'ora',
+      });
+      expect(mockLogger.success).toHaveBeenCalledWith('Documentation Setup!');
+    });
+
+    it('should use directory name as default project name', async () => {
+      vi.mocked(input).mockResolvedValue('my-docs');
+
+      const options: InitOptions = {
+        directory: 'my-docs',
+      };
+
+      await command.run(options);
+
+      expect(input).toHaveBeenCalledWith({
+        message: 'Project Name',
+        default: 'my-docs',
+      });
+    });
+
+    it('should use "Poetora" as default for current directory', async () => {
+      vi.mocked(input).mockResolvedValue('Poetora');
+
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await command.run(options);
+
+      expect(input).toHaveBeenCalledWith({
+        message: 'Project Name',
+        default: 'Poetora',
+      });
+    });
+  });
+
+  describe('run - non-empty directory', () => {
+    beforeEach(() => {
+      vi.mocked(mockTemplateService.checkDirectory).mockResolvedValue({
+        exists: true,
+        hasContents: true,
+      });
+
+      vi.mocked(mockTemplateService.getAvailableThemes).mockReturnValue(['quartz']);
+      vi.mocked(input).mockResolvedValue('My Project');
+      vi.mocked(mockTemplateService.installTemplate).mockResolvedValue(undefined);
+    });
+
+    it('should cancel installation when user chooses cancel', async () => {
+      vi.mocked(select).mockResolvedValueOnce('cancel');
+
+      const options: InitOptions = {
+        directory: 'existing-dir',
+      };
+
+      await command.run(options);
+
+      expect(mockLogger.info).toHaveBeenCalledWith('Installation cancelled');
+      expect(mockTemplateService.installTemplate).not.toHaveBeenCalled();
+    });
+
+    it('should overwrite when user chooses overwrite', async () => {
+      vi.mocked(select)
+        .mockResolvedValueOnce('overwrite') // directory choice
+        .mockResolvedValueOnce('ora'); // theme choice
+
+      const options: InitOptions = {
+        directory: 'existing-dir',
+      };
+
+      await command.run(options);
+
+      expect(mockTemplateService.installTemplate).toHaveBeenCalledWith({
+        directory: 'existing-dir',
+        projectName: 'My Project',
+        theme: 'ora',
+      });
+    });
+
+    it('should create subdirectory when user chooses subdir', async () => {
+      vi.mocked(select)
+        .mockResolvedValueOnce('subdir') // directory choice
+        .mockResolvedValueOnce('ora'); // theme choice
+
+      vi.mocked(input)
+        .mockResolvedValueOnce('docs') // subdirectory name
+        .mockResolvedValueOnce('My Project'); // project name
+
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await command.run(options);
+
+      expect(input).toHaveBeenCalledWith({
+        message: 'Subdirectory name:',
+        default: 'docs',
+      });
+
+      expect(mockTemplateService.installTemplate).toHaveBeenCalledWith({
+        directory: 'docs',
+        projectName: 'My Project',
+        theme: 'ora',
+      });
+    });
+
+    it('should combine parent dir with subdir when not current directory', async () => {
+      vi.mocked(select).mockResolvedValueOnce('subdir').mockResolvedValueOnce('ora');
+
+      vi.mocked(input).mockResolvedValueOnce('docs').mockResolvedValueOnce('My Project');
+
+      const options: InitOptions = {
+        directory: 'parent',
+      };
+
+      await command.run(options);
+
+      expect(mockTemplateService.installTemplate).toHaveBeenCalledWith({
+        directory: 'parent/docs',
+        projectName: 'My Project',
+        theme: 'ora',
+      });
+    });
+
+    it('should throw ValidationError for empty subdirectory name', async () => {
+      vi.mocked(select).mockResolvedValue('subdir');
+      vi.mocked(input).mockResolvedValue('   '); // empty with spaces
+
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await expect(command.run(options)).rejects.toThrow(ValidationError);
+      await expect(command.run(options)).rejects.toThrow('Subdirectory name cannot be empty');
+    });
+  });
+
+  describe('theme selection', () => {
+    beforeEach(() => {
+      vi.mocked(mockTemplateService.checkDirectory).mockResolvedValue({
+        exists: true,
+        hasContents: false,
+      });
+
+      vi.mocked(input).mockResolvedValue('My Project');
+      vi.mocked(mockTemplateService.installTemplate).mockResolvedValue(undefined);
+    });
+
+    it('should display all available themes', async () => {
+      vi.mocked(mockTemplateService.getAvailableThemes).mockReturnValue(['ora', 'sol', 'custom']);
+
+      vi.mocked(select).mockResolvedValue('sol');
+
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await command.run(options);
+
+      expect(select).toHaveBeenCalledWith({
+        message: 'Theme',
+        choices: [
+          { name: 'ora', value: 'ora' },
+          { name: 'sol', value: 'sol' },
+          { name: 'custom', value: 'custom' },
+        ],
+      });
+    });
+  });
+
+  describe('onboarding message', () => {
+    beforeEach(() => {
+      vi.mocked(mockTemplateService.checkDirectory).mockResolvedValue({
+        exists: true,
+        hasContents: false,
+      });
+
+      vi.mocked(mockTemplateService.getAvailableThemes).mockReturnValue(['ora']);
+      vi.mocked(input).mockResolvedValue('My Project');
+      vi.mocked(select).mockResolvedValue('ora');
+      vi.mocked(mockTemplateService.installTemplate).mockResolvedValue(undefined);
+    });
+
+    it('should show cd command for subdirectory installation', async () => {
+      const options: InitOptions = {
+        directory: 'docs',
+      };
+
+      await command.run(options);
+
+      expect(mockLogger.log).toHaveBeenCalledWith('  cd docs');
+      expect(mockLogger.log).toHaveBeenCalledWith('  poet dev');
+    });
+
+    it('should not show cd command for current directory', async () => {
+      const options: InitOptions = {
+        directory: '.',
+      };
+
+      await command.run(options);
+
+      expect(mockLogger.log).not.toHaveBeenCalledWith(expect.stringContaining('cd'));
+      expect(mockLogger.log).toHaveBeenCalledWith('  poet dev');
+    });
+  });
+});

package/{__test__ → src/commands/__tests__}/utils.ts

@@ -1,4 +1,4 @@
-import { cli } from '../src/cli';
+import { cli } from '../../cli';
 
 /**
  * Programmatically set arguments and execute the CLI script

package/src/commands/base.command.ts

@@ -0,0 +1,97 @@
+import { CliError } from '../errors/index.js';
+import type { ILogger } from '../utils/index.js';
+
+/**
+ * Base abstract class for all CLI commands
+ * Implements Template Method pattern for consistent command execution flow
+ */
+export abstract class BaseCommand<TOptions = unknown, TResult = void> {
+  /**
+   * Command name (e.g., 'dev', 'init', 'check')
+   */
+  abstract readonly name: string;
+
+  /**
+   * Command description for help text
+   */
+  abstract readonly description: string;
+
+  constructor(
+    protected readonly logger: ILogger,
+    protected readonly packageName: string = 'poet'
+  ) {}
+
+  /**
+   * Template method that orchestrates command execution
+   * This is the main entry point called by the CLI framework
+   */
+  /* prettier-ignore */
+  async run(options: TOptions): Promise<TResult> {
+    try {
+      // 1. Validate input options
+      await this.validate(options);
+
+      // 2. Execute command logic
+      const result = await this.execute(options);
+
+      // 3. Return result
+      return result;
+    } catch (error) {
+      // 4. Handle errors consistently
+      this.handleError(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Validate command options before execution
+   * Override this method to add custom validation logic
+   * @param options - Command options to validate
+   * @throws {ValidationError} if validation fails
+   */
+  // prettier-ignore
+  protected async validate(_options: TOptions): Promise<void> {
+    // Default: no validation
+    // Subclasses can override to add validation
+  }
+
+  /**
+   * Execute the main command logic
+   * This method must be implemented by all command subclasses
+   * @param options - Validated command options
+   * @returns Command execution result
+   */
+  protected abstract execute(options: TOptions): Promise<TResult>;
+
+  /**
+   * Handle errors that occur during command execution
+   * Can be overridden to provide custom error handling
+   * @param error - The error to handle
+   */
+  protected handleError(error: unknown): void {
+    if (error instanceof CliError) {
+      // CLI-specific errors with user-friendly messages
+      this.logger.error(error.message);
+    } else if (error instanceof Error) {
+      // Generic errors
+      this.logger.error(error.message);
+
+      // In debug mode, show stack trace
+      if (process.env.DEBUG === 'true') {
+        console.error(error.stack);
+      }
+    } else {
+      // Unknown error types
+      this.logger.error('An unexpected error occurred');
+      console.error(error);
+    }
+  }
+
+  /**
+   * Exit the process with given code
+   * Separated for easier testing (can be mocked)
+   */
+  protected exit(code: number): never {
+    process.exit(code);
+  }
+}

package/src/commands/check.command.ts

@@ -0,0 +1,40 @@
+import type { AccessibilityCheckService, OpenApiCheckService } from '../services/index.js';
+import type { OpenApiCheckOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+
+/**
+ * Check command - Validate OpenAPI specs and accessibility
+ */
+export class CheckCommand extends BaseCommand {
+  readonly name = 'check';
+  readonly description = 'check OpenAPI specs or accessibility';
+
+  constructor(
+    logger: ILogger,
+    private readonly openApiCheckService: OpenApiCheckService,
+    private readonly accessibilityCheckService: AccessibilityCheckService,
+    packageName: string = 'poet'
+  ) {
+    super(logger, packageName);
+  }
+
+  /**
+   * Execute OpenAPI check
+   */
+  async checkOpenApi(options: OpenApiCheckOptions): Promise<void> {
+    await this.openApiCheckService.validateSpec(options.filename, options.localSchema);
+  }
+
+  /**
+   * Execute accessibility check
+   */
+  async checkAccessibility(): Promise<number> {
+    return await this.accessibilityCheckService.checkAccessibility();
+  }
+
+  protected override async execute(options: OpenApiCheckOptions): Promise<void> {
+    // This is for openapi-check command
+    await this.openApiCheckService.validateSpec(options.filename, options.localSchema);
+  }
+}

package/src/commands/dev.command.ts

@@ -0,0 +1,63 @@
+import { dev } from '@poetora/previewing';
+import type { ArgumentsCamelCase } from 'yargs';
+import { InvalidEnvironmentError } from '../errors/index.js';
+import type { PortService, VersionService } from '../services/index.js';
+import type { DevOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+
+/**
+ * Dev command - Start local development server
+ */
+export class DevCommand extends BaseCommand {
+  readonly name = 'dev';
+  readonly description = 'initialize a local preview environment';
+
+  constructor(
+    logger: ILogger,
+    private readonly versionService: VersionService,
+    private readonly portService: PortService,
+    packageName: string = 'poet'
+  ) {
+    super(logger, packageName);
+  }
+
+  protected override async validate(_options: DevOptions): Promise<void> {
+    // Check Node.js version
+    const versionResult = this.versionService.checkNodeVersion();
+
+    if (!versionResult.isValid) {
+      throw new InvalidEnvironmentError(versionResult.message ?? 'Unsupported Node.js version');
+    }
+
+    // Show warning if below recommended version
+    if (versionResult.hasWarning && versionResult.message) {
+      this.logger.warn(versionResult.message);
+    }
+  }
+
+  protected override async execute(options: DevOptions): Promise<void> {
+    // Find available port
+    const port = await this.portService.findAvailablePort(options.port);
+
+    // Get CLI version
+    const cliVersion = this.versionService.getCliVersion();
+
+    // Start development server (delegate to @poetora/previewing)
+    // Convert DevOptions to ArgumentsCamelCase format expected by dev()
+    const devArgs: ArgumentsCamelCase = {
+      _: [],
+      $0: this.packageName,
+      port,
+      open: options.open ?? true,
+      localSchema: options.localSchema ?? false,
+      clientVersion: options.clientVersion,
+      groups: options.groups,
+      disableOpenapi: options.disableOpenapi ?? false,
+      packageName: this.packageName,
+      cliVersion,
+    };
+
+    await dev(devArgs);
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,6 @@
+export * from './base.command.js';
+export * from './check.command.js';
+export * from './dev.command.js';
+export * from './init.command.js';
+export * from './link.command.js';
+export * from './update.command.js';

package/src/commands/init.command.ts

@@ -0,0 +1,125 @@
+import { input, select } from '@inquirer/prompts';
+import { ValidationError } from '../errors/index.js';
+import type { TemplateService } from '../services/template.service.js';
+import type { InitOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+
+/**
+ * Init command - Create a new Poetora documentation site
+ */
+export class InitCommand extends BaseCommand {
+  readonly name = 'init';
+  readonly description = 'Create a new Poetora documentation site';
+
+  constructor(
+    logger: ILogger,
+    private readonly templateService: TemplateService,
+    packageName: string = 'poet'
+  ) {
+    super(logger, packageName);
+  }
+
+  protected override async execute(options: InitOptions): Promise<void> {
+    let installDir = options.directory;
+
+    // Step 1: Handle existing directory
+    const dirStatus = await this.templateService.checkDirectory(installDir);
+
+    if (dirStatus.exists && dirStatus.hasContents) {
+      const choice = await this.promptDirectoryChoice(installDir);
+
+      if (choice === 'cancel') {
+        this.logger.info('Installation cancelled');
+        return;
+      }
+
+      if (choice === 'subdir') {
+        const subdir = await this.promptSubdirectoryName();
+        installDir = installDir === '.' ? subdir : `${installDir}/${subdir}`;
+      }
+    }
+
+    // Step 2: Prompt for project configuration
+    const projectName = await this.promptProjectName(installDir);
+    const theme = await this.promptTheme();
+
+    // Step 3: Download and install template
+    this.logger.info('Setting up documentation project...');
+
+    await this.templateService.installTemplate({
+      directory: installDir,
+      projectName,
+      theme,
+    });
+
+    // Step 4: Show success message
+    this.showOnboardingMessage(installDir);
+  }
+
+  private async promptDirectoryChoice(
+    directory: string
+  ): Promise<'subdir' | 'overwrite' | 'cancel'> {
+    const choice = await select({
+      message: `Directory ${directory} is not empty. What would you like to do?`,
+      choices: [
+        { name: 'Create in a subdirectory', value: 'subdir' },
+        { name: 'Overwrite current directory (may lose contents)', value: 'overwrite' },
+        { name: 'Cancel', value: 'cancel' },
+      ],
+    });
+
+    return choice as 'subdir' | 'overwrite' | 'cancel';
+  }
+
+  private async promptSubdirectoryName(): Promise<string> {
+    const subdir = await input({
+      message: 'Subdirectory name:',
+      default: 'docs',
+    });
+
+    if (!subdir || subdir.trim() === '') {
+      throw new ValidationError('Subdirectory name cannot be empty');
+    }
+
+    return subdir.trim();
+  }
+
+  private async promptProjectName(installDir: string): Promise<string> {
+    const defaultProject = installDir === '.' ? 'Poetora' : installDir;
+
+    const projectName = await input({
+      message: 'Project Name',
+      default: defaultProject,
+    });
+
+    return projectName || defaultProject;
+  }
+
+  private async promptTheme(): Promise<string> {
+    const themes = this.templateService.getAvailableThemes();
+
+    const theme = await select({
+      message: 'Theme',
+      choices: themes.map((t) => ({
+        name: t,
+        value: t,
+      })),
+    });
+
+    return theme;
+  }
+
+  private showOnboardingMessage(installDir: string): void {
+    this.logger.log('');
+    this.logger.success('Documentation Setup!');
+    this.logger.log('');
+    this.logger.log('To see your docs run:');
+    this.logger.log('');
+    if (installDir !== '.') {
+      this.logger.log(`  cd ${installDir}`);
+    }
+    this.logger.log(`  ${this.packageName} dev`);
+    this.logger.log('');
+  }
+}

package/src/commands/link.command.ts

@@ -0,0 +1,39 @@
+import type { LinkService } from '../services/index.js';
+import type { RenameOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+
+/**
+ * Link command - Check broken links and rename files
+ */
+export class LinkCommand extends BaseCommand {
+  readonly name = 'link';
+  readonly description = 'manage documentation links';
+
+  constructor(
+    logger: ILogger,
+    private readonly linkService: LinkService,
+    packageName: string = 'poet'
+  ) {
+    super(logger, packageName);
+  }
+
+  /**
+   * Check for broken links
+   */
+  async checkBrokenLinks(): Promise<Record<string, string[]>> {
+    return await this.linkService.checkBrokenLinks();
+  }
+
+  /**
+   * Rename file and update references
+   */
+  async renameFile(options: RenameOptions): Promise<void> {
+    await this.linkService.renameFile(options.from, options.to, options.force);
+  }
+
+  protected override async execute(): Promise<void> {
+    // Default action: check broken links
+    await this.linkService.checkBrokenLinks();
+  }
+}

package/src/commands/update.command.ts

@@ -0,0 +1,23 @@
+import type { UpdateService } from '../services/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+
+/**
+ * Update command - Update CLI to latest version
+ */
+export class UpdateCommand extends BaseCommand {
+  readonly name = 'update';
+  readonly description = 'update the CLI to the latest version';
+
+  constructor(
+    logger: ILogger,
+    private readonly updateService: UpdateService,
+    packageName: string = 'poet'
+  ) {
+    super(logger, packageName);
+  }
+
+  protected override async execute(): Promise<void> {
+    await this.updateService.update();
+  }
+}